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) 算法的包装类。特定的 MCMC 算法是 TraceKernel 的实例，需要作为 kernel 参数提供给构造函数。

注意

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

参数

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()

参数

args – MCMCKernel.setup 接收的可选位置参数。
kwargs – MCMCKernel.setup 接收的可选关键字参数。

summary(prob=0.9)[source]¶

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

参数: prob (float) – 置信区间内样本的概率质量。

StreamingMCMC¶

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)[source]¶

基类: pyro.infer.mcmc.api.AbstractMCMC

StreamingMCMC 以流式方式计算所需的统计信息。此类不保留样本，仅保留汇总统计信息。这对于运行内存密集型模型很有用，尤其是当您只关心特定统计信息时（在 GPU 等内存受限环境中特别有用）。

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

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

get_statistics(group_by_chain=True)[source]¶

返回一个字典，其中包含传递给类构造函数时定义的统计信息。

参数: group_by_chain (bool) – 统计信息是按链计算还是合并在一起。

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

MCMCKernel¶

class MCMCKernel[source]¶

基类: object

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

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

end_warmup()[source]¶: 可选方法，通知核热身阶段已完成。

property initial_params¶

返回一个包含初始参数（默认为先验分布中的参数）的字典，用于启动 MCMC 运行。

返回: 参数值字典，键为参数名称。

logging()[source]¶

在 MCMC 运行的固定间隔打印相关的日志信息。默认为 None。

返回: 包含诊断摘要的字符串。例如，接受率
返回类型: 字符串

abstract sample(params)[source]¶

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

参数

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

返回

来自后验分布的新参数。

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

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

参数

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)[source]¶

基类: pyro.infer.mcmc.mcmc_kernel.MCMCKernel

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

参考文献

[1] MCMC Using Hamiltonian Dynamics，Radford M. Neal

参数

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) – 一个标志，决定是否在热身阶段使用对偶平均方案自适应调整 step_size。
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 (NUTS) 核，提供了一种高效便捷的运行哈密尔顿蒙特卡洛的方法。积分器在每次调用 sample 时动态调整步数，以确保哈密尔顿轨迹的最佳长度 [1]。因此，生成的样本通常比 HMC 核生成的样本具有更低的自相关性。可选地，NUTS 核还提供了在热身阶段自适应调整步长的能力。

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

参考文献

[1] The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo，: Matthew D. Hoffman 和 Andrew Gelman。
[2] A Conceptual Introduction to Hamiltonian Monte Carlo，: Michael Betancourt
[3] Slice Sampling，: Radford M. Neal

参数

model – 包含 Pyro 基本元素的 Python 可调用对象。
potential_fn – Python 可调用对象，计算势能，输入是实数支持参数的字典。
step_size (float) – 决定 Verlet 积分器在使用哈密尔顿动力学计算轨迹时单步的大小。如果未指定，将设置为 1。
adapt_step_size (bool) – 一个标志，决定是否在热身阶段使用对偶平均方案自适应调整 step_size。
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]¶

RandomWalkKernel¶

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

基类: pyro.infer.mcmc.mcmc_kernel.MCMCKernel

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

参数

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]¶

BlockMassMatrix¶

class BlockMassMatrix(init_scale=1.0)[source]¶

基类: object

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

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

参数: init_scale (float) – 用于构建初始质量矩阵的初始尺度。

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

设置初始质量矩阵。

参数

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

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

property inverse_mass_matrix¶

kinetic_grad(r)[source]¶

计算动能关于动量 r 的梯度。这等价于计算给定动量 r 的速度。

参数: r (dict) – 一个字典，将位点名称映射到张量动量。
返回: 一个字典，将位点名称映射到相应的梯度

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

scale(r_unscaled, r_prototype)[source]¶

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

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

参数

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

返回

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

unscale(r)[source]¶

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

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

参数: r (dict) – 一个字典，将位点名称映射到张量动量。
返回: 一个字典，将位点名称映射到相应的张量

update(z, z_grad)[source]¶

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

参数

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 中消耗采样参数的轨迹。

参数

model – 一个包含 Pyro 基本元素的 Pyro 模型。
model_args (tuple) – model 接收的可选位置参数。
model_kwargs (dict) – model 接收的可选关键字参数。
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) – 包含无约束空间中用于启动马尔可夫链的初始张量的字典。

返回

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

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

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

参数

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

返回

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

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

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

参数

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

返回

样本字典，键为位点名称。