MCMC¶

class MCMC(kernel, num_samples, warmup_steps=None, initial_params=None, num_chains=1, hook_fn=None, mp_context=None, disable_progbar=False, disable_validation=True, transforms=None, save_params=None)[source]¶

基础类：pyro.infer.mcmc.api.AbstractMCMC

马尔可夫链蒙特卡罗算法的包装类。具体的MCMC算法是TraceKernel实例，需要作为kernel参数提供给构造函数。

注意

当num_chains > 1时，使用python多进程来在多个进程中运行并行链。这伴随着python中多进程的常见注意事项，例如用于初始化kernel的模型必须可以通过pickle序列化，并且性能/约束将依赖于平台（例如，在Windows中只有“spawn”上下文可用）。这在Windows平台上也没有经过广泛的测试。

Parameters

kernel – TraceKernel 类的一个实例，当给定一个执行轨迹时，它会从目标（后验）分布中返回另一个样本轨迹。
num_samples (int) – 需要生成的样本数量，不包括在预热阶段丢弃的样本。
warmup_steps (int) – 预热迭代次数。在预热阶段生成的样本将被丢弃。如果未提供，默认值与num_samples相同。
num_chains (int) – 并行运行的MCMC链的数量。根据num_chains是1还是大于1，这个类内部会分派到_UnarySampler或_MultiSampler。
initial_params (dict) – 包含在无约束空间中用于启动马尔可夫链的初始张量的字典。前导维度的大小必须与num_chains的大小匹配。如果未指定，参数值将从先验中采样。
hook_fn – 一个Python可调用对象，接受(kernel, samples, stage, i)作为参数。stage可以是sample或warmup，i表示给定阶段的第i个样本。这可以用于实现额外的日志记录，或者更一般地，为每个生成的样本运行任意代码。
mp_context (str) – 当num_chains > 1时使用的多进程上下文。仅适用于Python 3.5及以上版本。对于CUDA，请使用mp_context=”spawn”。
disable_progbar (bool) – 禁用进度条和诊断更新。
disable_validation (bool) – 禁用分布验证检查。默认为 True，禁用验证，因为不同的转换将导致异常。切换到 False 以启用验证，或切换到 None 以保留现有的全局值。
transforms (dict) – 字典，指定了从受限空间到无约束空间的样本点的转换。
save_params (List[str]) – 可选的参数名称子集列表，用于在采样和诊断期间保存。这在具有大量无关变量的模型中非常有用。默认为None，保存所有参数。

diagnostics()[source]¶: 获取一些诊断统计信息，例如有效样本量、分裂 Gelman-Rubin，或采样器中的发散转换。

get_samples(num_samples=None, group_by_chain=False)[source]¶

从MCMC运行中获取样本，可能会进行有放回的重新采样。

有关参数详情，请参见：select_samples。

run(*args, **kwargs)[source]¶

运行MCMC以生成样本并填充self._samples。

示例用法：

def model(data):
    ...

nuts_kernel = NUTS(model)
mcmc = MCMC(nuts_kernel, num_samples=500)
mcmc.run(data)
samples = mcmc.get_samples()

Parameters

args – 由 MCMCKernel.setup 接受的可选参数。
kwargs – 可选的由 MCMCKernel.setup 接受的关键字参数。

summary(prob=0.9)[source]¶

打印一个汇总表，显示从后验获得的样本的诊断信息。显示的诊断信息包括均值、标准差、中位数、90%可信区间、effective_sample_size()、split_gelman_rubin()。

Parameters: prob (float) – 可信区间内样本的概率质量。

流式MCMC¶

class StreamingMCMC(kernel, num_samples, warmup_steps=None, initial_params=None, statistics=None, num_chains=1, hook_fn=None, disable_progbar=False, disable_validation=True, transforms=None, save_params=None)[源代码]¶

基础类：pyro.infer.mcmc.api.AbstractMCMC

MCMC以流式方式计算所需的统计量。对于此类，不保留样本，只保留聚合统计量。这对于运行内存消耗大的模型非常有用，我们只关心特定的统计量（特别是在内存受限的环境中，如GPU）。

有关可用的流操作，请参见 streaming。

diagnostics()[source]¶: 获取诊断信息。目前仅支持分割的Gelman-Rubin，并且需要存在'mean'和'variance'流式统计量。

