预测

pyro.contrib.forecast 是一个轻量级框架，用于使用熟悉的 Pyro 建模语法和 PyTorch 神经网络实验受限类别的时序模型和推断算法。

模型包括约 1000 个时间步长和约 1000 个独立序列的分层多元厚尾时间序列。推断将支持子采样的变分推断与基于 GaussianHMM 类的 Gaussian 变量消除相结合。HMCForecaster 也支持使用哈密顿蒙特卡洛抽样进行推断。预测以多个未来时间步长的联合后验样本形式给出。

分层模型使用熟悉的 plate 语法进行 Pyro 中的通用分层建模。Plate 可以进行子采样，从而能够训练数千个时间序列上的联合模型。多元观测通过 MultivariateNormal、GaussianHMM 或 LinearHMM 等多元似然处理。通过使用 StudentT 或 Stable 似然，可能结合 LinearHMM 以及包括 StudentTReparam、StableReparam 和 LinearHMMReparam 在内的重参数化器，可以构建厚尾模型。

可以使用 periodic_repeat()、periodic_cumsum() 和 periodic_features() 辅助函数处理季节性。

有关构建可用作似然的时态高斯过程的方法，请参阅 pyro.contrib.timeseries。

示例用法请参见

预测器接口

class ForecastingModel[source]

基类: pyro.nn.module.PyroModule

预测模型的抽象基类。

派生类必须实现 model() 方法。

abstract model(zero_data, covariates)[source]

生成模型定义。

实现必须且仅调用一次 predict() 方法。

实现必须在 time_plate() 中抽取所有时间相关的噪声。传递给 predict() 的预测必须是时间独立噪声张量的确定性函数。此要求比状态空间模型稍普遍。

参数

  • zero_data (张量) – 一个零张量，其形状类似于输入数据，但扩展到 time_plate() 的持续时间。这允许模型依赖数据的形状和设备，而不依赖其值。

  • covariates (张量) – 一个协变量张量，其时间维度为 -2。

返回

返回值被忽略。

property time_plate

用于在时间上创建 pyro.plate 的辅助函数。

返回

一个名为“time”的 plate，大小为 covariates.size(-2)，维度为 dim=-1。这仅在模型执行期间可用。

返回类型

plate

predict(noise_dist, prediction)[source]

预测函数，由 model() 实现调用。

这应该在 time_plate() 之外调用。

这类似于 Pyro 中的 observe 语句

pyro.sample("residual", noise_dist,
            obs=(data - prediction))

但有 (1) 附加的重塑逻辑以允许时间相关的 noise_dist（最常见的是 GaussianHMM 或其变体）；以及 (2) 附加的逻辑以允许部分观测并预测剩余数据。

参数

  • noise_dist (分布) – 一个噪声分布，其 .event_dim in {0,1,2}。 noise_dist 通常是零均值、零中位数、零众数或以某种方式居中。

  • prediction (张量) – 对数据的预测。其形状应与 data 相同，但可广播到 covariates 的完整持续时间。

class Forecaster(model, data, covariates, *, guide=None, init_loc_fn=<函数 init_to_sample>, init_scale=0.1, create_plates=None, optim=None, learning_rate=0.01, betas=(0.9, 0.99), learning_rate_decay=0.1, clip_norm=10.0, time_reparam=None, dct_gradients=False, subsample_aware=False, num_steps=1001, num_particles=1, vectorize_particles=True, warm_start=False, log_every=100)[source]

基类: torch.nn.modules.module.Module

使用变分推断的 ForecastingModel 预测器。

初始化时，它使用对潜在变量的变分推断和对噪声分布（通常是 GaussianHMM 或其变体）的精确推断来拟合分布。

构建完成后，可以调用此对象生成预测样本。

变量

losses (列表) – 训练期间记录的损失列表，通常用于调试收敛。由 loss = -elbo / data.numel() 定义。

