PyMC 概率分布 API 全景指南：从 Continuous 到 CustomDist 的建模工具箱

PyMC 概率分布 API 全景指南从 Continuous 到 CustomDist 的建模工具箱【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc导读docs/source/api/distributions.rst是 PyMC 官方 API 文档的分布模块入口它系统性地组织了整个pymc.distributions子包从连续、离散、多元、混合分布到时序分布、截断/审查分布、自定义分布再到分布变换与工具类。本文以该文档为骨架结合 pymc/distributions 目录下的源码实现为你梳理每一个分布家族的核心用途、关键参数与底层机制帮助你快速定位建模所需的概率分布并理解 PyMC 分布系统的设计哲学。一、分布 API 的整体架构distributions.rst通过 Sphinxtoctree将分布模块组织为 11 个类别每个类别对应一个独立的 API 子页面文档页面相对路径覆盖范围Continuousdistributions/continuous.rst32 个连续分布Discretedistributions/discrete.rst12 个离散分布Multivariatedistributions/multivariate.rst16 个多元分布Mixturedistributions/mixture.rst8 个混合/零膨胀/障碍分布Timeseriesdistributions/timeseries.rst5 个时序分布Truncateddistributions/truncated.rstTruncated截断分布Censoreddistributions/censored.rstCensored审查分布CustomDistdistributions/custom.rstCustomDist自定义分布Simulatordistributions/simulator.rstSimulator仿真分布Transformsdistributions/transforms.rst分布变换体系Utilitiesdistributions/utilities.rst分布基类与工具所有 API 页面均采用autosummary distribution.rst 模板 自动生成每个分布的详细文档这意味着每个分布类在 pymc/distributions 中的 docstring 即是最权威的参考。下面逐一展开每个类别。二、连续分布Continuous从 Normal 到 SkewStudentT连续分布是贝叶斯建模中使用最频繁的分布家族continuous.rst 列出了 32 个成员AsymmetricLaplace、Beta、Cauchy、ChiSquared、ExGaussian、Exponential、Flat、Gamma、Gumbel、HalfCauchy、HalfFlat、HalfNormal、HalfStudentT、Interpolated、InverseGamma、Kumaraswamy、Laplace、Logistic、LogitNormal、LogNormal、Moyal、Normal、Pareto、PolyaGamma、Rice、SkewNormal、SkewStudentT、StudentT、Triangular、TruncatedNormal、Uniform、VonMises、Wald、Weibull这些类均实现在 pymc/distributions/continuous.py 中。以最核心的Normal为例其类定义位于该文件第 445 行继承自Continuous基类class Normal(Continuous):在使用上PyMC 分布类遵循统一的构造约定——在模型上下文中直接实例化参数既可以是数值也可以是随机变量import pymc as pm with pm.Model() as model: # 位置-尺度参数化 mu pm.Normal(mu, mu0, sigma10) sigma pm.HalfNormal(sigma, sigma1) # 观测似然 y pm.Normal(y, mumu, sigmasigma, observeddata)源码中值得注意的几个特殊连续分布Interpolated第 3856 行BoundedContinuous允许用户用任意一组(x_points, pdf_points)来定义近似分布常用于将经验密度如从历史 MCMC 后验中提取的密度直接作为先验。Kumaraswamy第 1317 行UnitContinuous单位区间上的双参数分布可作为 Beta 的替代先验。PolyaGamma第 4140 行PositiveContinuousPolya-Gamma 分布常用于逻辑回归的辅助变量采样。Rice第 3538 行PositiveContinuousRice 分布用于幅度衰落类建模。SkewStudentT第 2001 行带偏度的 Student-t适合厚尾且有偏的数据。这些类通过Continuous基类统一获得random、logp等核心方法并与 PyMC 的采样器、变分推断无缝集成。三、离散分布Discrete从 Bernoulli 到 OrderedLogisticdiscrete.rst 列出 12 个离散分布Bernoulli、BetaBinomial、Binomial、Categorical、DiscreteUniform、DiscreteWeibull、Geometric、HyperGeometric、NegativeBinomial、OrderedLogistic、OrderedProbit、Poisson这些类实现在 pymc/distributions/discrete.py。典型用法with pm.Model() as model: p pm.Beta(p, alpha1, beta1) # 二项观测 k pm.Binomial(k, n100, pp, observedsuccesses) # 泊松计数 rate pm.Exponential(rate, lam1) count pm.Poisson(count, murate, observeddata)文档中特别标注的注意事项必须严格遵守OrderedLogistic 与 OrderedProbit这两个分布期望观测值为 0 基索引即取值范围应为0到K-1。如果使用 1 基索引如1, 2, 3, ..., K会导致错误。这是因为底层实现将类别编码为0..K-1的整数配合累积概率阈值cutpoints计算有序分类的似然。在建模有序量表如问卷等级 1–5时务必先对观测值做observed - 1的偏移。四、多元分布Multivariate向量与矩阵随机变量multivariate.rst 列出 16 个多元分布实现在 pymc/distributions/multivariate.py分布源码类定义位置典型用途MvNormal第 188 行多元正态向量观测建模Dirichlet第 515 行SimplexContinuous类别概率先验定义于单纯形上Wishart/WishartBartlett第 983 行协方差矩阵先验LKJCholeskyCov/LKJCorr第 1578 行相关矩阵先验推荐替代 WishartMatrixNormal—矩阵正态Multinomial/DirichletMultinomial—多项计数 / 过度离散计数CAR/ICAR第 2160 / 2315 行空间自回归先验区域统计建模KroneckerNormal—张量积结构的多元正态StickBreakingWeights—截断的 Stick-Breaking 过程DP 混合OrderedMultinomial—有序多项响应ZeroSumNormal—和为零约束的多元正态MvStudentT—多元 Student-t典型示例——分层模型中的多元正态与 LKJ 相关矩阵with pm.Model() as model: # 随机效应协方差矩阵LKJ 先验 chol, corr, stds pm.LKJCholeskyCov( chol, nK, eta2.0, sd_distpm.HalfCauchy.dist(beta2.5) ) betas pm.MvNormal(betas, munp.zeros(K), cholchol, shape(n_groups, K))从源码结构可以推断多元分布普遍基于Continuous基类并叠加形状约束如SimplexContinuous、BoundedContinuous配合 PyTensor 的矩阵运算实现因而在shape语义上支持批量维度与dims命名维度。五、混合与计数分布MixtureMixture、零膨胀与 Hurdlemixture.rst 列出 8 个成员实现在 pymc/distributions/mixture.pyMixture、NormalMixture、ZeroInflatedBinomial、ZeroInflatedNegativeBinomial、ZeroInflatedPoisson、HurdlePoisson、HurdleNegativeBinomial、HurdleGamma、HurdleLogNormal其中核心类Mixture的类定义位于第 356 行继承_BaseMixtureDistribution。Mixture允许将任意分布族按权重混合with pm.Model() as model: w pm.Dirichlet(w, anp.ones(2)) mu pm.Normal(mu, mu[-2, 2], sigma1) # 双峰混合 y pm.Mixture(y, ww, comp_distspm.Normal.dist(mumu, sigma1), observeddata)NormalMixture是高斯混合的便捷封装自动处理均值偏移的重新参数化以改善采样。零膨胀族ZeroInflated*用于「结构零 计数过程」的数据如过量零的销售记录Hurdle 族则把「零与非零」拆成两个独立机制适合零膨胀且零机制与计数机制参数解耦的场景。六、时序分布TimeseriesAR、GARCH11 与随机游走timeseries.rst 列出 5 个时序分布实现在 pymc/distributions/timeseries.py分布源码类定义位置说明GaussianRandomWalk第 300 行PredefinedRandomWalk高斯随机游走先验AR第 511 行自回归过程GARCH11第 782 行GARCH(1,1) 波动率模型EulerMaruyama第 934 行随机微分方程的欧拉-丸山离散MvGaussianRandomWalk/MvStudentTRandomWalk—多元随机游走典型应用——局部水平模型随机游走先验with pm.Model() as model: sigma pm.HalfNormal(sigma, sigma1) level pm.GaussianRandomWalk(level, sigmasigma, shapelen(data)) obs pm.Normal(obs, mulevel, sigmatau, observeddata)AR分布通过自回归系数与白噪声项构造条件均值GARCH11则对条件方差建模金融波动率EulerMaruyama将连续时间 SDE 离散化后与观测似然连接使 PyMC 能够直接拟合扩散过程。七、截断与审查分布Truncated 与 Censored这两个类对应的 API 页面都采用手动模板参照 distribution.rst 模板并仅暴露dist类方法Truncatedtruncated.rst类实现在 pymc/distributions/truncated.py 第 279 行对任意分布在其支撑集内部施加lower/upper边界截断。与TruncatedNormal不同Truncated是通用的「分布包装器」with pm.Model() as model: # 在 [0, 10] 上截断的指数分布 x pm.Truncated(x, distpm.Exponential.dist(lam0.5), lower0, upper10)Censoredcensored.rst类实现在 pymc/distributions/censored.py 第 79 行用于左/右审查数据如「低于检测限」的测量值。审查与截断的本质区别在于截断改变了随机变量的支撑集而审查保持原分布、只是观测被区间遮蔽with pm.Model() as model: mu pm.Normal(mu, mu5, sigma2) # 低于下限的观测全部记为 lower y pm.Censored(y, distpm.Normal.dist(mumu, sigma1), lowerlower_limit, observeddata)两种分布都提供了dist类方法用于在comp_dists或dist参数中组合使用且从源码看二者均继承自Distribution基类并在logp中分别处理边界概率质量。八、自定义与仿真分布CustomDist 与 SimulatorCustomDist —— 无痛接入任意似然distributions/custom.rst 对应的CustomDist类位于 pymc/distributions/custom.py 第 477 行。它允许用户提供自定义的logp、random与support_point函数把任意似然/先验接入 PyMC 生态def my_logp(value, mu, sigma): return pm.Normal.dist(mumu, sigmasigma).logp(value) with pm.Model() as model: mu pm.Normal(mu, mu0, sigma1) y pm.CustomDist(y, mu, sigma, logpmy_logp, observeddata)CustomDist是当前推荐的自定义分布入口替代了早期版本的DensityDist模式。Simulator —— 基于仿真的推断SBIdistributions/simulator.rst 对应的Simulator类位于 pymc/distributions/simulator.py 第 63 行。当似然难以解析写出、但可以通过仿真器生成数据时使用Simulator配合 SMC 采样器见 pymc/smc进行基于仿真的推断def simulator(theta, rngNone, sizeNone): return rng.normal(theta, 1, sizesize) with pm.Model() as model: theta pm.Normal(theta, mu0, sigma5) s pm.Simulator(s, theta, simulatorsimulator, observeddata)从源码结构看Simulator同样继承自Distribution其随机生成逻辑完全由用户提供的simulator回调驱动因此可配合pm.sample_smcpymc.smc.sampling进行似然无关推断。九、分布变换体系Transforms默认变换、自定义变换与 Chain变换部分是 distributions/transforms.rst 中篇幅最重的内容它解释了 PyMC 采样性能优化的核心机制。为什么需要变换许多分布定义在受限空间如区间上但 MCMC 采样器尤其是 HMC在无约束实直线上的采样效果最好。PyMC 通过变换在这两者之间建立映射并把变换随机变量的对数概率修正到后验对数概率中。变换目前不适用于离散随机变量。三个核心方法每个变换都实现三个核心方法forward从受限空间映射到无约束空间backward从无约束空间逆映射回受限空间log_jac_detbackward映射雅可比行列式的对数用于在后验对数概率中正确修正变换随机变量。这些方法的具体实现集中在 pymc/distributions/transforms.py例如LogTransform、LogExpM1第 60 行、Ordered第 79 行、Interval第 559 行、ZeroSumTransform第 644 行等。默认变换与自定义变换文档明确说明变换原则上仅供内部使用多数情况下用户无需改动。所有在受限定义域上实现的连续分布在 PyMC 中都有default_transform会自动完成变换而无需用户额外操作。例如正数取值随机变量的default_transform是log变换。需要自定义变换的主要场景有三类替换默认变换例如正数变量默认用log某些情况下改用log_exp_m1数值上对接近 0 的正数更稳定可能更有利完全移除变换使用非 HMC 采样器如 Metropolis、切片采样时可以删除默认变换附加约束通过transform参数在default_transform之外叠加约束实践中基本只用于在混合模型中施加ordered变换。注意ordered与simplex、ZeroSumTransform等其他变换组合使用时无法保证正确工作。with pm.Model() as model: # 用 log_exp_m1 替换默认的 log 变换 x pm.HalfNormal(x, sigma1, transformpm.distributions.transforms.log_exp_m1) # 在混合模型中强制有序组件均值 mu pm.Normal(mu, munp.zeros(K), sigma1, transformpm.distributions.transforms.ordered, shapeK)变换的适用边界重要警告文档给出了明确的警告变换仅在对未观测随机变量执行pm.sample时应用。具体而言前向采样pm.draw、pm.sample_prior_predictive、pm.sample_posterior_predictive不会应用变换对观测随机变量执行pm.sample时也不会应用变换。由于先验预测采样不应用变换文档建议的 workaround 是在进行先验预测检查时从似然中移除观测改用pm.sample来采样先验。另外需要强调变换不是表达生成式模型中数据变换的正确工具。属于生成过程一部分的变换应显式建模通常通过pm.Deterministic实现在 pymc/model/transform/deterministic.py声明这样变换后的随机变量才能被前向采样器正确采样。变换的三种使用形态变换实例Transform Instances直接用于default_transform或transform参数的单例包括circular、log、log_exp_m1、logodds、ordered、simplex具体变换类Specific Transform Classes需先实例化再使用包括CholeskyCovPacked、CircularTransform、Interval、LogExpM1、LogOddsTransform、LogTransform、Ordered、SimplexTransform、ZeroSumTransform变换组合类Transform Composition ClassesChain。如果随机变量已有default_transform同时又通过transform参数提供了额外变换PyMC 会自动创建Chain变换把用户变换叠加在默认变换之上。十、分布工具类Utilities基类与辅助组件distributions/utilities.rst 列出 5 个工具组件组件说明Continuous连续分布基类Discrete离散分布基类Distribution所有分布的统一基类SymbolicRandomVariable符号随机变量用于表示基于符号运算的分布DiracDelta退化的点质量分布常作为确定性约束的数学工具它们分别实现在 pymc/distributions/distribution.py 与 pymc/distributions/discrete.py 等文件中。这些基类统一提供dist类方法、random采样、logp对数概率、support_point以及default_transform等基础设施是理解整个分布体系的入口。十一、实战索引如何快速选用分布根据本文整理的 API 全景可以形成如下选型速查回归/均值结构Normal、StudentT厚尾、SkewNormal、SkewStudentT、LaplaceL1正数响应LogNormal、Gamma、InverseGamma、Weibull、Exponential、HalfNormal、Wald、Rice、PolyaGamma单位区间/比例Beta、Kumaraswamy、LogitNormal、Uniform(0,1)计数数据Poisson、NegativeBinomial、Binomial、BetaBinomial、Geometric、HyperGeometric过量零时升级为ZeroInflated*或Hurdle*类别/有序Categorical、Bernoulli、Multinomial、OrderedLogistic/OrderedProbit注意 0 基索引多元结构MvNormal、MvStudentT、Dirichlet、LKJCholeskyCov/LKJCorr、Wishart、MatrixNormal空间数据用CAR/ICAR混合分布Mixture、NormalMixture时间序列GaussianRandomWalk、AR、GARCH11、EulerMaruyama、多元随机游走受限观测通用截断用Truncated、审查数据用Censored、区间截断的正态用TruncatedNormal似然难解CustomDist自定义 logp或Simulator SMC基于仿真推断。每个分布类的精确参数签名、默认值与示例均可直接查阅 docs/source/api/distributions.rst 各子页面自动生成的全量 API 文档而底层实现细节参数化、随机生成、对数概率、变换则以 pymc/distributions 下的对应源码文件为最终权威。结合 tests/distributions 中的测试用例如 test_continuous.py、test_discrete.py、test_multivariate.py可以进一步验证每个分布在参数边界、形状广播与采样一致性上的行为为模型的正确性提供保障。【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考