加入 Slack   |   文档   |   博客 - 简介   |   博客 - v1.1

---

用户须知

仓库的默认页面位于 dev 分支。如需安装开发版，请参阅“从开发分支安装”部分。如果您正在寻找稳定版本，请参考 此处 的 master 分支。

免责声明

该项目

• 目前处于稳定阶段，并正被孵化以实现长期支持。它可能包含新的实验性代码，其 API 可能会发生变化。
• 需要 cmdstanpy 作为贝叶斯采样的核心依赖之一。

Orbit：用于贝叶斯预测的 Python 包

Orbit 是一个用于贝叶斯时间序列预测和推断的 Python 库。它为时间序列任务提供了一个熟悉且直观的初始化-拟合-预测接口，同时在底层利用了概率编程语言。

有关详细信息，请查看我们的文档和教程：

• HTML（稳定版）：https://orbit-ml.readthedocs.io/en/stable/
• HTML（最新版）：https://orbit-ml.readthedocs.io/en/latest/

目前，它支持以下模型的具体实现：

• 指数平滑 (ETS)
• 局部全局趋势 (LGT)
• 阻尼局部趋势 (DLT)
• 基于核的时间回归 (KTR)

此外，它还支持以下采样/优化方法来进行模型估计和推断：

• 马尔可夫链蒙特卡洛 (MCMC) 作为完整的采样方法
• 最大后验估计 (MAP) 作为点估计方法
• 变分推断 (VI) 作为基于近似分布的混合采样方法

安装

安装稳定版

您可以从 PyPI 或源代码使用 pip 安装该库。或者，您也可以通过 Anaconda 使用 conda 进行安装：

使用 pip

1. 从 PyPI 安装

   $ pip install orbit-ml
   

2. 从源代码安装

   $ git clone https://github.com/uber/orbit.git
   $ cd orbit
   $ pip install -r requirements.txt
   $ pip install .
   

使用 conda

该库可以从 conda-forge 频道使用 conda 安装。

$ conda install -c conda-forge orbit-ml

安装来自开发分支的版本

$ pip install git+https://github.com/uber/orbit.git@dev

阻尼局部趋势 (DLT) 模型快速入门

完整贝叶斯预测

from orbit.utils.dataset import load_iclaims
from orbit.models import DLT
from orbit.diagnostics.plot import plot_predicted_data

# 对数变换后的数据
df = load_iclaims()
# 训练集与测试集划分
test_size = 52
train_df = df[:-test_size]
test_df = df[-test_size:]

dlt = DLT(
  response_col='claims', date_col='week',
  regressor_col=['trend.unemploy', 'trend.filling', 'trend.job'],
  seasonality=52,
)
dlt.fit(df=train_df)

# 预测结果数据框
predicted_df = dlt.predict(df=test_df)

plot_predicted_data(
  training_actual_df=train_df, predicted_df=predicted_df,
  date_col=dlt.date_col, actual_col=dlt.response_col,
  test_actual_df=test_df
)

演示

DLT 中的回归即时预测：

M3 数据的回测：

更多示例可在 教程 和 示例 中找到。

贡献

我们欢迎社区贡献者参与本项目。在开始之前，请先阅读我们的 行为准则 并查看 贡献指南。

版本管理

我们在 变更日志 中记录版本和更改。

参考文献

演示文稿

请查看当前的 演示文稿 ，了解项目的范围和路线图。一份较早的演示文稿曾在 2021 年 7 月的 聚会 中使用，也可在此处找到：演示文稿。

引用

如需在出版物中引用 Orbit，请参考以下白皮书：

Orbit：基于指数平滑的概率预测

BibTeX 格式：

@misc{
    ng2020orbit,
    title={Orbit: Probabilistic Forecast with Exponential Smoothing},
    author={Edwin Ng,
        Zhishi Wang,
        Huigang Chen,
        Steve Yang,
        Slawek Smyl},
    year={2020}, eprint={2004.08492}, archivePrefix={arXiv}, primaryClass={stat.CO}
}

