与 Pyro 兼容的分布¶

此接口提供了一些 PyTorch 风格的分布，它们在内部使用 funsors 执行推理。这些高级对象基于一个包装类：FunsorDistribution，它将 funsor 包装在一个与 PyTorch 分布兼容的接口中。FunsorDistribution 对象可以直接在 Pyro 模型中使用（使用标准的 Pyro 后端）。

FunsorDistribution 基类¶

class FunsorDistribution(funsor_dist, batch_shape=torch.Size([]), event_shape=torch.Size([]), dtype='real', validate_args=None)[源码]¶

基类：TorchDistribution

围绕 Funsor 的 Distribution 包装器，用于 Pyro 代码。这通常用作特定 funsor 推理算法的基类，这些算法被包装在一个分布接口中。

参数

funsor_dist (funsor.terms.Funsor) – 一个 funsor，其输入名称为“value”，被视为随机变量。该分布应在“value”上归一化。
batch_shape (torch.Size) – 分布的批量形状（batch shape）。其顺序必须与 funsor_dist 的输入顺序相同，但可能包含大小为 1 的额外维度。
event_shape – 分布的事件形状（event shape）。

arg_constraints = {}¶

property support¶

log_prob(value)[源码]¶

sample(sample_shape=torch.Size([]))[源码]¶

rsample(sample_shape=torch.Size([]))[源码]¶

expand(batch_shape, _instance=None)[源码]¶

funsordistribution_to_funsor(pyro_dist, output=None, dim_to_name=None)[源码]¶

隐马尔可夫模型¶

class DiscreteHMM(initial_logits, transition_logits, observation_dist, validate_args=None)[源码]¶

基类：FunsorDistribution

具有离散潜在状态和任意观测分布的隐马尔可夫模型。这使用 [1] 在时间上进行并行化，实现了 O(log(时间)) 的并行复杂度。

此分布的 event_shape 在左侧包含时间

event_shape = (num_steps,) + observation_dist.event_shape

此分布支持 transition_logits 和 observation_dist 的齐次/非齐次时间依赖关系的任意组合。但是，由于时间包含在此分布的 event_shape 中，齐次+齐次情况下将拥有一个与 num_steps = 1 可广播的 event_shape，从而允许 log_prob() 处理任意长度的数据。

# homogeneous + homogeneous case:
event_shape = (1,) + observation_dist.event_shape

此类应可与 pyro.distributions.hmm.DiscreteHMM 互换使用。

参考文献

[1] Simo Sarkka, Angel F. Garcia-Fernandez (2019): “贝叶斯滤波器和平滑器的时间并行化” https://arxiv.org/pdf/1905.13002.pdf

参数

initial_logits (Tensor) – 潜在状态初始分类分布的 logits 张量。其最右边的尺寸应为 state_dim，并且应可广播到 batch_shape + (state_dim,)。
transition_logits (Tensor) – 潜在状态间转移条件分布的 logits 张量。其最右边的形状应为 (state_dim, state_dim) (旧状态, 新状态)，并且应可广播到 batch_shape + (num_steps, state_dim, state_dim)。
observation_dist (Distribution) – 观测数据以潜在状态为条件的条件分布。其 .batch_shape 的最右边尺寸应为 state_dim，并且应可广播到 batch_shape + (num_steps, state_dim)。其 .event_shape 可以是任意的。

property has_rsample¶

log_prob(value)[源码]¶

expand(batch_shape, _instance=None)[源码]¶

class GaussianHMM(initial_dist, transition_matrix, transition_dist, observation_matrix, observation_dist, validate_args=None)[源码]¶

基类：FunsorDistribution

使用高斯分布作为初始、转移和观测分布的隐马尔可夫模型。这改编自 [1]，用于在时间上进行并行化以实现 O(log(时间)) 的并行复杂度，但不同之处在于它跟踪对数归一化常数，以确保 log_prob() 是可微分的。

这对应于生成模型

