plotResiduals

Plot residuals of multinomial regression model

Since R2023a

Syntax

plotResiduals(mdl)

plotResiduals(mdl,plotType)

plotResiduals(ax,___)

plotResiduals(___,Name=Value)

h = plotResiduals(___)

Description

plotResiduals(mdl) generates a probability density plot of the deviance residuals for the multinomial regression model object mdl.

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

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

plotResiduals(___,Name=Value) specifies additional options using one or more name-value arguments. For example, you can specify the type of residuals to plot and the colors of the plotted objects.

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 or Patch Properties.

Examples

Generate a Probability Density Plot for Residuals

Load the fisheriris sample data set.

load fisheriris

The column vector species contains three iris flower species: setosa, versicolor, and virginica. The matrix meas contains four types of measurements for the flowers: the length and width of sepals and petals in centimeters.

Fit a multinomial regression model to predict the iris flower species using the measurements. Display the table of residuals for the fitted model.

mdl = fitmnr(meas,species);
mdl.Residuals

ans=150×3 table
        Raw          Pearson      Deviance
    ___________    ___________    ________

    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
    0    0    0    0    0    0       0    
      ⋮

The output shows the raw, Pearson, and deviance residuals for the model.

Generate a probability density plot of the deviance residuals.

plotResiduals(mdl)

The histogram shows that most of the deviance residuals are small. However, several residuals are greater than one.

Inspect the observations with larger residuals. Sort the residuals from largest to smallest by using the sort function. Use the head function to display the four largest residuals and their corresponding indices.

[r, ind] = sort(mdl.Residuals.Deviance,"descend");
head(r,4)

    4.0443
    3.1707
    1.0378
    0.8035

head(ind,4)

    84
   134
    71
   139

The outputs show that observations corresponding to rows 84, 134, and 71 of meas and species have residuals larger than one. Given that most other residuals are close to zero, observations 84, 134, and 71 are most likely outliers.

Determine Whether Residuals Are Random

Load the carbig sample data set.

load carbig

The vectors Displacement, Cylinders, and Model_Year contain data for car engine displacement, number of engine cylinders, and year the car was manufactured, respectively.

Fit a multinomial regression model using Displacement and Cylinders as predictors variables and Model_Year as the response.

mdl = fitmnr([Displacement Cylinders],Model_Year);

To determine whether the residuals are random, generate a lagged plot of the deviance residuals.

plotResiduals(mdl,"lagged")

The lagged plot of the deviance residuals shows a cluster of residuals trending toward the top right of the plot. The cluster indicates a mildly positive correlation between the residual for a data point and the residual for the previous data point, suggesting that the residuals might not be random.

Change Probability Plot Line Color

Load the carbig sample data set.

load carbig

The vectors Displacement, Cylinders, and Model_Year contain of data for car engine displacement, number of engine cylinders, and year the car was manufactured, respectively.

Fit a nominal multinomial regression model using Displacement and Cylinders as predictors variables and Model_Year as the response.

mdl = fitmnr([Displacement Cylinders],Model_Year);

mdl is a multinomial regression model object that contains the results of fitting a nominal multinomial regression model to the data.

Display the name of the first response category.

mdl.ClassNames(1)

ans = 
70

The output shows that the first response category corresponds to cars manufactured in 1970.

To determine whether the raw residuals for cars manufactured in 1970 are randomly distributed, create a probability plot and return a graphics array of the plotted objects. By default, plotResiduals uses the raw residuals for the first response category to create the probability plot.

h = plotResiduals(mdl,"probability",ResidualType="raw")

h = 
  2x1 graphics array:

  Line            (main)
  FunctionLine

The output shows the data types for the elements in the graphics array h. The Line element corresponds to the raw residuals. The FunctionLine element corresponds to the line representing the theoretical normal distribution.

Specify the color red for the normal distribution line by modifying the Color property of the second element in h.

h(2).Color = "r"

h = 
  2x1 graphics array:

  Line            (main)
  FunctionLine

The plot shows that the residuals do not follow the red line, indicating that the raw residuals for cars manufactured in 1970 are not normally distributed.

Input Arguments

mdl — Multinomial regression model object

MultinomialRegression model object

Multinomial regression model object, specified as a MultinomialRegression model object created with the fitmnr function.

plotType — Plot type

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

Plot type, specified as one of the following values.

