Causalis

Robust causal inference for experiments and observational studies in Python, organized around scenarios (e.g., Classic RCT, CUPED, Unconfoundedness) with a consistent fit() → estimate() workflow.

• 📚 Documentation & notebooks: https://causalis.causalcraft.com/
• 🔎 API reference: https://causalis.causalcraft.com/api-reference

Why Causalis?

Causalis focuses on:

• Scenario-first workflows (you pick the study design; Causalis provides best-practice defaults).
• Extensive robustness tests that reveal issues in the study design or model specification
• Pydantic data contracts
• An advanced DGP (Data Generating Process) with heterogeneous treatment effects, latent variables, and correlated confounders
• A website with notebooks based on real-world cases

Installation

Recommended

pip install causalis

Quickstart: Classic RCT (difference in means + inference)

from causalis.dgp import generate_classic_rct_26
from causalis.scenarios.classic_rct import DiffInMeans, check_srm

# Synthetic RCT data as a validated CausalData object
data = generate_classic_rct_26(seed=42, return_causal_data=True)

# Optional: Sample Ratio Mismatch check
srm = check_srm(data, target_allocation={0: 0.5, 1: 0.5}, alpha=1e-3)
print("SRM detected?", srm.is_srm, "p=", srm.p_value, "chi2=", srm.chi2)

# Estimate treatment effect with t-test inference (or bootstrap / conversion_ztest)
result = DiffInMeans().fit(data).estimate(method="ttest", alpha=0.05)
result.summary()

Quickstart: Observational study (Unconfoundedness / DML IRM)

from causalis.scenarios.unconfoundedness.dgp import generate_obs_hte_26
from causalis.scenarios.unconfoundedness import IRM
from causalis.data_contracts import CausalData

causaldata = generate_obs_hte_26(return_causal_data=True, include_oracle=False)

from causalis.scenarios.unconfoundedness import IRM

model = IRM().fit(causaldata)
result = model.estimate(score='ATTE')
result.summary()

Binary sensitivity protocol for observational DML/IRM

Pre-specify a practically meaningful effect boundary and one or more domain-justified groups of observed pre-treatment confounders. The primary decision uses element-based long/short gain statistics for the benchmark group. Its r2_y, r2_d, and rho are calibrated jointly from the outcome variance, Riesz-representer variance, and actual effect shift. The 2× strength and forced rho=1 scenarios are reported as secondary stress tests.

from causalis.scenarios.unconfoundedness.refutation import run_sensitivity_protocol

# Example only: replace with a domain-justified, pre-specified group.
primary_group = list(causaldata.confounders[:2])

protocol = run_sensitivity_protocol(
    model,
    causaldata,
    benchmark_groups={"primary_domain_benchmark": primary_group},
    decision_threshold=0.0,  # replace with the minimum practical effect
    direction="auto",  # default: infer direction relative to the threshold
    preconditions_passed=True,  # causal set, overlap, nuisance quality, stability
)

print(protocol["status"])
print(protocol["summary"])
protocol["primary"]
protocol["stress"]
protocol["adversarial"]

PASS means every primary benchmark's bias-aware confidence interval remains strictly beyond decision_threshold in the requested direction. RV and RVa are reported as robustness diagnostics, not compared with universal cutoffs. An empty benchmark set, failed external preconditions, unavailable sensitivity elements, or strengths outside the finite sensitivity domain produce FAIL.

By default, direction="auto" selects positive when the original estimate is at or above decision_threshold, and negative otherwise. It uses this same direction for every scenario and returns it in protocol["direction"], with an inference warning in protocol["warnings"]. For a negative estimate at a zero threshold, every primary CI must have ci_upper < 0; touching or crossing zero still fails. Thresholds retain their supplied sign, and an estimate equal to the threshold does not pass. Use explicit direction="positive" or direction="negative" for a pre-specified directional claim; these choices are never overridden. Significance before sensitivity analysis alone does not guarantee a pass.

Benchmark boundary handling matches DoubleML: raw cf_y and cf_d are clipped to [0, 1]. If either long/short gain is not strictly positive, primary and stress use rho=sign(theta_short-theta_long); the adversarial scenario still forces rho=1. protocol["benchmarks"] retains raw gains, clipping/fallback flags, long/short elements, and warnings for auditability. In particular, a negative cf_d_raw becomes a numerical cf_d=0 boundary benchmark rather than a missing scenario.

Pick your scenario

Introduction to Causal Inference: guide

See scenario notebooks: https://causalis.causalcraft.com/explore-scenarios

Contributing guidelines

Maintainers

Ioann Martynov

References

https://github.com/DoubleML/doubleml-for-py

Search terms / supported methods

Causalis covers methods often searched as:

• causal inference Python
• causal machine learning Python
• treatment effect estimation
• A/B testing Python
• randomized controlled trial analysis
• CUPED Python
• Double Machine Learning Python
• DML / IRM
• CATE estimation
• uplift modeling
• propensity score diagnostics
• synthetic control Python
• difference-in-differences Python