预测¶

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

模型包括层次多元重尾时间序列，约1000个时间步长和约1000个独立序列。推理结合了子样本兼容的变分推理和基于GaussianHMM类的高斯变量消除。使用哈密顿蒙特卡洛采样的推理也支持HMCForecaster。预测以多个未来时间步长的联合后验样本形式呈现。

层次模型使用熟悉的plate语法在Pyro中进行通用层次建模。可以对板块进行子采样，从而能够训练数千个时间序列的联合模型。通过多元似然函数处理多元观测，例如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)[来源]¶

生成模型定义。

实现必须准确调用一次 predict() 方法。

实现必须在time_plate()内绘制所有时间相关的噪声。传递给predict()的预测必须是随时间独立的噪声张量的确定性函数。这一要求比状态空间模型稍微更一般化。

Parameters

zero_data (Tensor) – 一个与输入数据相似的零张量，但扩展到time_plate()的持续时间。这使得模型可以依赖于数据的形状和设备，而不是其值。
协变量 (Tensor) – 一个具有时间维度-2的协变量张量。

Returns

返回值被忽略。

property time_plate¶

帮助创建一个随时间变化的 pyro.plate。

Returns: 一个名为“time”的板块，其大小为covariates.size(-2)和dim=-1。这仅在模型执行期间可用。
Return type: plate

predict(noise_dist, prediction)[来源]¶

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

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

这类似于Pyro中的观察语句：

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

但是增加了（1）额外的重塑逻辑，以允许时间依赖的 noise_dist（通常是一个GaussianHMM 或变体）；以及（2）额外的逻辑，以允许仅部分观察并预测剩余数据。

Parameters

noise_dist (Distribution) – 一个噪声分布，具有 .event_dim in {0,1,2}。 noise_dist 通常是零均值或零中位数或零模式，或以某种方式居中。
预测 (Tensor) – 对数据的预测。这应该与 data 具有相同的形状，但可以广播到 covariates 的整个持续时间。

class Forecaster(model, data, covariates, *, guide=None, init_loc_fn=<function 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)[源代码]¶

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

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

在初始化时，这通过变分推断对潜在变量进行分布拟合，并对噪声分布进行精确推断，通常是一个GaussianHMM或其变体。

构建后可以调用此函数以生成样本预测。

Variables

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

Parameters

model (ForecastingModel) – 一个预测模型子类的实例。
data (Tensor) – 一个具有时间维度-2的张量数据集。
协变量 (Tensor) – 一个具有时间维度-2的协变量张量。对于不使用协变量的模型，传递一个形状为空的张量 torch.empty(duration, 0)。
指南 (PyroModule) – 可选的指南实例。默认为 AutoNormal.
init_loc_fn (callable) – 一个用于AutoNormal指南的每个站点初始化函数。默认为init_to_sample()。请参阅初始化部分以了解可用的函数。
init_scale (float) – AutoNormal 引导的初始不确定性尺度。
create_plates (callable) – 一个可选函数，用于为使用AutoNormal指南的子采样创建板块。
optim (PyroOptim) – 一个可选的Pyro优化器。默认情况下，会新建一个DCTAdam。
learning_rate (float) – 由 DCTAdam使用的学习率。
betas (tuple) – 用于DCTAdam的运行平均值的系数。
learning_rate_decay (float) – 由 DCTAdam 使用的学习率衰减。请注意这是所有 num_steps 的总衰减，而不是每步的衰减因子。
clip_norm (float) – 在优化过程中用于梯度裁剪的范数。默认为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。

Parameters

data (Tensor) – 一个具有时间维度-2的张量数据集。
协变量 (Tensor) – 一个具有时间维度-2的协变量张量。对于不使用协变量的模型，传递一个形状为空的张量 torch.empty(duration, 0)。
num_samples (int) – 要生成的样本数量。
batch_size (int) – 可选的采样批量大小。这对于从内存占用较大的模型中生成许多样本非常有用。默认为 num_samples。

Returns

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

Return type

Tensor

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采样器以获取模型的后验样本。

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

Parameters

model (ForecastingModel) – 一个预测模型子类的实例。
data (Tensor) – 一个具有时间维度-2的张量数据集。
协变量 (Tensor) – 一个具有时间维度-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。

Parameters

data (Tensor) – 一个具有时间维度-2的张量数据集。
协变量 (Tensor) – 一个具有时间维度-2的协变量张量。对于不使用协变量的模型，传递一个形状为空的张量 torch.empty(duration, 0)。
num_samples (int) – 要生成的样本数量。
batch_size (int) – 可选的采样批量大小。这对于从内存占用较大的模型中生成许多样本非常有用。默认为 num_samples。

Returns

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

Return type

Tensor

评估¶

eval_mae(pred, truth)[source]¶

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

Parameters

pred (torch.Tensor) – 预测样本。
truth (torch.Tensor) – 真实值。

Return type

float

eval_rmse(pred, truth)[source]¶

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

Parameters

pred (torch.Tensor) – 预测样本。
真实值 (torch.Tensor) – 真实值。

Return type

float

eval_crps(pred, truth)[source]¶

评估连续排名概率得分，对所有数据元素进行平均。

参考文献

[1] Tilmann Gneiting, Adrian E. Raftery (2007): 严格适当的评分规则、预测和估计 https://www.stat.washington.edu/raftery/Research/PDF/Gneiting2007jasa.pdf

Parameters

pred (torch.Tensor) – 预测样本。
真实值 (torch.Tensor) – 真实值。

Return type

float

backtest(data, covariates, model_fn, *, forecaster_fn=<class '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]¶

在移动窗口的（训练，测试）数据上回测预测模型。

Parameters

data (Tensor) – 一个具有时间维度-2的张量数据集。
协变量 (Tensor) – 一个具有时间维度-2的协变量张量。对于不使用协变量的模型，传递一个形状为空的张量 torch.empty(duration, 0)。
model_fn (callable) – 返回一个 ForecastingModel 对象的函数。
forecaster_fn (callable) – 返回预测器对象的函数（例如，Forecaster 或 HMCForecaster) 给定参数模型、训练数据、训练协变量和在forecaster_options中定义的关键字参数。
metrics (dict) – 一个将指标名称映射到指标函数的字典。指标函数应输入预测值 pred 和真实值 truth，并且可以输出任何内容，通常是一个数字。示例指标包括：eval_mae(), eval_rmse(), 和 eval_crps()。
transform (callable) – 一个可选的转换函数，在计算指标之前应用。如果提供，将作为 pred, truth = transform(pred, truth) 应用。
train_window (int) – 训练窗口的大小。默认从数据开始处进行训练。如果预测器是 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 或 callable) – 传递给预测器的选项字典，或者是输入时间窗口 t0,t1,t2 并返回此类字典的可调用对象。详情请参见 Forecaster。

Returns

评估数据的字典列表。调用者负责聚合每个窗口的指标。字典键包括：训练开始时间“t0”，训练/测试分割时间“t1”，测试结束时间“t2”，“种子”，“样本数量”，“训练时间”，“测试时间”，以及每个指标的一个键。

Return type

list