feat: add temporal_resolution parameter to OpenMeteoSource

Allows fetching 3-hourly ("hourly_3"), 6-hourly ("hourly_6"), or
model-native resolution ("native") data in addition to the default 1 h.

When temporal_resolution is not None the parameter is forwarded to the
Open-Meteo API. For "native" the points-per-day value is inferred from
the delta between the first two returned timestamps instead of being
hardcoded to 24, so forecast index offsets stay correct regardless of
model step size. The value is included in the cache config key so
different resolutions cache independently.

Author: dawidlinek

docs/src/content/docs/data-sources/openmeteo.mdx

@@ -42,6 +42,35 @@ df = source.fetch(
 | `model` | str | No | `"jma_seamless"` | Weather model |
 | `columns` | List[str] | No | DEFAULT_COLUMNS | Weather variables |
 | `prefix` | str | No | `""` | Prefix for column names |
+| `temporal_resolution` | str \| None | No | `None` | Time step of returned data — see below |
+
+### Temporal Resolution
+
+| Value | Time step | Notes |
+|-------|-----------|-------|
+| `None` *(default)* | 1 h | Standard hourly data; no extra API parameter sent |
+| `"hourly_3"` | 3 h | 8 data points per day |
+| `"hourly_6"` | 6 h | 4 data points per day |
+| `"native"` | model-dependent | Uses the weather model's native resolution; step is inferred automatically from the response |
+
+```python
+# 3-hourly data — useful for coarser feature sets or faster pipelines
+source = OpenMeteoSource(
+    latitude=52.2297,
+    longitude=21.0122,
+    horizon=7,
+    prefix="warsaw",
+    temporal_resolution="hourly_3",
+)
+
+# Model-native resolution
+source = OpenMeteoSource(
+    latitude=52.2297,
+    longitude=21.0122,
+    model="icon_seamless",
+    temporal_resolution="native",
+)
+```
 
 ## Rate Limiting
 

epftoolbox2/data/sources/open_meteo.py

@@ -56,6 +56,9 @@ class OpenMeteoSource(DataSource):
         "wind_direction_10m",
     ]
 
