causalis.scenarios.unconfoundedness.refutation.overlap.overlap_validation

Overlap diagnostics focused on positivity and propensity calibration.

Module Contents

Functions

run_overlap_diagnostics

Run overlap and calibration diagnostics for an estimated propensity model.

Data

__all__

API

causalis.scenarios.unconfoundedness.refutation.overlap.overlap_validation.run_overlap_diagnostics(data: causalis.dgp.causaldata.CausalData, estimate: causalis.data_contracts.causal_estimate.CausalEstimate, *, thresholds: Optional[Dict[str, float]] = None, n_bins: int = 10, use_hajek: Optional[bool] = None, return_summary: bool = True, auc_flip_margin: float = 0.05) → Dict[str, Any]

Run overlap and calibration diagnostics for an estimated propensity model.

The core overlap object is the propensity score

.. math::

m(X) = \mathbb{P}(D=1 \mid X).

This diagnostic checks whether estimated propensities stay away from the edges and whether the implied weights are stable. For example, ATE weights use

.. math::

w_i^{(1)} = \frac{D_i}{m(X_i)},
\qquad
w_i^{(0)} = \frac{1-D_i}{1-m(X_i)},

so very small :math:m(X_i) or very large :math:m(X_i) can create large leverage points. The report combines:

  • edge mass near 0 and 1,

  • treated/control separation in propensity space (KS, AUC),

  • effective sample size and tail diagnostics for weights,

  • calibration summaries such as ECE, recalibration slope, and intercept.

Parameters

data : CausalData Dataset used to fit the estimator. estimate : CausalEstimate Effect estimate with diagnostic_data containing propensity-related arrays such as m_hat and d. thresholds : dict, optional Optional threshold overrides keyed by metric name. n_bins : int, default 10 Number of bins used for calibration summaries. use_hajek : bool, optional Whether to evaluate normalized IPW identities. If omitted, the value is inferred from diagnostic metadata. return_summary : bool, default True Include a compact tabular summary in the returned payload. auc_flip_margin : float, default 0.05 Margin around 0.5 used when flagging reversed treated/control ranking.

Returns

Dict[str, Any] Diagnostic report containing edge-mass, calibration, weight-stability, and optional summary tables.

Raises

ValueError If required diagnostic arrays are missing or have incompatible shapes.

Examples

from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor from causalis.dgp import obs_linear_26_dataset from causalis.scenarios.unconfoundedness.model import IRM data = obs_linear_26_dataset( … n=1000, … seed=3141, … include_oracle=False, … return_causal_data=True, … ) irm = IRM( … data=data, … ml_g=RandomForestRegressor( … n_estimators=200, … max_depth=6, … min_samples_leaf=5, … random_state=3141, … ), … ml_m=RandomForestClassifier( … n_estimators=200, … max_depth=6, … min_samples_leaf=5, … random_state=3141, … ), … n_folds=3, … random_state=3141, … ) estimate = irm.fit().estimate(score=”ATE”) report = run_overlap_diagnostics(data, estimate) report[“summary”] # doctest: +SKIP report[“edge_mass”] # doctest: +SKIP

causalis.scenarios.unconfoundedness.refutation.overlap.overlap_validation.__all__

[‘run_overlap_diagnostics’]