get_statistics(group_by_chain=True)[source]¶

返回由传递给类构造函数的统计信息定义的字典。

Parameters: group_by_chain (bool) – 统计是否应按链进行或合并在一起。

run(*args, **kwargs)[source]¶: 运行StreamingMCMC以计算所需的self._statistics。

MCMCKernel¶

class MCMCKernel[源代码]¶

基础类：object

cleanup()[source]¶: 可选方法，用于在终止时清理任何残留状态。

diagnostics()[source]¶: 在完成采样过程后返回一个包含有用诊断信息的字典。

end_warmup()[source]¶: 可选方法，用于告诉内核预热阶段已经完成。

property initial_params¶

返回一个初始参数的字典（默认情况下，来自先验）以启动MCMC运行。

Returns: 参数值的字典，按名称键控。

logging()[source]¶

在MCMC运行期间定期打印相关的日志信息。默认返回None。

Returns: 包含诊断摘要的字符串。例如，接受率
Return type: 字符串

abstract sample(params)[来源]¶

当给定现有参数时，从后验分布中采样参数。

Parameters

params (dict) – 当前参数值。
time_step (int) – 当前时间步。

Returns

来自后验分布的新参数。

setup(warmup_steps, *args, **kwargs)[源代码]¶

可选方法，用于设置模拟运行开始时所需的任何状态。

Parameters

warmup_steps (int) – 预热迭代次数。
*args – 算法特定的位置参数。
**kwargs – 算法特定的关键字参数。

HMC¶

class HMC(model=None, potential_fn=None, step_size=1, trajectory_length=None, num_steps=None, adapt_step_size=True, adapt_mass_matrix=True, full_mass=False, transforms=None, max_plate_nesting=None, jit_compile=False, jit_options=None, ignore_jit_warnings=False, target_accept_prob=0.8, init_strategy=<function init_to_uniform>, *, min_stepsize: float = 1e-10, max_stepsize: float = 10000000000.0)[源代码]¶

基础类：pyro.infer.mcmc.mcmc_kernel.MCMCKernel

简单的哈密顿蒙特卡洛核，其中step_size和num_steps需要由用户明确指定。

参考文献

[1] 使用哈密顿动力学的MCMC, Radford M. Neal

Parameters

model – 包含Pyro原语的Python可调用对象。
potential_fn – Python 可调用对象，用于计算势能，输入为真实支持参数的字典。
step_size (float) – 确定在使用哈密顿动力学计算轨迹时，verlet积分器所采取的单个步长的大小。如果未指定，它将设置为1。
trajectory_length (float) – MCMC轨迹的长度。如果未指定，它将设置为step_size x num_steps。如果未指定num_steps，它将设置为\(2\pi\)。
num_steps (int) – 模拟哈密顿动力学的离散步数。轨迹结束时的状态将作为提议返回。该值始终等于int(trajectory_length / step_size)。
adapt_step_size (bool) – 一个标志，用于决定我们是否希望在预热阶段使用双平均方案来调整步长。
adapt_mass_matrix (bool) – 一个标志，用于决定我们是否希望在预热阶段使用Welford方案来调整质量矩阵。
full_mass (bool) – 一个标志，用于决定质量矩阵是密集的还是对角的。
transforms (dict) – 可选的字典，用于指定将具有约束支持的样本站点转换为无约束空间的变换。该变换应该是可逆的，并且实现log_abs_det_jacobian。如果未指定且模型具有约束支持的站点，将应用自动变换，如torch.distributions.constraint_registry中所指定的。
max_plate_nesting (int) – 可选的最大嵌套次数限制 pyro.plate() 上下文。如果模型包含可以并行枚举的离散采样点，则需要此参数。
jit_compile (bool) – 可选参数，表示是否使用PyTorch JIT来跟踪对数密度计算，并在积分器中使用此优化的可执行跟踪。
jit_options (dict) – 一个包含可选参数的字典，用于 torch.jit.trace() 函数。
ignore_jit_warnings (bool) – 当jit_compile=True时，忽略JIT跟踪器的警告的标志。默认值为False。
target_accept_prob (float) – 增加此值将导致步长变小，因此采样将更慢且更稳健。默认为0.8。
init_strategy (callable) – 每个站点的初始化函数。有关可用函数，请参见初始化部分。
min_stepsize (float) – 适应策略中步长的下限。
max_stepsize (float) – 适应策略中步长的上限。

