plotResiduals

Plot residuals of linear mixed-effects model

Syntax

plotResiduals(lme,plottype)

plotResiduals(lme,plottype,Name=Value)

plotResiduals(ax,___)

h = plotResiduals(___)

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.

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

Examine Residuals

Open Live Script

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

`lme` — Linear mixed-effects model
`LinearMixedModel` object

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

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

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")

`ax` — Target axes
`Axes` object

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

collapse all

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.

Example: plotResiduals(lme,"probability",ResidualType="Standardized",Marker="o") specifies the residual type as standardized and the marker type as o for a probability plot.

The plotResiduals name-value arguments listed here are only a subset. For a complete list, see Patch Properties when the plot type is "histogram" and Line Properties for all other plot types.

`ResidualType` — Residual type
`"Raw"` (default) | `"Pearson"` | `"Standardized"`

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

Residual Type Conditional Marginal

Residual Type	Conditional	Marginal
`"Raw"`	$r_{i}^{C} = {[y - X \hat{β} - Z \hat{b}]}_{i}$	$r_{i}^{M} = {[y - X \hat{β}]}_{i}$
`"Pearson"`	$p r_{i}^{C} = \frac{r_{i}^{C}}{{\sqrt{[{\hat{V a r}}_{y, b} (y - X β - Z b)]}}_{i i}}$	$p r_{i}^{M} = \frac{r_{i}^{M}}{\sqrt{{[{\hat{V a r}}_{y} (y - X β)]}_{i i}}}$
`"Standardized"`	$s t_{i}^{C} = \frac{r_{i}^{C}}{\sqrt{{[{\hat{V a r}}_{y} (r^{C})]}_{i i}}}$	$s t_{i}^{M} = \frac{r_{i}^{M}}{\sqrt{{[{\hat{V a r}}_{y} (r^{M})]}_{i i}}}$

"Raw"

$r_{i}^{C} = {[y - X \hat{β} - Z \hat{b}]}_{i}$

$r_{i}^{M} = {[y - X \hat{β}]}_{i}$

"Pearson"

$p r_{i}^{C} = \frac{r_{i}^{C}}{{\sqrt{[{\hat{V a r}}_{y, b} (y - X β - Z b)]}}_{i i}}$

$p r_{i}^{M} = \frac{r_{i}^{M}}{\sqrt{{[{\hat{V a r}}_{y} (y - X β)]}_{i i}}}$

"Standardized"

$s t_{i}^{C} = \frac{r_{i}^{C}}{\sqrt{{[{\hat{V a r}}_{y} (r^{C})]}_{i i}}}$

$s t_{i}^{M} = \frac{r_{i}^{M}}{\sqrt{{[{\hat{V a r}}_{y} (r^{M})]}_{i i}}}$

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

Example: ResidualType="Standardized"

`FaceColor` — Histogram face color
`"interp"` | `"flat"` | RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

Histogram face color, specified as "interp", "flat" an RGB triplet, a hexadecimal color code, a color name, or a short name. FaceColor is supported only when plottype is "histogram".

To create a different color for each face, specify the CData or FaceVertexCData property as an array containing one color per face or one color per vertex. The colors can be interpolated from the colors of the surrounding vertices of each face, or they can be uniform. For interpolated colors, specify this property as "interp". For uniform colors, specify this property as "flat". If you specify "flat" and a different color for each vertex, the color of the first vertex you specify determines the face color.

To designate a single color for all of the faces, specify this property as an RGB triplet, a hexadecimal color code, a color name, or a short name.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].
A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
`"red"`	`"r"`	`[1 0 0]`	`"#FF0000"`
`"green"`	`"g"`	`[0 1 0]`	`"#00FF00"`
`"blue"`	`"b"`	`[0 0 1]`	`"#0000FF"`
`"cyan"`	`"c"`	`[0 1 1]`	`"#00FFFF"`
`"magenta"`	`"m"`	`[1 0 1]`	`"#FF00FF"`
`"yellow"`	`"y"`	`[1 1 0]`	`"#FFFF00"`
`"black"`	`"k"`	`[0 0 0]`	`"#000000"`
`"white"`	`"w"`	`[1 1 1]`	`"#FFFFFF"`
`"none"`	Not applicable	Not applicable	Not applicable	No color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^® uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
`[0 0.4470 0.7410]`	`"#0072BD"`
`[0.8500 0.3250 0.0980]`	`"#D95319"`
`[0.9290 0.6940 0.1250]`	`"#EDB120"`
`[0.4940 0.1840 0.5560]`	`"#7E2F8E"`
`[0.4660 0.6740 0.1880]`	`"#77AC30"`
`[0.3010 0.7450 0.9330]`	`"#4DBEEE"`
`[0.6350 0.0780 0.1840]`	`"#A2142F"`

