Causal Inference

Potential outcome means and control-vs-treatment ATEs with Wald inference.

causal_inference(...) reuses the package's semisupervised mean engine. For each treatment arm, it uses the corresponding column of Yhat_potential, treats units in that arm as labeled, and units outside that arm as unlabeled.

See Example Open in Colab

Quickstart

One column per arm, one result object back

The combined quickstart notebook opens in Colab installs ppi-aipw automatically and pairs this causal example with the main semisupervised mean workflow, so it is a good single entry point if you want both APIs side by side. 

from ppi_aipw import causal_inference

result = causal_inference(
    Y,
    A,
    Yhat_potential,
    X=X,
    w=w,
    treatment_levels=("control", "treated"),
    method="prognostic_linear",
    alpha=0.1,
)

mu_control = result.arm_means["control"]
mu_treated = result.arm_means["treated"]
ate = result.ate["treated"]
lower, upper = result.ate_cis["treated"]

print(result.summary())

The returned result object also has summary() for a compact Wald summary of the arm means and treatment effects.

All numeric inputs must be finite. The package rejects NaN and Inf values in outcomes, potential-outcome predictions, covariates, and weights with clear validation errors.

Inputs

What the API expects

Y

Observed scalar outcomes for all units.

A

Observed treatment assignments. Binary, discrete, and categorical labels are supported.

Yhat_potential

A matrix or DataFrame with one column per treatment arm and one row per unit.

treatment_levels

Optional arm labels matching the columns of Yhat_potential. If omitted, DataFrame columns are used; otherwise the sorted unique values in A are used.

control_arm

Optional control arm used for ATE comparisons. The default is the minimum resolved treatment level.

method

Any mean-API calibration method, including "aipw", "linear", "prognostic_linear", "sigmoid", "monotone_spline", "isotonic", and "auto".

X

Optional extra covariates passed through arm by arm. This is most useful with method="prognostic_linear", which uses the arm-specific predicted outcome plus X in a linear adjustment.

w

Optional full-sample observation weights. These can be inverse propensity weights or balancing weights. In randomized studies, they can be used to adjust for chance covariate imbalance and improve efficiency; in observational studies, they can be used to adjust for confounding and reduce bias. Uniform weights reproduce the unweighted behavior.

Outputs

Arm means, ATEs, and diagnostics

arm_means

Estimated mean potential outcome for every resolved treatment arm.

arm_cis

Wald confidence intervals for each arm-specific mean.

ate

All non-control-vs-control treatment effects by default.

arm_results

The underlying arm-by-arm MeanInferenceResult objects, exposed for inspection.

summary()

A human-readable Wald summary for all arm means and control-vs-treatment ATEs.

Scope

This API reuses the package's semisupervised mean machinery. It does not fit a propensity model or other nuisance functions for you.

Optional full-sample weights are supported, but this package does not currently provide a causal-arm-specific weight-construction helper.

In this version, uncertainty is Wald-only. The API uses arm-specific Wald contributions from the semisupervised mean engine to build both arm-level and ATE-level standard errors.