plotResiduals

Plot residuals of linear regression model

Syntax

plotResiduals(mdl)

plotResiduals(mdl,plottype)

plotResiduals(mdl,plottype,Name,Value)

plotResiduals(ax,___)

h = plotResiduals(___)

Description

plotResiduals(mdl) creates a histogram plot of the linear regression model (mdl) residuals.

plotResiduals(mdl,plottype) specifies the residual plot type plottype.

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

plotResiduals(ax,___) creates the plot in the axes specified by ax instead of the current axes, using any of the input argument combinations in the previous syntaxes.

h = plotResiduals(___) returns graphics objects for the lines or patch in the plot. Use h to modify the properties of a specific line or patch after you create the plot. For a list of properties, see Line Properties and Patch Properties.

Examples

Histogram of Residuals

Plot a histogram of the residuals of a fitted linear regression model.

Load the carsmall data set and fit a linear regression model of the mileage as a function of model year, weight, and weight squared.

load carsmall
tbl = table(MPG,Weight);
tbl.Year = categorical(Model_Year);
mdl = fitlm(tbl,'MPG ~ Year + Weight^2');

Create a histogram of the raw residuals using probability density function scaling.

plotResiduals(mdl)

The area of each bar is the relative number of observations. The sum of the bar areas is equal to 1.

Normal Probability Plot of Residuals

Create a normal probability plot of the residuals of a fitted linear regression model.

Load the carsmall data set and fit a linear regression model of the mileage as a function of model year, weight, and weight squared.

load carsmall
X = [Weight,Model_Year];
mdl = fitlm(X,MPG,...
    'y ~ x2 + x1^2','Categorical',2);

Create a normal probability plot of the residuals of the fitted model.

plotResiduals(mdl,'probability')

Input Arguments

mdl — Linear regression model

LinearModel object

Linear regression model, specified as a LinearModel object created using fitlm or stepwiselm.

plottype — Plot type

"histogram" (default) | "caseorder" | "fitted" | "lagged" | "probability" | "observed" | "symmetry"

Plot type, specified as one of the values in this table.

Value	Description
"caseorder"	Residuals vs. case order (row number)
"fitted"	Residuals vs. fitted values
"histogram"	Histogram of residuals using probability density function scaling. The area of each bar is the relative number of observations. The sum of the bar areas is equal to 1.
"lagged"	Residuals vs. lagged residuals (r(t) vs. r(t – 1))
"probability"	Normal probability plot of residuals. For details, see probplot.
"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 of residuals around their median (residuals in upper tail – median vs. median – residuals in lower tail). This plot includes a dotted reference line of y = x to examine the symmetry of residuals.

ax — Target axes

Axes object

Target axes, specified as an Axes object.

If you do not specify the axes and the current axes are Cartesian, then plotResiduals uses the current axes (gca). For more information on creating an Axes object, see axes and 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: 'Color','blue','Marker','o'

Note

The graphical properties listed here are only a subset. For a complete list, see Line Properties for lines and Patch Properties for histograms. The specified properties apply to the appearance of residual data points or the appearance of the histogram.

ResidualType — Type of residual

'raw' (default) | 'pearson' | 'standardized' | 'studentized'

Type of residual used in the plot, specified as the comma-separated pair consisting of 'ResidualType' and one of these values:

Value	Description
'raw'	Observed minus fitted values
'pearson'	Raw residuals divided by the root mean squared error (RMSE)
'standardized'	Raw residuals divided by their estimated standard deviation
'studentized'	Raw residuals divided by an independent (delete-1) estimate of their standard deviation

The Residuals property of mdl contains the residual values used by plotResiduals to create plots.

For details, see Residuals.

Example: 'ResidualType','Pearson'

Color — Line color

RGB triplet | hexadecimal color code | color name | short name

Line color, specified an RGB triplet, hexadecimal color code, color name, or short name for one of the color options listed in the following table.

The Color name-value argument also determines marker outline color and marker fill color if MarkerEdgeColor is "auto" (default) and MarkerFaceColor is "auto".

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
"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: Color="blue"

Data Types: single | double | string | char

LineWidth — Line width

positive value

Line width, specified as a positive value in points. If the line has markers, then the line width also affects the marker edges.

Example: LineWidth=0.75

Data Types: single | double

Marker — Marker symbol

"o" | "+" | "*" | "." | "x" | ...

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

Marker	Description	Resulting Marker
"o"	Circle
"+"	Plus sign
"*"	Asterisk
"."	Point
"x"	Cross
"_"	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
"none"	No markers	Not applicable

Example: Marker="+"

Data Types: string | char

MarkerEdgeColor — Marker outline color

"auto" (default) | "none" | RGB triplet | hexadecimal color code | color name | short name

Marker outline color, specified an RGB triplet, hexadecimal color code, color name, or short name for one of the color options listed in the Color name-value argument.

The default value "auto" uses the same color specified by using the Color name-value argument. You can also specify "none" for no color.

Example: MarkerEdgeColor="blue"

Data Types: single | double | string | char

MarkerFaceColor — Marker fill color

"none" (default) | "auto" | RGB triplet | hexadecimal color code | color name | short name

Marker fill color, specified as an RGB triplet, hexadecimal color code, color name, or short name for one of the color options listed in the Color name-value argument. The default value "none" specifies no color.

The "auto" value uses the same color specified by using the Color name-value argument.

Example: MarkerFaceColor="blue"

Data Types: single | double | string | char

MarkerSize — Marker size

6 (default) | positive value

Marker size, specified as a positive value in points.

Example: MarkerSize=2

Data Types: single | double

Output Arguments

h — Graphics objects

graphics array

Graphics objects corresponding to the lines or patch in the plot, returned as a graphics array. Use dot notation to query and set properties of the graphics objects. For details, see Line Properties and Patch Properties.

You can use name-value arguments to specify the appearance of residual data points or the appearance of the histogram, corresponding to the first graphics object h(1).

Tips

• The data cursor displays the values of the selected plot point in a data tip (small text box located next to the data point). The data tip includes the x-axis and y-axis values for the selected point, along with the observation name or number.

Alternative Functionality

• A LinearModel object provides multiple plotting functions.

  • When creating a model, use plotAdded to understand the effect of adding or removing a predictor variable.

  • When verifying a model, use plotDiagnostics to find questionable data and to understand the effect of each observation. Also, use plotResiduals to analyze the residuals of the model.

  • After fitting a model, use plotAdjustedResponse, plotPartialDependence, and plotEffects to understand the effect of a particular predictor. Use plotInteraction to understand the interaction effect between two predictors. Also, use plotSlice to plot slices through the prediction surface.

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2012a

R2024b: Plot observed versus fitted values

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