Reconciliation

polars_ts.reconciliation

Forecast reconciliation for hierarchical time series. Closes #55.

reconcile(df, hierarchy, method='bottom_up', forecast_col='y_hat', id_col='unique_id', time_col='ds')

Reconcile forecasts across a hierarchy so they sum coherently.

Parameters

df DataFrame with forecasts at all levels, identified by id_col. hierarchy Mapping from child node to parent node (e.g. {"product_A": "category_1", "product_B": "category_1", "category_1": "total"}). method Reconciliation method: "bottom_up", "top_down", or "ols" (MinTrace-OLS). forecast_col Column with forecast values. id_col Column identifying each node in the hierarchy. time_col Column with timestamps.

Returns

pl.DataFrame Reconciled forecasts with the same schema as df.

_get_bottom_nodes(hierarchy)

Return nodes that are not parents of anything (leaf nodes).

_get_top_node(hierarchy)

Return the root node (parent that is not a child of anything).

_get_children(hierarchy, parent)

Return direct children of a parent node.

_bottom_up(df, hierarchy, forecast_col, id_col, time_col)

Aggregate bottom-level forecasts upward.

_top_down(df, hierarchy, forecast_col, id_col, time_col)

Disaggregate top-level forecast using historical proportions.

_ols(df, hierarchy, forecast_col, id_col, time_col)

MinTrace-OLS reconciliation.

Computes reconciled forecasts as: y_tilde = S @ (S'S)^{-1} @ S' @ y_hat where S is the summing matrix.