https://github.com/nixtla/hierarchicalforecast

Probabilistic Hierarchical forecasting 👑 with statistical and econometric methods.

Science Score: 36.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
✓
Academic publication links
Links to: arxiv.org
○
Committers with academic emails
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (10.6%) to scientific vocabulary

Keywords

baselines bottomup coherent econometrics erm forecasting forecasting-models hierarchical hierarchical-forecast middleout mint permbu probabilistic-models python reconciliation statistics time-series time-series-forecasting timeseries topdown

Keywords from Contributors

automl nhits nbeatsx nbeats hint hierarchical-forecasting esrnn deepar deep-neural-networks baselines-zoo

Last synced: 5 months ago · JSON representation

Repository

Probabilistic Hierarchical forecasting 👑 with statistical and econometric methods.

Basic Info

Host: GitHub
Owner: Nixtla
License: apache-2.0
Language: Python
Default Branch: main
Homepage: https://nixtlaverse.nixtla.io/hierarchicalforecast
Size: 23.5 MB

Statistics

Stars: 692
Watchers: 11
Forks: 90
Open Issues: 12
Releases: 22

Topics

Created over 3 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Code of conduct

README.md

Nixtla

Hierarchical Forecast 👑

Probabilistic hierarchical forecasting with statistical and econometric methods

