CausalMediation.jl

This package is part of the CDCS Julia package set, which supports the Causal Dynamics of Complex Systems book.

Cross-fitted mediation for the CDCS Julia stack: interventional (RI), natural, organic, controlled direct, and recanting-twin effects, with intermediate confounding (moc) and continuous MTP one-step / TMLE estimators.

Documentation: simonab.github.io/CausalMediation.jl (after the Documentation workflow has run on main).

On the Julia General registry (Pkg.add("CausalMediation")). Requires Julia 1.12+, CausalDynamics 0.4+, and CausalTargeted 0.3+. Registry tracking: REGISTRATION.md.

Install

using Pkg
Pkg.add("CausalMediation")

Development tip of main (before a new version hits General):

Pkg.add(url="https://github.com/SimonAB/CausalMediation.jl.git")

Quick start

using CausalMediation, CausalTargeted, StableRNGs

df, truth = simulate_continuous_mtp_mediation(200; rng = StableRNG(1))
spec = MediationSpec(:A, :Y; mediators = [:M], covariates = [:W])
res = run_mediation(spec, df; deltas = [1.0], folds = 2, n_mc = 16, parallel = false)
decompose(res)

Factor A (recode MTP, continuous M):

df, truth = simulate_categorical_a_mediation(280)
spec = MediationSpec(
    :A, :Y;
    mediators = [:M],
    covariates = [:W],
    policy_d0 = discrete_recode_policy(Dict{String, String}()),
    policy_d1 = discrete_recode_policy(truth.recode),
)

With intermediate confounders:

spec = MediationSpec(:A, :Y; mediators = [:M], covariates = [:W], moc = [:L])

Testing and validation

CI develops tip CausalDynamics and CausalTargeted so RepresentationSpec and nuisance APIs match the stack; Pkg.test() on Julia 1.13 is the merge gate. Julia 1.12 remains within the declared compatibility range. Full-stack stress with real cohorts lives in CausalTargeted (see links below).

Guardrail	What we exercise	Where
Unit / API	Effect gates (interventional, natural, organic, CDE, recanting twin), MediationSpec / run_mediation*, identify natural vs interventional, schema guards, categorical-$A$ policies	test/runtests.jl
Synthetic recovery	Binary and continuous MTP mediation; intermediate confounding (moc); TE / NDE / NIE vs simulation oracles	test/runtests.jl (simulate_* DGPs)
Missing data	Shared MAR $Y$ helper; scalar path checks truth vs :ipcw; bootstrap / TMLE3 check finite :drop≠:ipcw	test/runtests.jl
Representation bridge	High-dim spectrum → codes → mediation grid on encoded panel	test/test_representation_bridge.jl
Integration	CausalDynamics identification certificates; CausalTargeted Super Learner / schema utilities	test/runtests.jl
Stack stress (pre-ship)	Mediation curves, missing-$M$ / missing-$Y$, freeze comparisons on conservation and CI benchmarks	CausalTargeted stress_validation.qmd
Deep SCM hand-off	Estimation on Lux / representation codes	deep_scm_estimation_stress.qmd

If you have a mediation scenario that should be harder to pass (tighter effect bounds, path-specific or natural-ID edge cases, messier MAR), please open an issue — we welcome stress cases that expose gaps before users do.

Documentation (local)

julia --project=docs -e 'using Pkg; Pkg.develop(path="."); Pkg.instantiate()'
julia --project=docs docs/make.jl

Pages: home, getting started, comparison, methods, naming, API, references.

Stress validation (Quarto notebook + catalogued datasets): CausalTargeted STRESS.md · stress_validation.qmd · deep_scm_estimation_stress.qmd (codes → mediation/LMTP) · Documenter · harness in causal-dynamics-book/scripts/stress_harness.

Design notes in-repo: DESIGN.md · BOUNDARIES.md · NAMING.md · REGISTRATION.md · ecosystem principles · ECOSYSTEM_COMPARISON.md.

License

MIT © Simon A. Babayan

Citation

@software{Babayan2026_CausalMediation,
  author  = {Babayan, Simon A.},
  title   = {CausalMediation.jl},
  year    = {2026},
  version = {v0.1.2},
  doi     = {10.5281/zenodo.21812342},
  url     = {https://github.com/SimonAB/CausalMediation.jl}
}

Concept DOI (all versions): 10.5281/zenodo.21812341.