Scope and architecture
CausalDynamics.jl implements Pearl-style identification and executable structural models for Causal Dynamical Models (CDMs), including time-indexed simulation, do(·), and shared-U counterfactual trajectories.
The CDCS book uses these exported APIs in narrative chapters. Identification and estimation names stay Pearl/SciML. Temporal identity may use the closed lexicon in Terminology (temporal_support, value_representation, referent_id, graph_kind, relation_kind, onset, replacement, deployment). Whitehead glossary terms live in the book (Concept Reference).
What is in core (v0.1–v0.2)
| Layer | Role | Typical API |
|---|---|---|
| Graphs | DAG validation, ancestral sets, paths | is_dag, get_ancestors, find_backdoor_paths |
| Identification | Criteria for adjustment / instruments | d_separated, backdoor_adjustment_set, frontdoor, IV |
| Static SCM | One-shot settlement given U | GraphSCM, DoIntervention, simulate_scm, compute_counterfactual |
| Discrete-time CDM | Trajectories over occasions | DiscreteTimeCDM, DoSequence, simulate, counterfactual |
| Observational panels | Wide tables for sequential estimation | CDMPanel, simulate_panel, panel_column_name |
| Hierarchical nesting | Cluster→unit exogenous draws; plate unroll for ID | RandomEffectSpec, simulate_hierarchical_panel, unroll_hierarchical_dag, attach_hierarchy_assumptions |
| Relational grounding | Entity/relation schemas grounded to ordinary causal graphs | RelationalSchema, RelationalSkeleton, RelationalParent, ground_relational_graph |
| Latent → observed bridge | Filter/smoother outputs → panel columns | ObservationBridge, panel_from_latent_series, simulate_observed_panel |
| Representation bridge | High-dim tensor → low-dim codes for ID/estimation | RepresentationSpec, encode_to_panel, representation_certificate |
| Structural constraints | Auditable declared invariance, feasibility, viability, or cross-embodiment claim | StructuralConstraintSpec, constraint_certificate |
| Deep mechanisms | Parent-constrained Lux $f_i$ / ODE residuals | MechanismSpec, MechanismLibrary, build_ode_rhs, train_mechanisms! (Lux weakdep) |
| Generative L3 | Additive-noise abduction on codes | abduce_noise, mechanism_counterfactual (:generative) |
| Soft interventions | State-dependent treatment rules | Policy, policy |
| Interventional means | Monte Carlo g-computation (discrete) | g_computation on DiscreteTimeCDM |
| Continuous functionals | Monte Carlo g-computation (SciML) | ContinuousEffectFunctional, g_computation on ContinuousCDMSpec |
| Time-indexed ID | Unrolled lag DAGs; support-driven node multiplicity | TemporalNodeSpec, TemporalDAGSpec, unroll_temporal_dag, causal_projection, temporal_backdoor_adjustment_set |
| Transport ID | Domain covariates in adjustment | TransportQuery → :transport_backdoor |
Hard dependencies stay lean: Graphs and CausalInference (d-separation, backdoor, and frontdoor adjustment via gensearch). IV, path enumeration, SCM/CDM simulation, and estimation bridges are owned here.
What is optional
- DAGMakie.jl — weakdep plotting (
plot_causal_graph, …) - Associations.jl — weakdep discovery bridge (PC, OCE → identification); see Associations integration
- RxInfer / GraphPPL / DataFrames — weakdep variational backdoor head (narrow residualised ATE; see RxInfer integration);
DataFrame(::CDMPanel)viaCausalDynamicsDataFramesExt - TMLE.jl — workflow helpers when the package is loaded (
prepare_for_tmle) - CausalTargeted.jl — sequential LMTP consumes
simulate_panelwide tables + temporalIdentificationResult(plan_sequential/sequential_spec_from_identification)
What is not in core
| Concern | Where it lives |
|---|---|
| LMM / MixedModels fitting | Application repos (or RxInfer hierarchical demos); see examples/hierarchical_mixedmodels_concordance.md |
| Discovery algorithms (PC, OCE, CCM, …) | Associations.jl (optional weakdep bridge) |
| ODE/SDE/UDE solvers | SciML (OrdinaryDiffEq, UniversalDiffEq, …); CausalDynamics supplies structure and do semantics |
| DeepSCM / non-additive image L3 encoders | Deferred; Phase 2b is additive-noise :generative on codes |
| UniversalDiffEq hard dependency | Deferred; optional advanced trainer only (SCIML recipes) |
| Flux-in-core | Deferred; Flux via MLJFlux / application encoders; Lux for mechanisms |
| Full MIRS / Twins cohort fixtures | Deferred; synthetic spectra in docs/stress/ |
| Full symbolic do-calculus / ModelingToolkit ID | Stubs only (is_identifiable, SymbolicSCM); unexported until implemented |
| Relational identification across unseen skeletons | Grounding prototype only; mechanism invariance and transport assumptions remain caller-specified |
| Process metaphysics vocabulary | CDCS book prose, not package exports |
Experimental (exported, quarantined)
| API | Status |
|---|---|
Hypergraph | Higher-order edges; not used by identify or CDM simulation |
| Relational grounding | Schema/skeleton expansion only; not relational identification or estimation |
SymbolicSCM | ModelingToolkit placeholder (system::Any); use GraphSCM for executable SCMs |
Façade vs own code
- Façades over CausalInference:
d_separated→dsep; backdoor adjustment → CausalInferencegensearch(van der Zander et al., 2019); frontdoor adjustment →find_frontdoor_adjustment(Wienöbst et al., 2024). - Own code: instruments, path finding, ancestral sets,
GraphSCM,DiscreteTimeCDM, TMLE/RxInfer/DAGMakie/Associations bridges.
Version narrative
- 0.1 — static graphs, identification façades,
GraphSCM - 0.2 —
DiscreteTimeCDMtrajectories (book Ch. 28); time-indexed unrolling - 0.3 — Associations.jl discovery bridge;
prepare_from_discovery, OCE →TemporalDAGSpec