fitlmematrix

Fit linear mixed-effects model

Syntax

lme = fitlmematrix(X,y,Z,[])

lme = fitlmematrix(X,y,Z,G)

lme = fitlmematrix(___,Name,Value)

Description

lme = fitlmematrix(X,y,Z,[]) creates a linear mixed-effects model of the responses y using the fixed-effects design matrix X and random-effects design matrix or matrices in Z.

[] implies that there is one group. That is, the grouping variable G is ones(n,1), where n is the number of observations. Using fitlmematrix(X,Y,Z,[]) without a specified covariance pattern most likely results in a nonidentifiable model. This syntax is recommended only if you build the grouping information into the random effects design Z and specify a covariance pattern for the random effects using the 'CovariancePattern' name-value pair argument.

lme = fitlmematrix(X,y,Z,G) creates a linear mixed-effects model of the responses y using the fixed-effects design matrix X and random-effects design matrix Z or matrices in Z, and the grouping variable or variables in G.

lme = fitlmematrix(___,Name,Value) also creates a linear mixed-effects model with additional options specified by one or more Name,Value pair arguments, using any of the previous input arguments.

For example, you can specify the names of the response, predictor, and grouping variables. You can also specify the covariance pattern, fitting method, or the optimization algorithm.

Examples

No Grouping Variable Specified

Load the sample data.

load carsmall

Fit a linear mixed-effects model, where miles per gallon (MPG) is the response, weight is the predictor variable, and the intercept varies by model year. First, define the design matrices. Then, fit the model using the specified design matrices.

y = MPG;
X = [ones(size(Weight)), Weight];
Z = ones(size(y));
lme = fitlmematrix(X,y,Z,Model_Year)

lme = 
Linear mixed-effects model fit by ML

Model information:
    Number of observations              94
    Fixed effects coefficients           2
    Random effects coefficients          3
    Covariance parameters                2

Formula:
    y ~ x1 + x2 + (z11 | g1)

Model fit statistics:
    AIC       BIC       LogLikelihood    Deviance
    486.09    496.26    -239.04          478.09  

Fixed effects coefficients (95% CIs):
    Name          Estimate      SE           tStat      DF    pValue        Lower         Upper     
    {'x1'}            43.575       2.3038     18.915    92    1.8371e-33            39        48.151
    {'x2'}        -0.0067097    0.0004242    -15.817    92    5.5373e-28    -0.0075522    -0.0058672

Random effects covariance parameters (95% CIs):
Group: g1 (3 Levels)
    Name1          Name2          Type           Estimate    Lower     Upper 
    {'z11'}        {'z11'}        {'std'}        3.301       1.4448    7.5421

Group: Error
    Name               Estimate    Lower     Upper 
    {'Res Std'}        2.8997      2.5075    3.3532

Now, fit the same model by building the grouping into the Z matrix.

Z = double([Model_Year==70, Model_Year==76, Model_Year==82]);
lme = fitlmematrix(X,y,Z,[],'Covariancepattern','Isotropic')

lme = 
Linear mixed-effects model fit by ML

Model information:
    Number of observations              94
    Fixed effects coefficients           2
    Random effects coefficients          3
    Covariance parameters                2

Formula:
    y ~ x1 + x2 + (z11 + z12 + z13 | g1)

Model fit statistics:
    AIC       BIC       LogLikelihood    Deviance
    486.09    496.26    -239.04          478.09  

Fixed effects coefficients (95% CIs):
    Name          Estimate      SE           tStat      DF    pValue        Lower         Upper     
    {'x1'}            43.575       2.3038     18.915    92    1.8371e-33            39        48.151
    {'x2'}        -0.0067097    0.0004242    -15.817    92    5.5373e-28    -0.0075522    -0.0058672

Random effects covariance parameters (95% CIs):
Group: g1 (1 Levels)
    Name1          Name2          Type           Estimate    Lower     Upper 
    {'z11'}        {'z11'}        {'std'}        3.301       1.4448    7.5421

Group: Error
    Name               Estimate    Lower     Upper 
    {'Res Std'}        2.8997      2.5075    3.3532

Longitudinal Study with a Covariate

Load the sample data.

load('weight.mat');

weight contains data from a longitudinal study, where 20 subjects are randomly assigned 4 exercise programs (A, B, C, D) and their weight loss is recorded over six 2-week time periods. This is simulated data.

Define Subject and Program as categorical variables. Create the design matrices for a linear mixed-effects model, with the initial weight, type of program, week, and the interaction between the week and type of program as the fixed effects. The intercept and coefficient of week vary by subject.

This model corresponds to

$$\begin{array}{l}{y}_{im}={\beta }_0+{\beta }_{1}I{W}_i+{\beta }_{2}Wee{k}_i+{\beta }_{3}I{\left[PB\right]}_i+{\beta }_{4}I{\left[PC\right]}_i+{\beta }_{5}I{\left[PD\right]}_i\\ +{\beta }_6\left(Wee{k}_i*I{\left[PB\right]}_i\right)+{\beta }_7\left(Wee{k}_i*I{\left[PC\right]}_i\right)+{\beta }_8\left(Wee{k}_i*I{\left[PD\right]}_i\right)\\ +b{}_{0m}+b_{1m}Wee{k}_{im}+{\epsilon }_{im},\end{array}$$

where $$i$$ = 1, 2, ..., 120, and $$m$$ = 1, 2, ..., 20. $${\beta }_j$$ are the fixed-effects coefficients, $$j$$ = 0, 1, ..., 8, and $$b_{0m}$$ and $$b_{1m}$$ are random effects. $$IW$$ stands for initial weight and $$I[\cdot ]$$ is a dummy variable representing a type of program. For example, $$I[PB{]}_i$$ is the dummy variable representing program type B. The random effects and observation error have the following prior distributions:

