Pathmc

pathmc

pathmc lets you specify a system of structural equations as a string, compile it to a generative PyMC model, fit with MCMC, and reason about causal effects using the do-operator.

Installation

pip install pathmc
# Optional faster samplers (nutpie, numpyro, jax):
pip install "pathmc[samplers]"

Quick start

import pathmc

spec = """
M ~ a*X
Y ~ b*M + c*X
indirect := a*b
"""

m = pathmc.model(spec, data=df)   # returns a PathModel (NOT a fitted result)
m.fit(draws=1000, chains=2)       # MCMC happens here

m.effects_summary()                # labeled coefficients + defined params
m.ate("Y", "X", values=(0, 1))     # average treatment effect via do()
m.adjustment_sets("X", "Y")        # valid backdoor adjustment sets

The DSL is lavaan-inspired:

• Y ~ X — regression
• Y ~~ X — residual covariance
• indirect := a*b — defined parameter
• a*X — labeled coefficient
• Transforms: adstock(x, decay=...), logistic_saturation(x, lam=...)
• Categorical predictors: string columns are treatment-coded automatically; C(region, reference='north', prior='hierarchical') makes the coding explicit

Decision table

Gotchas

1. pathmc.model(...) returns a PathModel, not a fitted result. You must call .fit() separately. model() only parses, builds the DAG, and compiles the PyMC graph — it does not sample.
2. m.do(...) is a structural intervention, not conditioning. It applies pm.do() graph surgery and forward-simulates from the intervened model, propagating posterior uncertainty through the causal chain (g-computation; Robins, 1986). It is not the same as conditioning on observed values. For typical user-facing queries, prefer the wrappers m.ate(), m.cate(), m.att(), m.atu(), m.prob().
3. ate()/cate()/att()/atu() return an EstimandResult, not a DoResult. It knows the outcome, so r.mean(), r.hdi(), and r.prob("> 0") need no variable argument, float(r) gives the posterior mean, and printing it shows a tidy summary. m.do(...) returns a DoResult describing the whole system, where accessors still take a variable name (r.mean("Y")).
4. The DSL is lavaan-inspired, not a 1:1 reimplementation. ~, ~~, :=, and labeled coefficients all work. Latent-variable measurement models (=~) are out of scope in v0.1 — see the user guide for the full operator list.
5. Prior is re-exported from pymc_extras for convenience. from pathmc import Prior is a shortcut for from pymc_extras.prior import Prior. The canonical reference and list of supported distributions live in pymc_extras.
6. Panel lag terms are declared in the model spec. Use lag(sales) directly in the DSL and pass panel={"unit": "region", "time": "week"} to pathmc.model(...). pathmc builds the lagged design internally.
7. Data-free models have a partial method surface. When data=None, graph(), equations(), priors(), adjustment_sets(), is_identifiable(), collider_warnings(), implied_independences() all work. fit(), do(), ate(), cate(), design(), sample_prior_predictive(), test_implications(), falsify(), sensitivity(), refute_placebo() raise RuntimeError until the model is rebuilt with data (and refute_placebo() also needs a prior .fit()).
8. PathModel is not in pathmc.__all__ — it's the class returned by model(). You don't import it directly; you receive it. Type annotations can use pathmc.PathModel (it is reachable as an attribute) but the public entrypoint is the model() function.
9. adjustment_model() returns an AdjustmentModel facade. Inspect adj.adjustment_set and adj.formula before calling adj.fit(). An empty set {} is valid when no covariates are needed to block backdoors; if no valid set exists, construction raises (effect not identifiable via backdoor). When several minimal sets exist, pass adjustment_set= explicitly; pathmc does not pick among them. Pass data= when the parent structural model is data-free. Panel models are not supported on the adjustment path. Outcome dispersion priors (sigma_Y, nu_Y, alpha_disp_Y) are inherited from the parent, but coefficient priors are not, because the reduced predictor set can differ: if the parent set a custom beta_Y, pass priors={"beta_Y": ...} to adjustment_model().
10. predictions() / comparisons() / slopes() share one API on PathModel and AdjustmentModel. On the structural model they use truncated-factorization g-computation; on adjustment_model() they delegate to the reduced outcome equation with estimator="regression_adjustment". Read result.causal: only queries on the designated treatment support a causal reading; slopes or contrasts on adjustment covariates are interventional on the fitted surface, not causal effects of those covariates. See the user guide page Predictions, Comparisons, and Slopes.
11. String columns become treatment-coded categoricals; integers stay continuous. Y ~ region on a string column creates beta_Y_region indexed by level name (coordinate Y_region_levels), with the first sorted level as reference. Wrap integer codes in C(...) to treat them as labels. The level set is frozen at model() time: do(), ate(), prob(), and predict(data=...) accept labels, and an unseen label raises rather than re-inferring the coding. Categorical interactions, transforms, outcomes, and panel models are rejected with an explanatory error.