Value	Description
"histogram"	Probability density plot for residuals (default)
"caseorder"	Residuals versus case (row) order
"fitted"	Residuals versus fitted class scores
"lagged"	Residuals versus lagged residuals—that is, r(i) versus r(i – 1), where r(i) is the residual for the ith data point
"probability"	Normal probability plot
"observed"	Observed versus 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: "lagged"

Data Types: char | string

ax — Target axes

Axes object

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.

Example: plotResiduals(mdl,ResidualType="Pearson",ClassToPlot="virginica",FaceColor="m") generates a magenta histogram for the Pearson residuals of the virginica response category.

Residuals

ResidualType — Type of residual to plot

"deviance" (default) | "Pearson" | "raw"

Type of residual to plot, specified as one of the options in the following table.

Option	Description
"deviance"	Deviance residuals (default)
"raw"	Raw residuals, which are the observed values minus the fitted values
"Pearson"	Pearson residuals, which are the raw residuals divided by the root mean squared error (RMSE)

For more information about each residual type, see Residuals.

Example: ResidualType="raw"

Data Types: char | string

ClassToPlot — Residual response category to plot

response category name

Residual response category to plot, specified as the name of a response category used to fit mdl. You can view the list of response category names by using the property mdl.ClassNames. The default value of ClassToPlot is mdl.ClassNames(1). This argument is valid only when ResidualType is "Pearson" or "raw".

Example: ClassToPlot="virginica"

Data Types: single | double | logical | char | cell | categorical

Histogram Graphics

FaceColor — Face color

[0 0 0] (default) | "interp" | "flat" | RGB triplet | hexadecimal color code | "r" | "g" | "b" | ...

Face color, specified as "interp", "flat" an RGB triplet, a hexadecimal color code, a color name, or a short name.

To designate a single color for all faces, specify FaceColor 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"

Example: FaceColor="g"

Data Types: single | double | char | string

FaceAlpha — Face transparency

1 (default) | scalar in the range [0,1] | 'flat' | 'interp'

Face transparency, specified as one of these values:

• Scalar in the range [0,1] — Use uniform transparency across all of the faces. A value of 1 is fully opaque and 0 is completely transparent. This option does not use the transparency values in the FaceVertexAlphaData property.

• 'flat' — Use a different transparency for each face based on the values in the FaceVertexAlphaData property. First you must specify the FaceVertexAlphaData name-value argument as a vector containing one transparency value per face or vertex. The transparency value at the first vertex determines the transparency for the entire face.

• 'interp' — Use interpolated transparency for each face based on the values in the FaceVertexAlphaData property. First you must specify the FaceVertexAlphaData name-value argument as a vector containing one transparency value per vertex. The transparency varies across each face by interpolating the values at the vertices.

Example: FaceAlpha=0.5

Data Types: single | double | char | string

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 appears as one pixel wide.

Example: LineWidth=1.5

Data Types: single | double

Note

The graphics properties for histograms listed here are only a subset. For a complete list, see Patch Properties.

Line Graphics

Color — Line color

[0 0 0] (default) | 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. The default value of [0 0 0] corresponds to black.

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

Example: Color="blue"

Example: Color=[0 0 1]

Example: Color="#0000FF"

Data Types: single | double | char | string

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

Example: LineStyle="--"

Data Types: char | string

Marker — Marker symbol

"none" (default) | "o" | "+" | "*" | "." | ...

Marker symbol, specified as one of the values listed in this table. By default, the object does not display markers. Specifying a marker symbol adds markers at each data point or vertex.

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="x"

Data Types: char | string

Note

The graphics properties for lines listed here are only a subset. For a complete list, see Line Properties.

Output Arguments

h — Handle to plotted objects

Patch object | graphics array

Handle to the plotted objects, returned as a Patch object or a graphics array.

When plotType is "Histogram", h is a Patch object. Otherwise, h is a graphics array. The contents of the graphics array depend on the value of plotType.

plotType Value	Contents of Graphics Array
"caseorder"	[Line; Line]
"lagged"	[Line; Line; Line]
"probability"	[Line; FunctionLine]
"symmetry"	[Line; Line]

Version History

Introduced in R2023a

R2024b: Specify two new plot types

You can now specify two new plot types using the plottype input argument:

• "observed" — Plot observed versus fitted values.

• "fitted" — Plot residuals versus fitted class scores.