Package: hierarchicalforecast
NixtlaHierarchical Forecast 👑Probabilistic hierarchical forecasting with statistical and econometric methodsHierarchicalForecastoffers a collection of reconciliation methods, includingBottomUp,TopDown,MiddleOut,MinTraceandERM. And Probabilistic coherent predictions includingNormality,Bootstrap, andPERMBU.📚 IntroA 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.🎊 FeaturesClassic 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📖 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 completepaper.Verbose:HierarchicalForecastintegrates 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.💻 InstallationYou can installHierarchicalForecast's the Python package indexpipwith:pipinstallhierarchicalforecastYou can also can installHierarchicalForecast's fromcondawith:condainstall-cconda-forgehierarchicalforecast🧬 How to useThe following example needsstatsforecastanddatasetsforecastas additional packages. If not installed, install it via your preferred method, e.g.pip install statsforecast datasetsforecast.
Thedatasetsforecastlibrary allows us to download hierarhical datasets and we will usestatsforecastto compute the base forecasts to be reconciled.You can open a complete example in ColabMinimal Example:# !pip install -U numba statsforecast datasetsforecastimportnumpyasnpimportpandasaspd#obtain hierarchical datasetfromdatasetsforecast.hierarchicalimportHierarchicalData# compute base forecast no coherentfromstatsforecast.coreimportStatsForecastfromstatsforecast.modelsimportAutoARIMA,Naive#obtain hierarchical reconciliation methods and evaluationfromhierarchicalforecast.coreimportHierarchicalReconciliationfromhierarchicalforecast.evaluationimportHierarchicalEvaluationfromhierarchicalforecast.methodsimportBottomUp,TopDown,MiddleOut# Load TourismSmall datasetY_df,S,tags=HierarchicalData.load('./data','TourismSmall')Y_df['ds']=pd.to_datetime(Y_df['ds'])#split train/test setsY_test_df=Y_df.groupby('unique_id').tail(4)Y_train_df=Y_df.drop(Y_test_df.index)# Compute base auto-ARIMA predictionsfcst=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 predictionsreconcilers=[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)EvaluationAssumes you have a test dataframe.defmse(y,y_hat):returnnp.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 thedocumentation.📃 LicenseThis project is licensed under the MIT License - see theLICENSEfile for details.🏟 HTS projectsIn the R ecosystem, we recommend checking outfable, and the now-retiredhts.
In Python we want to acknowledge the following librarieshiere2e,sktime,darts,pyhts,scikit-hts.📚 References and AcknowledgementsThis 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 thispaper.
We encourage users to explore thisliterature review.🙏 How to citeIf you enjoy or benefit from using these Python implementations, a citation to thishierarchical forecasting reference paperwill be greatly appreciated.@article{olivares2022hierarchicalforecast,author={Kin G. Olivares andFederico Garza andDavid Luo andCristian Challú andMax Mergenthaler andSouhaib Ben Taieb andShanika L. Wickramasuriya andArtur 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}}