$$b_{0m}\sim N(0,{\sigma }_0^2)$$

$$b_{1m}\sim N(0,{\sigma }_1^2)$$

$${\epsilon }_{im}\sim N(0,{\sigma }^2).$$

Subject = nominal(Subject);
Program = nominal(Program);
D = dummyvar(Program); % Create dummy variables for Program
X = [ones(120,1), InitialWeight, D(:,2:4), Week,...
		 D(:,2).*Week, D(:,3).*Week, D(:,4).*Week];
Z = [ones(120,1), Week];
G = Subject;

Since the model has an intercept, you only need the dummy variables for programs B, C, and D. This is also known as the 'reference' method of coding dummy variables.

Fit the model using fitlmematrix with the defined design matrices and grouping variables.

lme = fitlmematrix(X,y,Z,G,'FixedEffectPredictors',...
{'Intercept','InitWeight','PrgB','PrgC','PrgD','Week','Week_PrgB','Week_PrgC','Week_PrgD'},...
'RandomEffectPredictors',{{'Intercept','Week'}},'RandomEffectGroups',{'Subject'})

lme = 
Linear mixed-effects model fit by ML

Model information:
    Number of observations             120
    Fixed effects coefficients           9
    Random effects coefficients         40
    Covariance parameters                4

Formula:
    y ~ Intercept + InitWeight + PrgB + PrgC + PrgD + Week + Week_PrgB + Week_PrgC + Week_PrgD + (Intercept + Week | Subject)

Model fit statistics:
    AIC        BIC       LogLikelihood    Deviance
    -22.981    13.257    24.49            -48.981 

Fixed effects coefficients (95% CIs):
    Name                  Estimate     SE           tStat       DF     pValue       Lower         Upper    
    {'Intercept' }          0.66105      0.25892      2.5531    111     0.012034       0.14798       1.1741
    {'InitWeight'}        0.0031879    0.0013814      2.3078    111     0.022863    0.00045067    0.0059252
    {'PrgB'      }          0.36079      0.13139       2.746    111    0.0070394       0.10044      0.62113
    {'PrgC'      }        -0.033263      0.13117    -0.25358    111      0.80029      -0.29319      0.22666
    {'PrgD'      }          0.11317      0.13132     0.86175    111      0.39068      -0.14706       0.3734
    {'Week'      }           0.1732     0.067454      2.5677    111     0.011567      0.039536      0.30686
    {'Week_PrgB' }         0.038771     0.095394     0.40644    111      0.68521      -0.15026       0.2278
    {'Week_PrgC' }         0.030543     0.095394     0.32018    111      0.74944      -0.15849      0.21957
    {'Week_PrgD' }         0.033114     0.095394     0.34713    111      0.72915      -0.15592      0.22214

Random effects covariance parameters (95% CIs):
Group: Subject (20 Levels)
    Name1                Name2                Type            Estimate    Lower      Upper  
    {'Intercept'}        {'Intercept'}        {'std' }        0.18407     0.12281    0.27587
    {'Week'     }        {'Intercept'}        {'corr'}        0.66841     0.21076    0.88573
    {'Week'     }        {'Week'     }        {'std' }        0.15033     0.11004    0.20537

Group: Error
    Name               Estimate    Lower       Upper  
    {'Res Std'}        0.10261     0.087882    0.11981

Examine the fixed effects coefficients table. The row labeled 'InitWeight' has a $$p$$-value of 0.0228, and the row labeled 'Week' has a $$p$$-value of 0.0115. These $$p$$-values indicate significant effects of the initial weights of the subjects and the time factor in the amount of weight lost. The weight loss of subjects who are in program B is significantly different relative to the weight loss of subjects who are in program A. The lower and upper limits of the covariance parameters for the random effects do not include zero, thus they seem significant. You can also test the significance of the random-effects using the compare method.

Random Intercept Model

Load the sample data and convert it to table format.

load flu
flu = dataset2table(flu)

flu=52×11 table
         Date          NE      MidAtl    ENCentral    WNCentral    SAtl     ESCentral    WSCentral     Mtn      Pac     WtdILI
    ______________    _____    ______    _________    _________    _____    _________    _________    _____    _____    ______

    {'10/9/2005' }     0.97    1.025       1.232        1.286      1.082      1.457          1.1      0.981    0.971    1.182 
    {'10/16/2005'}    1.136     1.06       1.228        1.286      1.146      1.644        1.123      0.976    0.917     1.22 
    {'10/23/2005'}    1.135    1.172       1.278        1.536      1.274      1.556        1.236      1.102    0.895     1.31 
    {'10/30/2005'}     1.52    1.489       1.576        1.794       1.59      2.252        1.612      1.321    1.082    1.343 
    {'11/6/2005' }    1.365    1.394        1.53        1.825       1.62      2.059        1.471      1.453    1.118    1.586 
    {'11/13/2005'}     1.39    1.477       1.506          1.9      1.683      1.813        1.464      1.388    1.204     1.47 
    {'11/20/2005'}    1.212    1.231       1.295        1.495      1.347      1.794        1.303      1.371    1.137    1.611 
    {'11/27/2005'}    1.477    1.546       1.557        1.855      1.678      2.159        1.739      1.628    1.443    1.827 
    {'12/4/2005' }    1.285     1.43       1.482        1.635      1.577      1.903         1.53      1.701    1.516    1.776 
    {'12/11/2005'}    1.354     1.45        1.46        1.794      1.583      1.894        1.831      2.364    2.094    1.941 
    {'12/18/2005'}    1.502    1.622       1.638        1.988      1.947       2.22        2.577       3.89     2.66     2.34 
    {'12/25/2005'}     1.86    1.915       1.955         2.38      2.343      3.027        3.219      4.862    2.595    3.086 
    {'1/1/2006'  }    2.114    2.174       2.065        2.557      2.275      2.498        2.644      3.352    2.181     3.26 
    {'1/8/2006'  }    1.815    1.932       1.822        2.046      1.969      1.805        2.189      2.132    1.717    2.613 
    {'1/15/2006' }    1.541    1.695       1.581        2.008      1.718      1.662        2.156      1.694    1.351    2.247 
    {'1/22/2006' }    1.632    1.758       1.711        2.217      1.866      2.194        2.268      1.826    1.384    2.352 
      ⋮

