MarcoThiel/MMAMixedEffects | Paclet Repository

MarcoThiel`MMAMixedEffects`

MixedEffectsModelFit

MixedEffectsModelFit[data,fixed,{random,group},vars]
	fits a Gaussian model with one grouping structure.

MixedEffectsModelFit[data,fixed,{{random1,group1},{random2,group2},...},vars]
	fits crossed, nested, or independent random-effect structures.

MixedEffectsModelFit[...,Method"ML"]
	uses maximum likelihood instead of restricted maximum likelihood.

Details and Options

▪

fits Gaussian linear mixed-effects models using Wolfram expressions.

▪

Rows of data contain values for vars in order followed by one numeric response.

▪

The model is y = X beta + Z b + epsilon, with b distributed as multivariate normal with covariance G and epsilon distributed as multivariate normal with residual covariance R.

▪

fixed is a list of ordinary Wolfram basis expressions such as {1,x,x^2}; no formula or tilde parser is introduced.

▪

A random specification {terms,group} gives a correlated coefficient vector for terms at every observed group level.

▪

Separate random specifications are additive. Different factors are crossed; NestedGrouping constructs an explicit composite nested level; repeated factors in separate specifications produce independent covariance blocks.

▪

The ordinary fitting path keeps X, Z, and the relative covariance factor sparse, whitens independent residual blocks, and uses determinant/Woodbury identities instead of forming a global dense marginal covariance. Each residual-correlation block is dense, so a single very large residual group retains dense block cost.

▪

ML and REML likelihoods include all normalizing and residual-whitening determinant terms.

▪

Weights are inverse residual-variance weights: Var(epsilon_i) is proportional to 1/weight_i.

▪

Residual correlation and heteroscedastic variance functions follow nlme-style within-group semantics and can be estimated jointly when their parameters are Automatic.

▪

With OptimizationMethod->Automatic, Gaussian fits begin with quasi-Newton optimization and use deterministic Nelder-Mead refinement if the strict projected-gradient audit is not met.

▪

MissingDataMethod->"Exclude" records every removed row; no silent imputation is performed.

▪

DegreesOfFreedomMethod can request normal, Satterthwaite, or Kenward-Roger fixed-effect inference for applicable Gaussian REML fits.

▪

Known-group predictions can include conditional random effects. NewGroupAction->"Population" uses zero random effect; "Fail" rejects unseen levels.

▪

Converged, SingularFit, and optimizer termination are distinct diagnostics.

▪

The following options can be given:

Method	"REML"	Use "REML" or "ML".
DegreesOfFreedomMethod	"Normal"	Use "Normal", "Satterthwaite", or "KenwardRoger" fixed-effect inference.
ResidualCorrelation	None	Within-block correlation: AR1, ContinuousAR1, CompoundSymmetry, ARMA, Unstructured, Exponential, Gaussian, or Spherical.
ResidualGrouping	Automatic	Expression defining independent residual blocks; Automatic uses the first grouping structure.
ResidualCovariate	Automatic	Time index or coordinate vector used by temporal or spatial residual correlation.
VarianceFunction	"Identity"	Relative residual standard deviations: Identity, ByLevel, Power, Exponential, ConstantPower, or Product.
VarianceCovariate	Automatic	Numeric covariate used by a variance function.
VarianceStrata	Automatic	Levels used by a ByLevel variance function.
Weights	Automatic	Observation weights. Gaussian fitters interpret these as inverse residual-variance weights; generalized fitters report their frequency-weight interpretation.
LinearOffsetFunction	None	A scalar, vector, function, or Wolfram expression added to the linear predictor.
MissingDataMethod	"Exclude"	Use "Exclude" for recorded listwise deletion or "Fail" to reject missing input.
MaxIterations	600	Maximum outer optimizer iterations.
AccuracyGoal	Automatic	Accuracy goal passed to the selected numerical optimizer.
PrecisionGoal	Automatic	Precision goal passed to the selected numerical optimizer.
WorkingPrecision	MachinePrecision	Working precision used by numerical optimization.
OptimizationMethod	Automatic	Use the validated model-specific optimizer strategy, or request a supported explicit optimizer method.
OptimizationStarts	3	Number of deterministic starts; the fit with the smallest valid objective is retained.
ConvergenceTolerance	1 5 10	Tolerance for the scaled projected-gradient convergence gate.
ConfidenceLevel	0.95	Confidence level used for reported fixed-effect intervals.
ProgressReporting	Automatic	Show a live notebook progress panel with the current stage, objective evaluations, best objective, start number, and elapsed time. Automatic is silent without a notebook front end.
EvaluationMonitor	None	An expression evaluated after each uncached marginal-objective evaluation; use RuleDelayed for side effects.
StepMonitor	None	An expression evaluated after each completed outer optimization start; use RuleDelayed for side effects.

