ehrapy.tools.covariate_balance

ehrapy.tools.covariate_balance#

ehrapy.tools.covariate_balance(edata, treatment, *, covariates, weights=None, propensity_model='logistic', layer=None)[source]#

Report standardised mean differences (SMD) for each covariate, before and after weighting.

SMD is the standard “love-plot” diagnostic: (mean_treated − mean_control) / pooled_SD. Values with |SMD| < 0.1 are conventionally considered balanced. The variance ratio is Var_treated / Var_control; values near 1 indicate similar spread between treatment arms.

When weights is provided, the “after” columns use the supplied weights (typically the IPTW output stored in estimate.params['weights']). When weights is None, this function fits its own propensity model and computes IPTW weights internally.

Parameters:

  • edata (EHRData) – Central data object.

  • treatment (str) – Column name of the binary (0/1) treatment variable.

  • covariates (Sequence[str]) – Adjustment set to evaluate. Each entry must refer to a name in edata.var_names or edata.obs.columns.

  • weights (ndarray | None, default: None) – Optional pre-computed IPTW weight vector aligned with edata.obs.index. When None, weights are computed internally from a freshly fitted propensity model.

  • propensity_model (str | BaseEstimator, default: 'logistic') – Propensity model used to compute weights when weights is None (see iptw() for the accepted values).

  • layer (str | None, default: None) – Layer of edata to draw the var-side variables from. If None, edata.X is used.

Return type:

DataFrame

Returns:

A DataFrame indexed by covariate name with columns smd_unweighted, smd_weighted, var_ratio_unweighted, and var_ratio_weighted.

Examples

>>> import ehrapy as ep
>>> import ehrdata as ed
>>> edata = ed.dt.mimic_2_preprocessed()
>>> bal = ep.tl.covariate_balance(
...     edata,
...     "aline_flg",
...     covariates=["age", "sofa_first", "sapsi_first"],
... )
>>> print(bal.round(3).to_string())
             smd_unweighted  smd_weighted  var_ratio_unweighted  var_ratio_weighted
age                   0.117        -0.044                 0.896               1.018
sofa_first            0.818        -0.220                 1.135               0.480
sapsi_first           0.627        -0.157                 1.112               0.781