Nixtla

<div align="center"> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/886ce0ae-59b5-4c49-929b-8b05c5701358.png"> <h1 align="center">分层预测 👑</h1> <h3 align="center">使用统计和计量经济学方法进行概率分层预测</h3>

HierarchicalForecast 提供了一系列调和方法，包括 BottomUp、TopDown、MiddleOut、MinTrace 和 ERM。还包括概率一致性预测方法，如 Normality、Bootstrap 和 PERMBU。

</div>

📚 简介

大量时间序列数据集按不同层级或聚合层次的结构组织，如类别、品牌或地理分组。跨层级的一致性预测对于决策和规划的一致性至关重要。分层预测提供了不同的调和方法，使跨层级的预测保持一致。直到最近，这些方法主要在R生态系统中可用。这个基于Python的框架旨在弥合时间序列领域中统计建模和机器学习之间的差距。

🎊 特性

经典调和方法：
- BottomUp：简单地将下层数据加总到上层。
- TopDown：将顶层预测分配到各个层级。
替代调和方法：
- MiddleOut：将基准预测锚定在中间层。中间层以上的层级采用自下而上方法，而下面的层级采用自上而下方法。
- MinTrace：通过最小化一致性预测空间的总预测方差，实现最小迹调和。
- ERM：通过最小化L1正则化目标来优化调和矩阵。
概率一致性方法：
- Normality：在正态性假设下使用MinTrace方差-协方差闭式矩阵。
- Bootstrap：使用Gamakumara的自助法生成分层调和预测的分布。
- PERMBU：通过重新注入估计的秩置换copula多变量依赖关系，并执行自下而上的聚合，调和独立样本预测。

缺少什么？请在这里提出问题或在上联系我们

📖 为什么？

简短回答：我们希望为工业界和学术界的分层预测任务提供可靠的基准和标准，从而为机器学习领域做出贡献。这里是完整的论文。

详细回答：HierarchicalForecast 集成了公开可用的处理后数据集、评估指标和精心筛选的标准统计基准。在这个库中，我们提供了使用示例和广泛实验的参考，展示了基准的使用并评估了它们预测的准确性。通过这项工作，我们希望通过弥合与统计和计量经济学建模的差距，为机器学习预测做出贡献，并为开发基于这些成熟模型的全面比较的新型分层预测算法提供工具。我们计划继续维护和扩展这个仓库，促进整个预测社区的合作。

💻 安装

你可以通过Python包索引 pip 安装 HierarchicalForecast：

pip install hierarchicalforecast

你也可以通过 conda 安装 HierarchicalForecast：

conda install -c conda-forge hierarchicalforecast

🧬 如何使用

以下示例需要额外的包 statsforecast 和 datasetsforecast。如果尚未安装，请通过你偏好的方式安装，例如 pip install statsforecast datasetsforecast。 datasetsforecast 库允许我们下载分层数据集，我们将使用 statsforecast 计算待调和的基础预测。

你可以在Colab中打开完整示例

最小示例：

# !pip install -U numba statsforecast datasetsforecast
import numpy as np
import pandas as pd

# 获取分层数据集
from datasetsforecast.hierarchical import HierarchicalData

# 计算非一致性的基础预测
from statsforecast.core import StatsForecast
from statsforecast.models import AutoARIMA, Naive

# 获取分层调和方法和评估
from hierarchicalforecast.core import HierarchicalReconciliation
from hierarchicalforecast.evaluation import HierarchicalEvaluation
from hierarchicalforecast.methods import BottomUp, TopDown, MiddleOut

# 加载TourismSmall数据集
Y_df, S, tags = HierarchicalData.load('./data', 'TourismSmall')
Y_df['ds'] = pd.to_datetime(Y_df['ds'])

划分训练/测试集

Y_test_df = Y_df.groupby('unique_id').tail(4) Y_train_df = Y_df.drop(Y_test_df.index)

计算基础自动ARIMA预测

fcst = StatsForecast(df=Y_train_df, models=[AutoARIMA(season_length=4), Naive()], freq='Q', n_jobs=-1) Y_hat_df = fcst.forecast(h=4)

调和基础预测

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)


### 评估
假设你有一个测试数据框。

```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_df=Y_test_df.set_index('unique_id'),
                   tags=tags, benchmark='Naive')

📖 文档（进行中）

这是文档的链接。

📃 许可证

该项目采用MIT许可证 - 详见LICENSE文件。

🏟 HTS项目

在R生态系统中，我们推荐查看fable，以及现已停止维护的hts。在Python中，我们要感谢以下库hiere2e、sktime、darts、pyhts、scikit-hts。

📚 参考文献和致谢

本工作受到了之前贡献者和其他学者提出的调和方法的巨大影响。我们要特别强调Rob Hyndman、George Athanasopoulos、Shanika L. Wickramasuriya、Souhaib Ben Taieb和Bonsoo Koo的工作。完整的参考链接请访问这篇论文的参考文献部分。我们鼓励用户探索这篇文献综述。

🙏 如何引用

如果你喜欢或受益于使用这些Python实现，非常感谢你引用这篇层次化预测参考论文。

@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}
}