▪

The fitted object supports the following property groups:

▪

Data and design

	"Data"	Rows used for fitting after missing-data processing.
	"Variables"	Ordered predictor and grouping variables.
	"IncludedRowIndices"	Original row indices retained for fitting.
	"ExcludedRowIndices"	Original row indices excluded from fitting.
	"FixedEffectsDesignMatrix"	Fixed-effect design matrix.
	"RandomEffectsDesignMatrix"	Sparse random-effect design matrix.

▪

Fixed effects

	"FixedEffects"	Association of fixed-effect estimates.
	"ParameterTableEntries"	Machine-readable parameter inference entries.
	"FixedEffectCovariance"	Estimated covariance matrix of fixed effects.
	"FixedEffectCorrelationMatrix"	Corresponding correlation matrix.

▪

Random and residual effects

	"RandomEffects"	Conditional modes grouped by random-effect structure.
	"RandomEffectCovariances"	Association of estimated covariance matrices.
	"ResidualVariance"	Gaussian residual variance, when applicable.
	"ResidualParameterEstimates"	Estimated residual correlation and variance-function parameters.

▪

Predictions and residuals

	"PopulationPredictedResponse"	Training predictions with random effects set to zero.
	"ConditionalPredictedResponse"	Training predictions using conditional random effects.
	"MarginalPredictedResponse"	Response-scale predictions integrated over random effects.
	"Residuals"	Conditional response residuals.
	"PearsonResiduals"	Variance-standardized residuals.
	"DevianceResiduals"	Signed deviance residuals when defined.

▪

Likelihood and diagnostics

	"LogLikelihood"	Constants-inclusive maximized or approximated log likelihood.
	"AIC"	Akaike information criterion.
	"BIC"	Bayesian information criterion.
	"ConvergenceReport"	Gradient, error, optimizer, mode, and tolerance diagnostics.
	"Converged"	True only when documented numerical gates pass.
	"SingularFit"	Whether a random-effect covariance lies on a rank boundary.
	"Warnings"	Statistical and numerical warnings retained with the fit.

Examples

(8)

Basic Examples

(1)

Fit a patient random-intercept model and obtain a Wolfram-style fitted object:

In[1]:=

patientFit=

MixedEffectsModelFit

[patientData,{1,time,treatment},{{1},patient},{time,treatment,patient},Method"REML"]

Out[1]=

MixedEffectsModel[GaussianLinear, REML, 144 observations, 24 groups]

Compare the scientific decision with a row-independent fit:

In[1]:=

patientFit["ParameterTableEntries"]

Out[1]=

analysis	treatment	SE	p-value	decision
independent rows	0.7656	0.2701	0.0053	significant
patient random intercept	0.7656	0.6635	0.2486	not significant

Visualize all patient trajectories and the population trends:

In[1]:=

Show[ListLinePlot[patientTrajectories],populationCurves]

Out[1]=

Residual correlation is a separately modelled source of dependence: