Skip to content

Architecture

The package separates causal reasoning, simulation, estimation, and operational workflow.

src/causal_econometrics/
├── dgp/            # controlled data-generating processes with hidden truth
├── estimators/     # econometric and causal estimators + diagnostics
├── production/     # validation, preprocessing, provenance, artifact workflows
├── case_studies/   # portfolio-facing end-to-end analyses
├── methodology.py  # typed estimands and identification assumptions
├── marketing_mix.py
└── random.py

Data-generating processes

The dgp package creates controlled settings in which potential outcomes, treatment effects, latent confounders, or counterfactual trajectories are known.

Analyst-facing data and latent truth are returned separately. This prevents tests from accidentally giving an estimator information unavailable in a real study.

Estimators

The estimators package contains method-specific implementations.

Each causal estimator is expected to:

  • target a named estimand;
  • declare its identification assumptions;
  • expose uncertainty;
  • surface diagnostics;
  • include tests under both valid and invalid designs.

Methodology contracts

MethodologySpec binds an Estimand to a tuple of IdentificationAssumption values.

The metadata does not prove identification. It makes the causal contract discoverable in code and difficult to omit from a new estimator.

Production layer

The production package owns concerns that should not leak into estimator code:

  • business-column schemas;
  • type/range/key validation;
  • deterministic preprocessing;
  • workflow configuration;
  • design-specific checks;
  • provenance hashes;
  • artifact serialization;
  • command-line execution.

This keeps statistical functions reusable while giving operational workflows strict input and output contracts.

Case studies

Case studies compose production workflows and estimators into reviewer-facing analyses.

They are allowed to generate figures and decision tables, but should not reimplement the underlying causal estimators.

Tests as scientific checks

The test suite includes more than software smoke tests. It also checks statistical behavior such as:

  • recovery of known treatment effects;
  • failure under violated assumptions;
  • weak instruments;
  • lack of overlap;
  • anticipation effects;
  • dynamic misspecification;
  • prior sensitivity;
  • false placebo signals.

That distinction is intentional: correct code can still implement an invalid causal design.