MixedEffectEstimator#

class mmer.MixedEffectEstimator(fixed_effects_model, max_iter=30, tol=1e-06, patience=3, correction_method='bste', slq_steps=30, n_probes=60, preconditioner=True, cg_maxiter=1000, n_jobs=-1, backend='threading')[source]#

Bases: object

Multivariate Mixed-Effects Estimator.

This estimator structurally wraps a base predictive model (e.g., a neural network, random forest, or linear model) to seamlessly learn fixed population-level signals while formally isolating random group-level variations and complex covariance matrices. It utilizes an Expectation-Maximization (EM) algorithm to iteratively estimate variance components.

Parameters:

  • fixed_effects_model (object) – A predictive base model used to estimate the fixed population effects. This model must implement standard fit(X, y) and predict(X) methods.

  • max_iter (int, default=30) – The maximum number of Expectation-Maximization (EM) cycles to perform.

  • tol (float, default=1e-6) – The numerical tolerance for declaring convergence. Convergence is reached when the relative step change in the log-likelihood drops below this threshold.

  • patience (int, default=3) – The number of consecutive iterations to tolerate without significant log-likelihood improvement before invoking early stopping.

  • correction_method (str, default="bste") – The trace estimation method for variance components. Options are: - “bste”: Block-Stochastic Trace Estimator (Highly recommended for large datasets). - “de”: Deterministic Trace Evaluator (Recommended only for small matrix sizes).

  • slq_steps (int, default=30) – The number of Lanczos iterations used for stochastic log-determinant approximations in the BSTE method.

  • n_probes (int, default=60) – The number of Rademacher random probe vectors used during stochastic trace estimation.

  • preconditioner (bool, default=True) – Whether to apply a residual block preconditioner when resolving the linear system, significantly reducing Conjugate Gradient (CG) iterations.

  • cg_maxiter (int, default=1000) – Maximum allowable Conjugate Gradient solver iterations per step.

  • n_jobs (int, default=-1) – Number of parallel threading jobs to run during stochastic trace evaluation. Defaults to -1 (use all available processors).

  • backend (str, default="threading") – The parallel execution backend (e.g., “threading” or “loky”).

fit(X, y, groups, random_slopes=None)[source]#

Train the mixed-effects framework to separate fixed and random components.

This function triggers the Expectation-Maximization (EM) engine. It alternates between fitting the fixed-effects base model to the partial residuals and updating the random covariance matrices using generalized least squares.

Parameters:

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

  • y (ndarray of shape (n_samples, n_responses)) – The multi-output continuous response matrix.

  • groups (ndarray of shape (n_samples, n_groups)) – Categorical arrays linking each observation to its respective group levels.

  • random_slopes (tuple of tuples, optional) – A tuple of length n_groups. Each inner tuple specifies the column indices in X that should act as random slope covariates for that specific grouping factor. None denotes a random-intercepts-only model.

Returns:

A fitted structural container retaining the fully converged fixed-effects estimator, globally learned variance matrices, and learned group-level effects.

Return type:

MixedModel