Student-t (robust) family

Linear mixed models with Student-t residuals for robustness against heavy-tailed errors or outliers. Estimated via EM with latent scale variables (Lange, Little & Taylor 1989): each EM iteration reduces to a weighted Gaussian LMM, reusing the profiled-REML machinery.

student_t_fit(formula, data, groups=None, random=None, nu=None, weights=None, max_iter=200, tol=1e-06, nu_init=4.0, nu_min=2.001, nu_max=200.0, method='REML', df_method='satterthwaite')[source]

Fit a linear mixed model with Student-t residuals via EM.

Parameters:

  • formula, data, groups, random, method, df_method – See interlace.fit().

  • nu – Degrees of freedom of the Student-t residuals. None (default) → estimate via interleaved 1-D Brent search on the profile log-lik (ECM). Pass a positive scalar > 2 to fix it.

  • weights – Optional observation-level prior weights (multiplicative on the log-likelihood, as in interlace.fit()).

  • max_iter, tol – EM stopping criteria. Convergence is declared when the relative change in marginal log-lik is below tol.

  • nu_init, nu_min, nu_max – Initial value and bounds for nu when estimable. nu_min must exceed 2 (variance is undefined otherwise).

Return type:

StudentTResult

Parameters:

  • formula (str)

  • data (Any)

  • groups (str | list[str] | None)

  • random (list[str] | None)

  • nu (float | None)

  • weights (ndarray | None)

  • max_iter (int)

  • tol (float)

  • nu_init (float)

  • nu_min (float)

  • nu_max (float)

  • method (str)

  • df_method (str)

class StudentTResult(lmm, nu, sigma, n_iter, converged, marginal_loglik, nu_estimated)[source]

Result of a Student-t LMM fit.

Wraps the final weighted-LMM CrossedLMEResult and exposes the Student-t-specific scale (sigma) and degrees-of-freedom (nu).

Parameters:

  • lmm (CrossedLMEResult)

  • nu (float)

  • sigma (float)

  • n_iter (int)

  • converged (bool)

  • marginal_loglik (float)

  • nu_estimated (bool)

When to use

  • Residual heavy tails / outliers that would distort Gaussian REML.

  • Compensation, lifetime, or count-like outcomes after transformation, where a small number of observations have disproportionate influence.

  • Replacing a Bayesian Student-t LMM (e.g. cmdstanpy) with a faster frequentist point-estimator while keeping the robustness property.

Quickstart

import interlace

result = interlace.fit(
    "y ~ x1 + x2",
    data=df,
    groups=["g1", "g2"],     # crossed random intercepts
    family="student_t",      # robust residuals
)
print(result.nu)             # estimated degrees of freedom
print(result.fe_params)
print(result.variance_components)

Equivalently via the explicit entry point:

from interlace.student_t import student_t_fit

result = student_t_fit(
    formula="y ~ x1 + x2",
    data=df,
    groups=["g1", "g2"],
    nu=None,                 # None → estimate; pass a number > 2 to fix
    weights=df["w"].values,  # optional observation weights
)

Notes

  • nu must satisfy nu > 2 (variance is undefined otherwise).

  • nu is weakly identified above ~10; the likelihood becomes flat and the estimator approaches the Gaussian LMM. Use nu_max to cap.

  • Observation weights enter multiplicatively on the log-likelihood, identical in meaning to interlace.fit().