PyMC Python
Build an identifiable generative model with named dimensions, test it against
simulated observations, sample reproducibly, and treat diagnostics and
predictive adequacy as part of correctness.
Boundary
Use this skill when code directly constructs or samples a pymc.Model. Use
Bambi for formula-driven regression, NumPyro for a native JAX probabilistic
program, and ArviZ when the job starts from completed inference results. Do not
translate between frameworks unless the user requests it.
Know the objects
| Object |
Runtime meaning |
Use it for |
Model |
A named probabilistic graph plus coordinates, data containers, random variables, deterministics, and potentials. |
Owning one coherent generative model and its namespace. |
Coordinate / dims |
Semantic labels for tensor axes. |
Making observations, parameters, and predictions align by meaning rather than position. |
Data |
A named model input whose value can be replaced for prediction when shape/coordinates remain compatible. |
Covariates, indices, offsets, and other conditioned inputs. |
| Random variable |
A named distribution node; observed RVs define the likelihood and unobserved RVs are inferred. |
Priors, latent states, and observations. |
Deterministic |
A named graph expression derived from model variables. |
Interpretable quantities needed in results; not an independent random site. |
Potential |
A registered, named arbitrary contribution to the model joint log-probability; it is not a random variable. |
A mathematically justified density factor, not a substitute for an observed likelihood. |
InferenceData |
Grouped, labeled posterior, sample statistics, observed/constant data, and predictive draws. |
The durable inference artifact and ArviZ boundary. |
Distribution batch/support shape, named dimensions, and observed-data shape must
agree. A dimension label does not broadcast or transpose values for you. Read
the model and shape contract before repairing a
shape error, indexing hierarchical effects, or updating prediction data.
Ordered workflow
- State the estimand, observation unit, likelihood, link, censoring/truncation,
missing-data policy, grouping structure, and prediction target.
- Build coordinates from stable domain identifiers. Give every non-scalar
variable meaningful
dims; check data and coordinate lengths before sampling.
- Choose likelihood from the data-generating process, not from a convenient
distribution name. Encode exposure, trials, bounds, or measurement error.
- Choose proper priors on the scale where they are interpretable. Simulate the
prior predictive and reject impossible or implausible outcomes.
- Run a small sampled-data recovery test. If known parameters cannot be
recovered, repair the model before increasing draws.
- Select inference from variable support and geometry. Use automatic sampling
as a starting point, not proof that NUTS is valid for every site.
- Sample multiple independent chains with a recorded seed, warmup, draws, and
sampler settings; retain
InferenceData and sample statistics.
- Diagnose convergence and geometry, then run posterior predictive checks on
domain-relevant discrepancies. Fix causes rather than hiding warnings.
- For new data, update
Data and matching coordinates under the same model
contract; store out-of-sample draws as predictions, separate from in-sample
posterior predictive checks.
Decision map
| Condition |
Action |
| Continuous differentiable latent variables with workable geometry |
Start with NUTS; inspect divergences, tree depth, energy, R-hat, ESS, and traces. |
| Discrete unobserved sites |
Use a compatible discrete or compound method, or marginalize/reformulate; do not force gradient-based NUTS. |
| Hierarchical scale/funnel causes divergences |
Standardize predictors and test a non-centered parameterization; do not only raise target_accept. |
| Prior predictive is unrealistic |
Repair likelihood, scale, link, or priors before posterior sampling. |
| Prediction rows differ from training rows |
Update Data and coordinates together; preserve coefficient/category semantics. |
| Need in-sample replicated observations |
Posterior predictive group. |
| Need out-of-sample predictions |
Prediction data plus predictions=True or installed equivalent; keep a distinct predictions group. |
| Model comparison is required |
Ensure pointwise log likelihood and use ArviZ with compatibility and Pareto diagnostics. |
Read inference and predictive diagnostics
before changing sampler settings or claiming a fitted model is valid.
Canonical model flow
import numpy as np
import pymc as pm
def fit_logistic(x: np.ndarray, y: np.ndarray, seed: int):
coords = {"observation": np.arange(y.size), "feature": np.arange(x.shape[1])}
with pm.Model(coords=coords) as model:
x_data = pm.Data("x", x, dims=("observation", "feature"))
intercept = pm.Normal("intercept", 0, 1.5)
beta = pm.Normal("beta", 0, 1, dims="feature")
logit_p = pm.Deterministic("logit_p", intercept + x_data @ beta, dims="observation")
pm.Bernoulli("outcome", logit_p=logit_p, observed=y, dims="observation")
prior = pm.sample_prior_predictive(random_seed=seed)
idata = pm.sample(chains=4, random_seed=seed)
pm.sample_posterior_predictive(idata, random_seed=seed, extend_inferencedata=True)
return model, prior, idata
The seed makes the run reproducible, not deterministic across every backend and
hardware combination. Keep observed binary values and predictor dimensions
validated outside the model; PyMC graph construction is not input sanitation.
Non-negotiable rules
- Never infer axis meaning from length alone. Assert coordinates, dtypes, index
arrays, and category coding at ingress and prediction time.
- Do not use posterior data twice: choose priors before inspecting the target
outcomes, and evaluate on held-out or explicitly in-sample predictive tasks.
- Do not declare convergence from one chain, a trace plot alone, or R-hat alone.
Inspect rank-normalized R-hat, bulk/tail ESS, MCSE, divergences, energy/BFMI,
tree depth, and parameter-specific traces as applicable.
- Increasing draws reduces Monte Carlo error but does not repair divergences,
non-identifiability, a bad likelihood, or prior-data conflict.
- A posterior predictive distribution is conditional on the fitted model; it
does not prove causal identification or out-of-sample calibration.
- Do not use
Potential to hide a likelihood term needed for predictive
simulation. Potentials affect log-probability sampling but are ignored by
prior and posterior forward sampling. If one is necessary, document its
density and predictive consequences and test the intended behavior.
- Preserve chain and draw dimensions in
InferenceData; never flatten chains
before convergence diagnostics.
- Inspect the installed major before using experimental dims APIs or changing
posterior-predictive volatility arguments.
Inspect the installed version, then use testing and version
grounding for the
smallest falsifiers and installed-API checks.
Completion gate
Do not declare completion until the likelihood and priors match the stated
generative assumptions; coordinates/dims and data shapes are asserted; prior
predictive and simulated recovery checks pass; multiple-chain diagnostics show
no unresolved critical warnings; posterior predictive checks target meaningful
features; prediction data preserves feature/category coordinates; the final
InferenceData contains required groups and sample statistics; and every
skipped diagnostic, backend limitation, or version uncertainty is reported.
References
- Model construction recipes
- Inference and prediction recipes
- Model and shape contract
- Inference and predictive diagnostics
- Testing and version grounding
1---2name: pymc-python3description: Use for writing, reviewing, debugging, testing, or diagnosing Python Bayesian models built directly with PyMC, including Model, coords/dims, Data, random variables, potentials, posterior sampling, prior/posterior predictive checks, and InferenceData output. Trigger on model geometry, shape errors, divergences, sampler choice, mutable prediction data, and probabilistic validation. Do not use for Bambi formula models, NumPyro/JAX programs, ArviZ-only analysis of existing draws, deterministic optimization, or general statistics without PyMC code.4argument-hint: "[PyMC model, inference, prediction, diagnostic, or error]"5metadata:6 source: https://skillmd.com/skills/schattenspiegel/pymc-python7---89# PyMC Python1011Build an identifiable generative model with named dimensions, test it against12simulated observations, sample reproducibly, and treat diagnostics and13predictive adequacy as part of correctness.1415## Boundary1617Use this skill when code directly constructs or samples a `pymc.Model`. Use18Bambi for formula-driven regression, NumPyro for a native JAX probabilistic19program, and ArviZ when the job starts from completed inference results. Do not20translate between frameworks unless the user requests it.2122## Know the objects2324| Object | Runtime meaning | Use it for |25|---|---|---|26| `Model` | A named probabilistic graph plus coordinates, data containers, random variables, deterministics, and potentials. | Owning one coherent generative model and its namespace. |27| Coordinate / `dims` | Semantic labels for tensor axes. | Making observations, parameters, and predictions align by meaning rather than position. |28| `Data` | A named model input whose value can be replaced for prediction when shape/coordinates remain compatible. | Covariates, indices, offsets, and other conditioned inputs. |29| Random variable | A named distribution node; observed RVs define the likelihood and unobserved RVs are inferred. | Priors, latent states, and observations. |30| `Deterministic` | A named graph expression derived from model variables. | Interpretable quantities needed in results; not an independent random site. |31| `Potential` | A registered, named arbitrary contribution to the model joint log-probability; it is not a random variable. | A mathematically justified density factor, not a substitute for an observed likelihood. |32| `InferenceData` | Grouped, labeled posterior, sample statistics, observed/constant data, and predictive draws. | The durable inference artifact and ArviZ boundary. |3334Distribution batch/support shape, named dimensions, and observed-data shape must35agree. A dimension label does not broadcast or transpose values for you. Read36[the model and shape contract](references/object-model.md) before repairing a37shape error, indexing hierarchical effects, or updating prediction data.3839## Ordered workflow40411. State the estimand, observation unit, likelihood, link, censoring/truncation,42 missing-data policy, grouping structure, and prediction target.432. Build coordinates from stable domain identifiers. Give every non-scalar44 variable meaningful `dims`; check data and coordinate lengths before sampling.453. Choose likelihood from the data-generating process, not from a convenient46 distribution name. Encode exposure, trials, bounds, or measurement error.474. Choose proper priors on the scale where they are interpretable. Simulate the48 prior predictive and reject impossible or implausible outcomes.495. Run a small sampled-data recovery test. If known parameters cannot be50 recovered, repair the model before increasing draws.516. Select inference from variable support and geometry. Use automatic sampling52 as a starting point, not proof that NUTS is valid for every site.537. Sample multiple independent chains with a recorded seed, warmup, draws, and54 sampler settings; retain `InferenceData` and sample statistics.558. Diagnose convergence and geometry, then run posterior predictive checks on56 domain-relevant discrepancies. Fix causes rather than hiding warnings.579. For new data, update `Data` and matching coordinates under the same model58 contract; store out-of-sample draws as predictions, separate from in-sample59 posterior predictive checks.6061## Decision map6263| Condition | Action |64|---|---|65| Continuous differentiable latent variables with workable geometry | Start with NUTS; inspect divergences, tree depth, energy, R-hat, ESS, and traces. |66| Discrete unobserved sites | Use a compatible discrete or compound method, or marginalize/reformulate; do not force gradient-based NUTS. |67| Hierarchical scale/funnel causes divergences | Standardize predictors and test a non-centered parameterization; do not only raise `target_accept`. |68| Prior predictive is unrealistic | Repair likelihood, scale, link, or priors before posterior sampling. |69| Prediction rows differ from training rows | Update `Data` and coordinates together; preserve coefficient/category semantics. |70| Need in-sample replicated observations | Posterior predictive group. |71| Need out-of-sample predictions | Prediction data plus `predictions=True` or installed equivalent; keep a distinct predictions group. |72| Model comparison is required | Ensure pointwise log likelihood and use ArviZ with compatibility and Pareto diagnostics. |7374Read [inference and predictive diagnostics](references/inference-diagnostics.md)75before changing sampler settings or claiming a fitted model is valid.7677## Canonical model flow7879```python80import numpy as np81import pymc as pm828384def fit_logistic(x: np.ndarray, y: np.ndarray, seed: int):85 coords = {"observation": np.arange(y.size), "feature": np.arange(x.shape[1])}86 with pm.Model(coords=coords) as model:87 x_data = pm.Data("x", x, dims=("observation", "feature"))88 intercept = pm.Normal("intercept", 0, 1.5)89 beta = pm.Normal("beta", 0, 1, dims="feature")90 logit_p = pm.Deterministic("logit_p", intercept + x_data @ beta, dims="observation")91 pm.Bernoulli("outcome", logit_p=logit_p, observed=y, dims="observation")9293 prior = pm.sample_prior_predictive(random_seed=seed)94 idata = pm.sample(chains=4, random_seed=seed)95 pm.sample_posterior_predictive(idata, random_seed=seed, extend_inferencedata=True)96 return model, prior, idata97```9899The seed makes the run reproducible, not deterministic across every backend and100hardware combination. Keep observed binary values and predictor dimensions101validated outside the model; PyMC graph construction is not input sanitation.102103## Non-negotiable rules104105- Never infer axis meaning from length alone. Assert coordinates, dtypes, index106 arrays, and category coding at ingress and prediction time.107- Do not use posterior data twice: choose priors before inspecting the target108 outcomes, and evaluate on held-out or explicitly in-sample predictive tasks.109- Do not declare convergence from one chain, a trace plot alone, or R-hat alone.110 Inspect rank-normalized R-hat, bulk/tail ESS, MCSE, divergences, energy/BFMI,111 tree depth, and parameter-specific traces as applicable.112- Increasing draws reduces Monte Carlo error but does not repair divergences,113 non-identifiability, a bad likelihood, or prior-data conflict.114- A posterior predictive distribution is conditional on the fitted model; it115 does not prove causal identification or out-of-sample calibration.116- Do not use `Potential` to hide a likelihood term needed for predictive117 simulation. Potentials affect log-probability sampling but are ignored by118 prior and posterior forward sampling. If one is necessary, document its119 density and predictive consequences and test the intended behavior.120- Preserve chain and draw dimensions in `InferenceData`; never flatten chains121 before convergence diagnostics.122- Inspect the installed major before using experimental dims APIs or changing123 posterior-predictive volatility arguments.124125Inspect the installed version, then use [testing and version126grounding](references/testing-version.md) for the127smallest falsifiers and installed-API checks.128129## Completion gate130131Do not declare completion until the likelihood and priors match the stated132generative assumptions; coordinates/dims and data shapes are asserted; prior133predictive and simulated recovery checks pass; multiple-chain diagnostics show134no unresolved critical warnings; posterior predictive checks target meaningful135features; prediction data preserves feature/category coordinates; the final136`InferenceData` contains required groups and sample statistics; and every137skipped diagnostic, backend limitation, or version uncertainty is reported.138139## References140141- [Model construction recipes](references/recipes-models.md)142- [Inference and prediction recipes](references/recipes-inference.md)143- [Model and shape contract](references/object-model.md)144- [Inference and predictive diagnostics](references/inference-diagnostics.md)145- [Testing and version grounding](references/testing-version.md)