The flu table has a Date variable, and 10 variables for estimated influenza rates (in 9 different regions, estimated from Google® searches, plus a nationwide estimate from the Centers for Disease Control and Prevention, CDC).

To fit a linear-mixed effects model, where the influenza rates are the responses, combine the nine columns corresponding to the regions into an array that has a single response variable, FluRate, and a nominal variable, Region, the nationwide estimate WtdILI, that shows which region each estimate is from, and the grouping variable Date.

flu = stack(flu,2:10,NewDataVariableName="FluRate",...
    IndexVariableName="Region");
flu.Date = nominal(flu.Date);

Define the design matrices for a random-intercept linear mixed-effects model, where the intercept varies by Date. The corresponding model is

$$y_{im}={\beta }_0+{\beta }_1{WtdILI}_{im}+b_{0m}+{\epsilon }_{im},i=1,2,...,468,m=1,2,...,52,$$

where $$y_{im}$$ is the observation $$i$$ for level $$m$$ of grouping variable Date, $$b_{0m}$$ is the random effect for level $$m$$ of the grouping variable Date, and $${\epsilon }_{im}$$ is the observation error for observation $$i$$. The random effect has the prior distribution,

$$b_{0m}\sim N(0,{\sigma }_b^2),$$

and the error term has the distribution,

$${\epsilon }_{im}\sim N(0,{\sigma }^2).$$

y = flu.FluRate;
X = [ones(468,1) flu.WtdILI];
Z = [ones(468,1)];
G = flu.Date;

Fit the linear mixed-effects model.

lme = fitlmematrix(X,y,Z,G,'FixedEffectPredictors',{'Intercept','NationalRate'},...
'RandomEffectPredictors',{{'Intercept'}},'RandomEffectGroups',{'Date'})

lme = 
Linear mixed-effects model fit by ML

Model information:
    Number of observations             468
    Fixed effects coefficients           2
    Random effects coefficients         52
    Covariance parameters                2

Formula:
    y ~ Intercept + NationalRate + (Intercept | Date)

Model fit statistics:
    AIC       BIC       LogLikelihood    Deviance
    286.24    302.83    -139.12          278.24  

Fixed effects coefficients (95% CIs):
    Name                    Estimate    SE          tStat     DF     pValue        Lower       Upper  
    {'Intercept'   }        0.16385     0.057525    2.8484    466     0.0045885    0.050813    0.27689
    {'NationalRate'}         0.7236     0.032219    22.459    466    3.0502e-76     0.66028    0.78691

Random effects covariance parameters (95% CIs):
Group: Date (52 Levels)
    Name1                Name2                Type           Estimate    Lower      Upper  
    {'Intercept'}        {'Intercept'}        {'std'}        0.17146     0.13227    0.22226

Group: Error
    Name               Estimate    Lower      Upper  
    {'Res Std'}        0.30201     0.28217    0.32324

The confidence limits of the standard deviation of the random-effects term $${\sigma }_b$$, do not include zero (0.13227, 0.22226), which indicates that the random-effects term is significant. You can also test the significance of the random-effects using compare method.

The estimated value of an observation is the sum of the fixed-effects values and value of the random effect at the grouping variable level corresponding to that observation. For example, the estimated flu rate for observation 28

$$\begin{array}{l}{\underset{}{\overset{ˆ}{y}}}_{28}={\underset{}{\overset{ˆ}{\beta }}}_0+{\underset{}{\overset{ˆ}{\beta }}}_1{WtdILI}_{28}+{\underset{}{\overset{ˆ}{b}}}_{10/30/2005}\\ =0.1639+0.7236*(1.343)+0.3318\\ =1.46749,\end{array}$$

where $$\underset{}{\overset{ˆ}{b}}$$ is the best linear unbiased predictor (BLUP) of the random effects for the intercept. You can compute this value as follows.

beta = fixedEffects(lme);
[~,~,STATS] = randomEffects(lme); % compute the random effects statistics STATS
STATS.Level = nominal(STATS.Level);
y_hat = beta(1) + beta(2)*flu.WtdILI(28) + STATS.Estimate(STATS.Level=='10/30/2005')

y_hat = 
1.4674

You can simply display the fitted value using the fitted(lme) method.

F = fitted(lme);
F(28)

ans = 
1.4674

Randomized Block Design

Load the sample data.

load('shift.mat');

The data shows the deviations from the target quality characteristic measured from the products that five operators manufacture during three shifts: morning, evening, and night. This is a randomized block design, where the operators are the blocks. The experiment is designed to study the impact of the time of shift on the performance. The performance measure is the deviations of the quality characteristics from the target value. This is simulated data.

Define the design matrices for a linear mixed-effects model with a random intercept grouped by operator, and shift as the fixed effects. Use the 'effects' contrasts. 'effects' contrasts mean that the coefficients sum to 0. You need to create two contrast coded variables in the fixed-effects design matrix, X1 and X2, where

