Skip to content

Cold start

polars_ts.applications.perishables.cold_start

Cold-start forecasting for new SKUs with little or no history.

New perishables launch constantly; with days of history there is nothing for a statistical model to fit. Instead, borrow the early-life trajectory of established SKUs:

  • With some observations, find the k donors whose own launch-aligned, level-normalized early sales look most similar (Euclidean distance) and average their subsequent trajectory, rescaled to the new SKU's observed level.
  • With zero or near-zero observations, fall back to the mean launch-aligned trajectory of the SKU's category (or of all donors).

For richer similarity structure (DTW, k-medoids), cluster donor profiles with :func:polars_ts.auto_cluster upstream and pass a single cluster's SKUs into this module.

cold_start_skus(df, min_history=28, id_col='unique_id')

List SKUs with fewer than min_history observations.

Parameters

df Gap-free canonical sales frame (per-SKU calendars start at each SKU's launch, as produced by the loader). min_history Observation count below which a SKU is considered cold. id_col SKU column name.

Returns

list[str] Cold SKU identifiers, sorted.

_launch_profiles(df, id_col, time_col, target_col)

Return each SKU's launch-aligned demand array, sorted by date.

_donor_trajectory(obs, donors, h, k)

Forecast h steps by averaging the k most similar donor trajectories.

Donors are compared on the launch-aligned overlap with obs after mean-normalization, then their steps [len(obs), len(obs)+h) are averaged and rescaled to the new SKU's observed mean level.

cold_start_forecast(df, h, min_history=28, k=5, category_map=None, target_col='y', id_col='unique_id', time_col='ds')

Forecast cold SKUs by borrowing established SKUs' early life.

Parameters

df Gap-free canonical sales frame containing both cold and established SKUs. h Forecast horizon (periods). min_history Observation count below which a SKU is treated as cold. k Number of donor SKUs averaged per cold SKU. category_map Optional [id_col, "category"] frame; when given, donors are restricted to the cold SKU's category (falling back to all donors for unknown categories). target_col, id_col, time_col Canonical column names.

Returns

pl.DataFrame Columns [id_col, time_col, "y_hat"] with h rows per cold SKU. Established SKUs are not forecast here — route them to the standard pipeline.