注意

在内部，质量矩阵将根据潜在变量的名称顺序进行排序，而不是它们在模型中出现的顺序。

示例

>>> true_coefs = torch.tensor([1., 2., 3.])
>>> data = torch.randn(2000, 3)
>>> dim = 3
>>> labels = dist.Bernoulli(logits=(true_coefs * data).sum(-1)).sample()
>>>
>>> def model(data):
...     coefs_mean = torch.zeros(dim)
...     coefs = pyro.sample('beta', dist.Normal(coefs_mean, torch.ones(3)))
...     y = pyro.sample('y', dist.Bernoulli(logits=(coefs * data).sum(-1)), obs=labels)
...     return y
>>>
>>> hmc_kernel = HMC(model, step_size=0.0855, num_steps=4)
>>> mcmc = MCMC(hmc_kernel, num_samples=500, warmup_steps=100)
>>> mcmc.run(data)
>>> mcmc.get_samples()['beta'].mean(0)  
tensor([ 0.9819,  1.9258,  2.9737])

cleanup()[source]¶

clear_cache()[source]¶

diagnostics()[source]¶

property initial_params¶

property inverse_mass_matrix¶

logging()[source]¶

property mass_matrix_adapter¶

property num_steps¶

sample(params)[source]¶

setup(warmup_steps, *args, **kwargs)[source]¶

property step_size¶

NUTS¶

class NUTS(model=None, potential_fn=None, step_size=1, adapt_step_size=True, adapt_mass_matrix=True, full_mass=False, use_multinomial_sampling=True, transforms=None, max_plate_nesting=None, jit_compile=False, jit_options=None, ignore_jit_warnings=False, target_accept_prob=0.8, max_tree_depth=10, init_strategy=<function init_to_uniform>)[source]¶

基础类: pyro.infer.mcmc.hmc.HMC

No-U-Turn Sampler 内核，提供了一种高效便捷的运行哈密顿蒙特卡洛的方法。积分器在每次调用 sample 时动态调整步数，以确保哈密顿轨迹的最佳长度 [1]。因此，生成的样本通常比由 HMC 内核生成的样本具有更低的自相关性。可选地，NUTS 内核还提供了在预热阶段调整步长的能力。

参考棒球示例，了解如何在Pyro中使用NUTS进行贝叶斯推断。

参考文献

[1] The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo,: 马修·D·霍夫曼和安德鲁·格尔曼。
[2] A Conceptual Introduction to Hamiltonian Monte Carlo,: 迈克尔·贝坦科特
[3] Slice Sampling,: 拉德福德·M·尼尔

Parameters

model – 包含Pyro原语的Python可调用对象。
potential_fn – Python 可调用对象，用于计算势能，输入为真实支持参数的字典。
step_size (float) – 确定在使用哈密顿动力学计算轨迹时，verlet积分器所采取的单个步长的大小。如果未指定，它将设置为1。
adapt_step_size (bool) – 一个标志，用于决定我们是否希望在预热阶段使用双平均方案来调整步长。
adapt_mass_matrix (bool) – 一个标志，用于决定我们是否希望在预热阶段使用Welford方案来调整质量矩阵。
full_mass (bool) – 一个标志，用于决定质量矩阵是密集的还是对角的。
use_multinomial_sampling (bool) – 一个标志，用于决定我们是否要使用“多项式采样”或“切片采样”来沿着其轨迹采样候选者。切片采样在原始的NUTS论文[1]中使用，而多项式采样在[2]中建议。默认情况下，此标志设置为True。如果设置为False，NUTS将使用切片采样。
transforms (dict) – 可选的字典，用于指定将具有约束支持的样本站点转换为无约束空间的变换。该变换应该是可逆的，并且实现log_abs_det_jacobian。如果未指定且模型具有约束支持的站点，将应用自动变换，如torch.distributions.constraint_registry中所指定的。
max_plate_nesting (int) – 可选的最大嵌套次数限制 pyro.plate() 上下文。如果模型包含可以并行枚举的离散采样点，则需要此参数。
jit_compile (bool) – 可选参数，表示是否使用PyTorch JIT来跟踪对数密度计算，并在积分器中使用此优化的可执行跟踪。
jit_options (dict) – 一个包含可选参数的字典，用于 torch.jit.trace() 函数。
ignore_jit_warnings (bool) – 当jit_compile=True时，忽略JIT跟踪器的警告的标志。默认值为False。
target_accept_prob (float) – 步长适应方案的目标接受概率。增加此值将导致步长变小，因此采样会更慢但更稳健。默认为0.8。
max_tree_depth (int) – NUTS采样器的倍增方案期间创建的二叉树的最大深度。默认为10。
init_strategy (callable) – 每个站点的初始化函数。有关可用函数，请参见初始化部分。