参数

  • model (ForecastingModel) – 预测模型子类的实例。

  • data (张量) – 时间维度为 -2 的张量数据集。

  • covariates (张量) – 时间维度为 -2 的协变量张量。对于不使用协变量的模型，请传递形状为空的张量 torch.empty(duration, 0)。

  • guide (PyroModule) – 可选的 guide 实例。默认为 AutoNormal。

  • init_loc_fn (callable) – AutoNormal guide 的每站点初始化函数。默认为 init_to_sample()。有关可用函数，请参阅 Initialization 部分。

  • init_scale (浮点数) – AutoNormal guide 的初始不确定性尺度。

  • create_plates (callable) – 一个可选函数，用于使用 AutoNormal guide 创建用于子采样的 plate。

  • optim (PyroOptim) – 可选的 Pyro 优化器。默认为新构建的 DCTAdam。

  • learning_rate (浮点数) – DCTAdam 使用的学习率。

  • betas (元组) – DCTAdam 使用的移动平均系数。

  • learning_rate_decay (浮点数) – DCTAdam 使用的学习率衰减。请注意，这是所有 num_steps 的总衰减，而不是每步衰减因子。

  • clip_norm (浮点数) – 优化期间用于梯度裁剪的范数。默认为 10.0。

  • time_reparam (str) – 如果不是 None（默认值），则通过 Haar 小波变换（如果是“haar”）或离散余弦变换（如果是“dct”）对所有时间相关变量进行重参数化。

  • dct_gradients (bool) – 是否在 DCTAdam 中对梯度进行离散余弦变换。默认为 False。

  • subsample_aware (bool) – 是否仅更新出现在子样本中的元素的梯度统计信息。DCTAdam 使用此设置。

  • num_steps (int) – SVI 步数。

  • num_particles (int) – 用于计算 ELBO 的粒子数。

  • vectorize_particles (bool) – 如果 num_particles > 1，则决定是否向量化 ELBO 的计算。默认为 True。对于具有动态控制流的模型，请设置为 False。

  • warm_start (bool) – 是否从较小的时间窗口热启动参数。请注意，这可能会引入统计信息泄露；建议仅用于模型探索目的，发布指标时应禁用此功能。

  • log_every (int) – 日志消息之间的训练步数。

__call__(data, covariates, num_samples, batch_size=None)[source]

对时间步长在 [t1,t2) 范围内的数据进行预测采样，其中 t1 = data.size(-2) 是观测数据的持续时间，t2 = covariates.size(-2) 是协变量的扩展持续时间。例如，基于 30 天的观测数据预测未来 7 天，则设置 t1=30，t2=37。

参数

  • data (张量) – 时间维度为 -2 的张量数据集。

  • covariates (张量) – 时间维度为 -2 的协变量张量。对于不使用协变量的模型，请传递形状为空的张量 torch.empty(duration, 0)。

  • num_samples (int) – 要生成的样本数。

  • batch_size (int) – 可选的采样批量大小。这对于从内存占用大的模型生成大量样本非常有用。默认为 num_samples。

返回

一个联合后验样本批次，形状为 (num_samples,1,...,1) + data.shape[:-2] + (t2-t1,data.size(-1))，其中插入 1 是为了避免与模型 plate 冲突。

返回类型

张量

class HMCForecaster(model, data, covariates=None, *, num_warmup=1000, num_samples=1000, num_chains=1, time_reparam=None, dense_mass=False, jit_compile=False, max_tree_depth=10)[source]

基类: torch.nn.modules.module.Module

使用哈密顿蒙特卡洛的 ForecastingModel 预测器。

初始化时，它将运行 NUTS 采样器以获取模型的后验样本。

构建完成后，可以调用此对象生成预测样本。

参数

  • model (ForecastingModel) – 预测模型子类的实例。

  • data (张量) – 时间维度为 -2 的张量数据集。

  • covariates (张量) – 时间维度为 -2 的协变量张量。对于不使用协变量的模型，请传递形状为空的张量 torch.empty(duration, 0)。

  • num_warmup (int) – MCMC 热身步数。

  • num_samples (int) – MCMC 样本数。

  • num_chains (int) – 并行 MCMC 链数。

  • dense_mass (bool) – 一个标志，控制质量矩阵是稠密的还是对角的。默认为 False。

  • time_reparam (str) – 如果不是 None（默认值），则通过 Haar 小波变换（如果是“haar”）或离散余弦变换（如果是“dct”）对所有时间相关变量进行重参数化。

  • jit_compile (bool) – 是否使用 PyTorch JIT 跟踪对数密度计算，并在积分器中使用此优化后的可执行跟踪。默认为 False。

  • max_tree_depth (int) – NUTS 采样器倍增方案期间创建的二叉树的最大深度。默认为 10。

