Main Content

plotResiduals

Plot residuals of linear mixed-effects model

Description

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

example

plotResiduals(lme,plottype,Name,Value) specifies additional options using one or more name-value arguments. For example, you can specify the residual type and the graphical properties of residual data points.

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

example

plotResiduals(ax,___) plots into the axes specified by ax instead of the current axes (gca) using any of the input argument combinations in the previous syntaxes. (since R2024a)

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

Examples

collapse all

Load the sample data.

load('weight.mat')

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 = categorical(tbl.Subject);
tbl.Program = categorical(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.

plotResiduals(lme)

Figure contains an axes object. The axes object with title Histogram of residuals, xlabel Residuals, ylabel Probability density contains an object of type patch.

Plot the residuals versus the fitted values.

plotResiduals(lme,'fitted')

Figure contains an axes object. The axes object with title Plot of residuals vs. fitted values, xlabel Fitted values, ylabel Residuals contains 2 objects of type line. One or more of the lines displays its values using only markers

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

Create the normal probability plot of residuals.

plotResiduals(lme,'probability')

Figure contains an axes object. The axes object with title Normal probability plot of residuals, xlabel Residuals, ylabel Probability contains 2 objects of type functionline, line. One or more of the lines displays its values using only markers

Data appears to be normal.

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

find(residuals(lme)>0.25)
ans = 
101

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];
boxplot(X,'labels',{'Raw','Pearson','Standardized'})

Figure contains an axes object. The axes object contains 21 objects of type line. One or more of the lines displays its values using only markers

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.

find(pr<-2)
ans = 
10

Plot the raw residuals versus lagged residuals.

plotResiduals(lme,'lagged')

Figure contains an axes object. The axes object with title Plot of residuals vs. lagged residuals, xlabel Residual(t-1), ylabel Residual(t) contains 3 objects of type line. One or more of the lines displays its values using only markers

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

Input Arguments

collapse all

Linear mixed-effects model, specified as a LinearMixedModel object constructed using fitlme or fitlmematrix.

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

"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
"observed"Observed vs. fitted values. This plot includes a dotted reference line of y = x. Each residual is represented by the vertical distance from the corresponding observed value to the reference line.
"symmetry" Symmetry plot

Example: plotResiduals(lme,"lagged")

Since R2024a

Target axes, specified as an Axes object. If you do not specify the axes, then plotResiduals uses the current axes (gca).

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: plotResiduals(lme,plottype,'ResidualType','Standardized')

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

Residual TypeConditionalMarginal
'Raw'

riC=[yXβ^Zb^]i

riM=[yXβ^]i

'Pearson'

priC=riC[Var^y,b(yXβZb)]ii

priM=riM[Var^y(yXβ)]ii

'Standardized'

stiC=riC[Var^y(rC)]ii

stiM=riM[Var^y(rM)]ii

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

collapse all

Handle to the residual plot, returned as a handle.

Version History

Introduced in R2013b

expand all