# `causalis.scenarios.unconfoundedness.refutation.unconfoundedness.unconfoundedness_validation`

Unconfoundedness diagnostics focused on covariate balance (SMD).

## Module Contents

### Functions

`run_unconfoundedness_diagnostics` | Run covariate-balance diagnostics implied by unconfoundedness.

### Data

`__all__` |

### API

causalis.scenarios.unconfoundedness.refutation.unconfoundedness.unconfoundedness_validation.run_unconfoundedness_diagnostics(data: causalis.dgp.causaldata.CausalData, estimate: causalis.data_contracts.causal_estimate.CausalEstimate, *, threshold: float = 0.1, normalize: Optional[bool] = None, return_summary: bool = True) → Dict[str, Any]

  Run covariate-balance diagnostics implied by unconfoundedness.

  The diagnostic compares the treated and control pseudo-populations induced by the estimated propensity score. For ATE, the effective weights are

  .. math::

      w_{1i} = \bar w_i \frac{D_i}{\hat m_i},
      \qquad
      w_{0i} = \bar w_i \frac{1-D_i}{1-\hat m_i},

  while for ATTE this implementation uses

  .. math::

      w_{1i} = D_i,
      \qquad
      w_{0i} = (1-D_i)\frac{\hat m_i}{1-\hat m_i}.

  For each confounder :math:`X_j`, the weighted standardized mean difference is

  .. math::

      \mathrm{SMD}_j =
      \frac{|\mu_{1j}^{(w)} - \mu_{0j}^{(w)}|}
      {\sqrt{(s_{1j}^{2,(w)} + s_{0j}^{2,(w)}) / 2}}.

  Smaller weighted SMDs are better. A common rule of thumb is to aim for :math:`|\mathrm{SMD}| < 0.10`.

  Parameters

  data : CausalData Dataset used to fit the estimator. estimate : CausalEstimate Effect estimate with `diagnostic_data` containing propensity and, when available, weight information. threshold : float, default 0.10 SMD threshold used for warnings and pass/fail summaries. normalize : bool, optional Override whether pseudo-population weights are mean-normalized. return_summary : bool, default True Include a compact summary table in the returned payload.

  Returns

  Dict[str, Any] Diagnostic report with weighted balance tables, severity flags, and an optional summary DataFrame.

  Raises

  ValueError If required diagnostic arrays are missing or have incompatible shapes. RuntimeError If balance weights collapse to zero total mass.

  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_unconfoundedness_diagnostics(data, estimate) report[“balance”][“smd_max”] # doctest: +SKIP report[“balance”][“worst_features”].head() # doctest: +SKIP

causalis.scenarios.unconfoundedness.refutation.unconfoundedness.unconfoundedness_validation.__all__

  [‘run_unconfoundedness_diagnostics’]