Skip to content

residual_plot

residual_plot(
    data: PlotData,
    x: str,
    y: str,
    *,
    method: Literal = "lm",
    deg: int = 1,
    span: float = 0.5,
    seed: int | None = None,
    max_n: int | None = None,
    geom: JointGeom = "point",
    bins: int | Sequence[int] | None = None,
    binwidth: float | Sequence[float] | None = None,
    color: str | None = None,
    size: float | None = None,
    alpha: float | None = None,
    color_by: str | None = None,
    show_legend: bool | None = None,
    hline: bool = True,
    marginal: str = "dens:r",
) -> PlotSpec

Plot the residuals of y after a fit on x, against x.

As lets_plot's residual_plot: the residuals (y minus the fitted value) as points, 2D bins or a 2D density, a dashed magenta line at zero and a marginal density of the residuals on the right.

Parameters:

  • data (DataFrame or dict) –

    The data. Rows with a missing, NaN or infinite x or y are left out.

  • x (str) –

    Names of the predictor and response columns.

  • y (str) –

    Names of the predictor and response columns.

  • method ((lm, loess, lowess, none), default: "lm" ) –

    The model: a polynomial least-squares fit, a local regression (needs statsmodels and scipy), or none (plots y itself).

  • deg (int, default: 1 ) –

    Degree of the "lm" polynomial.

  • span (float, default: 0.5 ) –

    Share of the data in each local "loess" fit.

  • seed (int, default: None ) –

    Random seed for max_n sampling.

  • max_n (int, default: None ) –

    Fit "loess" on this many randomly chosen rows (of each group).

  • geom ((point, tile, hex, density2d, density2df, pointdensity, none), default: "point" ) –

    The main layer.

  • bins (int or list of int, default: None ) –

    Number of bins along x and y (one value for both), for "tile"/"hex" and histogram margins. Overridden by binwidth.

  • binwidth (float or list of float, default: None ) –

    Bin width along x and y (one value for both). By default both are the larger of (x range / 30) and (y range / 30) of the data, when bins is not given.

  • color (str, default: None ) –

    Color of the main layer and of the margins.

  • size (float, default: None ) –

    Size of the main layer's marks.

  • alpha (float, default: None ) –

    Transparency of the main layer, in 0..1.

  • color_by (str, default: None ) –

    Column whose values color (and fill) the layers; one fit per value.

  • show_legend (bool, default: True ) –

    False hides the legend of the main and marginal layers.

  • hline (bool, default: True ) –

    Draw the dashed line at zero.

  • marginal (str, default: "dens:r" ) –

    The margins as "geom:sides[:size]" items separated by commas (see joint_plot); "none" draws no margins.

Returns:

  • PlotSpec –

    The plot; add more layers, scales and themes with +.

Raises:

  • SpecError –

    If method, geom, deg or a marginal item is not accepted, x or y is not numeric, a group has a single row, or "loess" is asked for without statsmodels and scipy.

  • ColumnNotFoundError –

    If x, y or color_by is not a column of data.

Examples:

>>> import numpy as np
>>> from ggrust import *
>>> from ggrust.bistro.residual import residual_plot
>>> rng = np.random.default_rng(42)
>>> hours = rng.uniform(0, 10, 150)
>>> data = {"hours": hours, "score": 50 + 4 * hours + rng.normal(0, 6, 150)}
>>> plot = residual_plot(data, "hours", "score")

The residuals of a quadratic fit, with a histogram on the margin:

>>> plot = residual_plot(data, "hours", "score", deg=2, color="#1f4e79", marginal="hist:r")

The residuals of a quadratic fit, with a histogram on the margin