causalis.shared.confounder_clustering

Correlation-based clustering of observed confounders.

Module Contents

Functions

cluster_confounders	Cluster confounders using their absolute pairwise correlations.
rank_confounder_clusters	Cluster confounders and rank the clusters by joint nuisance importance.

Data

CorrelationMethod
LinkageMethod
OutcomeImportanceMethod
__all__

API

causalis.shared.confounder_clustering.CorrelationMethod

None

causalis.shared.confounder_clustering.LinkageMethod

None

causalis.shared.confounder_clustering.OutcomeImportanceMethod

None

causalis.shared.confounder_clustering.cluster_confounders(data: causalis.dgp.causaldata.CausalData | causalis.dgp.multicausaldata.MultiCausalData, *, min_abs_correlation: float = 0.7, correlation_method: causalis.shared.confounder_clustering.CorrelationMethod = 'pearson', linkage_method: causalis.shared.confounder_clustering.LinkageMethod = 'complete', max_samples: Optional[int] = 200000, random_state: Optional[int] = 42) → list[list[str]]

Cluster confounders using their absolute pairwise correlations.

The clustering distance is

.. math::

d(X_i, X_j) = 1 - |\operatorname{corr}(X_i, X_j)|.

Hierarchical clustering is cut at 1 - min_abs_correlation. Negative and positive correlations of the same magnitude are therefore treated as equally similar. By default, complete linkage is used, so every pair of features in a non-singleton cluster has an absolute correlation at least as large as min_abs_correlation on the sampled data.

Parameters

data : CausalData or MultiCausalData Causal data contract exposing numeric df and confounders attributes. min_abs_correlation : float, default 0.7 Correlation cut-off in the closed interval [0, 1]. Larger values form smaller, more strongly related clusters. correlation_method : {“pearson”, “spearman”}, default “pearson” Pairwise correlation measure. Spearman correlation is useful for monotonic non-linear relationships but requires more work and memory. linkage_method : {“average”, “complete”, “single”}, default “complete” Hierarchical-linkage rule. Only complete linkage guarantees the pairwise threshold interpretation described above. max_samples : int or None, default 200000 Maximum number of rows used to estimate correlations. If the dataset is larger, rows are sampled without replacement. Pass None to use all rows. random_state : int or None, default 42 Seed used for row sampling.

Returns

list[list[str]] Clusters in the original confounder order. Features within each cluster also preserve their original order. Singleton clusters are retained.

Examples

clusters = cluster_confounders(data, min_abs_correlation=0.8) strongest_group = clusters[0] strongest_group # doctest: +SKIP [‘income’, ‘salary’, ‘credit_limit’]

Notes

Missing correlations can occur when a rare feature is constant in the sampled rows. They are treated as zero correlation, leaving that feature separate unless it is linked to another feature by valid correlations.

causalis.shared.confounder_clustering.rank_confounder_clusters(data: causalis.dgp.causaldata.CausalData | causalis.dgp.multicausaldata.MultiCausalData, effect_estimation: Any, *, min_abs_correlation: float = 0.7, correlation_method: causalis.shared.confounder_clustering.CorrelationMethod = 'pearson', linkage_method: causalis.shared.confounder_clustering.LinkageMethod = 'complete', max_samples: Optional[int] = 200000, random_state: Optional[int] = 42, outcome_importance: causalis.shared.confounder_clustering.OutcomeImportanceMethod = 'mean') → pandas.DataFrame

Cluster confounders and rank the clusters by joint nuisance importance.

For each correlation cluster :math:C_g, the treatment and outcome importances are aggregated as

.. math::

I_{D,g} = \sum_{j \in C_g} I_{m,j},

and, by default,

.. math::

I_{Y,g} = \frac{1}{2}\left(
    \sum_{j \in C_g} I_{g0,j}
    + \sum_{j \in C_g} I_{g1,j}
\right).

Clusters are sorted by score = importance_d * importance_y in descending order. Native importance vectors are normalized separately for m, g0, and g1 before aggregation.

Parameters

data : CausalData or MultiCausalData Data containing the confounders to cluster. effect_estimation : Any Fitted IRM, causal estimate with diagnostic data, or dictionary containing one of them. Feature importance must have been collected. min_abs_correlation, correlation_method, linkage_method, max_samples, random_state Forwarded to :func:cluster_confounders. outcome_importance : {“mean”, “max”}, default “mean” Combine the cluster-level g0 and g1 importance by their mean or maximum. "max" is more conservative for features important in only one treatment arm.

Returns

pandas.DataFrame Cluster ranking with columns cluster_id, features, n_features, importance_d, importance_g0, importance_g1, importance_y, and score. Row zero is the highest-ranked cluster; features can be passed directly to sensitivity_benchmark_group.

Examples

ranking = rank_confounder_clusters(data, estimate) top_group = ranking.loc[0, “features”]

causalis.shared.confounder_clustering.__all__

[‘cluster_confounders’, ‘rank_confounder_clusters’]