PyMC 是用于贝叶斯建模与概率编程的 Python 库。本技能围绕 PyMC 的现代 API（5.x 及以上版本）展开，涵盖层级模型、MCMC 采样（NUTS）、变分推断以及模型比较（LOO、WAIC）等内容，目标是帮助完成模型的构建、拟合、验证与比较。
用途与适用情形
该技能适用于：构建贝叶斯模型（线性/逻辑回归、层级模型、时间序列等）；执行 MCMC 采样或变分推断；进行先验/后验预测检查；诊断采样问题（发散、收敛、ESS）；使用信息准则（LOO、WAIC）比较多个模型；通过贝叶斯方法实现不确定性量化；处理层级/多水平数据结构；以有原则的方式处理缺失数据或测量误差。
标准贝叶斯工作流
-
数据准备：导入 pymc、arviz、numpy；对连续预测变量做标准化以提升采样效率；尽可能中心化结果变量；显式处理缺失数据（作为参数处理）；使用具名维度 coords 提升可读性。
-
模型构建：使用 pm.Model(coords=...) 上下文；先验方面，使用弱信息先验而非平坦先验，尺度参数用 HalfNormal 或 Exponential；线性预测器通过 pm.math.dot 组合；似然通过 observed 传入数据。优先使用具名维度 dims 而非 shape，对需要更新以做预测的值使用 pm.Data()。
-
先验预测检查：拟合前始终验证先验，使用 pm.sample_prior_predictive() 采样并用 az.plot_ppc(group='prior') 可视化；检查先验预测是否覆盖合理取值，若先验生成不合常理的数据则调整并重新检查。
-
拟合模型：可选用 ADVI 快速探索（pm.fit(n=20000)），随后进行完整 MCMC 推断 pm.sample(draws=2000, tune=1000, chains=4, target_accept=0.9, random_seed=42, idata_kwargs={'log_likelihood': True})。draws 为每条链样本数，tune 为丢弃的预热样本，chains=4 用于收敛检查，target_accept 在难采样后验时可提高至 0.95–0.99，log_likelihood=True 用于模型比较。
-
检查诊断：可调用 scripts.model_diagnostics 中的 check_diagnostics()。关注 R-hat < 1.01、ESS > 400、无发散、迹图混合良好。出现问题时的处理：发散则提高 target_accept 或改用非中心化参数化；ESS 低则增加采样量或重新参数化以降低相关性；R-hat 高则延长采样并检查多峰性。
-
后验预测检查：使用 pm.sample_posterior_predictive(idata, extend_inferencedata=True) 并用 az.plot_ppc(idata) 可视化，检查后验预测是否捕捉观测数据模式、是否存在系统性偏差（模型设定错误）。
-
分析结果：使用 az.summary() 获取统计摘要，az.plot_posterior() 查看后验分布，az.plot_forest() 查看系数估计。
-
预测：对新预测变量按训练时相同方式标准化，使用 pm.set_data() 更新数据后调用 pm.sample_posterior_predictive()，可提取预测均值与 az.hdi() 预测区间。
常见模型模式
线性回归：连续结果与线性关系，alpha/beta 用 Normal 先验，sigma 用 HalfNormal，均值 alpha + pm.math.dot(X, beta)，似然为 Normal。模板见 assets/linear_regression_template.py。
逻辑回归：二分类结果，logit_p = alpha + pm.math.dot(X, beta)，似然为 Bernoulli(logit_p=...)。
层级模型：适用于分组数据，使用非中心化参数化。定义超先验 mu_alpha 与 sigma_alpha，组级用 alpha_offset 再经 pm.Deterministic 组合为 alpha，观测级 mu = alpha[group_idx]。模板见 assets/hierarchical_model_template.py。文中强调层级模型务必使用非中心化参数化以避免发散。
泊松回归：计数数据，log_lambda = alpha + pm.math.dot(X, beta)，似然为 Poisson(mu=pm.math.exp(log_lambda))。过度分散计数改用 NegativeBinomial。
时间序列：自回归过程，rho 用 Normal，sigma 用 HalfNormal，init_dist = pm.Normal.dist(...)，似然使用 pm.AR(...)。
模型比较
使用 LOO 或 WAIC 比较模型。scripts.model_comparison 提供 compare_models()、check_loo_reliability()、model_averaging()。解释标准：Δloo < 2 模型相似、优先选更简单的；2 < Δloo < 4 证据较弱；4 < Δloo < 10 中等证据；Δloo > 10 强证据。Pareto-k 检查：k < 0.7 表示 LOO 可靠，k > 0.7 可考虑 WAIC 或 k 折交叉验证。模型相似时可用 model_averaging() 对预测做加权平均。
分布选择指南
先验方面：尺度参数（σ、τ）默认 HalfNormal，也可用 Exponential 或 Gamma；无界参数用 Normal，抗离群值用 StudentT；正参数用 LogNormal 或 Gamma；概率用 Beta（弱信息）或 Uniform（非信息，慎用）；相关矩阵用 LKJCorr（eta=1 均匀，eta>1 偏好单位矩阵）。
似然方面：连续结果默认 Normal，抗离群值用 StudentT；计数数据用 Poisson（等分散）、NegativeBinomial（过度分散）、ZeroInflatedPoisson（过多零）；二分类用 Bernoulli；分类结果用 Categorical。详见 references/distributions.md。
采样与推断
MCMC 与 NUTS 为多数模型的默认推荐方法，参数可参考上文 pm.sample()；需要时可将 target_accept 提高、用 ADVI 初始化、对离散参数使用 pm.Metropolis()。变分推断（pm.fit(method='advi')）速度远快于 MCMC，但为近似结果，可能低估不确定性，适合大模型或快速探索，也可用于初始化 MCMC。详见 references/sampling_inference.md。
诊断脚本与常见问题
create_diagnostic_report() 可生成迹图、秩图、自相关图、能量图、ESS 演化与统计摘要 CSV；check_diagnostics() 快速检查 R-hat、ESS、发散与树深。常见问题及解决：发散可提高 target_accept、改用非中心化参数化、加强先验或检查模型设定；ESS 低可增加采样、重新参数化、对相关预测变量使用 QR 分解；R-hat 高可延长采样、检查多峰性、用 ADVI 改善初始化；采样慢可用 ADVI 初始化、降低模型复杂度、提高并行度（如 cores=8, chains=8）或在合适时使用变分推断。
最佳实践
建模时标准化预测变量、使用弱信息先验、使用具名维度、层级模型使用非中心化参数化、拟合前做先验预测检查。采样时运行至少 4 条链、以 target_accept=0.9 为基线、包含 log_likelihood 以便比较、设置随机种子保证可复现。验证时先看诊断再解释、做后验预测检查、必要时比较多模型、报告不确定性（HDI 区间而非仅点估计）。工作流上从简单开始逐步增加复杂度，按“先验预测检查 → 拟合 → 诊断 → 后验预测检查”的顺序迭代，并记录假设与先验选择。
配套资源
参考文档：distributions.md（按类别组织的 PyMC 分布目录，用于选择先验或似然）、sampling_inference.md（采样算法与变分推断指南及采样问题处理）、workflows.md（常见模型类型的完整工作流示例与代码模式，可作标准贝叶斯分析的参考手册）。脚本：model_diagnostics.py（诊断检查与报告生成）、model_comparison.py（基于 LOO/WAIC 的模型比较）。模板：linear_regression_template.py（完整线性回归工作流）、hierarchical_model_template.py（非中心化参数化的层级/多水平模型）。
其他说明
PyMC 与 ArviZ 集成以进行可视化与诊断；可用 pm.model_to_graphviz(model) 可视化模型结构；用 idata.to_netcdf('results.nc') 保存结果，用 az.from_netcdf() 加载；对超大模型可考虑小批量 ADVI 或数据子采样。