hierarchicalforecast API完全参考：核心类与方法使用手册

hierarchicalforecast API完全参考核心类与方法使用手册【免费下载链接】hierarchicalforecastProbabilistic Hierarchical forecasting with statistical and econometric methods.项目地址: https://gitcode.com/gh_mirrors/hi/hierarchicalforecast分层预测是现代时间序列分析中的关键技术而HierarchicalForecast库提供了最先进的概率分层预测解决方案。本文将为您提供完整的API参考手册帮助您掌握这个强大工具的核心功能。无论您是数据科学家、业务分析师还是时间序列预测工程师这份手册都将成为您日常工作的得力助手。 核心概念与架构HierarchicalForecast库采用模块化设计主要包含以下核心模块核心类HierarchicalReconciliation- 主协调类协调方法BottomUp,TopDown,MiddleOut,MinTrace,ERM等概率方法Normality,Bootstrap,PERMBU,Conformal评估工具evaluate函数实用工具aggregate,SMatrix,HierarchicalPlot等 核心类详解HierarchicalReconciliation 类这是库的核心入口点负责协调所有预测方法。位于 hierarchicalforecast/core.py 文件中的HierarchicalReconciliation类是整个框架的枢纽。初始化方法from hierarchicalforecast.core import HierarchicalReconciliation # 创建协调器实例 reconcilers [ BottomUp(), TopDown(methodforecast_proportions), MiddleOut(middle_levelCountry/Purpose/State, top_down_methodforecast_proportions), MinTrace(methodmint_shrink) ] hrec HierarchicalReconciliation(reconcilersreconcilers)主要方法reconcile()- 执行协调预测bootstrap_reconcile()- 使用自助法进行概率协调协调方法类所有协调方法都继承自HReconciler基类位于 hierarchicalforecast/methods.py。每个方法都有独特的适用场景1. BottomUp 方法from hierarchicalforecast.methods import BottomUp # 自底向上方法 - 简单累加 bottom_up BottomUp()2. TopDown 方法from hierarchicalforecast.methods import TopDown # 自顶向下方法 - 多种分配策略 top_down TopDown(methodforecast_proportions) # 预测比例法 top_down TopDown(methodaverage_proportions) # 平均比例法 top_down TopDown(methodproportion_averages) # 比例平均法3. MiddleOut 方法from hierarchicalforecast.methods import MiddleOut # 中间向外方法 - 结合上下策略 middle_out MiddleOut( middle_levelCountry/Purpose/State, top_down_methodforecast_proportions )4. MinTrace 方法from hierarchicalforecast.methods import MinTrace # 最小迹方法 - 最小化预测方差 min_trace MinTrace(methodmint_shrink) # 收缩协方差估计 min_trace MinTrace(methodmint_ols) # OLS估计 min_trace MinTrace(methodmint_wls) # WLS估计 min_trace MinTrace(methodmint_wls_var) # WLS方差估计5. ERM 方法from hierarchicalforecast.methods import ERM # 经验风险最小化方法 - L1正则化 erm ERM(lambda_reg0.5, nonnegativeFalse) 概率协调方法HierarchicalForecast提供了多种概率预测方法支持不确定性量化1. Normality 方法基于正态性假设使用MinTrace方差-协方差闭式矩阵# 在协调时指定间隔方法 Y_rec_df hrec.reconcile( Y_hat_dfY_hat_df, Y_dfY_train_df, S_dfS_df, tagstags, intervals_methodnormality, level[80, 95] )2. Bootstrap 方法使用Gamakumara的自助法生成分层协调预测分布Y_rec_df hrec.reconcile( Y_hat_dfY_hat_df, Y_dfY_train_df, S_dfS_df, tagstags, intervals_methodbootstrap, level[80, 95], num_samples1000 )3. PERMBU 方法通过估计秩置换copula重新注入多变量依赖关系Y_rec_df hrec.reconcile( Y_hat_dfY_hat_df, Y_dfY_train_df, S_dfS_df, tagstags, intervals_methodpermbu, level[80, 95], num_samples1000 )4. Conformal 方法基于共形预测的无分布预测区间Y_rec_df hrec.reconcile( Y_hat_dfY_hat_df, Y_dfY_train_df, S_dfS_df, tagstags, intervals_methodconformal, level[80, 95] ) 评估与验证evaluate() 函数位于 hierarchicalforecast/evaluation.py 的评估函数支持多层级评估from hierarchicalforecast.evaluation import evaluate from utilsforecast.losses import mse, mae, rmse # 评估协调预测 evaluation evaluate( dfdf, tagstags, metrics[mse, mae, rmse], models[AutoARIMA, Naive, BottomUp, TopDown], benchmarkNaive, agg_fnmean )支持的评估指标mse- 均方误差mae- 平均绝对误差rmse- 均方根误差mase- 平均绝对标度误差rmae- 相对平均绝对误差mape- 平均绝对百分比误差️ 实用工具函数1. aggregate() 函数从底层序列构建聚合序列from hierarchicalforecast.utils import aggregate # 创建聚合序列 Y_df, S_df, tags aggregate( dfbottom_df, specspec_dict, agg_fnsum )2. SMatrix 类处理求和矩阵的核心工具from hierarchicalforecast.utils import SMatrix # 创建求和矩阵 S SMatrix(specspec_dict)3. HierarchicalPlot 类可视化分层结构和预测结果from hierarchicalforecast.utils import HierarchicalPlot # 创建可视化对象 plotter HierarchicalPlot(Y_df, S_df, tags) plotter.plot_forecasts(Y_hat_df, models[AutoARIMA, BottomUp]) 完整工作流程示例步骤1准备数据import pandas as pd import numpy as np from datasetsforecast.hierarchical import HierarchicalData # 加载分层数据集 Y_df, S_df, tags HierarchicalData.load(./data, TourismSmall) Y_df[ds] pd.to_datetime(Y_df[ds]) S_df S_df.reset_index(namesunique_id) # 分割训练测试集 Y_test_df Y_df.groupby(unique_id).tail(4) Y_train_df Y_df.drop(Y_test_df.index)步骤2生成基础预测from statsforecast.core import StatsForecast from statsforecast.models import AutoARIMA, Naive # 计算基础预测 fcst StatsForecast( models[AutoARIMA(season_length4), Naive()], freqQE, n_jobs-1 ) Y_hat_df fcst.forecast(dfY_train_df, h4)步骤3协调预测from hierarchicalforecast.core import HierarchicalReconciliation from hierarchicalforecast.methods import BottomUp, TopDown, MinTrace # 配置协调器 reconcilers [ BottomUp(), TopDown(methodforecast_proportions), MinTrace(methodmint_shrink) ] hrec HierarchicalReconciliation(reconcilersreconcilers) # 执行协调 Y_rec_df hrec.reconcile( Y_hat_dfY_hat_df, Y_dfY_train_df, S_dfS_df, tagstags, intervals_methodnormality, level[80, 95] )步骤4评估结果from hierarchicalforecast.evaluation import evaluate from utilsforecast.losses import mse, mae # 合并测试数据 df Y_rec_df.merge(Y_test_df, on[unique_id, ds]) # 评估性能 evaluation evaluate( dfdf, tagstags, metrics[mse, mae], models[AutoARIMA, Naive, BottomUp, TopDown, MinTrace], benchmarkNaive ) 高级功能与技巧1. 时间分层协调# 时间分层协调 Y_rec_df hrec.reconcile( Y_hat_dfY_hat_df, S_dfS_df, tagstags, temporalTrue, id_time_coltemporal_id )2. 自定义线程控制from hierarchicalforecast.utils import set_num_threads, get_num_threads # 设置OpenMP线程数 set_num_threads(4) current_threads get_num_threads() print(f当前线程数: {current_threads})3. 稀疏矩阵优化对于大规模分层结构使用稀疏方法提高性能from hierarchicalforecast.methods import BottomUpSparse, TopDownSparse, MinTraceSparse # 使用稀疏版本 reconcilers [ BottomUpSparse(), TopDownSparse(methodforecast_proportions), MinTraceSparse(methodmint_shrink) ] 性能优化建议数据预处理确保时间序列数据格式正确缺失值已处理方法选择根据数据规模和结构选择合适的方法内存管理对于大型数据集使用稀疏矩阵方法并行计算利用多线程加速计算缓存机制重复使用已拟合的协调器 最佳实践1. 方法选择指南小规模数据所有方法都适用中等规模推荐MinTrace和ERM大规模数据使用稀疏版本或BottomUp需要概率区间使用Bootstrap或PERMBU2. 参数调优# MinTrace方法参数调优 min_trace MinTrace( methodmint_shrink, # 协方差估计方法 nonnegativeFalse, # 是否强制非负 covariance_estimatorlw # 协方差估计器 ) # ERM方法参数调优 erm ERM( lambda_reg0.5, # L1正则化强度 nonnegativeTrue, # 非负约束 solverclarabel # 优化求解器 )3. 错误处理try: Y_rec_df hrec.reconcile( Y_hat_dfY_hat_df, Y_dfY_train_df, S_dfS_df, tagstags ) except ValueError as e: print(f输入数据错误: {e}) except NotImplementedError as e: print(f方法不支持: {e}) except Exception as e: print(f其他错误: {e}) 学习资源与扩展官方文档核心API文档docs/core.html.md方法文档docs/methods.html.md概率方法文档docs/probabilistic_methods.html.md评估文档docs/evaluation.html.md工具文档docs/utils.html.md示例笔记本项目包含丰富的示例笔记本位于nbs/examples/目录introduction.ipynb- 入门教程tourismlarge-evaluation.ipynb- 大规模旅游数据评估probabilistic-reconciliation-comparison.ipynb- 概率方法比较reconciliationdiagnostics.ipynb- 协调诊断 总结HierarchicalForecast提供了完整的分层预测解决方案从基础协调方法到高级概率预测。通过本API参考手册您应该能够理解核心类的功能和使用方法选择合适的协调策略实现概率预测和不确定性量化评估和比较不同方法的性能优化大规模数据集的预测流程无论您是处理销售预测、库存管理还是资源规划HierarchicalForecast都能为您提供可靠、一致且可解释的分层预测结果。开始使用这个强大的工具提升您的预测准确性和业务决策质量【免费下载链接】hierarchicalforecastProbabilistic Hierarchical forecasting with statistical and econometric methods.项目地址: https://gitcode.com/gh_mirrors/hi/hierarchicalforecast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考