论文

• Bingham, E., Chen, J. P., Jankowiak, M., Obermeyer, F., Pradhan, N., Karaletsos, T., Singh, R., Szerlip, P., Horsfall, P., 和 Goodman, N. D. Pyro：深度通用概率编程。机器学习研究杂志，20(1)：973–978，2019年。
• Hoffman, M.D. 和 Gelman, A. 无回转采样器：在哈密顿蒙特卡洛中自适应设置路径长度。J. Mach. Learn. Res., 15(1)，第1593–1623页，2014年。
• Hyndman, R., Koehler, A. B., Ord, J. K., 和 Snyder, R. D. 指数平滑法预测：状态空间方法。施普林格科学与商业媒体，2008年。
• Smyl, S. Zhang, Q. 使用Stan拟合和扩展指数平滑模型。国际预测研讨会，2015年。

相关项目

• Pyro
• Stan
• Rlgt
• forecast
• prophet

Orbit 快速上手指南

Orbit 是由 Uber 开源的 Python 贝叶斯时间序列预测与推断包。它提供了直观的“初始化 - 拟合 - 预测”接口，底层基于概率编程语言（如 Stan），支持多种经典时间序列模型。

环境准备

• 操作系统：Linux, macOS, Windows (需配置 C++ 编译环境以支持 cmdstanpy)
• Python 版本：3.7+
• 核心依赖：
  • cmdstanpy：用于贝叶斯采样（安装 Orbit 时通常会自动处理，但需确保系统已安装 C++ 编译器）。
  • 常用数据科学库：pandas, numpy, matplotlib 等。

注意：由于涉及贝叶斯采样，首次运行模型时可能会自动下载 Stan 编译器，请确保网络畅通。国内用户若遇到下载缓慢问题，可尝试配置代理或手动预装 CmdStan。

安装步骤

推荐使用 pip 或 conda 进行安装。

方式一：使用 pip 安装（推荐）

直接从 PyPI 安装稳定版：

pip install orbit-ml

若需从源码安装（适用于开发或特定版本需求）：

git clone https://github.com/uber/orbit.git
cd orbit
pip install -r requirements.txt
pip install .

方式二：使用 conda 安装

通过 conda-forge 渠道安装：

conda install -c conda-forge orbit-ml

安装开发版（可选）

如需体验最新功能（非稳定版）：

pip install git+https://github.com/uber/orbit.git@dev

基本使用

以下示例演示如何使用 阻尼局部趋势 (DLT) 模型进行全贝叶斯预测。

1. 导入库与加载数据

from orbit.utils.dataset import load_iclaims
from orbit.models import DLT
from orbit.diagnostics.plot import plot_predicted_data

# 加载示例数据（已进行对数变换）
df = load_iclaims()

# 划分训练集和测试集
test_size = 52
train_df = df[:-test_size]
test_df = df[-test_size:]

2. 定义并训练模型

配置模型参数，包括响应列、日期列、回归变量及季节性周期。

dlt = DLT(
  response_col='claims', 
  date_col='week',
  regressor_col=['trend.unemploy', 'trend.filling', 'trend.job'],
  seasonality=52,
)

# 拟合模型
dlt.fit(df=train_df)

3. 预测与可视化

使用训练好的模型对测试集进行预测，并绘制结果。

# 生成预测数据框
predicted_df = dlt.predict(df=test_df)

# 绘制预测图
plot_predicted_data(
  training_actual_df=train_df, 
  predicted_df=predicted_df,
  date_col=dlt.date_col, 
  actual_col=dlt.response_col,
  test_actual_df=test_df
)

运行上述代码后，将输出包含预测区间的时间序列预测图表。更多高级用法（如 MCMC、MAP、VI 等不同推断方法）请参考官方文档。