# Nixtla [](https://join.slack.com/t/nixtlacommunity/shared_invite/zt-1pmhan9j5-F54XR20edHk0UtYAPcW4KQ)
<div align="center">
<img src="https://raw.githubusercontent.com/Nixtla/neuralforecast/main/nbs/imgs_indx/logo_mid.png">
<h1 align="center">Hierarchical Forecast 👑</h1>
<h3 align="center">Probabilistic hierarchical forecasting with statistical and econometric methods</h3>
[](https://github.com/Nixtla/hierarchicalforecast/actions/workflows/ci.yml)
[](https://pypi.org/project/hierarchicalforecast/)
[](https://pypi.org/project/hierarchicalforecast/)
[](https://anaconda.org/conda-forge/hierarchicalforecast)
[](https://github.com/Nixtla/hierarchicalforecast/blob/main/LICENSE)
**HierarchicalForecast** offers a collection of reconciliation methods, including `BottomUp`, `TopDown`, `MiddleOut`, `MinTrace` and `ERM`. And Probabilistic coherent predictions including `Normality`, `Bootstrap`, and `PERMBU`.
</div>
## 📚 Intro
A vast amount of time series datasets are organized into structures with different levels or hierarchies of aggregation. Examples include categories, brands, or geographical groupings. Coherent forecasts across levels are necessary for consistent decision-making and planning. Hierachical Forecast offers differnt reconciliation methods that render coherent forecasts across hierachies.
Until recent, this methods were mainly avaiable in the R ecosystem. This Python-based framework aims to bridge the gap between statistical modeling and Machine Learning in the time series field.
## 🎊 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.
Missing something? Please open an issue here or write us in [](https://join.slack.com/t/nixtlaworkspace/shared_invite/zt-135dssye9-fWTzMpv2WBthq8NK0Yvu6A)
## 📖 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](https://arxiv.org/abs/2207.03517).
**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
You can install `HierarchicalForecast`'s the Python package index [pip](https://pypi.org) with:
```python
pip install hierarchicalforecast
```
You can also can install `HierarchicalForecast`'s from [conda](https://anaconda.org) with:
```python
conda install -c conda-forge 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 [](https://colab.research.google.com/github/nixtla/hierarchicalforecast/blob/main/nbs/examples/TourismSmall.ipynb)
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 HierarchicalEvaluation
from hierarchicalforecast.methods import BottomUp, TopDown, MiddleOut
# Load TourismSmall dataset
Y_df, S, tags = HierarchicalData.load('./data', 'TourismSmall')
Y_df['ds'] = pd.to_datetime(Y_df['ds'])
#split train/test sets
Y_test_df = Y_df.groupby('unique_id').tail(4)
Y_train_df = Y_df.drop(Y_test_df.index)
# Compute base auto-ARIMA predictions
fcst = StatsForecast(df=Y_train_df,
models=[AutoARIMA(season_length=4), Naive()],
freq='Q', n_jobs=-1)
Y_hat_df = fcst.forecast(h=4)
# Reconcile the base predictions
reconcilers = [
BottomUp(),
TopDown(method='forecast_proportions'),
MiddleOut(middle_level='Country/Purpose/State',
top_down_method='forecast_proportions')
]
hrec = HierarchicalReconciliation(reconcilers=reconcilers)
Y_rec_df = hrec.reconcile(Y_hat_df=Y_hat_df, Y_df=Y_train_df,
S=S, tags=tags)
```
### Evaluation
Assumes you have a test dataframe.
```python
def mse(y, y_hat):
return np.mean((y-y_hat)**2)
evaluator = HierarchicalEvaluation(evaluators=[mse])
evaluator.evaluate(Y_hat_df=Y_rec_df, Y_test=Y_test_df.set_index('unique_id'),
tags=tags, benchmark='Naive')
```
## 📖 Documentation (WIP)
Here is a link to the [documentation](https://nixtla.github.io/hierarchicalforecast/).
## 📃 License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/Nixtla/neuralforecast/blob/main/LICENSE) file for details.
## 🏟 HTS projects
In the R ecosystem, we recommend checking out [fable](http://fable.tidyverts.org/), and the now-retired [hts](https://github.com/earowang/hts).
In Python we want to acknowledge the following libraries [hiere2e](https://github.com/rshyamsundar/gluonts-hierarchical-ICML-2021), [sktime](https://github.com/sktime/sktime-tutorial-pydata-berlin-2022), [darts](https://github.com/unit8co/darts), [pyhts](https://github.com/AngelPone/pyhts), [scikit-hts](https://github.com/carlomazzaferro/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](https://arxiv.org/pdf/2207.03517.pdf).
We encourage users to explore this [literature review](https://otexts.com/fpp3/hierarchical-reading.html).
## 🙏 How to cite
If you enjoy or benefit from using these Python implementations, a citation to this [hierarchical forecasting reference paper](https://arxiv.org/abs/2207.03517) will be greatly appreciated.
```bibtex
@article{olivares2022hierarchicalforecast,
author = {Kin G. Olivares and
Federico Garza and
David Luo and
Cristian Challú and
Max Mergenthaler and
Souhaib Ben Taieb and
Shanika L. Wickramasuriya and
Artur Dubrawski},
title = {{HierarchicalForecast}: A Reference Framework for Hierarchical Forecasting in Python},
journal = {Work in progress paper, submitted to Journal of Machine Learning Research.},
volume = {abs/2207.03517},
year = {2022},
url = {https://arxiv.org/abs/2207.03517},
archivePrefix = {arXiv}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Nixtla/hierarchicalforecast/",
"name": "hierarchicalforecast",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "time-series forecasting datasets hierarchical",
"author": "Nixtla",
"author_email": "business@nixtla.io",
"download_url": "https://files.pythonhosted.org/packages/38/84/8ed2f8116dc386f298393a63f7ef38df9789ef342a9e17d8a6c7b3e818f3/hierarchicalforecast-0.4.1.tar.gz",
"platform": null,
"description": "# Nixtla [](https://join.slack.com/t/nixtlacommunity/shared_invite/zt-1pmhan9j5-F54XR20edHk0UtYAPcW4KQ)\n\n<div align=\"center\">\n<img src=\"https://raw.githubusercontent.com/Nixtla/neuralforecast/main/nbs/imgs_indx/logo_mid.png\">\n<h1 align=\"center\">Hierarchical Forecast \ud83d\udc51</h1>\n<h3 align=\"center\">Probabilistic hierarchical forecasting with statistical and econometric methods</h3>\n \n[](https://github.com/Nixtla/hierarchicalforecast/actions/workflows/ci.yml)\n[](https://pypi.org/project/hierarchicalforecast/)\n[](https://pypi.org/project/hierarchicalforecast/)\n[](https://anaconda.org/conda-forge/hierarchicalforecast)\n[](https://github.com/Nixtla/hierarchicalforecast/blob/main/LICENSE)\n \n**HierarchicalForecast** offers a collection of reconciliation methods, including `BottomUp`, `TopDown`, `MiddleOut`, `MinTrace` and `ERM`. And Probabilistic coherent predictions including `Normality`, `Bootstrap`, and `PERMBU`.\n</div>\n\n## \ud83d\udcda Intro\nA vast amount of time series datasets are organized into structures with different levels or hierarchies of aggregation. Examples include categories, brands, or geographical groupings. Coherent forecasts across levels are necessary for consistent decision-making and planning. Hierachical Forecast offers differnt reconciliation methods that render coherent forecasts across hierachies. \nUntil recent, this methods were mainly avaiable in the R ecosystem. This Python-based framework aims to bridge the gap between statistical modeling and Machine Learning in the time series field.\n\n## \ud83c\udf8a Features \n\n* Classic reconciliation methods:\n - `BottomUp`: Simple addition to the upper levels.\n - `TopDown`: Distributes the top levels forecasts trough the hierarchies.\n* Alternative reconciliation methods:\n - `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.\n - `MinTrace`: Minimizes the total forecast variance of the space of coherent forecasts, with the Minimum Trace reconciliation.\n - `ERM`: Optimizes the reconciliation matrix minimizing an L1 regularized objective.\n* Probabilistic coherent methods:\n - `Normality`: Uses MinTrace variance-covariance closed form matrix under a normality assumption.\n - `Bootstrap`: Generates distribution of hierarchically reconciled predictions using Gamakumara's bootstrap approach.\n - `PERMBU`: Reconciles independent sample predictions by reinjecting multivariate dependence with estimated rank permutation copulas, and performing a Bottom-Up aggregation.\n\nMissing something? Please open an issue here or write us in [](https://join.slack.com/t/nixtlaworkspace/shared_invite/zt-135dssye9-fWTzMpv2WBthq8NK0Yvu6A)\n\n## \ud83d\udcd6 Why? \n\n**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](https://arxiv.org/abs/2207.03517).\n\n**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.\n\n## \ud83d\udcbb Installation\n\nYou can install `HierarchicalForecast`'s the Python package index [pip](https://pypi.org) with:\n\n```python\npip install hierarchicalforecast\n```\n\nYou can also can install `HierarchicalForecast`'s from [conda](https://anaconda.org) with:\n\n```python\nconda install -c conda-forge hierarchicalforecast\n```\n\n\n## \ud83e\uddec How to use\n\nThe following example needs `statsforecast` and `datasetsforecast` as additional packages. If not installed, install it via your preferred method, e.g. `pip install statsforecast datasetsforecast`.\nThe `datasetsforecast` library allows us to download hierarhical datasets and we will use `statsforecast` to compute the base forecasts to be reconciled.\n\nYou can open a complete example in Colab [](https://colab.research.google.com/github/nixtla/hierarchicalforecast/blob/main/nbs/examples/TourismSmall.ipynb)\n\nMinimal Example:\n```python\n# !pip install -U numba statsforecast datasetsforecast\nimport numpy as np\nimport pandas as pd\n\n#obtain hierarchical dataset\nfrom datasetsforecast.hierarchical import HierarchicalData\n\n# compute base forecast no coherent\nfrom statsforecast.core import StatsForecast\nfrom statsforecast.models import AutoARIMA, Naive\n\n#obtain hierarchical reconciliation methods and evaluation\nfrom hierarchicalforecast.core import HierarchicalReconciliation\nfrom hierarchicalforecast.evaluation import HierarchicalEvaluation\nfrom hierarchicalforecast.methods import BottomUp, TopDown, MiddleOut\n\n\n# Load TourismSmall dataset\nY_df, S, tags = HierarchicalData.load('./data', 'TourismSmall')\nY_df['ds'] = pd.to_datetime(Y_df['ds'])\n\n#split train/test sets\nY_test_df = Y_df.groupby('unique_id').tail(4)\nY_train_df = Y_df.drop(Y_test_df.index)\n\n# Compute base auto-ARIMA predictions\nfcst = StatsForecast(df=Y_train_df,\n models=[AutoARIMA(season_length=4), Naive()],\n freq='Q', n_jobs=-1)\nY_hat_df = fcst.forecast(h=4)\n\n# Reconcile the base predictions\nreconcilers = [\n BottomUp(),\n TopDown(method='forecast_proportions'),\n MiddleOut(middle_level='Country/Purpose/State',\n top_down_method='forecast_proportions')\n]\nhrec = HierarchicalReconciliation(reconcilers=reconcilers)\nY_rec_df = hrec.reconcile(Y_hat_df=Y_hat_df, Y_df=Y_train_df,\n S=S, tags=tags)\n```\n\n### Evaluation\nAssumes you have a test dataframe.\n\n```python\ndef mse(y, y_hat):\n return np.mean((y-y_hat)**2)\n\nevaluator = HierarchicalEvaluation(evaluators=[mse])\nevaluator.evaluate(Y_hat_df=Y_rec_df, Y_test=Y_test_df.set_index('unique_id'),\n tags=tags, benchmark='Naive')\n```\n\n## \ud83d\udcd6 Documentation (WIP)\nHere is a link to the [documentation](https://nixtla.github.io/hierarchicalforecast/).\n\n## \ud83d\udcc3 License\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/Nixtla/neuralforecast/blob/main/LICENSE) file for details.\n\n## \ud83c\udfdf HTS projects\nIn the R ecosystem, we recommend checking out [fable](http://fable.tidyverts.org/), and the now-retired [hts](https://github.com/earowang/hts).\nIn Python we want to acknowledge the following libraries [hiere2e](https://github.com/rshyamsundar/gluonts-hierarchical-ICML-2021), [sktime](https://github.com/sktime/sktime-tutorial-pydata-berlin-2022), [darts](https://github.com/unit8co/darts), [pyhts](https://github.com/AngelPone/pyhts), [scikit-hts](https://github.com/carlomazzaferro/scikit-hts).\n\n## \ud83d\udcda References and Acknowledgements\nThis 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](https://arxiv.org/pdf/2207.03517.pdf).\nWe encourage users to explore this [literature review](https://otexts.com/fpp3/hierarchical-reading.html).\n\n## \ud83d\ude4f How to cite\nIf you enjoy or benefit from using these Python implementations, a citation to this [hierarchical forecasting reference paper](https://arxiv.org/abs/2207.03517) will be greatly appreciated.\n```bibtex\n@article{olivares2022hierarchicalforecast,\n author = {Kin G. Olivares and\n Federico Garza and \n David Luo and \n Cristian Chall\u00fa and\n Max Mergenthaler and\n Souhaib Ben Taieb and\n Shanika L. Wickramasuriya and\n Artur Dubrawski},\n title = {{HierarchicalForecast}: A Reference Framework for Hierarchical Forecasting in Python},\n journal = {Work in progress paper, submitted to Journal of Machine Learning Research.},\n volume = {abs/2207.03517},\n year = {2022},\n url = {https://arxiv.org/abs/2207.03517},\n archivePrefix = {arXiv}\n}\n```\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Hierarchical Methods Time series forecasting",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/Nixtla/hierarchicalforecast/"
},
"split_keywords": [
"time-series",
"forecasting",
"datasets",
"hierarchical"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dfc311a2b8936c4c6d867dcc591378bfc1422bd7265dab3193a0a7e190f1afbb",
"md5": "4f0f32d17bbdee21ccd07ab0b33ac138",
"sha256": "0167b80ba2bb5d6313cedd26bfb22a8cc56ee1efab18e32af655c507e80ba12d"
},
"downloads": -1,
"filename": "hierarchicalforecast-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4f0f32d17bbdee21ccd07ab0b33ac138",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 45079,
"upload_time": "2023-11-21T18:36:13",
"upload_time_iso_8601": "2023-11-21T18:36:13.751991Z",
"url": "https://files.pythonhosted.org/packages/df/c3/11a2b8936c4c6d867dcc591378bfc1422bd7265dab3193a0a7e190f1afbb/hierarchicalforecast-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "38848ed2f8116dc386f298393a63f7ef38df9789ef342a9e17d8a6c7b3e818f3",
"md5": "724e021dead03327b35b7e08cd57ba7c",
"sha256": "6add2a50f3536a7df045e28c366e72b8c71b5782cd477a95ad9f9821be886cc3"
},
"downloads": -1,
"filename": "hierarchicalforecast-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "724e021dead03327b35b7e08cd57ba7c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 47764,
"upload_time": "2023-11-21T18:36:16",
"upload_time_iso_8601": "2023-11-21T18:36:16.221375Z",
"url": "https://files.pythonhosted.org/packages/38/84/8ed2f8116dc386f298393a63f7ef38df9789ef342a9e17d8a6c7b3e818f3/hierarchicalforecast-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-21 18:36:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Nixtla",
"github_project": "hierarchicalforecast",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"lcname": "hierarchicalforecast"
}
JSON