z = initial_distribution.sample()
x = []
for t in range(num_steps):
    z = z @ transition_matrix + transition_dist.sample()
    x.append(z @ observation_matrix + observation_dist.sample())

此分布的 event_shape 在左侧包含时间

event_shape = (num_steps,) + observation_dist.event_shape

此分布支持 transition_dist 和 observation_dist 的齐次/非齐次时间依赖关系的任意组合。但是，由于时间包含在此分布的 event_shape 中，齐次+齐次情况下将拥有一个与 num_steps = 1 可广播的 event_shape，从而允许 log_prob() 处理任意长度的数据。

event_shape = (1, obs_dim)  # homogeneous + homogeneous case

此类应与 pyro.distributions.hmm.GaussianHMM 兼容，此外还支持 funsor 的 伴随 算法。

参考文献

[1] Simo Sarkka, Angel F. Garcia-Fernandez (2019): “贝叶斯滤波器和平滑器的时间并行化” https://arxiv.org/pdf/1905.13002.pdf

变量

hidden_dim (int) – 隐藏状态的维度。
obs_dim (int) – 观测状态的维度。

参数

initial_dist (MultivariateNormal) – 初始状态的分布。其 batch_shape 应可广播到 self.batch_shape。其 event_shape 应为 (hidden_dim,)。
transition_matrix (Tensor) – 隐藏状态的线性变换矩阵。其形状应可广播到 self.batch_shape + (num_steps, hidden_dim, hidden_dim)，其中最右边的维度顺序为 (旧状态, 新状态)。
transition_dist (MultivariateNormal) – 过程噪声分布。其 batch_shape 应可广播到 self.batch_shape + (num_steps,)。其 event_shape 应为 (hidden_dim,)。
observation_matrix – 从隐藏状态到观测状态的线性变换矩阵。其形状应可广播到 self.batch_shape + (num_steps, hidden_dim, obs_dim)。
observation_dist (MultivariateNormal 或 Independent of Normal) – 观测噪声分布。其 batch_shape 应可广播到 self.batch_shape + (num_steps,)。其 event_shape 应为 (obs_dim,)。

has_rsample = True¶

arg_constraints = {}¶

class GaussianMRF(initial_dist, transition_dist, observation_dist, validate_args=None)[源码]¶

基类：FunsorDistribution

使用高斯因子作为初始、转移和观测分布的时间马尔可夫随机场。这改编自 [1]，用于在时间上进行并行化以实现 O(log(时间)) 的并行复杂度，但不同之处在于它跟踪对数归一化常数，以确保 log_prob() 是可微分的。

此分布的 event_shape 在左侧包含时间

event_shape = (num_steps,) + observation_dist.event_shape

此分布支持 transition_dist 和 observation_dist 的齐次/非齐次时间依赖关系的任意组合。但是，由于时间包含在此分布的 event_shape 中，齐次+齐次情况下将拥有一个与 num_steps = 1 可广播的 event_shape，从而允许 log_prob() 处理任意长度的数据。

event_shape = (1, obs_dim)  # homogeneous + homogeneous case

此类应与 pyro.distributions.hmm.GaussianMRF 兼容，此外还支持 funsor 的 伴随 算法。

参考文献

[1] Simo Sarkka, Angel F. Garcia-Fernandez (2019): “贝叶斯滤波器和平滑器的时间并行化” https://arxiv.org/pdf/1905.13002.pdf

变量

hidden_dim (int) – 隐藏状态的维度。
obs_dim (int) – 观测状态的维度。

参数

initial_dist (MultivariateNormal) – 初始状态的分布。其 batch_shape 应可广播到 self.batch_shape。其 event_shape 应为 (hidden_dim,)。
transition_dist (MultivariateNormal) – 表示一对连续时间步长的联合分布因子。其 batch_shape 应可广播到 self.batch_shape + (num_steps,)。其 event_shape 应为 (hidden_dim + hidden_dim,) (旧状态+新状态)。
observation_dist (MultivariateNormal) – 表示隐藏状态和观测状态的联合分布因子。其 batch_shape 应可广播到 self.batch_shape + (num_steps,)。其 event_shape 应为 (hidden_dim + obs_dim,)。

