pathmc

Structural causal models with Bayesian estimation and interventional simulation via a concise DSL.

What is pathmc?

pathmc is a Python package for Bayesian path analysis and structural causal modeling. You write your causal assumptions as a small set of structural equations in a lavaan-inspired formula language, and pathmc compiles them into a generative PyMC model in which every variable is wired through its structural parents in the DAG.

The result is a single model object that keeps the directed acyclic graph (DAG) at the center of the workflow. From that one object you can estimate effects with full posterior uncertainty, inspect the implied graph, check whether a causal effect is identifiable from your assumptions, falsify the graph against the data, run do()-operator interventions, and stress-test conclusions for unmeasured confounding, all without rewriting the model for each task.

pathmc is a good fit when you want the interpretability of path / structural equation modeling, the rigor of explicit causal identification, and the uncertainty quantification of full Bayesian inference, all in one place.

Installation

pip install pathmc

pathmc requires Python ≥ 3.12 and PyMC ≥ 6.0.

Quickstart

Pass a pandas DataFrame with columns matching the variables in your structural equations:

import pandas as pd
import pathmc
from pathmc.paths import data_dir

df = pd.read_csv(data_dir / "mediation.csv")
#           X         M         Y
# 0 -1.315113 -1.534242 -0.926176
# 1  0.490564  0.187741  1.742414
# 2 -1.077202 -0.691821 -0.233461
# 3  0.077516  0.156411  1.285188
# 4  1.600833  0.232611  1.379142
# ...

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

m = pathmc.model(spec, data=df)
m.fit(draws=1000, chains=2)

m.effects_summary()             # labeled coefficients + defined parameters
m.ate("Y", "X", values=(0, 1))  # average treatment effect via the do-operator
m.adjustment_sets("X", "Y")     # what to condition on for identification
m.comparisons("Y", "X")         # same estimand, or ratio/lift via comparison=

adj = m.adjustment_model("X -> Y")  # DAG-derived backdoor outcome regression
adj.fit(draws=1000, chains=2)
adj.ate(values=(0, 1))

The DSL mirrors lavaan: ~ defines a regression of an outcome on its parents, label*var attaches a name to a coefficient, and := defines derived quantities (such as an indirect/mediated effect) that are tracked with full posterior uncertainty.

Capabilities

For concepts, tutorials, and the full API reference, see the documentation at pathmc.pymc-labs.com.

Documentation

Documentation, concepts, and worked examples are available at pathmc.pymc-labs.com. The user guide covers the Bayesian workflow, model specification, transforms, identification, estimation approaches (structural vs regression adjustment), predictions/comparisons/slopes, standardized effects, and panel data, alongside runnable examples from foundations through applied models and the interpret gallery.

Contributing

Development setup, testing, and pull request guidance live in CONTRIBUTING.md.

Citation

If you use pathmc in academic work, please cite the project using the metadata in the repository's CITATION.cff.

Thanks to our contributors

The contributor image is regenerated weekly by a GitHub Actions workflow (.github/workflows/contributors.yml) that opens a PR when the contributor list changes.