[![pytest](https://github.com/Nixtla/hierarchicalforecast/actions/workflows/pytest.yml/badge.svg)](https://github.com/Nixtla/hierarchicalforecast/actions/workflows/pytest.yml) [![Python](https://img.shields.io/pypi/pyversions/hierarchicalforecast)](https://pypi.org/project/hierarchicalforecast/) [![PyPi](https://img.shields.io/pypi/v/hierarchicalforecast?color=blue)](https://pypi.org/project/hierarchicalforecast/) [![conda-nixtla](https://img.shields.io/conda/vn/conda-forge/hierarchicalforecast?color=seagreen&label=conda)](https://anaconda.org/conda-forge/hierarchicalforecast) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/Nixtla/hierarchicalforecast/blob/main/LICENSE) **HierarchicalForecast** offers a collection of cross-sectional and temporal reconciliation methods, including `BottomUp`, `TopDown`, `MiddleOut`, `MinTrace` and `ERM`, as well as probabilistic coherent prediction methods such as `Normality`, `Bootstrap`, and `PERMBU`.

📚 Intro

A vast amount of time series datasets are organized into structures with different levels or hierarchies of aggregation. Examples include cross-sectional aggregations such as categories, brands, or geographical groupings, or temporal aggregations such as weeks, months or years. Coherent forecasts across levels are necessary for consistent decision-making and planning. Hierachical Forecast offers different reconciliation methods that render coherent forecasts across cross-sectional and temporal hierachies.

🎊 Features

Classic reconciliation methods:
- BottomUp: Simple addition to the upper levels.
- TopDown: Distributes the top levels forecasts trough the hierarchies.
Alternative reconciliation methods:
- MiddleOut: It anchors the base predictions in a middle level. The levels above the base predictions use the bottom-up approach, while the levels below use a top-down.
- MinTrace: Minimizes the total forecast variance of the space of coherent forecasts, with the Minimum Trace reconciliation.
- ERM: Optimizes the reconciliation matrix minimizing an L1 regularized objective.
Probabilistic coherent methods:
- Normality: Uses MinTrace variance-covariance closed form matrix under a normality assumption.
- Bootstrap: Generates distribution of hierarchically reconciled predictions using Gamakumara's bootstrap approach.
- PERMBU: Reconciles independent sample predictions by reinjecting multivariate dependence with estimated rank permutation copulas, and performing a Bottom-Up aggregation.
Temporal reconciliation methods:
- All reconciliation methods (except for the insample methods) are available to use with temporal hierarchies too.

Missing something? Please open an issue here or write us in

📖 Why?

Short: We want to contribute to the ML field by providing reliable baselines and benchmarks for hierarchical forecasting task in industry and academia. Here's the complete paper.

Verbose: HierarchicalForecast integrates publicly available processed datasets, evaluation metrics, and a curated set of standard statistical baselines. In this library we provide usage examples and references to extensive experiments where we showcase the baseline's use and evaluate the accuracy of their predictions. With this work, we hope to contribute to Machine Learning forecasting by bridging the gap to statistical and econometric modeling, as well as providing tools for the development of novel hierarchical forecasting algorithms rooted in a thorough comparison of these well-established models. We intend to continue maintaining and increasing the repository, promoting collaboration across the forecasting community.

💻 Installation

We recommend using uv as Python package manager, for which you can find installation instructions here. You can then install HierarchicalForecast with:

python uv pip install hierarchicalforecast

Alternatively, you can use the Python package index pip directly:

python pip install hierarchicalforecast

🧬 How to use

The following example needs statsforecast and datasetsforecast as additional packages. If not installed, install it via your preferred method, e.g. pip install statsforecast datasetsforecast. The datasetsforecast library allows us to download hierarhical datasets and we will use statsforecast to compute the base forecasts to be reconciled.

You can open a complete example in Colab

Minimal Example: ```python

!pip install -U numba statsforecast datasetsforecast

import numpy as np import pandas as pd

obtain hierarchical dataset

from datasetsforecast.hierarchical import HierarchicalData

compute base forecast no coherent

from statsforecast.core import StatsForecast from statsforecast.models import AutoARIMA, Naive

obtain hierarchical reconciliation methods and evaluation

from hierarchicalforecast.core import HierarchicalReconciliation from hierarchicalforecast.evaluation import evaluate from hierarchicalforecast.methods import BottomUp, TopDown, MiddleOut from utilsforecast.losses import mse

Load TourismSmall dataset

Ydf, Sdf, tags = HierarchicalData.load('./data', 'TourismSmall') Ydf['ds'] = pd.todatetime(Ydf['ds']) Sdf = Sdf.resetindex(names="unique_id")

split train/test sets

Ytestdf = Ydf.groupby('uniqueid').tail(4) Ytraindf = Ydf.drop(Ytest_df.index)

Compute base auto-ARIMA predictions

fcst = StatsForecast(models=[AutoARIMA(seasonlength=4), Naive()], freq='QE', njobs=-1) Yhatdf = fcst.forecast(df=Ytraindf, h=4)

Reconcile the base predictions

reconcilers = [ BottomUp(), TopDown(method='forecastproportions'), MiddleOut(middlelevel='Country/Purpose/State', topdownmethod='forecastproportions') ] hrec = HierarchicalReconciliation(reconcilers=reconcilers) Yrecdf = hrec.reconcile(Yhatdf=Yhatdf, Ydf=Ytraindf, Sdf=Sdf, tags=tags) ```

Evaluation

Assumes you have a test dataframe.

python df = Y_rec_df.merge(Y_test_df, on=['unique_id', 'ds']) evaluation = evaluate(df = df, tags = tags, metrics = [mse], benchmark = "Naive")

📖 Documentation

Here is a link to the documentation.

📃 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🏟 HTS projects

In the R ecosystem, we recommend checking out fable, and the now-retired hts. In Python we want to acknowledge the following libraries hiere2e, hierts, sktime, darts, pyhts, scikit-hts.

📚 References and Acknowledgements

This work is highly influenced by the fantastic work of previous contributors and other scholars who previously proposed the reconciliation methods presented here. We want to highlight the work of Rob Hyndman, George Athanasopoulos, Shanika L. Wickramasuriya, Souhaib Ben Taieb, and Bonsoo Koo. For a full reference link, please visit the Reference section of this paper. We encourage users to explore this literature review.

🙏 How to cite

If you enjoy or benefit from using these Python implementations, a citation to this hierarchical forecasting reference paper will be greatly appreciated. bibtex @article{olivares2024hierarchicalforecastreferenceframeworkhierarchical, title={HierarchicalForecast: A Reference Framework for Hierarchical Forecasting in Python}, author={Kin G. Olivares and Azul Garza and David Luo and Cristian Challú and Max Mergenthaler and Souhaib Ben Taieb and Shanika L. Wickramasuriya and Artur Dubrawski}, year={2024}, eprint={2207.03517}, archivePrefix={arXiv}, primaryClass={stat.ML}, url={https://arxiv.org/abs/2207.03517}, }

Owner

Name: Nixtla
Login: Nixtla
Kind: organization
Email: ops@nixtla.io
Location: United States of America

Website: https://www.nixtla.io/
Twitter: nixtlainc
Repositories: 13
Profile: https://github.com/Nixtla

Open Source Time Series Ecosystem

GitHub Events

Total

Create event: 44
Issues event: 75
Release event: 5
Watch event: 105
Delete event: 34
Member event: 1
Issue comment event: 184
Push event: 243
Pull request event: 100
Pull request review event: 159
Pull request review comment event: 132
Fork event: 12

Last Year

Create event: 44
Issues event: 75
Release event: 5
Watch event: 105
Delete event: 34
Member event: 1
Issue comment event: 184
Push event: 243
Pull request event: 100
Pull request review event: 159
Pull request review comment event: 132
Fork event: 12

Committers

Last synced: about 2 years ago

All Time

Total Commits: 327
Total Committers: 13
Avg Commits per committer: 25.154
Development Distribution Score (DDS): 0.388

Past Year

Commits: 45
Committers: 11
Avg Commits per committer: 4.091
Development Distribution Score (DDS): 0.667

Top Committers

Name	Email	Commits
FedericoGarza	f**z@g**m	200
Kin	k**s@g**m	80
José Morales	j**2@g**m	15
mergenthaler	m**m@g**m	12
David Luo	d**f@g**m	6
David Luo	6****o	4
mcsqr	1****r	3
Nick To	n****o	2
Cristian	c**u@g**m	1
Hahnbee Lee	5****e	1
Pedro Mercado	3****o	1
Ronan McCarter	6****r	1
Sugato Ray	s****y	1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 117
Total pull requests: 183
Average time to close issues: 7 months
Average time to close pull requests: 12 days
Total issue authors: 55
Total pull request authors: 27
Average comments per issue: 2.2
Average comments per pull request: 1.41
Merged pull requests: 148
Bot issues: 0
Bot pull requests: 18

Past Year

Issues: 29
Pull requests: 85
Average time to close issues: 19 days
Average time to close pull requests: 10 days
Issue authors: 17
Pull request authors: 12
Average comments per issue: 2.45
Average comments per pull request: 1.46
Merged pull requests: 70
Bot issues: 0
Bot pull requests: 18

View more stats

Top Authors

Issue Authors

kdgutier (20)
Grogu1992 (6)
iamyihwa (5)
FedericoGarza (5)
AzulGarza (5)
candalfigomoro (5)
macarw (5)
ngupta23 (4)
baniasbaabe (4)
melopeo (3)
elephaint (3)
tbellamey (3)
dluuo (2)
vinaybridge (2)
mattbuot (2)

Pull Request Authors

elephaint (59)
kdgutier (36)
dependabot[bot] (29)
FedericoGarza (21)
jmoralez (11)
christophertitchen (11)
mergenthaler (7)
dluuo (5)
christopher-titchen (5)
KuriaMaingi (5)
mcsqr (4)
janrth (2)
DManowitz (2)
tracykteal (2)
mattbuot (2)

Top Labels

Issue Labels

bug (33) enhancement (19) feature (12) awaiting response (8) documentation (7) 🔥 urgent bug (3) fix (3) refactor (1) discussion (1) question (1)

Pull Request Labels

dependencies (33) feature (12) documentation (10) enhancement (5) fix (5) github_actions (4) bug (3) breaking change (2) refactor (1)

Packages

Total packages: 2
Total downloads:
- pypi 222,509 last-month

Total dependent packages: 5
(may contain duplicates)
Total dependent repositories: 48
(may contain duplicates)
Total versions: 23
Total maintainers: 3

pypi.org: hierarchicalforecast

Hierarchical Methods Time series forecasting

Homepage: https://github.com/Nixtla/hierarchicalforecast/
Documentation: https://hierarchicalforecast.readthedocs.io/
License: Apache Software License 2.0
Latest release: 1.2.1
published 11 months ago

Versions: 22
Dependent Packages: 5
Dependent Repositories: 48
Downloads: 222,509 Last month

Rankings

Dependent repos count: 2.1%

Downloads: 2.3%

Stargazers count: 3.2%

Average: 4.2%

Forks count: 5.9%

Dependent packages count: 7.3%

Maintainers (3)

fgarzar capybara MergenthalerMax

Last synced: 6 months ago

conda-forge.org: hierarchicalforecast

**HierarchicalForecast** offers a collection of reconciliation methods, including `BottomUp`, `TopDown`, `MiddleOut`, `MinTrace` and `ERM`. * Classic reconciliation methods: - `BottomUp`: Simple addition to the upper levels. - `TopDown`: Distributes the top levels forecasts trough the hierarchies. * Alternative reconciliation methods: - `MiddleOut`: It anchors the base predictions in a middle level. The levels above the base predictions use the bottom-up approach, while the levels below use a top-down. - `MinTrace`: Minimizes the total forecast variance of the space of coherent forecasts, with the Minimum Trace reconciliation. - `ERM`: Optimizes the reconciliation matrix minimizing an L1 regularized objective. PyPI: [https://pypi.org/project/hierarchicalforecast/](https://pypi.org/project/hierarchicalforecast/)

Homepage: https://github.com/Nixtla/hierarchicalforecast/tree/main/
License: Apache-2.0
Latest release: 0.0.6
published over 3 years ago

Versions: 1
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Stargazers count: 21.7%

Forks count: 28.5%

Average: 33.9%

Dependent repos count: 34.0%

Dependent packages count: 51.2%

Last synced: 6 months ago

Dependencies

.github/workflows/ci.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
mamba-org/provision-with-micromamba main composite

.github/workflows/python-publish.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite
pypa/gh-action-pypi-publish 27b31702a0e7fc50959f5ad993c78deac1bdfc29 composite

action_files/test_models/requirements.txt pypi

datasetsforecast * test
fire * test

.github/workflows/build-docs.yaml actions

actions/checkout v3 composite
actions/setup-python v4 composite
peaceiris/actions-gh-pages v3 composite

.github/workflows/no-response.yaml actions

lee-dohm/no-response v0.5.0 composite

.github/workflows/selfassign.yml actions

experiments/libs-comparison/environment.yml conda

fire
jupyterlab
pip 20.3.3
python 3.7.*
r-base 3.6.3
r-fable
r-forecast
r-furrr
r-future
r-future.apply
r-tidyverse
r-tsibble
r-tsibbledata
r-urca

environment.yml pypi

nbdev *

experiments/hierarchical_baselines/environment.yml pypi

hierarchicalforecast *
statsforecast *

setup.py pypi