PyMC modeling
Choose a useful starting point: a simple scaffold, an established subject-matter model, or a decomposition of a larger target model. Expand, simplify or branch as the question, data and checks warrant. Use the consuming project's data and Python environment; check installed APIs and package compatibility.
For pymc-extras tasks, start with feature selection and compatibility,
then load only the relevant workflow reference. Prefer its supported algorithms
to bespoke implementations; do not use an extension merely because it is installed.
Choose the primary task
- Construct, fit or initialize a model: use
pymc-modeling. - Elicit prior assumptions or check prior-predictive plausibility: use
prior-elicitationwhen available. - Diagnose an existing completed fit or evaluate its predictions: use
arviz-diagnosticswhen available. - Repair symbolic computation, broadcasting, gradients or compilation: use
pytensor-workflowswhen available. - Track experiments, preserve MLflow artifacts or restore a logged MMM model: use
pymc-mlflowwhen available.
Multipart requests can use more than one skill. The references below support modeling when specialist skills are not installed.
Workflow
- Formulate. State the estimand or prediction target, observation units, outcome support, grouping/time structure, selection and missingness, and what information is available at prediction time. Separate predictive, inferential and causal claims; respect data authorization and retain source identities.
- Specify and inspect. Match the likelihood to the observation process;
choose identifiable parameterizations and priors in declared units. Check
row alignment, shapes, support and finite initial log density. Ordinary
dimslabel positional tensors; they do not join coordinates. Use known-parameter simulated cases to probe new implementations and their failure modes; use scoped SBC when repeated inference checks are warranted. - Check prior predictions. Simulate before fitting and compare support, scales and decision-relevant features to domain knowledge. Do not tune priors solely to the realized extrema.
- Explore, then fit for inference. Prefer nutpie when compatible and installed. Short preliminary fits can reveal bugs, difficult geometry or gross misfit; label them exploratory, not reliable posterior inference. For reportable results, allocate warmup and draws from adaptation and required ESS/MCSE. Save results before diagnostics or plotting.
- Diagnose, then criticize. Inspect divergences, rank R-hat, bulk/tail ESS, MCSE and chain/rank plots. Diagnose every divergence. Unreliable computation leaves posterior conclusions unresolved; it does not disprove a likelihood. Use posterior predictive discrepancies to check the observation model. In-sample PPCs are not held-out validation.
- Predict, decide and revise. Preserve training identities and align new inputs; distinguish latent means from noisy observations. For recommendations, propagate uncertainty through stated consequences, utilities and constraints, or hand off the inference without inventing the decision maker's values. Retain relevant model variants and explain how changed assumptions affect estimands, predictions and decisions—not just which has the best score. Adaptive PPC/CV-driven search can overfit; do not present its winner as uniquely confirmed or change seeds/criteria merely to obtain a favorable result.
PyMC 6 returns xarray.DataTree: use idata["posterior"], not attribute group
access. Call pm.compute_log_likelihood(idata, model=model) explicitly before
LOO or other pointwise-likelihood workflows. ArviZ 1.0 uses LOO, not removed WAIC;
state interval probability and type (the default is 89% ETI). Similar stacking
weights do not imply model equivalence.
Sampler preferences, warmup starting points and interval defaults are implementation
conventions, not universal Bayesian workflow requirements. Choose them for the task.
Read only what the task needs
| When working on | Reference |
|---|---|
| End-to-end fitting, diagnostics and scientific checks | Workflow |
| Model construction, data containers and dimensions | Model and data |
| Failed initialization, shape errors, stuck sampling or warnings | Troubleshooting |
| Group effects, pooling and parameterization | Hierarchical models |
| Outcome support, censoring, multivariate families and Jacobians | Likelihoods |
| Algorithms, backends, budgets and persistence | Sampling |
| pymc-extras feature selection, compatibility and validation | PyMC Extras |
| Markov chains, specialized counts, extreme values and histogram likelihoods | Extras distributions |
| Kalman-marginalized models, structural components and forecasting | Extras state-space workflows |
| Prior factories, model packaging, VIP and posterior-as-prior transfer | Extras model tools |
| Variational, Laplace and Pathfinder approximations | Approximate inference |
| Covariance models and finite-basis error | Gaussian processes |
| Temporal dependence, differential equations and forecasting | Time series |
| Label invariance and discrete elimination | Mixtures |
| External densities, simulators and predictive callbacks | Custom likelihoods |
| Conditioning, interventions and graph transformations | Transformations |
| In-sample criticism and new-input prediction | Predictive checks |
| Tree ensembles and prediction state | BART |
| Basis penalties and distributional predictors | Splines |
| Simulated-data experiments, SBC, numerical oracles and mocks | Model testing |
| Advanced numerical and extension interfaces | Interface boundaries |
For version-specific APIs, use help() or inspect.signature() on the installed
object in the consuming environment, then consult version-matched official
documentation or source.
