preprocessing.exog_builder.ExogBuilder

preprocessing.exog_builder.ExogBuilder(
    periods=None,
    country_code=None,
    providers=None,
    on_provider_failure='raise',
)

Builds a set of exogenous features for a given date range.

This builder combines temporal features (day of year, day of week, hour, etc.) with cyclical features encoded via RepeatingBasisFunctions and optional holiday indicators.

Optional ExogFeatureProvider objects extend the built frame with additional drivers (e.g. ENTSO-E day-ahead forecasts, COVID infection rate). Each provider returns numeric, NaN-free columns aligned to the same hourly index; a provider that cannot cover the range is either re-raised or skipped according to on_provider_failure.

Attributes

Name	Type	Description
periods	List[Period]	List of periodic features to encode.
country_code	Optional[str]	Country code for holiday lookups.
holidays_list	Optional[`holidays`.`HolidayBase`]	List of holidays for the specified country.
providers	List[ExogFeatureProvider]	Extra exogenous-feature providers appended to every built frame.
on_provider_failure	str	`"raise"` (default) to propagate an `ExogProviderError` from a provider, or `"skip"` to log and omit that provider’s columns.

Examples

import pandas as pd
from spotforecast2_safe.data.data_classes import Period
from spotforecast2_safe.preprocessing.exog_builder import ExogBuilder

periods = [Period(name="hour", n_periods=24, column="hour", input_range=(0, 23))]
builder = ExogBuilder(periods=periods, country_code="DE")
start = pd.Timestamp("2025-01-01", tz="UTC")
end = pd.Timestamp("2025-01-02", tz="UTC")
exog = builder.build(start, end)
print(f"shape: {exog.shape}")
assert exog.shape[1] > 0

shape: (25, 26)

Methods

Name	Description
build	Build the exogenous feature DataFrame for a date range.

build

preprocessing.exog_builder.ExogBuilder.build(start_date, end_date)

Build the exogenous feature DataFrame for a date range.

The generated DataFrame has an hourly frequency.

Parameters

Name	Type	Description	Default
start_date	pd.Timestamp	Start of the date range (inclusive).	required
end_date	pd.Timestamp	End of the date range (inclusive).	required

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: DataFrame containing exogenous features.

Raises

Name	Type	Description
	ValueError	If the date range is invalid.

Examples

import pandas as pd
from spotforecast2_safe.data.data_classes import Period
from spotforecast2_safe.preprocessing.exog_builder import ExogBuilder

periods = [Period(name="hour", n_periods=24, column="hour", input_range=(0, 23))]
builder = ExogBuilder(periods=periods, country_code="DE")
start = pd.Timestamp("2025-01-01", tz="UTC")
end = pd.Timestamp("2025-01-02", tz="UTC")
exog = builder.build(start, end)
print(f"shape: {exog.shape}, columns: {list(exog.columns[:4])}")
assert exog.shape == (25, 26)
assert "holidays" in exog.columns
assert "is_weekend" in exog.columns

shape: (25, 26), columns: ['hour_0', 'hour_1', 'hour_2', 'hour_3']