Skip to content

joint_plot

joint_plot(
    data: PlotData,
    x: str,
    y: str,
    *,
    geom: Literal | None = None,
    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,
    reg_line: bool | None = None,
    se: bool | None = None,
    marginal: str | None = None,
) -> PlotSpec

Draw a bivariate plot of x and y with their distributions in the margins.

As lets_plot's joint_plot: a main layer (points, 2D bins or a 2D density), a dashed linear regression line for point layers, and marginal densities, histograms or boxplots (ggmarginal) on the chosen sides.

Parameters:

  • data (DataFrame or dict) –

    The data.

  • x (str) –

    Names of the columns on the x and y axes.

  • y (str) –

    Names of the columns on the x and y axes.

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

    The main layer; "none" draws only the regression line and margins.

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

    Number of bins along x and y (one value for both), for "tile"/"hex" and the 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), 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 regression line and one marginal shape per value.

  • show_legend (bool, default: True ) –

    False hides the legend of the main and marginal layers.

  • reg_line (bool, default: None ) –

    Draw a linear regression line; by default only for "point" and "pointdensity".

  • se (bool, default: True ) –

    Draw the confidence band around the regression line.

  • marginal (str, default: None ) –

    The margins as "geom:sides[:size]" items separated by commas: geom one of "dens"/"density", "hist"/"histogram", "box"/"boxplot", sides any of "t", "b", "l", "r", size a share of the plot (see ggmarginal), e.g. "hist:tr:0.3" or "box:tr:.05, dens:bl". Default "dens:tr" for 2D densities or with color_by, else "hist:tr"; "none" draws no margins.

Returns:

  • PlotSpec –

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

Raises:

  • SpecError –

    If geom or a marginal item is not one of the accepted values.

  • ColumnNotFoundError –

    If x or y is not a column of data (only when default bin widths must be computed from the data).

Examples:

>>> import numpy as np
>>> from ggrust import *
>>> from ggrust.bistro.joint import joint_plot
>>> rng = np.random.default_rng(42)
>>> data = {"height": rng.normal(170, 8, 200), "weight": rng.normal(70, 10, 200)}
>>> plot = joint_plot(data, "height", "weight")

2D bins, with histograms on the margins:

>>> plot = joint_plot(data, "height", "weight", geom="tile", bins=[12, 12])

A filled 2D density, with boxplots on the top and right:

>>> plot = joint_plot(data, "height", "weight", geom="density2df", marginal="box:tr")

2D bins, with histograms on the margins

A filled 2D density, with boxplots on the top and right