CrossedLMEResult

The result object returned by interlace.fit(). Its attribute names and structure mirror statsmodels.MixedLMResults, making it a drop-in replacement for downstream code.

class CrossedLMEResult(fe_params, fe_bse, fe_pvalues, fe_conf_int, random_effects, variance_components, theta, resid, fittedvalues, scale, fe_cov, fe_df, model, converged, nobs, ngroups, method, llf, aic, bic, nparams, _primary_group_col, _secondary_group_cols=<factory>, _random_specs=<factory>, _Z=None, _n_levels=<factory>, _fit_kwargs=<factory>, _A11=None, _W=None, correlation_params=<factory>, df_method='satterthwaite')

Result of a profiled REML fit for crossed random intercepts.

Attribute names and structure mirror statsmodels MixedLMResults so that this object is a drop-in replacement.

Parameters:

• fe_params (Any)

• fe_bse (Any)

• fe_pvalues (Any)

• fe_conf_int (Any)

• random_effects (dict[str, Any])

• variance_components (dict[str, Any])

• theta (ndarray)

• resid (ndarray)

• fittedvalues (ndarray)

• scale (float)

• fe_cov (ndarray)

• fe_df (Any)

• model (ModelInfo)

• converged (bool)

• nobs (int)

• ngroups (dict[str, int])

• method (str)

• llf (float)

• aic (float)

• bic (float)

• nparams (int)

• _primary_group_col (str)

• _secondary_group_cols (list[str])

• _random_specs (list[Any])

• _Z (Any)

• _n_levels (list[int])

• _fit_kwargs (dict[str, Any])

• _A11 (Any)

• _W (Any)

• correlation_params (dict[str, float])

• df_method (str)

fe_params

Fixed-effect coefficient estimates, indexed by predictor name. Always a pd.Series regardless of the input backend — polars Series have no named-index concept and downstream code relies on .index for parameter lookup.

Type:

pd.Series

fe_bse

Standard errors of the fixed-effect estimates. Always pd.Series.

Type:

pd.Series

fe_pvalues

Two-sided p-values for fixed-effect coefficients (t-distribution, Satterthwaite degrees of freedom). Always pd.Series.

Type:

pd.Series

fe_conf_int

95 % confidence intervals for fixed effects; columns "lower" and "upper". Always pd.DataFrame.

Type:

pd.DataFrame

fe_df

Satterthwaite denominator degrees of freedom for each fixed effect. Always pd.Series.

Type:

pd.Series

random_effects

Predicted random intercepts (BLUPs) keyed by grouping-factor name. Each value is a pd.Series (intercept-only) or pd.DataFrame (random slopes). Always pandas regardless of input backend.

Type:

dict[str, Any]

Notes

Backend behaviour: interlace accepts any narwhals-compatible frame (pandas, polars, …) as input. Augmented and diagnostic frames (hlm_augment(), hlm_resid(), hlm_influence(), hlm_leverage()) are returned in the same native type as the input. Fit-result attributes listed above are always pandas objects. variance_components : dict[str, Any]

Estimated variance components keyed by grouping-factor name.

thetanp.ndarray

Raw Cholesky factor elements (the optimised parameter vector).

residnp.ndarray

Conditional residuals y - X @ fe_params - Z @ u.

fittedvaluesnp.ndarray

Conditional fitted values X @ fe_params + Z @ u.

scalefloat

Residual variance estimate (sigma^2).

fe_covnp.ndarray

