energykit.features

Energy-specific feature engineering - 40+ features from any hourly time series.

energykit.features — Energy-specific feature engineering.

class energykit.features.EnergyFeatureExtractor(lags: List[int] | None = None, rolling_windows: List[int] | None = None, cyclical: bool = True, tou_schedule: Dict[str, List[int]] | None = {'mid_peak': [7, 8, 9, 10, 11, 12, 13, 14, 15, 16], 'off_peak': [0, 1, 2, 3, 4, 5, 6, 22, 23], 'on_peak': [17, 18, 19, 20, 21]}, country: str | None = None, lat: float | None = None, lon: float | None = None)

Bases: BaseEstimator, TransformerMixin

Scikit-learn compatible transformer for energy time-series features.

Transforms a pd.Series or pd.DataFrame with a DatetimeIndex into a rich feature matrix suited for load forecasting, anomaly detection, and device disaggregation tasks.

Parameters:

• lags (list of int, default [1, 2, 3, 24, 48, 168]) – Lag periods (assumes hourly data). Lag features are built from the first column (or the Series itself).

• rolling_windows (list of int, default [24, 168]) – Rolling window sizes (number of periods). Rolling statistics are computed on lag-1 shifted data to prevent data leakage.

• cyclical (bool, default True) – Encode periodic features as sin/cos pairs to avoid boundary discontinuities.

• tou_schedule (dict or None) – Time-of-use block mapping {block_name: [hour, ...]} where hours are 0-based integers (0 = midnight). Pass {} to disable. Defaults to a typical US on_peak / mid_peak / off_peak schedule.

• country (str or None) – ISO 3166-1 alpha-2 country code for holiday detection (e.g. "US", "DE"). Requires the holidays package (pip install holidays).

• lat (float or None) – Latitude in decimal degrees. Required for solar position features.

• lon (float or None) – Longitude in decimal degrees. Required for solar position features.

feature_names_

Names of all generated features (set after fit/fit_transform).

Type:

list of str

Examples

>>> fe = EnergyFeatureExtractor(country="US", lags=[1, 24, 168])
>>> X = fe.fit_transform(meter_series)
>>> X.shape
(8760, 42)

fit(X, y=None)

No fitting required; features are fully deterministic.

get_feature_names_out(input_features=None) → ndarray

Return feature names (sklearn Pipeline compatibility).

transform(X) → DataFrame

Generate energy features.

Parameters:

X (pd.Series or pd.DataFrame) – Input data with a DatetimeIndex. If a DataFrame, the first column is used for lag and rolling features.

Returns:

Feature matrix indexed identically to X.

Return type:

pd.DataFrame

Raises:

ValueError – If X does not have a DatetimeIndex.

Temporal Features

energykit.features.temporal

Energy-specific feature engineering from time-indexed smart-meter data.

Features generated

Temporal

hour, day_of_week, month, week_of_year, day_of_year is_weekend, is_holiday (optional, requires holidays package) season (0=winter, 1=spring, 2=summer, 3=autumn)

Cyclical encoding

sin/cos encoding for hour, day-of-week, month, day-of-year. Avoids discontinuities at period boundaries (e.g. hour 23 → hour 0).

Time-of-use blocks

Configurable on-peak / mid-peak / off-peak binary flags. Default schedule follows a typical US utility TOU tariff.

Lag features

Autoregressive lags at configurable horizons (default: 1h, 2h, 3h, 24h, 48h, 168h).

Rolling statistics

Rolling mean, std, min, max over configurable windows (default: 24h, 168h). Window is applied to lagged data to prevent data leakage.

Solar position

Simplified solar elevation angle (degrees). Requires lat/lon. Useful proxy for solar irradiance and PV generation features.

Usage

>>> import pandas as pd
>>> from energykit.features import EnergyFeatureExtractor
>>>
>>> meter = pd.read_csv("meter.csv", index_col=0, parse_dates=True)["kwh"]
>>> fe = EnergyFeatureExtractor(country="US", lat=37.7, lon=-122.4)
>>> features = fe.fit_transform(meter)
>>> print(features.shape)   # (n_samples, n_features)

class energykit.features.temporal.EnergyFeatureExtractor(lags: List[int] | None = None, rolling_windows: List[int] | None = None, cyclical: bool = True, tou_schedule: Dict[str, List[int]] | None = {'mid_peak': [7, 8, 9, 10, 11, 12, 13, 14, 15, 16], 'off_peak': [0, 1, 2, 3, 4, 5, 6, 22, 23], 'on_peak': [17, 18, 19, 20, 21]}, country: str | None = None, lat: float | None = None, lon: float | None = None)

Bases: BaseEstimator, TransformerMixin

Scikit-learn compatible transformer for energy time-series features.

Transforms a pd.Series or pd.DataFrame with a DatetimeIndex into a rich feature matrix suited for load forecasting, anomaly detection, and device disaggregation tasks.

Parameters:

• lags (list of int, default [1, 2, 3, 24, 48, 168]) – Lag periods (assumes hourly data). Lag features are built from the first column (or the Series itself).

• rolling_windows (list of int, default [24, 168]) – Rolling window sizes (number of periods). Rolling statistics are computed on lag-1 shifted data to prevent data leakage.

• cyclical (bool, default True) – Encode periodic features as sin/cos pairs to avoid boundary discontinuities.

• tou_schedule (dict or None) – Time-of-use block mapping {block_name: [hour, ...]} where hours are 0-based integers (0 = midnight). Pass {} to disable. Defaults to a typical US on_peak / mid_peak / off_peak schedule.

• country (str or None) – ISO 3166-1 alpha-2 country code for holiday detection (e.g. "US", "DE"). Requires the holidays package (pip install holidays).

• lat (float or None) – Latitude in decimal degrees. Required for solar position features.

• lon (float or None) – Longitude in decimal degrees. Required for solar position features.

feature_names_

Names of all generated features (set after fit/fit_transform).

Type:

list of str

Examples

>>> fe = EnergyFeatureExtractor(country="US", lags=[1, 24, 168])
>>> X = fe.fit_transform(meter_series)
>>> X.shape
(8760, 42)

fit(X, y=None)

No fitting required; features are fully deterministic.

get_feature_names_out(input_features=None) → ndarray

Return feature names (sklearn Pipeline compatibility).

transform(X) → DataFrame

Generate energy features.

Parameters:

X (pd.Series or pd.DataFrame) – Input data with a DatetimeIndex. If a DataFrame, the first column is used for lag and rolling features.

Returns:

Feature matrix indexed identically to X.

Return type:

pd.DataFrame

Raises:

ValueError – If X does not have a DatetimeIndex.