{"id":7287,"library":"hierarchicalforecast","title":"Hierarchical Forecast","description":"HierarchicalForecast, currently at version 1.5.1, is a Python library offering a comprehensive collection of cross-sectional and temporal reconciliation methods for hierarchical time series forecasting. It provides various reconciliation techniques, including BottomUp, TopDown, MiddleOut, MinTrace, and ERM, as well as probabilistic coherent prediction methods like Normality, Bootstrap, and Conformal. The library is actively maintained with regular releases and focuses on bridging the gap between statistical modeling and machine learning in time series analysis.","status":"active","version":"1.5.1","language":"en","source_language":"en","source_url":"https://github.com/Nixtla/hierarchicalforecast/","tags":["time-series","forecasting","hierarchical","reconciliation","machine-learning","python"],"install":[{"cmd":"pip install hierarchicalforecast","lang":"bash","label":"PyPI (recommended)"},{"cmd":"conda install -c conda-forge hierarchicalforecast","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Numerical operations","package":"numpy"},{"reason":"Data manipulation","package":"pandas"},{"reason":"Scientific computing","package":"scipy"},{"reason":"Performance optimization (deprecated for C++ in v1.5.0, but still a dependency for older features)","package":"numba"},{"reason":"Numba integration with SciPy","package":"numba-scipy"},{"reason":"Commonly used for generating base forecasts in examples and practical applications, not a strict runtime dependency but highly recommended for typical usage.","package":"statsforecast","optional":true},{"reason":"Used for loading example hierarchical datasets in quickstarts and tutorials.","package":"datasetsforecast","optional":true}],"imports":[{"symbol":"HierarchicalReconciliation","correct":"from hierarchicalforecast.reconciliation import HierarchicalReconciliation"},{"symbol":"BottomUp","correct":"from hierarchicalforecast.methods import BottomUp"},{"symbol":"TopDown","correct":"from hierarchicalforecast.methods import TopDown"},{"symbol":"MinTrace","correct":"from hierarchicalforecast.methods import MinTrace"},{"note":"The core class is within the 'core' submodule.","wrong":"from hierarchicalforecast import HierarchicalForecast","symbol":"HierarchicalForecast","correct":"from hierarchicalforecast.core import HierarchicalForecast"}],"quickstart":{"code":"import pandas as pd\nfrom statsforecast import StatsForecast\nfrom statsforecast.models import Naive\nfrom hierarchicalforecast.reconciliation import HierarchicalReconciliation\nfrom hierarchicalforecast.methods import BottomUp, TopDown, MinTrace\n\n# Dummy hierarchical data (replace with datasetsforecast.HierarchicalData.load for real data)\n# Y_df: DataFrame with 'unique_id', 'ds', 'y' columns\n# S_df: Summing matrix (DataFrame) for reconciliation\n# tags: Dictionary defining the hierarchy levels\n\n# Create dummy data for demonstration\nn_series = 5\nn_dates = 10\n\nunique_ids = [f'id_{i}' for i in range(n_series)]\nall_dates = pd.to_datetime(pd.date_range(start='2020-01-01', periods=n_dates, freq='D'))\n\n# Create Y_df (time series data)\nY_df = pd.DataFrame({\n    'unique_id': [uid for uid in unique_ids for _ in range(n_dates)],\n    'ds': list(all_dates) * n_series,\n    'y': [i * 10 + j + (k % 5) for i in range(n_series) for j in range(n_dates) for k in range(1)] # Simple increasing data\n})\n\n# Create S_df (summing matrix)\n# Example: A simple 2-level hierarchy: Total -> id_0, id_1, ..., id_N-1\nS_df = pd.DataFrame({\n    'unique_id': ['Total'] + unique_ids,\n    'Total': [1.0] * (n_series + 1)\n})\nfor i, uid in enumerate(unique_ids):\n    S_df[uid] = 0.0\n    S_df.loc[S_df['unique_id'] == uid, uid] = 1.0\n\ntags = {'Total': ['Total'], 'Items': unique_ids}\n\n# 1. Generate base forecasts using StatsForecast\n# (Requires `pip install statsforecast`)\nsf = StatsForecast(models=[Naive()], freq='D')\nfcst_df = sf.predict(Y_df, h=3)\n\n# 2. Reconcile forecasts\nreconcilers = [\n    BottomUp(),\n    TopDown(method='forecast_proportions'), # Or 'average_proportions', 'simple_average'\n    MinTrace(method='ols') # Or 'wls_var', 'wls_struct', 'mint_shrink'\n]\n\nhrec = HierarchicalReconciliation(reconcilers=reconcilers, S=S_df, tags=tags)\nreconciled_fcst_df = hrec.reconcile(fcst_df=fcst_df, Y_df=Y_df)\n\nprint(\"Original Forecasts:\")\nprint(fcst_df.head())\nprint(\"\\nReconciled Forecasts (BottomUp, TopDown, MinTrace):\")\nprint(reconciled_fcst_df.head())\n\n# Verify coherence for 'Total' (simple check)\n# Note: This is a simplified check. Full coherence verification requires more logic.\nif 'Total' in reconciled_fcst_df['unique_id'].values:\n    total_forecast_bottomup = reconciled_fcst_df[reconciled_fcst_df['unique_id'] == 'Total']['Naive/BottomUp'].iloc[0]\n    sum_items_bottomup = reconciled_fcst_df[reconciled_fcst_df['unique_id'].isin(unique_ids)]['Naive/BottomUp'].sum()\n    print(f\"\\nBottomUp Coherence Check: Total={total_forecast_bottomup}, Sum of Items={sum_items_bottomup}\")\n    assert abs(total_forecast_bottomup - sum_items_bottomup) < 1e-6, \"BottomUp reconciliation failed coherence check!\"\n","lang":"python","description":"This quickstart demonstrates how to perform hierarchical reconciliation using `hierarchicalforecast`. It outlines the steps to generate base forecasts (using `StatsForecast` from the Nixtlaverse) and then apply various reconciliation methods like BottomUp, TopDown, and MinTrace to ensure coherence across different levels of a hierarchy. The example includes the necessary data structures: `Y_df` (time series data), `S_df` (summing matrix), and `tags` (hierarchy definition). Note that `statsforecast` and `datasetsforecast` are commonly used alongside `hierarchicalforecast` and may need separate installation."},"warnings":[{"fix":"Ensure your input DataFrames (`Y_df`, `S_df`, `fcst_df`) have `unique_id` as a regular column. If your DataFrame is indexed by `unique_id`, call `.reset_index()` before passing it to `hierarchicalforecast` functions. This also applies to other Nixtlaverse libraries.","message":"As of v1.0.0, the `unique_id` column is no longer supported as a DataFrame index for input data. It must be a regular column.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"No direct action required for existing code, but be aware that future versions might remove Numba dependencies. Performance-sensitive applications should leverage the latest versions and monitor for C++ optimization announcements.","message":"Numba-based implementations for some operations are being deprecated in favor of C++ for improved performance. While still functional, users are encouraged to rely on newer C++ optimized paths or future versions that may remove Numba.","severity":"deprecated","affected_versions":">=1.5.0"},{"fix":"Install these auxiliary libraries: `pip install statsforecast datasetsforecast`.","message":"To run the quickstart and most practical examples, `hierarchicalforecast` typically requires `statsforecast` for generating base forecasts and `datasetsforecast` for easily loading sample hierarchical datasets. These are not direct core dependencies but are essential for a complete forecasting pipeline.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Convert your `unique_id` index to a column using `.reset_index(names='unique_id')` or ensure a column named 'unique_id' exists in your DataFrame.","cause":"The input DataFrame (e.g., `Y_df`, `fcst_df`, `S_df`) is indexed by the unique_id or lacks a 'unique_id' column entirely, which is no longer supported as of v1.0.0.","error":"ValueError: unique_id column not found. The input dataframe must contain a unique_id column."},{"fix":"Apply one of the reconciliation methods provided by `hierarchicalforecast.reconciliation.HierarchicalReconciliation`. For example, use `BottomUp`, `TopDown`, or `MinTrace` methods to enforce coherence across the hierarchy.","cause":"Base forecasts are generated independently for each series in the hierarchy without enforcing aggregation constraints, leading to inconsistencies.","error":"The forecasts are not coherent (e.g., sums of lower levels do not match higher levels)."},{"fix":"Install the `statsforecast` library: `pip install statsforecast`.","cause":"The quickstart or examples rely on `statsforecast` to generate base forecasts, but the package is not installed.","error":"ModuleNotFoundError: No module named 'statsforecast'"}]}