MixedModel

class mmer.MixedModel(fixed_effects_model, n_samples, n_responses, n_groups, G, R, log_likelihood, is_converged, is_early_stopped, best_log_likelihood, preconditioner, cg_maxiter, force_iterative, random_slopes, training_group_posteriors=None)

Bases: object

Fitted Mixed-Effects Model Result.

Encapsulates the fitted fixed-effects model alongside the learned variance components (covariance matrices). Provides access to model selection metrics (AIC/BIC), prediction, random effects inference (BLUPs), and diagnostics.

Variables:

• fixed_effects_model (object) – The fitted base predictive model containing the fixed effects.

• n_samples (int) – The number of samples used during fitting.

• n_responses (int) – The number of response variables (outputs).

• n_groups (int) – The number of grouping factors.

• G (list of np.ndarray) – The learned random effects covariance matrices, one for each grouping factor.

• R (np.ndarray) – The learned residual covariance matrix.

• log_likelihood (list of float) – The history of the log-likelihood over the EM iterations.

• is_converged (bool) – Whether the EM algorithm successfully reached the tolerance limit.

• best_log_likelihood (float) – The highest log-likelihood achieved during fitting.

Parameters:

• n_samples (int)

• n_responses (int)

• n_groups (int)

• G (tuple[RandomCovariance, ...])

• R (ResidualCovariance)

• log_likelihood (list[float])

• is_converged (bool)

• is_early_stopped (bool)

• best_log_likelihood (float)

• preconditioner (bool)

• cg_maxiter (int)

• force_iterative (bool)

• random_slopes (tuple)

• training_group_posteriors (list[GroupPosterior])

predict(X, groups=None)

Predict responses using the fixed-effects model, and optionally include personalized random effects.

By default, if groups is not provided, predictions strictly reflect population-level trends learned by the base estimator. If groups are provided, the model performs a fast dictionary-style lookup to match the input groups to the properties (BLUPs) it learned during training.

Parameters:

• X (ndarray of shape (n_samples, n_features)) – The fixed-effects design matrix (covariates).

• groups (ndarray of shape (n_samples, n_groups), optional) – The categorical grouping factors for each observation. If provided, the predictions will be personalized by adding the learned random effect offsets.

Returns:

The predicted response values.

Return type:

ndarray of shape (n_samples, n_responses)

Notes

Known vs. Unknown Groups: When groups are provided, the prediction logic matches each group identifier to the effects learned during training. - If a group was known (seen during training), its learned Best Linear Unbiased Predictor (BLUP) offset is retrieved, scaled by any random slope covariates, and added to the prediction. - If a group is unknown (not present in the training data), the lookup safely defaults the random effect to 0. This mathematically grounds the prediction back to the population average.

Importantly, this method does not recalculate new random effects or residuals based on the input X. It purely applies historically learned offsets. For evaluating exact posterior properties on a validation dataset where true outcomes are known, use infer() instead.

infer(X, y, groups)

Perform exact posterior inference on a specific dataset where true outcomes are known.

Unlike predict(), which applies historically learned BLUPs to new data, infer takes the true known responses (y) and mathematically deconstructs them. It solves the generalized least squares equations strictly for the provided dataset using the population-level predictions and the globally learned variance matrices (G and R).

Parameters:

• X (ndarray of shape (n_samples, n_features)) – The fixed-effects design matrix.

• y (ndarray of shape (n_samples, n_responses)) – The true, known continuous response matrix.

• groups (ndarray of shape (n_samples, n_groups)) – The grouping factors linking observations to group structures.

Returns:

A unified structural container holding the exactly reconstructed observation-level properties (conditional residuals and total random effects) and group-level properties (the mathematically optimal BLUP offsets for these specific groups).

Return type:

InferenceResult

Notes

When to use `infer` vs `predict`: - Use `predict(X, groups)` in production when y is entirely unknown and you simply want to guess the outcome using previously learned group profiles. - Use `infer(X, y, groups)` during validation, testing, or model diagnostics. Because y is known, infer ignores the old training BLUPs and precisely calculates exactly how much of the error was driven by group properties versus pure noise in this specific dataset.

residuals(X, y, groups, type='conditional')

Calculate residuals of the fitted model.

Parameters:

• X (np.ndarray) – The fixed-effects design matrix.

• y (np.ndarray) – The true response matrix.

• groups (np.ndarray) – The grouping factors.

• type (str, default="conditional") – The type of residual to compute. “marginal” uses only fixed effects (y - Xb). “conditional” uses both fixed and random effects (y - Xb - Zu).

Returns:

The residuals.

Return type:

np.ndarray of shape (n_samples, n_responses)

static cov_to_corr(cov)

Convert a covariance matrix to a correlation matrix.

Parameters:

cov (np.ndarray) – A square covariance matrix.

Returns:

The corresponding correlation matrix.

Return type:

np.ndarray

property R: ndarray

Get the estimated residual covariance matrix.

property G: list[ndarray]

Get the estimated covariance matrices for each random effect grouping factor.

property R_corr: ndarray

The correlation matrix of the residuals.

property G_corr: list[ndarray]

A list containing the correlation matrices for the random effects of each grouping factor.

property fixed_effects_df: int

The degrees of freedom (number of coefficients) in the fixed-effects model, if discernible. Otherwise 0.

property aic: float

The Akaike Information Criterion (AIC) for model selection.

property bic: float

The Bayesian Information Criterion (BIC) for model selection.

pseudo_r2(X, y, groups)

Compute the pseudo R-squared values.

Calculates both the marginal R-squared (variance explained by fixed effects only) and conditional R-squared (variance explained by both fixed and random effects).

Parameters:

• X (np.ndarray) – The fixed-effects design matrix.

• y (np.ndarray) – The true response matrix.

• groups (np.ndarray) – The grouping factors.

Returns:

A dictionary with keys “marginal” and “conditional” containing the respective R-squared values for each output.

Return type:

dict

icc()

Compute the Intra-Class Correlation Coefficient (ICC) for each group.

Returns:

A dictionary where keys are group names and values are the proportion of total variance explained by the group random intercepts.

Return type:

dict

blups(X, y, groups, group_idx=0)

Extract the Best Linear Unbiased Predictors (BLUPs) for a specific grouping factor.

Parameters:

• X (np.ndarray) – The fixed-effects design matrix.

• y (np.ndarray) – The true response matrix.

• groups (np.ndarray) – The grouping factors.

• group_idx (int, default=0) – The index of the grouping factor to extract BLUPs for.

Returns:

A DataFrame containing the random intercepts and slopes for each unique level of the group.

Return type:

pandas.DataFrame

marginal_corr(slope_covariates=None)

Compute the total marginal correlation matrix (m x m) for a single observation profile.

Parameters:

slope_covariates (list of np.ndarray or None, optional) – A list specifying the covariates (excluding the intercept) for each grouping factor.

Returns:

The marginal correlation matrix of shape (n_responses, n_responses).

Return type:

np.ndarray

marginal_cov(slope_covariates=None)

Compute the unconditional marginal covariance matrix for a single new observation.

Parameters:

slope_covariates (list of np.ndarray or None, optional) – A list specifying the covariates (excluding the intercept) for each grouping factor.

Returns:

The marginal covariance matrix of shape (n_responses, n_responses).

Return type:

np.ndarray

summary()

Generate a formatted summary string of the fitted model.

Return type:

str