plotDiagnostics

Plot diagnostics of nonlinear regression model

Syntax

plotDiagnostics(mdl)

plotDiagnostics(mdl,plottype)

plotDiagnostics(___,Name,Value)

plotDiagnostics(ax,___)

h = plotDiagnostics(___)

Description

plotDiagnostics creates a plot of observation diagnostics such as leverage or Cook's distance statistics to identify outliers and influential observations.

plotDiagnostics(mdl) creates a leverage plot of the nonlinear regression model (mdl) observations. A dotted line in the plot represents the recommended threshold values.

plotDiagnostics(mdl,plottype) specifies the type of observation diagnostics plottype.

plotDiagnostics(___,Name,Value) specifies additional options using one or more name-value arguments in addition to any of the input argument combinations in the previous syntaxes. For example, you can specify the marker symbol and size for the data points.

plotDiagnostics(ax,___) plots into the axes specified by ax instead of the current axes (gca). (since R2024a)

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

Examples

Nonlinear Model Leverage Plot

Create a leverage plot of a fitted nonlinear model, and find the points with high leverage.

Load the reaction data and fit a model of the reaction rate as a function of reactants.

load reaction
mdl = fitnlm(reactants,rate,@hougen,[1 .05 .02 .1 2]);

Create a leverage plot of the fitted model.

plotDiagnostics(mdl)

Use data tips to examine the observation with high leverage. A data tip appears when you hover over a data point.

Alternatively, find the high-leverage observation at the command line.

find(mdl.Diagnostics.Leverage > 0.8)

ans =

     6

Input Arguments

mdl — Nonlinear regression model

NonLinearModel object

Nonlinear regression model, specified as a NonLinearModel object created using fitnlm.

plottype — Type of plot

'leverage' (default) | 'contour' | 'cookd'

Type of plot, specified as one of the values in this table.

Value	Plot Type	Dotted Reference Line in Plot	Purpose
'contour'	Residual vs. leverage with overlaid contours of Cook's distance	Contours of Cook's distance	Identify observations with large residual values, high leverage, and large Cook's distance values.
'cookd'	Cook's distance	Recommended threshold, computed by 3*mean(mdl.Diagnostics.CooksDistance)	Identify observations with large Cook's distance values.
'leverage'	Leverage (Diagonal of Hat matrix)	Recommended threshold, computed by 2*p/n	Identify high leverage observations.

For all plot types except 'contour', the x-axis is the row number (case order) of observations.

The Diagnostics property of mdl contains the diagnostic values used by plotDiagnostics to create plots.

For more information about observation diagnostics, see Cook’s Distance and Leverage.

ax — Target axes

Axes object

Since R2024a

Target axes, specified as an Axes object. If you do not specify the axes, then plotDiagnostics 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: 'Color','blue','Marker','o'

Note

The graphical properties listed here are only a subset. For a complete list, see Line Properties. The specified properties determine the appearance of diagnostic data points.

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 contour 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 Contour Properties.

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

More About

Hat Matrix

The hat matrix H is defined in terms of the data matrix X and the Jacobian matrix J:

$$J_{i,j}={\frac{\partial f}{\partial {\beta }_j}|}_{x_i,\beta }$$

Here f is the nonlinear model function, and β is the vector of model coefficients.

The Hat Matrix H is

H = J(J^TJ)^–1J^T.

The diagonal elements H_ii satisfy

$$\begin{array}{l}0\le h_{ii}\le 1\\ {\displaystyle \sum _{i=1}^n{h}_{ii}}=p,\end{array}$$

where n is the number of observations (rows of X), and p is the number of coefficients in the regression model.

Leverage

Leverage is a measure of the effect of a particular observation on the regression predictions due to the position of that observation in the space of the inputs.

The leverage of observation i is the value of the ith diagonal term h_ii of the hat matrix H. Because the sum of the leverage values is p (the number of coefficients in the regression model), an observation i can be considered an outlier if its leverage substantially exceeds p/n, where n is the number of observations.

Cook’s Distance

The Cook’s distance D_i of observation i is

$$D_i=\frac{{\displaystyle \sum _{j=1}^n{\left({\widehat{y}}_j-{\widehat{y}}_{j(i)}\right)}^2}}{pMSE},$$

where

• $${\widehat{y}}_j$$ is the jth fitted response value.

• $${\widehat{y}}_{j(i)}$$ is the jth fitted response value, where the fit does not include observation i.

• MSE is the mean squared error.

• p is the number of coefficients in the regression model.

Cook’s distance is algebraically equivalent to the following expression:

$$D_i=\frac{r_i^2}{pMSE}\left(\frac{h_{ii}}{{\left(1-h_{ii}\right)}^2}\right),$$

where e_i is the ith residual.

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.

References

[1] Neter, J., M. H. Kutner, C. J. Nachtsheim, and W. Wasserman. Applied Linear Statistical Models, Fourth Edition. Irwin, Chicago, 1996.

Version History

Introduced in R2012a

R2024a: Specify target axes

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