__call__(data, covariates, num_samples, batch_size=None)[source]

对时间步长在 [t1,t2) 范围内的数据进行预测采样，其中 t1 = data.size(-2) 是观测数据的持续时间，t2 = covariates.size(-2) 是协变量的扩展持续时间。例如，基于 30 天的观测数据预测未来 7 天，则设置 t1=30，t2=37。

参数

  • data (张量) – 时间维度为 -2 的张量数据集。

  • covariates (张量) – 时间维度为 -2 的协变量张量。对于不使用协变量的模型，请传递形状为空的张量 torch.empty(duration, 0)。

  • num_samples (int) – 要生成的样本数。

  • batch_size (int) – 可选的采样批量大小。这对于从内存占用大的模型生成大量样本非常有用。默认为 num_samples。

返回

一个联合后验样本批次，形状为 (num_samples,1,...,1) + data.shape[:-2] + (t2-t1,data.size(-1))，其中插入 1 是为了避免与模型 plate 冲突。

返回类型

张量

评估

eval_mae(pred, truth)[source]

评估平均绝对误差，使用样本中位数作为点估计。

参数
返回类型

浮点数

eval_rmse(pred, truth)[source]

评估均方根误差，使用样本均值作为点估计。

参数
返回类型

浮点数

eval_crps(pred, truth)[source]

评估连续分级概率评分，对所有数据元素取平均。

参考文献

[1] Tilmann Gneiting, Adrian E. Raftery (2007)

严格适当的评分规则、预测和估计 https://www.stat.washington.edu/raftery/Research/PDF/Gneiting2007jasa.pdf

参数
返回类型

浮点数

backtest(data, covariates, model_fn, *, forecaster_fn=<类 'pyro.contrib.forecast.forecaster.Forecaster'>, metrics=None, transform=None, train_window=None, min_train_window=1, test_window=None, min_test_window=1, stride=1, seed=1234567890, num_samples=100, batch_size=None, forecaster_options={})[source]

在移动的 (训练,测试) 数据窗口上回测预测模型。

参数

  • data (张量) – 时间维度为 -2 的张量数据集。

  • covariates (张量) – 时间维度为 -2 的协变量张量。对于不使用协变量的模型，请传递形状为空的张量 torch.empty(duration, 0)。

  • model_fn (callable) – 返回 ForecastingModel 对象的函数。

  • forecaster_fn (callable) – 给定参数 model、训练数据、训练协变量以及 forecaster_options 中定义的关键字参数，返回一个预测器对象（例如，Forecaster 或 HMCForecaster）的函数。

  • metrics (dict) – 一个将指标名称映射到指标函数的字典。指标函数应输入预测 pred 和真实值 truth，并可输出任何值，通常是一个数字。示例指标包括：eval_mae()、eval_rmse() 和 eval_crps()。

  • transform (callable) – 计算指标前应用的可选变换。如果提供，将应用为 pred, truth = transform(pred, truth)。

  • train_window (int) – 训练窗口的大小。默认从数据开头开始训练。如果 forecaster 是 Forecaster 且 forecaster_options["warm_start"] 为真，则此值必须为 None。

  • min_train_window (int) – 如果 train_window 为 None，则指定最小训练窗口大小。默认为 1。

  • test_window (int) – 测试窗口的大小。默认预测到数据末尾。

  • min_test_window (int) – 如果 test_window 为 None，则指定最小测试窗口大小。默认为 1。

  • stride (int) – 可选的测试/训练分割步幅。默认为 1。

  • seed (int) – 随机数种子。

  • num_samples (int) – 预测样本数。默认为 100。

  • batch_size (int) – 预测采样批量大小。默认为 num_samples。

  • forecaster_options (dict or callable) – 传递给预测器的选项字典，或者一个输入时间窗口 t0,t1,t2 并返回此类字典的可调用对象。有关详细信息，请参见 Forecaster。

返回

一个评估数据字典列表。调用方负责汇总每个窗口的指标。字典键包括：训练开始时间“t0”、训练/测试分割时间“t1”、测试结束时间“t2”、“seed”、“num_samples”、“train_walltime”、“test_walltime”以及每个指标的一个键。

返回类型

列表