示例

>>> true_coefs = torch.tensor([1., 2., 3.])
>>> data = torch.randn(2000, 3)
>>> dim = 3
>>> labels = dist.Bernoulli(logits=(true_coefs * data).sum(-1)).sample()
>>>
>>> def model(data):
...     coefs_mean = torch.zeros(dim)
...     coefs = pyro.sample('beta', dist.Normal(coefs_mean, torch.ones(3)))
...     y = pyro.sample('y', dist.Bernoulli(logits=(coefs * data).sum(-1)), obs=labels)
...     return y
>>>
>>> nuts_kernel = NUTS(model, adapt_step_size=True)
>>> mcmc = MCMC(nuts_kernel, num_samples=500, warmup_steps=300)
>>> mcmc.run(data)
>>> mcmc.get_samples()['beta'].mean(0)  
tensor([ 0.9221,  1.9464,  2.9228])

sample(params)[source]¶

随机游走核¶

class RandomWalkKernel(model, init_step_size: float = 0.1, target_accept_prob: float = 0.234)[source]¶

基础类：pyro.infer.mcmc.mcmc_kernel.MCMCKernel

简单的无梯度核，利用模型无约束潜在空间中的各向同性高斯随机游走。控制核方差的步长在预热期间通过一个简单的适应方案进行调整，该方案针对用户提供的接受概率。

Parameters

model – 包含Pyro原语的Python可调用对象。
init_step_size (float) – 一个正浮点数，用于控制初始步长。默认为0.1。
target_accept_prob (float) – 用于步长调整的目标接受概率。默认为0.234。

示例

>>> true_coefs = torch.tensor([1., 2., 3.])
>>> data = torch.randn(2000, 3)
>>> dim = 3
>>> labels = dist.Bernoulli(logits=(true_coefs * data).sum(-1)).sample()
>>>
>>> def model(data):
...     coefs_mean = torch.zeros(dim)
...     coefs = pyro.sample('beta', dist.Normal(coefs_mean, torch.ones(3)))
...     y = pyro.sample('y', dist.Bernoulli(logits=(coefs * data).sum(-1)), obs=labels)
...     return y
>>>
>>> hmc_kernel = RandomWalkKernel(model, init_step_size=0.2)
>>> mcmc = MCMC(hmc_kernel, num_samples=200, warmup_steps=100)
>>> mcmc.run(data)
>>> mcmc.get_samples()['beta'].mean(0)  
tensor([ 0.9819,  1.9258,  2.9737])

diagnostics()[source]¶

property initial_params¶

logging()[source]¶

sample(params)[source]¶

setup(warmup_steps, *args, **kwargs)[source]¶

块质量矩阵¶

class BlockMassMatrix(init_scale=1.0)[source]¶

基础类：object

实验性此类用于调整（逆）质量矩阵，并提供有用的方法来计算涉及质量矩阵的代数项。

质量矩阵将具有块结构，可以通过使用configure()方法与相应的结构化mass_matrix_shape参数来指定。

Parameters: init_scale (float) – 用于构建初始质量矩阵的初始比例。

configure(mass_matrix_shape, adapt_mass_matrix=True, options={})[source]¶

设置初始质量矩阵。

Parameters

mass_matrix_shape (dict) – 一个将站点名称的元组映射到相应质量矩阵形状的字典。每个站点名称的元组对应一个块。
adapt_mass_matrix (bool) – 一个标志，用于决定是否使用适应方案。
options (dict) – 用于构建初始质量矩阵的张量选项。

end_adaptation()[source]¶: 使用适应方案更新当前的质量矩阵。

property inverse_mass_matrix¶

kinetic_grad(r)[source]¶

计算动能相对于动量r的梯度。它等同于在给定动量r的情况下计算速度。

