manager.features.create_interaction_features

manager.features.create_interaction_features(
    exogenous_features,
    weather_aligned,
    base_cols=None,
    weather_window_pattern='_window_',
    include_weather_funcs=None,
    holiday_col='is_holiday',
    degree=1,
)

Append bilinear interaction terms to an exogenous feature matrix.

Constructs interaction features between calendar cyclical columns, weather rolling-window statistics, raw weather variables, and (optionally) a holiday indicator. Only pairwise products are generated (interaction_only=True) without a bias term. The new columns are named poly_<col_a>__<col_b> and are appended to the right of exogenous_features.

Parameters

Name	Type	Description	Default
exogenous_features	pd.DataFrame	DataFrame containing all current exogenous features. Must already include the columns listed in base_cols.	required
weather_aligned	pd.DataFrame	DataFrame containing only the raw (un-transformed) weather variables. Used to identify which columns in exogenous_features are raw weather columns.	required
base_cols	Optional[List[str]]	Calendar cyclical columns that form the left side of each interaction. Defaults to `["day_of_week_sin", "day_of_week_cos", "hour_sin", "hour_cos"]`.	`None`
weather_window_pattern	str	Substring used to detect rolling-window weather columns in exogenous_features. Defaults to `"_window_"`.	`'_window_'`
include_weather_funcs	Optional[List[str]]	Rolling-aggregation suffixes to include. Defaults to `["_mean", "_min", "_max"]`.	`None`
holiday_col	str	Name of the binary holiday indicator column. If present in exogenous_features it is added to the interaction pool. Defaults to `"is_holiday"`.	`'is_holiday'`
degree	int	Polynomial degree passed to :class:`~sklearn.preprocessing.PolynomialFeatures`. At degree 1 only pairwise products are produced (no higher-order terms). Defaults to `1`.	`1`

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: exogenous_features with `poly_*` interaction columns
	pd.DataFrame	appended. The original columns are unchanged.

Examples

Add interaction terms between cyclical hour features and a weather variable:

import numpy as np
import pandas as pd
from spotforecast2_safe.manager.features import create_interaction_features

rng = np.random.default_rng(0)
idx = pd.date_range("2024-01-01", periods=72, freq="h", tz="UTC")

weather = pd.DataFrame(
    {"temperature": rng.normal(10, 3, 72)},
    index=idx,
)
exog = pd.DataFrame(
    {
        "day_of_week_sin": np.sin(2 * np.pi * idx.dayofweek / 7),
        "day_of_week_cos": np.cos(2 * np.pi * idx.dayofweek / 7),
        "hour_sin": np.sin(2 * np.pi * idx.hour / 24),
        "hour_cos": np.cos(2 * np.pi * idx.hour / 24),
        "temperature": weather["temperature"],
    },
    index=idx,
)

result = create_interaction_features(
    exogenous_features=exog,
    weather_aligned=weather,
)
poly_cols = [c for c in result.columns if c.startswith("poly_")]
print("poly columns:", poly_cols[:4])
print("total columns:", result.shape[1])

poly columns: []
total columns: 5