`Color` — Line color
RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

Line color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name. Color is not supported when plottype is "histogram".

For a custom color, specify an RGB triplet or a hexadecimal color code.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].
A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
`"red"`	`"r"`	`[1 0 0]`	`"#FF0000"`
`"green"`	`"g"`	`[0 1 0]`	`"#00FF00"`
`"blue"`	`"b"`	`[0 0 1]`	`"#0000FF"`
`"cyan"`	`"c"`	`[0 1 1]`	`"#00FFFF"`
`"magenta"`	`"m"`	`[1 0 1]`	`"#FF00FF"`
`"yellow"`	`"y"`	`[1 1 0]`	`"#FFFF00"`
`"black"`	`"k"`	`[0 0 0]`	`"#000000"`
`"white"`	`"w"`	`[1 1 1]`	`"#FFFFFF"`
`"none"`	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors

Palette	Palette Colors
`"gem"` — Light theme default Before R2025a: Most plots use these colors by default.
`"glow"` — Dark theme default

"gem" — Light theme default

Before R2025a: Most plots use these colors by default.

"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Example: "blue"

Example: [0 0 1]

Example: "#0000FF"

`LineStyle` — Line style
`"-"` (default) | `"--"` | `":"` | `"-."` | `"none"`

Line style, specified as one of the options listed in this table.

Line Style	Description	Resulting Line
`"-"`	Solid line
`"--"`	Dashed line
`":"`	Dotted line
`"-."`	Dash-dotted line
`"none"`	No line	No line

`LineWidth` — Line width
`0.5` (default) | positive value

Line width, specified as a positive value in points, where 1 point = 1/72 of an inch. If the line has markers, then the line width also affects the marker edges.

The line width cannot be thinner than the width of a pixel. If you set the line width to a value that is less than the width of a pixel on your system, the line displays as one pixel wide.

`Marker` — Marker symbol
`"x"` (default) | `"+"` | `"*"` | `"."` | ...

Marker symbol, specified as one of the values listed in this table.

Marker	Description	Resulting Marker
`"x"`	Cross
`"o"`	Circle
`"+"`	Plus sign
`"*"`	Asterisk
`"."`	Point
`"_"`	Horizontal line
`"\|"`	Vertical line
`"square"`	Square
`"diamond"`	Diamond
`"^"`	Upward-pointing triangle
`"v"`	Downward-pointing triangle
`">"`	Right-pointing triangle
`"<"`	Left-pointing triangle
`"pentagram"`	Pentagram
`"hexagram"`	Hexagram

`MarkerIndices` — Indices of data points at which to display markers
`1:length(YData)` (default) | vector of positive integers | scalar positive integer

Indices of data points at which to display markers, specified as a vector of positive integers. If you do not specify the indices, then MATLAB displays a marker at every data point.

You cannot specify MarkerIndices when plottype is "histogram".

Example: plotResiduals(lme,"probability",MarkerIndices=[1 5 10]) displays a marker at the first, fifth, and tenth data points in a probability plot.

Example: plotResiduals(lme,"fitted",MarkerIndices=1:3:length(y)) displays a marker every three data points in a plot of the residuals versus fitted values.

Example: plotResiduals(lme,"lagged",MarkerIndices=5) displays a marker at the fifth data point in a plot of residuals versus lagged residuals.

`MarkerEdgeColor` — Marker outline color
`"auto"` (default) | RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

Marker outline color, specified as "auto", an RGB triplet, a hexadecimal color code, a color name, or a short name. The default value of "auto" uses the same color as the Color property.

For a custom color, specify an RGB triplet or a hexadecimal color code.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].
A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
`"red"`	`"r"`	`[1 0 0]`	`"#FF0000"`
`"green"`	`"g"`	`[0 1 0]`	`"#00FF00"`
`"blue"`	`"b"`	`[0 0 1]`	`"#0000FF"`
`"cyan"`	`"c"`	`[0 1 1]`	`"#00FFFF"`
`"magenta"`	`"m"`	`[1 0 1]`	`"#FF00FF"`
`"yellow"`	`"y"`	`[1 1 0]`	`"#FFFF00"`
`"black"`	`"k"`	`[0 0 0]`	`"#000000"`
`"white"`	`"w"`	`[1 1 1]`	`"#FFFFFF"`
`"none"`	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors

