weather.features.get_weather_features

weather.features.get_weather_features(
    data,
    start,
    cov_end,
    forecast_horizon,
    latitude=51.5136,
    longitude=7.4653,
    timezone='UTC',
    freq='h',
    window_periods=None,
    window_functions=None,
    fallback_on_failure=True,
    cache_home=None,
    verbose=False,
)

Fetch weather data and compute rolling-window features.

Downloads weather observations/forecasts for the requested period, aligns them to a regular freq grid, and applies WindowFeatures to produce rolling-mean, -max, and -min features over configurable windows.

Parameters

Name	Type	Description	Default
data	pd.DataFrame	Reference time series DataFrame used only for validation (shape / temporal coverage checks via `curate_weather()`).	required
start	Union[str, pd.Timestamp]	Start of the feature window. String values are parsed with `utc=True`.	required
cov_end	Union[str, pd.Timestamp]	Inclusive end of the feature window (must cover the full forecast horizon beyond `end`). String values are parsed with `utc=True`.	required
forecast_horizon	int	Number of forecast steps; passed to `curate_weather()` for validation.	required
latitude	float	Latitude of the target location in decimal degrees. Defaults to `51.5136` (Dortmund, Germany).	`51.5136`
longitude	float	Longitude of the target location in decimal degrees. Defaults to `7.4653` (Dortmund, Germany).	`7.4653`
timezone	str	Timezone label applied to the generated index. Defaults to `"UTC"`.	`'UTC'`
freq	str	Pandas-compatible frequency string for the output index. Defaults to `"h"` (hourly).	`'h'`
window_periods	Optional[List[str]]	Rolling window sizes passed to `WindowFeatures`. Defaults to `["1D", "7D"]`.	`None`
window_functions	Optional[List[str]]	Aggregation functions applied over each window. Defaults to `["mean", "max", "min"]`.	`None`
fallback_on_failure	bool	If `True`, use locally cached fallback data when the weather API is unavailable. Defaults to `True`.	`True`
cache_home	Optional[Union[str, Path]]	Optional path to cache directory. When provided, fetched weather data is cached in `<cache_home>/weather_cache.parquet`. When None (default), no caching is performed.	`None`
verbose	bool	If `True`, print progress messages to stdout. Defaults to `False`.	`False`

Returns

Name	Type	Description
	pd.DataFrame	tuple[pd.DataFrame, pd.DataFrame]: A two-element tuple:
	pd.DataFrame	- weather_features – DataFrame with rolling-window weather features aligned to the `[start, cov_end]` index.
	Tuple[pd.DataFrame, pd.DataFrame]	- weather_aligned – Raw weather DataFrame reindexed to the same `[start, cov_end]` hourly grid (forward-filled).

Raises

Name	Type	Description
	ValueError	If no numeric weather columns are found, or if missing values cannot be filled after fetching.

Examples

import pandas as pd
from spotforecast2_safe.data.fetch_data import fetch_data, get_package_data_home
from spotforecast2_safe.preprocessing.curate_data import (
    agg_and_resample_data,
    get_start_end,
)
from spotforecast2_safe.weather import get_weather_features

# Load and resample demo data
data = fetch_data(filename=str(get_package_data_home() / "demo10.csv"))
data = agg_and_resample_data(data, verbose=False)
start, end, _, cov_end = get_start_end(data=data, forecast_horizon=24, verbose=False)

# Fetch weather features for one week of data
week_start = pd.Timestamp("2020-06-01", tz="UTC")
week_end = pd.Timestamp("2020-06-08", tz="UTC")
weather_features, weather_aligned = get_weather_features(
    data=data,
    start=week_start,
    cov_end=week_end,
    forecast_horizon=24,
    verbose=False,
)
print("weather_features shape:", weather_features.shape)
print("weather_aligned shape:", weather_aligned.shape)

Weather dataframe has wrong shape.
weather_features shape: (169, 105)
weather_aligned shape: (169, 15)