MarcoThiel/MMAMixedEffects | Paclet Repository

New in:

1.0

| Modified in:

1.2.4

| Obsolete in:

Categorization



Keywords



Syntax Templates



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.

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.

Related Links

MixedEffectsFamily

Examples Initialization

Needs["MarcoThiel`MMAMixedEffects`"];BlockRandom[SeedRandom[6,Method"MersenneTwister"];patientIntercepts=RandomVariate[NormalDistribution[0.`,2.2`],24];iidErrors=RandomVariate[NormalDistribution[0.`,0.55`],{24,6}]];patientData=Flatten[Table[With[{tr=Boole[OddQ[i]]},Table[{N[t],tr,"P"<>IntegerString[i,10,2],N[10.`+0.35`t-0.2`tr+0.3`trt+patientIntercepts〚i〛+iidErrors〚i,t+1〛]},{t,0,5}]],{i,24}],1];

Examples

MoreExamples⊳

Fit a treatment-by-time patient random-intercept model with seeded IID residual errors:

patientFit=MixedEffectsModelFit[patientData,{1,time,treatment,timetreatment},{{1},patient},{time,treatment,patient},Method"REML"]

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

Compare an illustrative visit-5 contrast with a row-independent fit:

rowFit=LinearModelFit[patientData〚All,{1,2,4}〛,{1,time,treatment,timetreatment},{time,treatment}];c={0.`,0.`,1.`,5.`};summary[beta_,cov_]:=Withe=c.beta,s=

c.cov.c

,e,s,21-CDFNormalDistribution[],Abs

;{summary[Values[rowFit["BestFitParameters"]],rowFit["CovarianceMatrix"]],summary[Values[patientFit["FixedEffects"]],patientFit["FixedEffectCovariance"]]}

visit-5 analysis	contrast	SE	normal-Wald p-value	decision
independent rows	1.4279	0.5755	0.0131	significant
patient random intercept	1.4279	0.8004	0.0744	not significant

Visualize all patient trajectories and the population trends:

Show[ListLinePlot[patientTrajectories],populationCurves]

Residual correlation is a separately modelled source of dependence:

ListLinePlotTable[h,

0.72`

,{h,0,8}],Tableh,Exp-

2.8`

,{h,0,8},Table[{h,If[h0,1,0.35`]},{h,0,8}]

More Examples

Cross subject and item intercepts:

Nest classroom within school:

Fit independent intercept and slope blocks:

Use an AR(1) residual model:

Fit power heteroscedasticity:

Use a spatial exponential residual correlation:

Combine variance functions:

Use maximum likelihood for fixed-effect model comparison:

Exclude incomplete rows and inspect the audit trail:

Request Kenward-Roger inference:

Show or suppress live progress:

Predict an observed patient and a new patient:

Reproduce the nlme Machines worker-block example with treatment-coded machines:

Fit the nlme Oats split-plot design with variety nested inside block:

Combine a quadratic trajectory, correlated dog slopes, and side nested within dog in Pixel:

Add serial correlation to the nlme Ovary harmonic model:

Stress boundary handling with the deeply nested nlme Wafer polynomial model:

Fit the 861-row statsmodels Dietox pig-growth example:

Inspect convergence separately from singularity:

Reject a new group when population fallback is inappropriate:

Inspect boundary covariance estimates rather than treating them as optimizer failure:

Inspect the cost of one long correlated residual series:

Visualize partial pooling by connecting raw group means to conditional intercepts: