Skip to content

Reconciliation

polars_ts.reconciliation

Forecast reconciliation for hierarchical time series. Closes #55.

_normalize_hierarchy(hierarchy)

Convert tree dict[str, str] to grouped dict[str, list[str]].

_to_tree(hierarchy)

Convert grouped hierarchy back to tree (raises if not a tree).

_is_tree(hierarchy)

Check if all nodes have exactly one parent.

reconcile(df, hierarchy, method='bottom_up', forecast_col='y_hat', id_col='unique_id', time_col='ds', *, middle_level=None, residuals=None, train_data=None, n_folds=5, interval_cols=None)

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(s). For tree hierarchies use dict[str, str]; for grouped/cross-sectional hierarchies use dict[str, list[str]] where a bottom node can map to multiple aggregate parents. method Reconciliation method: "bottom_up", "top_down", "ols" (MinTrace-OLS), "middle_out", "permbu", or "mint_cv" (MinTrace with cross-validation). forecast_col Column with forecast values. id_col Column identifying each node in the hierarchy. time_col Column with timestamps. middle_level Node names for the anchor level (required for "middle_out"). residuals DataFrame with columns [id_col, time_col, "residual"] containing historical forecast residuals (required for "permbu"). train_data Historical forecasts for cross-validation (required for "mint_cv"). n_folds Number of CV folds for "mint_cv" (default 5). interval_cols Column names for prediction intervals (e.g. ["y_lower", "y_upper"]). When provided, each interval column is reconciled independently using the same projection matrix as the point forecasts.

Returns

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

_get_bottom_nodes_tree(hierarchy)

Return leaf nodes for a tree hierarchy.

_get_bottom_nodes_grouped(hierarchy)

Return leaf nodes for a grouped hierarchy.

_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.

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

Bottom-up for grouped hierarchies using the summing matrix.

Keeps bottom-level forecasts and recomputes all aggregates via S matrix.

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

Disaggregate top-level forecast using historical proportions.

_build_summing_matrix(hierarchy)

Build the summing matrix S for tree or grouped hierarchies.

For grouped hierarchies (DAGs), traces all ancestor paths from each bottom node via BFS, handling nodes with multiple parents.

_apply_projection(df, P, all_nodes, node_idx, forecast_col, id_col, time_col, extra_cols=None)

Apply projection matrix P to forecasts, optionally to extra columns too.

_ols(df, hierarchy, forecast_col, id_col, time_col, *, interval_cols=None)

MinTrace-OLS reconciliation.

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

_middle_out(df, hierarchy, forecast_col, id_col, time_col, middle_level)

Middle-out reconciliation: anchor at intermediate level.

Below the middle level: disaggregate using historical proportions. Above the middle level: aggregate by summing children.

_permbu(df, hierarchy, forecast_col, id_col, time_col, residuals)

PERMBU: Projection-based Empirical Residual MinTrace Bottom-Up.

Uses empirical residual covariance to weight the MinTrace reconciliation, producing a shrinkage estimator between OLS and sample-covariance MinTrace.

_mint_cv(df, hierarchy, forecast_col, id_col, time_col, train_data, n_folds)

MinTrace with cross-validation for covariance estimation.

Splits train_data into folds, computes in-sample residuals per fold, and averages the resulting covariance matrices for a robust W estimate.