weather.derived.add_derived_weather_features

weather.derived.add_derived_weather_features(
    weather,
    features,
    *,
    hdh_base=DEFAULT_HDH_BASE_C,
    cdh_base=DEFAULT_CDH_BASE_C,
    temp_col=TEMP_COL,
    humidity_col=HUMIDITY_COL,
    wind_col=WIND_COL,
    wind_speed_unit='kmh',
)

Append the requested derived columns to a raw weather frame (fail-safe).

A thin, deterministic orchestrator over :func:heating_degree_hours, :func:cooling_degree_hours, :func:dew_point, and :func:apparent_temperature. The original columns are preserved; the requested derived columns are appended in the fixed order of :data:DERIVED_FEATURE_KEYS (stable column ordering). The default wind_speed_unit is "kmh" to match the Open-Meteo payload consumed by :func:spotforecast2_safe.weather.get_weather_features.

Parameters

Name	Type	Description	Default
weather	pd.DataFrame	Raw weather frame containing the source columns the requested features need.	required
features	Sequence[str]	Any subset of :data:`DERIVED_FEATURE_KEYS`. An empty sequence returns weather unchanged (a copy).	required
hdh_base	float	Heating base temperature in °C.	`DEFAULT_HDH_BASE_C`
cdh_base	float	Cooling base temperature in °C.	`DEFAULT_CDH_BASE_C`
temp_col	str	Name of the temperature column.	`TEMP_COL`
humidity_col	str	Name of the relative-humidity column.	`HUMIDITY_COL`
wind_col	str	Name of the wind-speed column.	`WIND_COL`
wind_speed_unit	str	Unit of wind_col, `"ms"` or `"kmh"` (default).	`'kmh'`

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: A copy of weather with the requested derived columns
	pd.DataFrame	appended.

Raises

Name	Type	Description
	ValueError	If a requested feature is unknown, or a source column it needs is absent from weather.

Examples

import pandas as pd
from spotforecast2_safe.weather.derived import add_derived_weather_features

idx = pd.date_range("2023-07-01", periods=2, freq="h", tz="UTC")
weather = pd.DataFrame(
    {
        "temperature_2m": [28.0, 30.0],
        "relative_humidity_2m": [60.0, 55.0],
        "wind_speed_10m": [7.2, 10.8],  # km/h
    },
    index=idx,
)
out = add_derived_weather_features(
    weather, ["hdh", "cdh", "apparent_temperature", "dew_point"]
)
print(sorted(set(out.columns) - set(weather.columns)))

['apparent_temperature', 'cdh', 'dew_point', 'hdh']