Features
polars_ts.applications.perishables.features
Perishables-specific feature engineering.
Domain features layered on top of the generic helpers
(:func:polars_ts.lag_features, :func:polars_ts.rolling_features,
:func:polars_ts.calendar_features): retail calendar flags, per-SKU
day-of-week demand profiles (fresh-goods demand is dominated by weekly
shopping rhythm), and promotion lift estimation.
perishable_calendar_features(df, time_col='ds')
Add retail calendar features relevant to perishables demand.
Extends the generic calendar features (day of week, month, weekend
flag) with month-boundary flags that proxy payday-driven grocery
spikes: is_month_start (first 5 days) and is_month_end
(last 5 days).
Parameters
df Canonical sales frame. time_col Date column.
Returns
pl.DataFrame
Input frame with day_of_week, day_of_month, week,
month, is_weekend, is_month_start, is_month_end
appended.
dow_profile(df, target_col='y', id_col='unique_id', time_col='ds')
Compute per-SKU day-of-week demand indices.
The index is the SKU's mean demand on that weekday divided by its overall mean, so 1.0 is a neutral day and e.g. 1.8 on Saturday means an 80% uplift. Use it to shape flat intermittent-demand forecasts across the week before feeding the restock calculator.
Parameters
df Gap-free canonical sales frame. target_col, id_col, time_col Canonical column names.
Returns
pl.DataFrame
Columns [id_col, "day_of_week", "dow_index"] (weekday 1 =
Monday ... 7 = Sunday, matching polars).
estimate_promo_lift(df, promo_col='promo', target_col='y', id_col='unique_id')
Estimate each SKU's multiplicative promotion lift.
Lift is mean demand on promoted periods divided by mean demand on non-promoted periods. SKUs never (or always) promoted get a null lift — there is no counterfactual to compare against.
Parameters
df Canonical sales frame with a promotion flag column. promo_col Column with a truthy promotion indicator. target_col, id_col Canonical column names.
Returns
pl.DataFrame
Columns [id_col, "promo_lift", "n_promo_periods"].