Skip to content

Calendar Features

This section documents calendar-based feature extraction utilities provided by eb-features.

Calendar features are derived from timestamp columns and may include cyclical encodings for periodic components.

All content below is generated automatically from NumPy-style docstrings in the source code.

Calendar Feature API

eb_features.panel.calendar

Calendar and time-derived features for panel time series.

This module provides utilities to derive calendar/time features from a timestamp column. It is designed for panel time-series data (entity-by-timestamp) and is typically used as part of a broader feature engineering pipeline.

Supported base calendar features

Given a timestamp column timestamp_col:

  • "hour": Hour of day in [0, 23]
  • "dow": Day of week in [0, 6] where Monday=0 (pandas convention)
  • "dom": Day of month in [1, 31]
  • "month": Month in [1, 12]
  • "is_weekend": Weekend indicator (Saturday/Sunday) as 0/1
Optional cyclical encodings

Certain calendar attributes are periodic and can be represented with sine/cosine pairs:

  • hour (period 24):
\[ \sin\left(2\pi \frac{\mathrm{hour}}{24}\right),\quad \cos\left(2\pi \frac{\mathrm{hour}}{24}\right) \]
  • day of week (period 7):
\[ \sin\left(2\pi \frac{\mathrm{dow}}{7}\right),\quad \cos\left(2\pi \frac{\mathrm{dow}}{7}\right) \]

These encodings are added only when: - the corresponding base feature (hour or dow) is present, and - use_cyclical_time=True.

Notes
  • Feature construction is stateless: functions operate only on the provided DataFrame.
  • Time features are derived from pandas.to_datetime conversion of timestamp_col. Timezone-aware timestamps are supported; feature values reflect the timestamp's local representation as stored in the column.

add_calendar_features(df, *, timestamp_col, calendar_features, use_cyclical_time=True)

Add calendar/time-derived features to a DataFrame.

Parameters:

Name Type Description Default
df DataFrame

Input DataFrame containing a timestamp column.

 required
timestamp_col str

Name of the timestamp column.

 required
calendar_features Sequence[str]

Base calendar features to derive. Allowed values are: {"hour", "dow", "dom", "month", "is_weekend"}.

 required
use_cyclical_time bool

If True, add sine/cosine encodings for hour and/or day-of-week when those base features are included.

 True

Returns:

Name Type Description
df_out DataFrame

Copy of df with the requested calendar features added as columns.
feature_cols list[str]

Names of all features added by this call, including cyclical encodings (if any).
calendar_cols list[str]

Names of base calendar feature columns added (excludes cyclical encodings).

Raises:

Type Description
KeyError

If timestamp_col is not present in df.
ValueError

If an unsupported calendar feature is requested.
Notes

The derived columns are currently named:

  • hour
  • dayofweek (for requested "dow")
  • dayofmonth (for requested "dom")
  • month
  • is_weekend

This naming is stable and intended to be referenced by downstream steps.