Parameters: r (dict) – 一个将站点名称映射到张量动量的字典。
Returns: 字典将站点名称映射到相应的梯度

property mass_matrix_size¶: 一个字典，将站点名称映射到相应质量矩阵的大小。

scale(r_unscaled, r_prototype)[source]¶

计算 M^{1/2} @ r_unscaled。

请注意，r 是从具有尺度 mass_matrix_sqrt 的高斯分布生成的。此方法将对其进行缩放。

Parameters

r_unscaled (dict) – 一个将站点名称映射到张量动量的字典。
r_prototype (dict) – 一个将站点名称映射到原型动量的字典。这些原型值用于获取缩放版本的形状。

Returns

一个字典将站点名称映射到相应的张量

unscale(r)[来源]¶

计算 inv(M^{1/2}) @ r。

请注意，r 是从具有尺度 mass_matrix_sqrt 的高斯分布生成的。此方法将对其进行去尺度化。

Parameters: r (dict) – 一个将站点名称映射到张量动量的字典。
Returns: 一个字典将站点名称映射到相应的张量

update(z, z_grad)[source]¶

使用新样本z或其梯度z_grad更新适应方案。

Parameters

z (dict) – 当前值。
z_grad (dict) – 当前值的梯度。

实用工具¶

initialize_model(model, model_args=(), model_kwargs={}, transforms=None, max_plate_nesting=None, jit_compile=False, jit_options=None, skip_jit_warnings=False, num_chains=1, init_strategy=<function init_to_uniform>, initial_params=None)[source]¶

给定一个带有Pyro原语的Python可调用对象，生成以下使用HMC/NUTS内核进行推理所需的模型特定属性：

使用HMC核采样的初始参数，
一个潜在函数，其输入是无约束空间中的参数字典，
将model的潜在位置转换为无约束空间，
一个原型跟踪，用于MCMC以消耗来自采样参数的跟踪。

Parameters

model – 一个包含Pyro原语的Pyro模型。
model_args (tuple) – 可选的由model接受的参数。
model_kwargs (dict) – 可选的由model接受的kwargs。
transforms (dict) – 可选的字典，用于指定将具有约束支持的样本站点转换为无约束空间的变换。该变换应该是可逆的，并且实现log_abs_det_jacobian。如果未指定且模型具有约束支持的站点，将应用自动变换，如torch.distributions.constraint_registry中所指定的。
max_plate_nesting (int) – 可选的最大嵌套次数限制 pyro.plate() 上下文。如果模型包含可以并行枚举的离散采样点，则需要此参数。
jit_compile (bool) – 可选参数，表示是否使用PyTorch JIT来跟踪对数密度计算，并在积分器中使用此优化的可执行跟踪。
jit_options (dict) – 一个包含可选参数的字典，用于 torch.jit.trace() 函数。
ignore_jit_warnings (bool) – 当jit_compile=True时，忽略JIT跟踪器的警告的标志。默认值为False。
num_chains (int) – 并行链的数量。如果 num_chains > 1，返回的 initial_params 将是一个包含 num_chains 个元素的列表。
init_strategy (callable) – 每个站点的初始化函数。有关可用函数，请参见初始化部分。
initial_params (dict) – 包含在无约束空间中初始张量的字典，用于启动马尔可夫链。

Returns

一个元组，包含 (initial_params, potential_fn, transforms, prototype_trace)

diagnostics(samples, group_by_chain=True)[source]¶

获取诊断统计信息，例如从后验分布中抽取的样本的有效样本量和分裂Gelman-Rubin。

Parameters

样本 (dict) – 按站点名称键控的样本字典。
group_by_chain (bool) – 如果为True，samples中的每个变量将被视为具有形状num_chains x num_samples x sample_shape。否则，相应的形状将为num_samples x sample_shape（即没有链维度）。

Returns

每个采样点的诊断统计信息字典。

select_samples(samples, num_samples=None, group_by_chain=False)[source]¶

从给定的MCMC样本中执行选择。

Parameters

样本 (字典) – 从中采样的样本对象。
num_samples (int) – 要返回的样本数量。如果为None，则返回MCMC链中的所有样本，并保持其原始顺序。
group_by_chain (bool) – 是否保留链维度。如果为True，所有样本将具有num_chains作为其前导维度的大小。

Returns

按站点名称索引的样本字典。