Palette	Palette Colors
`"gem"` — Light theme default Before R2025a: Most plots use these colors by default.
`"glow"` — Dark theme default

"gem" — Light theme default

Before R2025a: Most plots use these colors by default.

"glow" — Dark theme default

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

`MarkerFaceColor` — Marker fill color
`"none"` (default) | RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

Marker fill color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].
A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
`"red"`	`"r"`	`[1 0 0]`	`"#FF0000"`
`"green"`	`"g"`	`[0 1 0]`	`"#00FF00"`
`"blue"`	`"b"`	`[0 0 1]`	`"#0000FF"`
`"cyan"`	`"c"`	`[0 1 1]`	`"#00FFFF"`
`"magenta"`	`"m"`	`[1 0 1]`	`"#FF00FF"`
`"yellow"`	`"y"`	`[1 1 0]`	`"#FFFF00"`
`"black"`	`"k"`	`[0 0 0]`	`"#000000"`
`"white"`	`"w"`	`[1 1 1]`	`"#FFFFFF"`
`"none"`	Not applicable	Not applicable	Not applicable	No color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
`[0 0.4470 0.7410]`	`"#0072BD"`
`[0.8500 0.3250 0.0980]`	`"#D95319"`
`[0.9290 0.6940 0.1250]`	`"#EDB120"`
`[0.4940 0.1840 0.5560]`	`"#7E2F8E"`
`[0.4660 0.6740 0.1880]`	`"#77AC30"`
`[0.3010 0.7450 0.9330]`	`"#4DBEEE"`
`[0.6350 0.0780 0.1840]`	`"#A2142F"`

`MarkerSize` — Marker size
`6` (default) | positive value

Marker size, specified as a positive value in points, where 1 point = 1/72 of an inch.

Output Arguments

collapse all

`h` — Handle to residual plot
handle

Handle to the residual plot, returned as a handle.

Version History

Introduced in R2013b

expand all

R2024b: Plot observed versus fitted values

You can now plot observed versus fitted values by specifying the plottype input argument as "observed".

R2024a: Specify target axes

Specify the target axes for the plot by using the ax input argument.

plotResiduals

Syntax

Description

Examples

Examine Residuals

Input Arguments

lme — Linear mixed-effects model LinearMixedModel object

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

ax — Target axes Axes object

Name-Value Arguments

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

FaceColor — Histogram face color "interp" | "flat" | RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Color — Line color RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

LineStyle — Line style "-" (default) | "--" | ":" | "-." | "none"

LineWidth — Line width 0.5 (default) | positive value

Marker — Marker symbol "x" (default) | "+" | "*" | "." | ...

MarkerIndices — Indices of data points at which to display markers 1:length(YData) (default) | vector of positive integers | scalar positive integer

MarkerEdgeColor — Marker outline color "auto" (default) | RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

MarkerFaceColor — Marker fill color "none" (default) | RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

MarkerSize — Marker size 6 (default) | positive value

Output Arguments

h — Handle to residual plot handle

Version History

R2024b: Plot observed versus fitted values

R2024a: Specify target axes

See Also

`lme` — Linear mixed-effects model
`LinearMixedModel` object

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

`ax` — Target axes
`Axes` object

`ResidualType` — Residual type
`"Raw"` (default) | `"Pearson"` | `"Standardized"`

`FaceColor` — Histogram face color
`"interp"` | `"flat"` | RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

`Color` — Line color
RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

`LineStyle` — Line style
`"-"` (default) | `"--"` | `":"` | `"-."` | `"none"`

`LineWidth` — Line width
`0.5` (default) | positive value

`Marker` — Marker symbol
`"x"` (default) | `"+"` | `"*"` | `"."` | ...

`MarkerIndices` — Indices of data points at which to display markers
`1:length(YData)` (default) | vector of positive integers | scalar positive integer

`MarkerEdgeColor` — Marker outline color
`"auto"` (default) | RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

`MarkerFaceColor` — Marker fill color
`"none"` (default) | RGB triplet | hexadecimal color code | `"r"` | `"g"` | `"b"` | ...

`MarkerSize` — Marker size
`6` (default) | positive value

`h` — Handle to residual plot
handle