plotResiduals

Plot residuals of censored linear regression model

Since R2025a

collapse all in page

    Syntax

    plotResiduals(mdl)
    plotResiduals(mdl,plottype)
    plotResiduals(mdl,plottype,Name=Value)
    plotResiduals(ax,___)
    h = plotResiduals(___)

    Description

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

    example

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

    plotResiduals(mdl,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,___) 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

    collapse all

    Open Live Script

    Load the readmissiontimes data set, and fit a censored linear regression model of the readmission time as a function of patient age, weight, and smoking status.

    load readmissiontimes
tbl = table(Age,Weight,Smoker,Censored,ReadmissionTime);
mdl = fitlmcens(tbl,Censoring="Censored",CategoricalVars="Smoker");

    Create a histogram of the raw residuals.

    plotResiduals(mdl)

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

    The area of each bar is the relative number of observations. The sum of the bar areas is equal to 1. The histogram indicates that the residuals are approximately normally distributed.

    Open Live Script

    Load the censoreddata sample data.

    load censoreddata.mat

    The matrix X contains data for three predictors, and the matrix yint contains bounds for a censored response variable.

    Fit a linear regression model to the censored data in X and yint.

    mdl = fitlmcens(X,yint);

    Display a probability plot of the standardized residuals.

    plotResiduals(mdl,"probability",ResidualType="standardized")

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

    The plot shows that the standardized residuals have a normal distribution (approximately).

    Input Arguments

    collapse all

    Censored linear regression model, specified as a CensoredLinearModel object created using fitlmcens.

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

    ValueDescription
    "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. plotResiduals calculates the distance of each residual from the median. The smallest distance corresponding to a residual in the lower tail is then plotted against the smallest distance corresponding to a residual in the upper tail, and so on. This plot includes a dotted reference line of y = x to examine the symmetry of residuals.

    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

    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(mdl,"probability",Residuals="standardized",Color="m") specifies magenta markers and standardized residuals for a probability plot of the residuals in mdl.

    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.

    Type of residual used in the plot, specified as "raw" or "standardized".

    • "raw" — Observed minus fitted values

    • "standardized" — Raw residuals divided by their estimated standard deviation

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

    For details, see Residuals.

    Example: ResidualType="standardized"

    Data Types: string | char

    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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

    "none"Not applicableNot applicableNot applicableNo color

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

    PalettePalette Colors

    "gem" — Light theme default

    Before R2025a: Most plots use these colors by default.

    Sample of the "gem" color palette

    "glow" — Dark theme default

    Sample of the "glow" color palette

    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

    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 symbol, specified as one of the values in this table.

    MarkerDescriptionResulting Marker
    "o"Circle

    Sample of circle marker

    "+"Plus sign

    Sample of plus sign marker

    "*"Asterisk

    Sample of asterisk marker

    "."Point

    Sample of point marker

    "x"Cross

    Sample of cross marker

    "_"Horizontal line

    Sample of horizontal line marker

    "|"Vertical line

    Sample of vertical line marker

    "square"Square

    Sample of square marker

    "diamond"Diamond

    Sample of diamond marker

    "^"Upward-pointing triangle

    Sample of upward-pointing triangle marker

    "v"Downward-pointing triangle

    Sample of downward-pointing triangle marker

    ">"Right-pointing triangle

    Sample of right-pointing triangle marker

    "<"Left-pointing triangle

    Sample of left-pointing triangle marker

    "pentagram"Pentagram

    Sample of pentagram marker

    "hexagram"Hexagram

    Sample of hexagram marker

    "none"No markersNot applicable

    Example: Marker="+"

    Data Types: string | char

    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

    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

    Marker size, specified as a positive value in points.

    Example: MarkerSize=2

    Data Types: single | double

    Output Arguments

    collapse all

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

    Alternative Functionality

    A CensoredLinearModel object provides multiple plotting functions. After fitting a model, use plotPartialDependence to understand the effect of a particular predictor. Use plotSlice to plot slices through the prediction surface.

    Version History

    Introduced in R2025a

    See Also

    | |