Leverage

Compute the hat-matrix diagonal decomposed into fixed-effect and random-effect components, following Demidenko & Stukel (2005) and Nobre & Singer (2007).

leverage(model, level=1)

Calculate observation-level leverage for a fitted linear mixed model.

Parameters:

• model – A CrossedLMEResult or statsmodels MixedLMResults object.

• level – Reserved for future group-level leverage; currently only 1 (observation level) is supported.

Return type:

Any

Returns:

Native DataFrame (pandas, polars, …) matching the model input type. – Columns: overall (H1+H2), fixef (H1), ranef (H2), ranef.uc (unconfounded H2, Nobre & Singer).

Parameters:

• model (Any)

• level (int)

Examples

>>> lev = interlace.leverage(result)
>>> lev["overall"].mean()

Returned columns

Column	Description
overall	H1 + H2 (total leverage)
fixef	H1 — fixed-effect leverage
ranef	H2 — random-effect leverage (Demidenko & Stukel)
ranef.uc	Unconfounded H2 (Nobre & Singer)

Example

import interlace

result = interlace.fit("rt ~ condition", data=df, groups=["subject", "item"])
lev = interlace.leverage(result)

# Flag high-leverage observations (rule of thumb: overall > 2p/n)
p = len(result.fe_params)
n = result.nobs
lev_high = lev[lev["overall"] > 2 * p / n]
print(f"{len(lev_high)} high-leverage observations")

Structure helpers

These functions extract the model structures needed to dispatch leverage computation to the correct code path. They are part of the stable public API and are used by downstream consumers (e.g. gpgap) to inspect model layout.

crossed_structures(model)

Extract (groups, group_labels, exog_re_li, D) from a CrossedLMEResult.

Builds the per-primary-group Z_i matrices using the full joint random-effects structure so that V_i = Z_i D Z_i’ + σ²I is correct for random intercepts and slopes.

Parameters:

model – A fitted CrossedLMEResult object.

Return type:

tuple[ndarray, list[Any], list[ndarray], ndarray]

Returns:

tuple – (groups, group_labels, exog_re_li, D) where

• groups (np.ndarray, shape (n,)) — primary-group label for each observation.

• group_labels (list) — sorted unique levels of the primary grouping factor.

• exog_re_li (list of np.ndarray) — per-group Z_i design matrices for random effects.

• D (np.ndarray) — block-diagonal covariance matrix for the joint random-effects vector.

Parameters:

model (CrossedLMEResult)

Examples

>>> groups, labels, Zi_list, D = interlace.crossed_structures(result)

statsmodels_structures(model)

Extract leverage structures from a statsmodels MixedLMResults object.

Parameters:

model – A fitted statsmodels MixedLMResults object.

Return type:

tuple[Any, Any, Any, Any, Any]

Returns:

tuple – (groups, group_labels, exog_re_li, D, cov_fe) where

• groups — primary-group label array for each observation.

• group_labels — sorted unique group levels.

• exog_re_li (list of np.ndarray) — per-group random-effects design matrices.

• D (np.ndarray) — random-effects covariance matrix.

• cov_fe (np.ndarray) — fixed-effects covariance matrix (X'Ω⁻¹X)⁻¹.

Parameters:

model (Any)

Examples

>>> groups, labels, Zi_list, D, cov_fe = interlace.statsmodels_structures(model)

See also

• Influence diagnostics — Cook’s distance and MDFFITS (impact on estimates, not just fit)

• Augment — append leverage + influence metrics to the original DataFrame

• Residuals — residual diagnostics