has_rsample = True¶

class SwitchingLinearHMM(initial_logits, initial_mvn, transition_logits, transition_matrix, transition_mvn, observation_matrix, observation_mvn, exact=False, validate_args=None)[源码]¶

基类：FunsorDistribution

表示为隐马尔可夫模型的切换线性动力系统。

这对应于生成模型

z = Categorical(logits=initial_logits).sample()
y = initial_mvn[z].sample()
x = []
for t in range(num_steps):
    z = Categorical(logits=transition_logits[t, z]).sample()
    y = y @ transition_matrix[t, z] + transition_mvn[t, z].sample()
    x.append(y @ observation_matrix[t, z] + observation_mvn[t, z].sample())

视为动态贝叶斯网络

z[t-1] ----> z[t] ---> z[t+1]         Discrete latent class
   |  \       |  \       |   \
   | y[t-1] ----> y[t] ----> y[t+1]   Gaussian latent state
   |   /      |   /      |   /
   V  /       V  /       V  /
x[t-1]       x[t]      x[t+1]         Gaussian observation

令 class 为潜在类别，state 为潜在多变量正态状态，value 为观测多变量正态值。

参数

initial_logits (Tensor) – 表示 p(class[0])。
initial_mvn (MultivariateNormal) – 表示 p(state[0] | class[0])。
transition_logits (Tensor) – 表示 p(class[t+1] | class[t])。
transition_matrix (Tensor) –
transition_mvn (MultivariateNormal) – 与 transition_matrix 一起，这表示 p(state[t], state[t+1] | class[t])。
observation_matrix (Tensor) –
observation_mvn (MultivariateNormal) – 与 observation_matrix 一起，这表示 p(value[t+1], state[t+1] | class[t+1])。
exact (bool) – 如果为 True，执行精确推理，其成本随 num_steps 指数级增长。如果为 False，使用 moment_matching() 近似，并使用并行扫描算法将并行复杂度降低到 num_steps 的对数级。默认为 False。

has_rsample = True¶

arg_constraints = {}¶

log_prob(value)[源码]¶

expand(batch_shape, _instance=None)[源码]¶

filter(value)[源码]¶

给定观测序列，计算最终状态的后验分布。

参数: value (Tensor) – 观测序列。
返回: 最终时间步长潜在状态的后验分布，表示为一对 (cat, mvn)，其中 Categorical 分布在混合分量上，mvn 是一个 MultivariateNormal，其最右边的批量维度范围覆盖混合分量。然后可以用来初始化一个顺序的 Pyro 模型进行预测。
返回类型: tuple

转换工具¶

此模块遵循一套在 funsors 和 PyTorch 分布对象之间进行转换的约定。此约定与 NumPy/PyTorch 风格的广播兼容。遵循 PyTorch 分布（和 Tensorflow 分布），我们认为“event shapes”在右侧，而可广播的“batch shapes”在左侧。

此模块还在输入方面力求宽松，在输出方面力求严谨：方法接受超类 torch.distributions.Distribution 对象或子类 pyro.distributions.TorchDistribution 对象。方法只返回更具体的子类 pyro.distributions.TorchDistribution 对象。

tensor_to_funsor(tensor, event_inputs=(), event_output=0, dtype='real')[源码]¶

将 torch.Tensor 转换为 funsor.tensor.Tensor 。

注意，这不应触及数据，但可能会触发一个 torch.Tensor.reshape() 操作。

参数

tensor (torch.Tensor) – 一个 PyTorch 张量。
event_inputs (tuple) – 最右边张量维度的名称元组。如果 tensor 具有这些名称，它们将被转换为 result.inputs。
event_output (int) – 分配给 result.output 的张量维度数量。这些维度必须位于任何 event_input 维度的右侧。