Fixed-effects covariance matrix (p x p): scale * (X' Omega^{-1} X)^{-1}.

modelModelInfo

Lightweight container carrying model matrices and metadata (exog, endog_names, groups, formula, etc.).

convergedbool

True if the optimiser reported successful convergence.

nobsint

Number of observations used in fitting.

ngroupsdict[str, int]

Number of unique levels per grouping factor.

methodstr

Estimation method used: "REML" or "ML".

llffloat

Maximised (restricted) log-likelihood at convergence.

aicfloat

Akaike information criterion: -2 * llf + 2 * nparams.

bicfloat

Bayesian information criterion: -2 * llf + nparams * log(nobs).

nparamsint

Total number of free parameters (fixed effects p + variance components n_theta + residual variance 1).

Examples

>>> import interlace, pandas as pd
>>> df = pd.DataFrame({
...     "y": [1.0, 2.0, 3.0, 1.5, 2.5, 3.5],
...     "x": [0.1, 0.2, 0.3, 0.1, 0.2, 0.3],
...     "g": ["a", "a", "a", "b", "b", "b"],
... })
>>> result = interlace.fit("y ~ x", df, groups="g")
>>> result.fe_params
Intercept    ...
x            ...
dtype: float64
>>> result.summary()

fe_params: Any

fe_bse: Any

fe_pvalues: Any

fe_conf_int: Any

random_effects: dict[str, Any]

variance_components: dict[str, Any]

theta: ndarray

resid: ndarray

fittedvalues: ndarray

scale: float

fe_cov: ndarray

fe_df: Any

model: ModelInfo

converged: bool

nobs: int

ngroups: dict[str, int]

method: str

llf: float

aic: float

bic: float

nparams: int

correlation_params: dict[str, float]

df_method: str = 'satterthwaite'

property params: Any

Fixed-effect estimates (alias for fe_params, mirrors statsmodels).

property bse: Any

Fixed-effect standard errors (alias for fe_bse, mirrors statsmodels).

property pvalues: Any

Fixed-effect p-values (alias for fe_pvalues, mirrors statsmodels).

property llf_restricted: float | None

Restricted log-likelihood for REML fits; None for ML fits.

For REML, this equals llf (the profiled REML criterion). For ML fits there is no restricted log-likelihood, so None is returned.

property fe_tvalues: Any

Fixed-effect z-scores (estimate / SE).

Named fe_tvalues for API symmetry with statsmodels; note that interlace uses the normal (z) distribution for inference, not t.

property tvalues: Any

Fixed-effect t/z-values (alias for fe_tvalues, mirrors statsmodels).

property is_singular: bool

True if the model is at the boundary of the parameter space.

A model is singular when one or more variance components have collapsed to zero. Equivalent to calling interlace.isSingular(self)().

property boundary_flags: dict[str, bool]

Per-grouping-factor boundary flags.

Returns a dict mapping each grouping factor name to True if its variance component is at the boundary (theta diagonal < 1e-4).

summary()

Return a human-readable summary mirroring lme4’s summary.merMod().

Return type:

object

simulate(nsim=1, seed=None)

Simulate response vectors; see interlace.simulate.simulate().

Return type:

ndarray

Parameters:

• nsim (int)

• seed (int | None)

bootMer(statistic=None, B=500, seed=None, show_progress=False)

Parametric bootstrap; see interlace.simulate.bootMer().

Return type:

Any

Parameters:

• statistic (Any)

• B (int)

• seed (int | None)

• show_progress (bool)

predict(newdata=None, include_re=True)

Return predictions; see interlace.predict.predict().

Return type:

ndarray

Parameters:

• newdata (object | None)

• include_re (bool)

bootstrap_se(statistic='median', n_bootstrap=1000, resample_level='group', seed=None)

Bootstrap standard error for a scalar statistic of the response.

Parameters:

• statistic – Statistic to compute on each bootstrap sample. Only "median" is currently supported.

• n_bootstrap – Number of bootstrap replicates.

• resample_level – "group" (default) resamples grouping-factor levels with replacement, then includes all observations from the sampled groups — matching R’s boot package cluster bootstrap used in the R boot cluster bootstrap convention. "observation" resamples individual observations; this underestimates the SE when group variance is substantial.

• seed – Seed for the random number generator. Pass an integer for reproducible results.

Return type:

float

Returns:

float – Bootstrap standard error (std(bootstrap_stats, ddof=1)).

Parameters:

• statistic (str)

• n_bootstrap (int)

• resample_level (str)

• seed (int | None)

property random_effects_se: dict[str, Any]

Standard errors for BLUP estimates.

Returns the square-root of the diagonal of the posterior variance matrix Var(b | y) = σ² * Lambda * A11⁻¹ * Lambda'.

Returns:

dict[str, Any] – Same structure as random_effects: for intercept-only specs a pd.Series per group, for multi-term specs a pd.DataFrame per group.

random_effects_ci(level=0.95)

Confidence intervals for BLUP estimates (normal approximation).

Returns symmetric CIs: blup ± z * se, where z is the appropriate quantile of the standard normal.

Parameters:

level – Nominal coverage probability (default 0.95).

Return type:

dict[str, Any]

Returns:

dict[str, Any] – For intercept-only specs: pd.DataFrame with columns ["lower", "upper"] and index matching group levels. For multi-term specs: pd.DataFrame with MultiIndex columns (term, bound) where bound is "lower" or "upper".

Parameters:

level (float)

confint(method='profile', level=0.95)

Confidence intervals for fixed-effect parameters.

Parameters:

• method – 'profile' (default) uses profile likelihood CIs for variance parameters (theta) via 1D Brent root-finding. 'wald' returns normal-approximation CIs for fixed effects based on the estimated standard errors.

• level – Nominal coverage probability (default 0.95).

Return type:

Any

Returns:

pd.DataFrame – For method='profile': rows are theta parameters, columns ['estimate', lo_col, hi_col]. For method='wald': rows are fixed-effect names, columns ['estimate', lo_col, hi_col].

Parameters:

• method (str)

• level (float)

update(formula=None, data=None, **kwargs)

Refit the model with a modified formula, data, or fit arguments.

Mirrors R’s update.merMod(). Any argument not supplied is taken from the original fit. The formula argument supports lme4-style dot notation: . ~ . + x2 means “keep the original LHS and RHS, then add x2 to the fixed effects”.

Parameters:

• formula – New fixed-effects formula. May use . to refer to the corresponding part of the original formula. If None, the original formula is reused unchanged.

• data – New data frame. If None, the original data is reused.

• **kwargs – Additional keyword arguments forwarded to interlace.fit() (e.g. method, groups, random, optimizer). Override the stored values from the original fit.

Return type:

CrossedLMEResult

Returns:

CrossedLMEResult

Parameters:

• formula (str | None)

• data (Any)

• kwargs (Any)

ModelInfo

Internal container for model matrices and metadata, accessible as result.model.

class ModelInfo(exog, endog, groups, endog_names, formula, data)

Container for model matrices and metadata (mirrors statsmodels model attr).

Parameters:

• exog (ndarray)

• endog (ndarray)

• groups (ndarray)

• endog_names (str)

• formula (str)

• data (_DataWrapper)

exog: ndarray

endog: ndarray

groups: ndarray

endog_names: str

formula: str

data: _DataWrapper