+    VALID_TEMPORAL_RESOLUTIONS = {None, "native", "hourly_3", "hourly_6"}
+    _POINTS_PER_DAY = {None: 24, "hourly_3": 8, "hourly_6": 4}
+
     def __init__(
         self,
         latitude: float,
@@ -65,6 +68,7 @@ def __init__(
         columns: List[str] = None,
         prefix: str = "",
         proxy_url: str = None,
+        temporal_resolution: str = None,
     ):
         """
         Initialize Open-Meteo data source
@@ -77,6 +81,10 @@ def __init__(
             columns: List of weather variables to fetch (default: DEFAULT_COLUMNS)
             prefix: Prefix to add to column names (default: "")
             proxy_url: Proxy URL (e.g., 'http://proxy.example.com:8080')
+            temporal_resolution: Temporal resolution of the data. One of:
+                None (default) — hourly (1 h), no parameter sent to API;
+                "hourly_3" — 3-hourly; "hourly_6" — 6-hourly;
+                "native" — model-native resolution (inferred from response).
         """
         self.latitude = latitude
         self.longitude = longitude
@@ -85,6 +93,7 @@ def __init__(
         self.columns = columns if columns else self.DEFAULT_COLUMNS
         self.prefix = prefix
         self.proxy_url = proxy_url
+        self.temporal_resolution = temporal_resolution
 
         self.session = requests.Session()
         self._configure_proxy()
@@ -113,6 +122,12 @@ def _validate_config(self) -> bool:
         if not self.columns:
             raise ValueError("At least one weather column must be specified")
 
+        if self.temporal_resolution not in self.VALID_TEMPORAL_RESOLUTIONS:
+            raise ValueError(
+                f"temporal_resolution must be one of {self.VALID_TEMPORAL_RESOLUTIONS}, "
+                f"got {self.temporal_resolution!r}"
+            )
+
         return True
 
     def _configure_proxy(self):
@@ -208,6 +223,8 @@ def _fetch_chunk(self, start: pd.Timestamp, end: pd.Timestamp) -> pd.DataFrame:
             "start_date": start.strftime("%Y-%m-%d"),
             "end_date": end.strftime("%Y-%m-%d"),
         }
+        if self.temporal_resolution is not None:
+            params["temporal_resolution"] = self.temporal_resolution
 
         max_retries = 5
         retry_count = 0
@@ -252,13 +269,22 @@ def _fetch_chunk(self, start: pd.Timestamp, end: pd.Timestamp) -> pd.DataFrame:
 
         raise RuntimeError(f"Failed to fetch data after {max_retries} retries")
 
+    def _points_per_day(self, times: list) -> int:
+        if self.temporal_resolution == "native":
+            if len(times) >= 2:
+                delta_hours = (pd.Timestamp(times[1]) - pd.Timestamp(times[0])).total_seconds() / 3600
+                return max(1, int(round(24 / delta_hours)))
+            return 24
+        return self._POINTS_PER_DAY.get(self.temporal_resolution, 24)
+
     def _parse_weather_data(self, response_data: dict) -> pd.DataFrame:
         if "hourly" not in response_data or "time" not in response_data["hourly"]:
             return pd.DataFrame()
 
         weather = {}
         hourly_data = response_data["hourly"]
         times = hourly_data["time"]
+        points_per_day = self._points_per_day(times)
 
         for x, timestamp_str in enumerate(times):
             try:
@@ -267,7 +293,7 @@ def _parse_weather_data(self, response_data: dict) -> pd.DataFrame:
                     for column in self.columns:
                         column_key = f"{column}_previous_day{i}"
                         if column_key in hourly_data:
-                            forecast_idx = x + (i * 24)
+                            forecast_idx = x + (i * points_per_day)
                             if forecast_idx < len(hourly_data[column_key]):
                                 value = hourly_data[column_key][forecast_idx]
                                 tmp[f"{column}_d+{i}"] = value
@@ -302,6 +328,7 @@ def get_cache_config(self) -> dict:
             "model": self.model,
             "columns": sorted(self.columns),
             "prefix": self.prefix,
+            "temporal_resolution": self.temporal_resolution,
         }
 
         return config

llms.txt

@@ -110,15 +110,22 @@ source = OpenMeteoSource(
     model="jma_seamless",        # Optional. Weather model (default: "jma_seamless")
     columns=None,                # Optional. Weather variables (default: DEFAULT_COLUMNS)
     prefix="warsaw",             # Optional. Prefix for column names (default: "")
+    temporal_resolution=None,    # Optional. None|"hourly_3"|"hourly_6"|"native" (default: None = 1 h)
 )
 ```
 
 **Default columns:** `temperature_2m`, `rain`, `showers`, `snowfall`, `relative_humidity_2m`, `dew_point_2m`, `apparent_temperature`, `precipitation`, `weather_code`, `surface_pressure`, `pressure_msl`, `cloud_cover`, `wind_speed_10m`, `wind_direction_10m`
 
+**temporal_resolution values:**
+- `None` (default) — 1-hourly; no extra API parameter sent
+- `"hourly_3"` — 3-hourly (8 points/day)
+- `"hourly_6"` — 6-hourly (4 points/day)
+- `"native"` — model-native resolution; time step inferred from the API response
+
 **Output column naming:** `{prefix}_{variable}_d+{horizon}`
 - Example: `warsaw_temperature_2m_d+1`, `warsaw_temperature_2m_d+2`, ..., `warsaw_temperature_2m_d+7`
 
-**Caching:** Returns cache config based on location, horizon, model, columns.
+**Caching:** Returns cache config based on location, horizon, model, columns, temporal_resolution.
 
 ---