返回

一个 funsor。

返回类型

funsor.tensor.Tensor

funsor_to_tensor(funsor_, ndims, event_inputs=())[源码]¶

将 funsor.tensor.Tensor 转换为 torch.Tensor 。

注意，这不应触及数据，但可能会触发一个 torch.Tensor.reshape() 操作。

参数

funsor (funsor.tensor.Tensor) – 一个 funsor。
ndims (int) – 结果的维度数量，== result.dim()。
event_inputs (tuple) – 分配给最右边维度的名称。

返回

一个 PyTorch 张量。

返回类型

torch.Tensor

dist_to_funsor(pyro_dist, event_inputs=())[源码]¶

将 PyTorch 分布转换为 Funsor。

参数: torch.distribution.Distribution – 一个 PyTorch 分布。
返回: 一个 funsor。
返回类型: funsor.terms.Funsor

mvn_to_funsor(pyro_dist, event_inputs=(), real_inputs={})[源码]¶

将联合的 torch.distributions.MultivariateNormal 分布转换为具有多个实数输入的 Funsor。

这应满足

sum(d.num_elements for d in real_inputs.values())
  == pyro_dist.event_shape[0]

参数

pyro_dist (torch.distributions.MultivariateNormal) – 一个多变量正态分布，作用于一个或多个实数、向量或张量类型的变量。
event_inputs (tuple) – 最右边维度的名称元组。这些将被分配到类型为 Bint 的 result.inputs。
real_inputs (OrderedDict) – 一个字典，将实数变量名称映射到适当大小的 Real。所有实数输入的 .numel() 总和应等于 pyro_dist 的维度。

返回

一个具有给定 real_inputs 和可能额外 Bint 输入的 funsor。

返回类型

funsor.terms.Funsor

funsor_to_mvn(gaussian, ndims, event_inputs=())[源码]¶

将 Funsor 转换为 pyro.distributions.MultivariateNormal ，忽略归一化常数。

参数

gaussian (funsor.gaussian.Gaussian 或 funsor.joint.Joint) – 一个高斯 funsor。
ndims (int) – 结果中的批量维度数量。
event_inputs (tuple) – 分配给最右边维度的名称元组。

返回

一个多变量正态分布。

返回类型

pyro.distributions.MultivariateNormal

funsor_to_cat_and_mvn(funsor_, ndims, event_inputs)[源码]¶

将带标签的高斯混合模型转换为一对分布。

参数

funsor (funsor.joint.Joint) – 一个高斯混合 funsor。
ndims (int) – 结果中的批量维度数量。

返回

一对 (cat, mvn)，其中 cat 是在混合分量上的 Categorical 分布，mvn 是一个 MultivariateNormal，其最右边的批量维度范围覆盖混合分量。

matrix_and_mvn_to_funsor(matrix, mvn, event_dims=(), x_name='value_x', y_name='value_y')[源码]¶

将带噪声的仿射函数转换为高斯分布。带噪声的仿射函数定义为

y = x @ matrix + mvn.sample()

结果是一个非归一化的高斯 funsor，具有两个实数输入 x_name 和 y_name，对应于给定实数向量 x` 时，实数向量 y` 的条件分布。

参数

matrix (torch.Tensor) – 一个矩阵，其最右边的形状为 (x_size, y_size)。
mvn (torch.distributions.MultivariateNormal 或 torch.distributions.Independent of torch.distributions.Normal) – 一个多变量正态分布，其 event_shape == (y_size,)。
event_dims (tuple) – 最右边维度的名称元组。这些将被分配到类型为 Bint 的 result.inputs。
x_name (str) – 随机变量 x 的名称。
y_name (str) – 随机变量 y 的名称。

返回

一个具有给定 real_inputs 和可能额外 Bint 输入的 funsor。

返回类型

funsor.terms.Funsor