hierarchicalforecast

What it is and what it does

HierarchicalForecast provides reconciliation methods for time-series forecasts organized in hierarchical structures—such as geographical regions, product categories, or temporal aggregations (weeks, months, years). It takes base forecasts and enforces coherence across hierarchy levels so that predictions at different aggregation levels remain mathematically consistent. The package includes classic methods like BottomUp and TopDown, alternative approaches like MinTrace and MiddleOut, and probabilistic methods such as Normality, Bootstrap, and PERMBU that generate coherent prediction intervals.

The library is designed for practitioners who need coherent forecasts across multiple organizational or temporal levels for consistent decision-making. It integrates with the broader forecasting ecosystem and provides evaluation tools to measure reconciliation quality. The package depends on standard scientific Python libraries (numpy, pandas, scikit-learn, matplotlib) and specialized tools like narwhals for dataframe abstraction and qpsolvers for optimization.

Use it for:

• Reconcile sales forecasts across product hierarchies (brand → category → SKU) to ensure consistency in inventory planning.
• Enforce temporal coherence in forecasts across different time aggregations (daily → weekly → monthly) for supply-chain alignment.
• Generate probabilistic coherent forecasts with valid prediction intervals using Bootstrap or Normality methods for risk assessment.
• Combine independent forecasts from multiple models at different hierarchy levels and reconcile them into a coherent forecast.
• Evaluate and benchmark reconciliation methods on hierarchical datasets using built-in evaluation metrics.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Reconciles hierarchical time-series forecasts across multiple levels of aggregation using statistical and probabilistic methods to ensure coherent predictions.

Yes. Active maintenance, permissive license, and no known vulnerabilities make it a reliable choice. Medium install friction is acceptable given the specialized nature of hierarchical forecasting. Install if you need to enforce coherence across hierarchical time-series forecasts; skip if your forecasts are flat or non-hierarchical.

Install

hierarchicalforecast on PyPI

pip install hierarchicalforecast

uv add hierarchicalforecast

poetry add hierarchicalforecast

Installing hierarchicalforecast

Before you install

Medium install friction with 7 runtime dependencies including numpy, pandas, and scikit-learn. Active maintenance with recent release and repository activity. Supports Python 3.10–3.14 with pre-built wheels across macOS, Linux, and Windows.

License in practice

Apache Software License 2.0 is permissive, allowing commercial use, modification, and distribution with minimal restrictions. Suitable for most production and research applications.

Quickstart

pip install hierarchicalforecast

from hierarchicalforecast.core import HierarchicalReconciliation
from hierarchicalforecast.methods import BottomUp, TopDown

reconcilers = [BottomUp(), TopDown(method='forecast_proportions')]
hrec = HierarchicalReconciliation(reconcilers=reconcilers)
Y_rec_df = hrec.reconcile(Y_hat_df=Y_hat_df, Y_df=Y_train_df, S_df=S_df, tags=tags)

Requires base forecasts (Y_hat_df) and a hierarchy structure (S_df, tags) as input; typically used downstream of a forecasting model.

Verify before relying

• Performance characteristics and reconciliation accuracy across different hierarchy sizes and depths.
• Whether the package handles missing values or irregular time-series structures automatically.
• Scalability limits for very large hierarchies or high-frequency data.
• Monthly download volume and adoption metrics beyond repository stars.

Package facts

Evidence: hierarchicalforecast-1.5.1-cp310-cp310-macosx_14_0_arm64.whl; hierarchicalforecast-1.5.1-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; hierarchicalforecast-1.5.1-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; hierarchicalforecast-1.5.1-cp310-cp310-win_amd64.whl; hierarchicalforecast-1.5.1-cp311-cp311-macosx_14_0_arm64.whl; hierarchicalforecast-1.5.1-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; hierarchicalforecast-1.5.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; hierarchicalforecast-1.5.1-cp311-cp311-win_amd64.whl; hierarchicalforecast-1.5.1-cp312-cp312-macosx_14_0_arm64.whl; hierarchicalforecast-1.5.1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; hierarchicalforecast-1.5.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; hierarchicalforecast-1.5.1-cp312-cp312-win_amd64.whl; hierarchicalforecast-1.5.1-cp313-cp313-macosx_14_0_arm64.whl; hierarchicalforecast-1.5.1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; hierarchicalforecast-1.5.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; hierarchicalforecast-1.5.1-cp313-cp313-win_amd64.whl; hierarchicalforecast-1.5.1-cp314-cp314-macosx_14_0_arm64.whl; hierarchicalforecast-1.5.1-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; hierarchicalforecast-1.5.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; hierarchicalforecast-1.5.1-cp314-cp314-win_amd64.whl

Keywords: time-series, forecasting, datasets, hierarchical

Tags

More Scientific/Engineering packages

Further reading