$$\text{Shift}\text{\_}\text{Evening}=\{\begin{array}{ll}0,& \text{if}\text{Morning}\\ 1,& \text{if}\text{Evening}\\ -1,& \text{if}\text{Night}\end{array}$$

$$\text{Shift}\text{\_}\text{Morning}=\{\begin{array}{ll}1,& \text{if}\text{Morning}\\ 0,& \text{if}\text{Evening}\\ -1,& \text{if}\text{Night}\end{array}$$

The model corresponds to

$$\begin{array}{lrl}\text{Morning}\text{Shift:}& {\text{QCDev}}_{im}& ={\beta }_0+{\beta }_2{\text{Shift}\text{\_}\text{Morning}}_i+b_{0m}+{ϵ}_{im},\\ \text{Evening}\text{Shift:}& {\text{QCDev}}_{im}& ={\beta }_0+{\beta }_1{\text{Shift}\text{\_}\text{Evening}}_i+b_{0m}+{ϵ}_{im},\\ \text{Night}\text{Shift:}& {\text{QCDev}}_{im}& ={\beta }_0-{\beta }_1{\text{Shift}\text{\_}\text{Evening}}_i-{\beta }_2{\text{Shift}\text{\_}\text{Morning}}_i+b_{0m}+{ϵ}_{im},\end{array}$$

where $$i$$ represents the observations, and $$m$$ represents the operators, $$i$$ = 1, 2, ..., 15, and $$m$$ = 1, 2, ..., 5. The random effects and the observation error have the following distributions:

$$b_{0m}\sim N(0,{\sigma }_b^2)$$

and

$${\epsilon }_{im}\sim N(0,{\sigma }^2).$$

S = shift.Shift;
X1 = (S=='Morning') - (S=='Night');
X2 = (S=='Evening') - (S=='Night');
X = [ones(15,1), X1, X2];
y = shift.QCDev;
Z = ones(15,1);
G = shift.Operator;

Fit a linear mixed-effects model using the specified design matrices and restricted maximum likelihood method.

lme = fitlmematrix(X,y,Z,G,'FitMethod','REML','FixedEffectPredictors',....
{'Intercept','S_Morning','S_Evening'},'RandomEffectPredictors',{{'Intercept'}},...
'RandomEffectGroups',{'Operator'},'DummyVarCoding','effects')

lme = 
Linear mixed-effects model fit by REML

Model information:
    Number of observations              15
    Fixed effects coefficients           3
    Random effects coefficients          5
    Covariance parameters                2

Formula:
    y ~ Intercept + S_Morning + S_Evening + (Intercept | Operator)

Model fit statistics:
    AIC       BIC       LogLikelihood    Deviance
    58.913    61.337    -24.456          48.913  

Fixed effects coefficients (95% CIs):
    Name                 Estimate    SE         tStat      DF    pValue       Lower      Upper   
    {'Intercept'}          3.6525    0.94109     3.8812    12    0.0021832     1.6021       5.703
    {'S_Morning'}        -0.91973    0.31206    -2.9473    12     0.012206    -1.5997    -0.23981
    {'S_Evening'}        -0.53293    0.31206    -1.7078    12      0.11339    -1.2129     0.14699

Random effects covariance parameters (95% CIs):
Group: Operator (5 Levels)
    Name1                Name2                Type           Estimate    Lower      Upper 
    {'Intercept'}        {'Intercept'}        {'std'}        2.0457      0.98207    4.2612

Group: Error
    Name               Estimate    Lower      Upper
    {'Res Std'}        0.85462     0.52357    1.395

Compute the best linear unbiased predictor (BLUP) estimates of random effects.

B = randomEffects(lme)

B = 5×1

    0.5775
    1.1757
   -2.1715
    2.3655
   -1.9472

The estimated deviation from the target quality characteristics for the third operator working the evening shift is

$$\begin{array}{l}{\underset{}{\overset{ˆ}{y}}}_{\text{Evening},\text{Operator}3}={\underset{}{\overset{ˆ}{\beta }}}_0+{\underset{}{\overset{ˆ}{\beta }}}_1\text{Shift}\text{\_}\text{Evening}+{\underset{}{\overset{ˆ}{b}}}_{03}\\ =3.6525-0.53293-2.1715\\ =0.94807.\end{array}$$

You can also display this value as follows.

F = fitted(lme);
F(shift.Shift=='Evening' & shift.Operator=='3')

ans = 
0.9481

Correlated and Uncorrelated Random-Effects Terms

Load the sample data.

load carbig

Fit a linear mixed-effects model for miles per gallon (MPG), with fixed effects for acceleration and horsepower, and uncorrelated random effect for intercept and acceleration grouped by the model year. This model corresponds to

$${MPG}_{im}={\beta }_0+{\beta }_1{Acc}_i+{\beta }_{2}HP+b_{0m}+{b_1}_m{Acc}_{im}+{\epsilon }_{im},m=1,2,3,$$

with the random-effects terms having the following prior distributions:

$$b_{0m}\sim N(0,{\sigma }_0^2),$$

$$b_{1m}\sim N(0,{\sigma }_1^2),$$

where $$m$$ represents the model year.

First, prepare the design matrices for fitting the linear mixed-effects model.

X = [ones(406,1) Acceleration Horsepower];
Z = {ones(406,1),Acceleration};
G = {Model_Year,Model_Year};
Model_Year = nominal(Model_Year);

Now, fit the model using fitlmematrix with the defined design matrices and grouping variables.

lme = fitlmematrix(X,MPG,Z,G,'FixedEffectPredictors',....
{'Intercept','Acceleration','Horsepower'},'RandomEffectPredictors',...
{{'Intercept'},{'Acceleration'}},'RandomEffectGroups',{'Model_Year','Model_Year'})

lme = 
Linear mixed-effects model fit by ML

Model information:
    Number of observations             392
    Fixed effects coefficients           3
    Random effects coefficients         26
    Covariance parameters                3

Formula:
    y ~ Intercept + Acceleration + Horsepower + (Intercept | Model_Year) + (Acceleration | Model_Year)

Model fit statistics:
    AIC       BIC       LogLikelihood    Deviance
    2194.5    2218.3    -1091.3          2182.5  

Fixed effects coefficients (95% CIs):
    Name                    Estimate    SE           tStat      DF     pValue        Lower       Upper   
    {'Intercept'   }          49.839       2.0518     24.291    389    5.6168e-80      45.806      53.873
    {'Acceleration'}        -0.58565      0.10846    -5.3995    389    1.1652e-07     -0.7989     -0.3724
    {'Horsepower'  }        -0.16534    0.0071227    -23.213    389    1.9755e-75    -0.17934    -0.15133

Random effects covariance parameters (95% CIs):
Group: Model_Year (13 Levels)
    Name1                Name2                Type           Estimate      Lower    Upper
    {'Intercept'}        {'Intercept'}        {'std'}        7.8006e-07    NaN      NaN  

Group: Model_Year (13 Levels)
    Name1                   Name2                   Type           Estimate    Lower      Upper  
    {'Acceleration'}        {'Acceleration'}        {'std'}        0.18783     0.12523    0.28172

Group: Error
    Name               Estimate    Lower     Upper 
    {'Res Std'}        3.7258      3.4698    4.0007

Note that the random effects covariance parameters for intercept and acceleration are separate in the display. The standard deviation of the random effect for the intercept does not seem significant.

Refit the model with potentially correlated random effects for intercept and acceleration. In this case, the random-effects terms has this prior distribution

$$b_m=\left(\begin{array}{l}{b}_{0m}\\ b_{1m}\end{array}\right)\sim N\left(0,\left(\begin{array}{cc}{\sigma }_0^2& {\sigma }_{0,1}\\ {\sigma }_{0,1}& {\sigma }_1^2\end{array}\right)\right),$$

where $$m$$ represents the model year.

First, prepare the random-effects design matrix and grouping variable.

Z = [ones(406,1) Acceleration];
G = Model_Year;

lme = fitlmematrix(X,MPG,Z,G,'FixedEffectPredictors',....
{'Intercept','Acceleration','Horsepower'},'RandomEffectPredictors',...
{{'Intercept','Acceleration'}},'RandomEffectGroups',{'Model_Year'})

lme = 
Linear mixed-effects model fit by ML

Model information:
    Number of observations             392
    Fixed effects coefficients           3
    Random effects coefficients         26
    Covariance parameters                4

Formula:
    y ~ Intercept + Acceleration + Horsepower + (Intercept + Acceleration | Model_Year)

Model fit statistics:
    AIC       BIC       LogLikelihood    Deviance
    2193.5    2221.3    -1089.7          2179.5  

Fixed effects coefficients (95% CIs):
    Name                    Estimate    SE           tStat      DF     pValue        Lower       Upper   
    {'Intercept'   }          50.133       2.2652     22.132    389    7.7727e-71      45.679      54.586
    {'Acceleration'}        -0.58327      0.13394    -4.3545    389    1.7075e-05    -0.84661    -0.31992
    {'Horsepower'  }        -0.16954    0.0072609     -23.35    389     5.188e-76    -0.18382    -0.15527

Random effects covariance parameters (95% CIs):
Group: Model_Year (13 Levels)
    Name1                   Name2                   Type            Estimate    Lower       Upper   
    {'Intercept'   }        {'Intercept'   }        {'std' }          3.3475      1.2862      8.7119
    {'Acceleration'}        {'Intercept'   }        {'corr'}        -0.87971    -0.98501    -0.29675
    {'Acceleration'}        {'Acceleration'}        {'std' }         0.33789      0.1825     0.62558

Group: Error
    Name               Estimate    Lower     Upper 
    {'Res Std'}        3.6874      3.4298    3.9644

Note that the random effects covariance parameters for intercept and acceleration are together in the display, with an addition of the correlation between the intercept and acceleration. The confidence intervals for the standard deviations and the correlation between the random effects for intercept and acceleration do not include 0s, hence they seem significant. You can compare these two models using the compare method.

Specify the Covariance Pattern

Load the sample data.

load('weight.mat');

weight contains data from a longitudinal study, where 20 subjects are randomly assigned 4 exercise programs, and their weight loss is recorded over six 2-week time periods. This is simulated data.

Define Subject and Program as categorical variables.

Subject = nominal(Subject);
Program = nominal(Program);

Create the design matrices for a linear mixed-effects model, with the initial weight, type of program, and week as the fixed effects.

D = dummyvar(Program);
X = [ones(120,1), InitialWeight, D(:,2:4), Week];
Z = [ones(120,1) Week];
G = Subject;

This model corresponds to

$$\begin{array}{l}{y}_{im}={\beta }_0+{\beta }_{1}I{W}_i+{\beta }_{2}Wee{k}_i+{\beta }_{3}I{\left[PB\right]}_i+{\beta }_{4}I{\left[PC\right]}_i+{\beta }_{5}I{\left[PD\right]}_i\\ +b{}_{0m}+b_{1m}Week{2}_{im}+b_{2m}Week{4}_{im}+b_{3m}Week{6}_{im}+b_{4m}Week{8}_{im}\\ +b_{5m}Week10_{im}+b_{6m}Week12_{im}+{\epsilon }_{im},\end{array}$$

where $$i$$ = 1, 2, ..., 120, and $$m$$ = 1, 2, ..., 20.

$${\beta }_j$$ are the fixed-effects coefficients, $$j$$ = 0, 1, ...,8, and $$b_{0m}$$ and $$b_{1m}$$ are random effects. $$IW$$ stands for initial weight and $$I[.]$$ is a dummy variable representing a type of program. For example, $$I[PB{]}_i$$ is the dummy variable representing program type B. The random effects and observation error have the following prior distributions:

$$b_{0m}\sim N(0,{\sigma }_0^2)$$

$$b_{1m}\sim N(0,{\sigma }_1^2)$$

$${\epsilon }_{im}\sim N(0,{\sigma }^2).$$

Fit the model using fitlmematrix with the defined design matrices and grouping variables. Assume the repeated observations collected on a subject have common variance along diagonals.

lme = fitlmematrix(X,y,Z,G,'FixedEffectPredictors',...
{'Intercept','InitWeight','PrgB','PrgC','PrgD','Week'},...
'RandomEffectPredictors',{{'Intercept','Week'}},...
'RandomEffectGroups',{'Subject'},'CovariancePattern','Isotropic')

lme = 
Linear mixed-effects model fit by ML

Model information:
    Number of observations             120
    Fixed effects coefficients           6
    Random effects coefficients         40
    Covariance parameters                2

Formula:
    y ~ Intercept + InitWeight + PrgB + PrgC + PrgD + Week + (Intercept + Week | Subject)

Model fit statistics:
    AIC        BIC       LogLikelihood    Deviance
    -24.783    -2.483    20.391           -40.783 

Fixed effects coefficients (95% CIs):
    Name                  Estimate     SE           tStat       DF     pValue        Lower        Upper    
    {'Intercept' }           0.4208      0.28169      1.4938    114       0.13799     -0.13723      0.97883
    {'InitWeight'}        0.0045552    0.0015338      2.9699    114     0.0036324    0.0015168    0.0075935
    {'PrgB'      }          0.36993      0.12119      3.0525    114     0.0028242      0.12986         0.61
    {'PrgC'      }        -0.034009       0.1209    -0.28129    114       0.77899     -0.27351       0.2055
    {'PrgD'      }            0.121      0.12111     0.99911    114       0.31986     -0.11891      0.36091
    {'Week'      }          0.19881     0.037134      5.3538    114    4.5191e-07      0.12525      0.27237

Random effects covariance parameters (95% CIs):
Group: Subject (20 Levels)
    Name1                Name2                Type           Estimate    Lower      Upper  
    {'Intercept'}        {'Intercept'}        {'std'}        0.16561     0.12896    0.21269

Group: Error
    Name               Estimate    Lower       Upper  
    {'Res Std'}        0.10272     0.088014    0.11987

Input Arguments

X — Fixed-effects design matrix

n-by-p matrix

Fixed-effects design matrix, specified as an n-by-p matrix, where n is the number of observations, and p is the number of fixed-effects predictor variables. Each row of X corresponds to one observation, and each column of X corresponds to one variable.

Data Types: single | double

y — Response values

n-by-1 vector

Response values, specified as an n-by-1 vector, where n is the number of observations.

Data Types: single | double

Z — Random-effects design

n-by-q matrix | cell array of R n-by-q(r) matrices, r = 1, 2, ..., R

Random-effects design, specified as either of the following.

• If there is one random-effects term in the model, then Z must be an n-by-q matrix, where n is the number of observations and q is the number of variables in the random-effects term.

• If there are R random-effects terms, then Z must be a cell array of length R. Each cell of Z contains an n-by-q(r) design matrix Z{r}, r = 1, 2, ..., R, corresponding to each random-effects term. Here, q(r) is the number of random effects term in the rth random effects design matrix, Z{r}.

Data Types: single | double | cell

G — Grouping variable or variables

n-by-1 vector | cell array of R n-by-1 vectors

Grouping variable or variables, specified as either of the following.

• If there is one random-effects term, then G must be an n-by-1 vector corresponding to a single grouping variable with M levels or groups.

  G can be a categorical vector, logical vector, numeric vector, character array, string array, or cell array of character vectors.

• If there are multiple random-effects terms, then G must be a cell array of length R. Each cell of G contains a grouping variable G{r}, r = 1, 2, ..., R, with M(r) levels.

  G{r} can be a categorical vector, logical vector, numeric vector, character array, string array, or cell array of character vectors.

Data Types: categorical | logical | single | double | char | string | cell

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'CovariancePattern','Diagonal','DummyVarCoding','full','Optimizer','fminunc' specifies a random-effects covariance pattern with zero off-diagonal elements, creates a dummy variable for each level of a categorical variable, and uses the fminunc optimization algorithm.

FixedEffectPredictors — Names of columns in fixed-effects design matrix

{'x1','x2',...,'xP'} (default) | string array or cell array of length p

Names of columns in the fixed-effects design matrix X, specified as the comma-separated pair consisting of 'FixedEffectPredictors' and a string array or cell array of length p.

For example, if you have a constant term and two predictors, say TimeSpent and Gender, where Female is the reference level for Gender, as the fixed effects, then you can specify the names of your fixed effects in the following way. Gender_Male represents the dummy variable you must create for category Male. You can choose different names for these variables.

Example: 'FixedEffectPredictors',{'Intercept','TimeSpent','Gender_Male'},

Data Types: string | cell

RandomEffectPredictors — Names of columns in random-effects design matrix or cell array

string array or cell array of length q | cell array of length R with elements of length q(r), r = 1, 2, ..., R

Names of columns in the random-effects design matrix or cell array Z, specified as the comma-separated pair consisting of 'RandomEffectPredictors' and either of the following:

• A string array or cell array of length q when Z is an n-by-q design matrix. In this case, the default is {'z1','z2',...,'zQ'}.

• A cell array of length R, when Z is a cell array of length R with each element Z{r} of length q(r), r = 1, 2, ..., R. In this case, the default is {'z11','z12',...,'z1Q(1)'},...,{'zr1','zr2',...,'zrQ(r)'}.

For example, suppose you have correlated random effects for intercept and a variable named Acceleration. Then, you can specify the random-effects predictor names as follows.

Example: 'RandomEffectPredictors',{'Intercept','Acceleration'}

If you have two random effects terms, one for the intercept and the variable Acceleration grouped by variable g1, and the second for the intercept, grouped by the variable g2, then you specify the random-effects predictor names as follows.

Example: 'RandomEffectPredictors',{{'Intercept','Acceleration'},{'Intercept'}}

Data Types: string | cell

ResponseVarName — Name of response variable

'y' (default) | character vector | string scalar

Name of response variable, specified as the comma-separated pair consisting of 'ResponseVarName' and a character vector or string scalar.

For example, if your response variable name is score, then you can specify it as follows.

Example: 'ResponseVarName','score'

Data Types: char | string

RandomEffectGroups — Names of random effects grouping variables

'g' or {'g1','g2',...,'gR'} (default) | character vector | string scalar | string array | cell array of character vectors

Names of random effects grouping variables, specified as the comma-separated pair 'RandomEffectGroups' and either of the following:

• Character vector or string scalar — If there is only one random-effects term, that is, if G is a vector, then the value of 'RandomEffectGroups' is the name for the grouping variable G. The default is 'g'.

• String array or cell array of character vectors — If there are multiple random-effects terms, that is, if G is a cell array of length R, then the value of 'RandomEffectGroups' is a string array or cell array of length R, where each element is the name for the grouping variable G{r}. The default is {'g1','g2',...,'gR'}.

For example, if you have two random-effects terms, z1 and z2, grouped by the grouping variables sex and subject, then you can specify the names of your grouping variables as follows.

Example: 'RandomEffectGroups',{'sex','subject'}

Data Types: char | string | cell

CovariancePattern — Pattern of covariance matrix

'FullCholesky' (default) | character vector | string scalar | square symmetric logical matrix | string array | cell array of character vectors or logical matrices

Pattern of the covariance matrix of the random effects, specified as the comma-separated pair consisting of 'CovariancePattern' and a character vector, a string scalar, a square symmetric logical matrix, a string array, or a cell array of character vectors or logical matrices.

If there are R random-effects terms, then the value of 'CovariancePattern' must be a string array or cell array of length R, where each element r of the array specifies the pattern of the covariance matrix of the random-effects vector associated with the rth random-effects term. The options for each element follow.

'FullCholesky'	Default. Full covariance matrix using the Cholesky parameterization. fitlme estimates all elements of the covariance matrix.
'Full'	Full covariance matrix, using the log-Cholesky parameterization. fitlme estimates all elements of the covariance matrix.
'Diagonal'	Diagonal covariance matrix. That is, off-diagonal elements of the covariance matrix are constrained to be 0. $$\left(\begin{array}{ccc}{\sigma }_{b1}^2& 0& 0\\ 0& {\sigma }_{b2}^2& 0\\ 0& 0& {\sigma }_{b3}^2\end{array}\right)$$
'Isotropic'	Diagonal covariance matrix with equal variances. That is, off-diagonal elements of the covariance matrix are constrained to be 0, and the diagonal elements are constrained to be equal. For example, if there are three random-effects terms with an isotropic covariance structure, this covariance matrix looks like $$\left(\begin{array}{ccc}{\sigma }_b^2& 0& 0\\ 0& {\sigma }_b^2& 0\\ 0& 0& {\sigma }_b^2\end{array}\right)$$ where σ2b is the common variance of the random-effects terms.
'CompSymm'	Compound symmetry structure. That is, common variance along diagonals and equal correlation between all random effects. For example, if there are three random-effects terms with a covariance matrix having a compound symmetry structure, this covariance matrix looks like $$\left(\begin{array}{ccc}{\sigma }_{b1}^2& {\sigma }_{b1,b2}& {\sigma }_{b1,b2}\\ {\sigma }_{b1,b2}& {\sigma }_{b1}^2& {\sigma }_{b1,b2}\\ {\sigma }_{b1,b2}& {\sigma }_{b1,b2}& {\sigma }_{b1}^2\end{array}\right)$$ where σ2b1 is the common variance of the random-effects terms and σb1,b2 is the common covariance between any two random-effects term.
PAT	Square symmetric logical matrix. If 'CovariancePattern' is defined by the matrix PAT, and if PAT(a,b) = false, then the (a,b) element of the corresponding covariance matrix is constrained to be 0.

Example: 'CovariancePattern','Diagonal'

Example: 'CovariancePattern',{'Full','Diagonal'}

Data Types: char | string | logical | cell

FitMethod — Method for estimating parameters

'ML' (default) | 'REML'

Method for estimating parameters of the linear mixed-effects model, specified as the comma-separated pair consisting of 'FitMethod' and either of the following.

'ML'	Default. Maximum likelihood estimation
'REML'	Restricted maximum likelihood estimation

Example: 'FitMethod','REML'

Weights — Observation weights

vector of scalar values

Observation weights, specified as the comma-separated pair consisting of 'Weights' and a vector of length n, where n is the number of observations.

Data Types: single | double

Exclude — Indices for rows to exclude

use all rows without NaNs (default) | vector of integer or logical values

Indices for rows to exclude from the linear mixed-effects model in the data, specified as the comma-separated pair consisting of 'Exclude' and a vector of integer or logical values.

For example, you can exclude the 13th and 67th rows from the fit as follows.

Example: 'Exclude',[13,67]

Data Types: single | double | logical

DummyVarCoding — Coding to use for dummy variables

'reference' (default) | 'effects' | 'full'

Coding to use for dummy variables created from the categorical variables, specified as the comma-separated pair consisting of 'DummyVarCoding' and one of the variables in this table.

Value	Description
'reference' (default)	fitlmematrix creates dummy variables with a reference group. This scheme treats the first category as a reference group and creates one less dummy variables than the number of categories. You can check the category order of a categorical variable by using the categories function, and change the order by using the reordercats function.
'effects'	fitlmematrix creates dummy variables using effects coding. This scheme uses –1 to represent the last category. This scheme creates one less dummy variables than the number of categories.
'full'	fitlmematrix creates full dummy variables. This scheme creates one dummy variable for each category.

For more details about creating dummy variables, see Automatic Creation of Dummy Variables.

Example: 'DummyVarCoding','effects'

Optimizer — Optimization algorithm

'quasinewton' (default) | 'fminunc'

Optimization algorithm, specified as the comma-separated pair consisting of 'Optimizer' and either of the following.

'quasinewton'	Default. Uses a trust region based quasi-Newton optimizer. Change the options of the algorithm using statset('LinearMixedModel'). If you don’t specify the options, then LinearMixedModel uses the default options of statset('LinearMixedModel').
'fminunc'	You must have Optimization Toolbox™ to specify this option. Change the options of the algorithm using optimoptions('fminunc'). If you don’t specify the options, then LinearMixedModel uses the default options of optimoptions('fminunc') with 'Algorithm' set to 'quasi-newton'.

Example: 'Optimizer','fminunc'

OptimizerOptions — Options for optimization algorithm

structure returned by statset | object returned by optimoptions

Options for the optimization algorithm, specified as the comma-separated pair consisting of 'OptimizerOptions' and a structure returned by statset('LinearMixedModel') or an object returned by optimoptions('fminunc').

• If 'Optimizer' is 'fminunc', then use optimoptions('fminunc') to change the options of the optimization algorithm. See optimoptions for the options 'fminunc' uses. If 'Optimizer' is 'fminunc' and you do not supply 'OptimizerOptions', then the default for LinearMixedModel is the default options created by optimoptions('fminunc') with 'Algorithm' set to 'quasi-newton'.

• If 'Optimizer' is 'quasinewton', then use statset('LinearMixedModel') to change the optimization parameters. If you don’t change the optimization parameters, then LinearMixedModel uses the default options created by statset('LinearMixedModel'):

The 'quasinewton' optimizer uses the following fields in the structure created by statset('LinearMixedModel').

TolFun — Relative tolerance on gradient of objective function

1e-6 (default) | positive scalar value

Relative tolerance on the gradient of the objective function, specified as a positive scalar value.

TolX — Absolute tolerance on step size

1e-12 (default) | positive scalar value

Absolute tolerance on the step size, specified as a positive scalar value.

MaxIter — Maximum number of iterations allowed

10000 (default) | positive scalar value

Maximum number of iterations allowed, specified as a positive scalar value.

Display — Level of display

'off' (default) | 'iter' | 'final'

Level of display, specified as one of 'off', 'iter', or 'final'.

StartMethod — Method to start iterative optimization

'default' (default) | 'random'

Method to start iterative optimization, specified as the comma-separated pair consisting of 'StartMethod' and either of the following.

Value	Description
'default'	An internally defined default value
'random'	A random initial value

Example: 'StartMethod','random'

Verbose — Indicator to display optimization process on screen

false (default) | true

Indicator to display the optimization process on screen, specified as the comma-separated pair consisting of 'Verbose' and either false or true. Default is false.

The setting for 'Verbose' overrides the field 'Display' in 'OptimizerOptions'.

Example: 'Verbose',true

CheckHessian — Indicator to check positive definiteness of Hessian

false (default) | true

Indicator to check the positive definiteness of the Hessian of the objective function with respect to unconstrained parameters at convergence, specified as the comma-separated pair consisting of 'CheckHessian' and either false or true. Default is false.

Specify 'CheckHessian' as true to verify optimality of the solution or to determine if the model is overparameterized in the number of covariance parameters.

Example: 'CheckHessian',true

Output Arguments

lme — Linear mixed-effects model

LinearMixedModel object

Linear mixed-effects model, returned as a LinearMixedModel object.

More About

Cholesky Parameterization

One of the assumptions of linear mixed-effects models is that the random effects have the following prior distribution.

$$b~N\left(0,{\sigma }^{2}D\left(\theta \right)\right),$$

where D is a q-by-q symmetric and positive semidefinite matrix, parameterized by a variance component vector θ, q is the number of variables in the random-effects term, and σ² is the observation error variance. Since the covariance matrix of the random effects, D, is symmetric, it has q(q+1)/2 free parameters. Suppose L is the lower triangular Cholesky factor of D(θ) such that

$$D\left(\theta \right)=L\left(\theta \right)L{\left(\theta \right)}^T,$$

then the q*(q+1)/2-by-1 unconstrained parameter vector θ is formed from elements in the lower triangular part of L.

For example, if

$$L=\left[\begin{array}{ccc}{L}_{11}& 0& 0\\ L_{21}& L_{22}& 0\\ L_{31}& L_{32}& L_{33}\end{array}\right],$$

then

$$\theta =\left[\begin{array}{c}{L}_{11}\\ L_{21}\\ L_{31}\\ L_{22}\\ L_{32}\\ L_{33}\end{array}\right].$$

Log-Cholesky Parameterization

When the diagonal elements of L in Cholesky parameterization are constrained to be positive, then the solution for L is unique. Log-Cholesky parameterization is the same as Cholesky parameterization except that the logarithm of the diagonal elements of L are used to guarantee unique parameterization.

For example, for the 3-by-3 example in Cholesky parameterization, enforcing L_ii ≥ 0,

$$\theta =\left[\begin{array}{c}\log \left(L_{11}\right)\\ L_{21}\\ L_{31}\\ \log \left(L_{22}\right)\\ L_{32}\\ \log \left(L_{33}\right)\end{array}\right].$$

Alternative Functionality

You can also fit a linear mixed-effects model using fitlme(tbl,formula), where tbl is a table containing the response y, the predictor variables X, and the grouping variables, and formula is of the form 'y ~ fixed + (random1|g1) + ... + (randomR|gR)'.

Version History

Introduced in R2013b