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 bybinwidth. -
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
binsis 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 (seeggmarginal), e.g."hist:tr:0.3"or"box:tr:.05, dens:bl". Default"dens:tr"for 2D densities or withcolor_by, else"hist:tr";"none"draws no margins.
Returns:
-
PlotSpec–The plot; add more layers, scales and themes with
+.
Raises:
-
SpecError–If
geomor a marginal item is not one of the accepted values. -
ColumnNotFoundError–If
xoryis not a column ofdata(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