Skip to content

Loader

polars_ts.applications.perishables.loader

CSV ingestion for perishables sales history.

Maps arbitrary source column names onto the canonical polars-ts long format (unique_id, ds, y), validates the schema, aggregates duplicate (SKU, date) rows, and fills calendar gaps with zero demand — for perishables a missing day means "no sales", not "missing data".

Raw CSVs live under data/perishables/ which is gitignored.

ColumnMapping dataclass

Maps source CSV column names to canonical polars-ts columns.

Parameters

sku Source column identifying the product (mapped to unique_id). date Source column with the sale date (mapped to ds). quantity Source column with units sold (mapped to y). category Optional product category/family column, kept as category. Critical for cold-start borrowing across similar SKUs. price Optional unit-price column, kept as price. promo Optional promotion-flag column, kept as promo.

required()

Return the mandatory source-to-canonical rename mapping.

optional()

Return the optional source-to-canonical rename mapping.

validate_sales_frame(df, mapping=None)

Validate a raw sales frame against a column mapping.

Parameters

df Raw sales DataFrame (source column names). mapping Column mapping; defaults to ColumnMapping().

Raises

ValueError If mapped columns are missing, dates contain nulls, or the quantity column is not numeric.

fill_missing_dates(df, freq='1d', id_col='unique_id', time_col='ds', target_col='y')

Fill calendar gaps per SKU with zero demand.

Each SKU's calendar runs from its own first sale (its launch) to the global last date, so new SKUs are not padded with pre-launch zeros. Static columns (category) are re-attached; promo gaps become 0 and price gaps are forward/backward filled within each SKU.

Parameters

df Canonical sales frame. freq Polars interval string for the calendar grid. id_col, time_col, target_col Canonical column names.

Returns

pl.DataFrame Gap-free frame sorted by (id_col, time_col).

load_sales_csv(source, mapping=None, *, fill_gaps=True, freq='1d', clip_negative=True)

Load a perishables sales CSV into canonical long format.

Parameters

source CSV path, or an already-parsed DataFrame (useful for tests and multi-file concatenation done upstream). mapping Source column mapping; defaults to ColumnMapping(). fill_gaps Fill per-SKU calendar gaps with zero demand. freq Calendar interval used when fill_gaps is enabled. clip_negative Clip negative quantities (returns/corrections) to zero so they do not distort demand models.

Returns

pl.DataFrame Columns [unique_id, ds, y] plus any mapped optional columns, one row per SKU per period, sorted by (unique_id, ds).