CyclicFeaturesAdder#

class openstef_models.transforms.time_domain.CyclicFeaturesAdder(**data: Any) → None[source]

Bases: BaseConfig, TimeSeriesTransform

Transform that generates cyclic temporal features from datetime indices.

Converts temporal information into sine and cosine components that preserve the periodic nature of time. This encoding ensures temporal boundaries (e.g., end of day/week/year) are properly connected.

The features generated depend on the included_features configuration:

  • season: season_sine, season_cosine (based on day of year, 365.25 day cycle)

  • day_of_week: day_of_week_sine, day_of_week_cosine (based on day of week, 7 day cycle)

  • month: month_sine, month_cosine (based on month of year, 12 month cycle)

  • time_of_day: time_of_day_sine, time_of_day_cosine (based on seconds in day, 24 hour cycle)

Example

>>> import pandas as pd
>>> from datetime import timedelta
>>> from openstef_core.datasets import TimeSeriesDataset
>>> from openstef_models.transforms.time_domain import (
...     CyclicFeaturesAdder,
... )
>>>
>>> # Create sample dataset
>>> data = pd.DataFrame({
...     'load': [100, 120, 110]
... }, index=pd.date_range('2025-01-01 12:00:00', periods=3, freq='1h'))
>>> dataset = TimeSeriesDataset(data, timedelta(hours=1))
>>>
>>> # Apply cyclic features with custom configuration
>>> transform = CyclicFeaturesAdder(included_features=["season", "time_of_day"])
>>> transformed = transform.transform(dataset)
>>> result = transformed.data[['season_sine', 'time_of_day_sine']].round(3)
>>> print(result.head(2))
                     season_sine  time_of_day_sine
timestamp
2025-01-01 12:00:00        0.017            -0.000
2025-01-01 13:00:00        0.017            -0.259
Parameters:

data (Any)

included_features: list[TypeAliasType]
transform(data: TimeSeriesDataset) → TimeSeriesDataset[source]

Transform dataset by adding cyclic features as new columns.

Parameters:
Returns:

New TimeSeriesDataset with original data plus cyclic features (number depends on included_features configuration).

Return type:

TimeSeriesDataset

features_added() → list[str][source]

List of feature names added by this transform.

Return type:

list[str]

Returns:

A list of strings representing the names of features added to the dataset by this transform. Default is an empty list.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].