Documentation Center

  • Trial Software
  • Product Updates


Class: LinearMixedModel

Plot residuals of linear mixed-effects model


  • plotResiduals(lme,plottype) example
  • plotResiduals(lme,plottype,Name,Value) example
  • h = plotResiduals(___)



plotResiduals(lme,plottype) plots the raw conditional residuals of the linear mixed-effects model lme in a plot of the type specified by plottype.


plotResiduals(lme,plottype,Name,Value) also plots the residuals of the linear mixed-effects model lme with additional options specified by one or more name-value pair arguments. For example, you can specify the residual type to plot.

plotResiduals also accepts some other name-value pair arguments that specify the properties of the primary line in the plot. For those name-value pairs, see plot.

h = plotResiduals(___) returns a handle, h, to the lines or patches in the plot of residuals.

Input Arguments

expand all

lme — Linear mixed-effects modelLinearMixedModel object

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

For properties and methods of this object, see LinearMixedModel.

plottype — Type of residual plot'histogram' (default) | 'caseorder' | 'fitted' | 'lagged' | 'probability' | 'symmetry'

Type of residual plot, specified as one of the following strings.

'histogram'Default. Histogram of residuals
'caseorder'Residuals versus case (row) order
'fitted'Residuals versus fitted values
'lagged'Residuals versus lagged residual (r(t) versus r(t – 1))
'probability'Normal probability plot
'symmetry' Symmetry plot

Example: plotResiduals(lme,'lagged')

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'Conditional' — Indicator for conditional residualsTrue (default) | False

Indicator for conditional residuals, specified as the comma-separated pair consisting of 'Conditional' and one of the following.

TrueContribution from both fixed effects and random effects (conditional)
FalseContribution from only fixed effects (marginal)

Example: 'Conditional,'False'

'ResidualType' — Residual type'Raw' (default) | 'Pearson' | 'Standardized'

Residual type, specified by the comma-separated pair consisting of ResidualType and one of the following.

Residual TypeConditionalMarginal



For more information on the conditional and marginal residuals and residual variances, see Definitions at the end of this page.

Example: 'ResidualType','Standardized'

Output Arguments

expand all

h — Handle to residual plothandle

Handle to the residual plot, returned as a handle.


expand all

Examine Residuals

Navigate to a folder containing sample data.


Load the sample data.

load weight

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

Store the data in a table. Define Subject and Program as categorical variables.

tbl = table(InitialWeight,Program,Subject,Week,y);
tbl.Subject = nominal(tbl.Subject);
tbl.Program = nominal(tbl.Program);

Fit a linear mixed-effects model where the initial weight, type of program, week, and the interaction between the week and type of program are the fixed effects. The intercept and week vary by subject.

lme = fitlme(tbl,'y ~ InitialWeight + Program*Week + (Week|Subject)');

Plot the histogram of the raw residuals.


Plot the residuals versus the fitted values.


There is no obvious pattern, so there are no immediate signs of heteroscedasticity.

Create the normal probability plot of residuals.


Data appears to be normal.

Find the observation number for the data that appears to be an outlier to the right of the plot.

ans =


Create a box plot of the raw, Pearson, and standardized residuals.

r = residuals(lme);
pr = residuals(lme,'ResidualType','Pearson');
st = residuals(lme,'ResidualType','Standardized');
X = [r pr st];

All three box plots point out the outlier on the right tail of the distribution. The box plots of raw and Pearson residuals also point out a second possible outlier on the left tail. Find the corresponding observation number.

ans =


Plot the raw residuals versus lagged residuals.


There is no obvious pattern in the graph. The residuals do not appear to be correlated.


Conditional and Marginal Residuals

Conditional residuals include contributions from both fixed and random effects, whereas marginal residuals include contribution from only fixed effects.

Suppose the linear mixed-effects model lmehas an n-by-p fixed-effects design matrix X and an n-by-q random-effects design matrix Z. Also, suppose the p-by-1 estimated fixed-effects vector is , and the q-by-1 estimated best linear unbiased predictor (BLUP) vector of random effects is . The fitted conditional response is

and the fitted marginal response is

residuals can return three types of residuals: raw, Pearson, and standardized. For any type, you can compute the conditional or the marginal residuals. For example, the conditional raw residual is

and the marginal raw residual is

For more information on other types of residuals, see the ResidualType name-value pair argument.

See Also

| |

Was this topic helpful?