calendar.features.get_calendar_features

calendar.features.get_calendar_features(
    start,
    cov_end,
    freq='h',
    timezone='UTC',
    features_to_extract=None,
)

Create calendar-based features for a contiguous time range.

Uses DatetimeFeatures to extract temporal components from a regularly spaced DatetimeIndex. The resulting DataFrame has the same index as the generated time grid and one integer column per requested feature.

Parameters

Name	Type	Description	Default
start	Union[str, pd.Timestamp]	Start of the time range. String values are parsed with `utc=True`.	required
cov_end	Union[str, pd.Timestamp]	Inclusive end of the time range. String values are parsed with `utc=True`.	required
freq	str	Pandas-compatible frequency string for the output index. Defaults to `"h"` (hourly).	`'h'`
timezone	str	Timezone label applied to the generated index. Defaults to `"UTC"`.	`'UTC'`
features_to_extract	Optional[List[str]]	Calendar components to extract. Defaults to `["month", "week", "day_of_week", "hour"]`.	`None`

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: DataFrame with integer columns for each extracted
	pd.DataFrame	calendar feature. The index is a tz-aware
	pd.DataFrame	`DatetimeIndex` with the requested `freq`.

Raises

Name	Type	Description
	ValueError	If `start` is later than `cov_end`.

Examples

import pandas as pd
from spotforecast2_safe.calendar import get_calendar_features

start = pd.Timestamp("2024-01-01", tz="UTC")
cov_end = pd.Timestamp("2024-01-07 23:00", tz="UTC")

features = get_calendar_features(
    start=start,
    cov_end=cov_end,
    freq="h",
    timezone="UTC",
)
print("shape:", features.shape)
print("columns:", features.columns.tolist())
print(features.head(3))

shape: (168, 4)
columns: ['month', 'week', 'day_of_week', 'hour']
                           month  week  day_of_week  hour
2024-01-01 00:00:00+00:00      1     1            0     0
2024-01-01 01:00:00+00:00      1     1            0     1
2024-01-01 02:00:00+00:00      1     1            0     2