Advanced

polars_ts.features.advanced

Advanced feature engineering: target encoding, holidays, interactions, time embeddings. Closes #53.

target_encode(df, cat_col, target_col='y', smoothing=10.0, _id_col='unique_id')

Encode a categorical column by smoothed per-category target mean.

Uses regularized (smoothed) encoding: encoded = (n * cat_mean + smoothing * global_mean) / (n + smoothing)

Parameters

df Input DataFrame. cat_col Categorical column to encode. target_col Target column for computing means. smoothing Smoothing factor (higher = more regularization). id_col Not used directly but kept for API consistency.

Returns

pl.DataFrame DataFrame with {cat_col}_encoded column appended.

holiday_features(df, country='US', time_col='ds', distance=False)

Add binary holiday columns and optional distance-to-holiday features.

Requires the holidays package (pip install holidays).

Parameters

df Input DataFrame. country ISO country code (e.g. "US", "DE", "BR"). time_col Datetime or date column. distance If True, add days_to_holiday and days_since_holiday columns.

interaction_features(df, pairs, method='multiply')

Generate interaction features between pairs of columns.

Parameters

df Input DataFrame. pairs List of (col_a, col_b) tuples. method "multiply" (default) or "add".

time_embeddings(df, time_col='ds', components=None)

Encode cyclical time features as sin/cos pairs.

Parameters

df Input DataFrame. time_col Datetime column. components Time components to encode. Defaults to ["hour", "day_of_week", "month"]. Each produces a sin/cos pair.