nispace.stats.coloc.dominance

nispace.stats.coloc.dominance(x, y, adj_r2=False, verbose=False)[source]

Dominance analysis: decompose R2 into each predictor’s average contribution.

Fits r2 on every possible predictor subset (2**n_predictors - 1 models) and averages each predictor’s marginal R2 contribution across subset sizes, giving “individual”, “partial”, and “total” dominance per predictor (the total dominance values sum exactly to the full model’s R2). Not numba-jitted; cost grows combinatorially with n_predictors.

Parameters:

  • x (np.ndarray, shape (n_obs, n_predictors), dtype float) – Does not handle NaN – callers must pre-mask.

  • y (np.ndarray, shape (n_obs,), dtype float) –

  • adj_r2 (bool, default False) – Use adjusted R2 in the underlying r2 fits.

  • verbose (bool, default False) – Print progress (model count, running R2) as fitting proceeds.

Returns:

dom_stats – "sum" (full-model R2, float), "individual" (shape (1, n_predictors)), "partial" (shape (n_predictors, n_predictors - 1)), "total" (shape (n_predictors,), sums to "sum"), "relative" ("total" normalized to sum to 1).

Return type:

dict

Raises:

ValueError – If the summed total dominance does not reconstruct the full-model R2 within np.allclose tolerance (internal consistency check).

Notes

Used by core/colocalize.py’s “dominance” colocalization method, on pre-masked, NaN-free x/y.

References

[37].