Skip to content

corr_plot

corr_plot(
    data: PlotData,
    show_legend: bool = True,
    flip: bool = True,
    threshold: float | None = None,
)

Build a correlation matrix plot of tiles, points and/or labels.

Add layers with tiles(), points() and labels(), pick a palette, then call build(). Each layer covers the "upper", "lower" or "full" matrix; unset types and diagonals are chosen from the combination of layers, as lets_plot does (tiles below, points or labels above the diagonal).

Parameters:

  • data (DataFrame or dict) –

    Data (Pearson correlations of every numeric column pair are computed, over the rows where both are present) or a correlation matrix: square, float columns, every value in -1..1 or NaN.

  • show_legend (bool, default: True ) –

    False hides the colorbar.

  • flip (bool, default: True ) –

    True draws the first variable at the top of the y axis.

  • threshold (float, default: None ) –

    Cells whose absolute correlation is below this (0..1) are left out; variables left without any cell are dropped.

Examples:

>>> import numpy as np
>>> from ggrust.bistro.corr import corr_plot
>>> rng = np.random.default_rng(42)
>>> data = {name: rng.normal(size=10) for name in "abcd"}
>>> plot = corr_plot(data).tiles().labels().palette_RdBu().build()

Points sized by the correlation, with the values on top:

>>> plot = corr_plot(data).points().labels().palette_PiYG().build()

Only the lower triangle, without the weakest correlations:

>>> plot = corr_plot(data, threshold=0.2).tiles(type="lower").labels(type="lower").build()

build

build() -> PlotSpec

Create the plot.

Returns:

  • PlotSpec –

    An ordinary plot (layers, scales, theme, coord_fixed and ggsize); more features can be added with +.

Raises:

  • SpecError –

    If no layer was added (call tiles(), points() or labels()).

labels

labels(
    type: Literal | None = None,
    diag: bool | None = None,
    map_size: bool | None = None,
    color: str | None = None,
    halo_width: float | None = None,
    halo_color: str | None = None,
) -> corr_plot

Write the correlations (two decimals) in the cells.

Parameters:

  • type ((upper, lower, full), default: "upper" ) –

    Cells to label. Default: from the other layers.

  • diag (bool, default: None ) –

    Whether the main diagonal is labelled. Default: only for "full".

  • map_size (bool, default: None ) –

    True sizes the text by the absolute correlation. Default: True when the labels sit on points.

  • color (str, default: None ) –

    Text color. Default: white on tiles or points, else colored by correlation.

  • halo_width (float, default: None ) –

    Width of a text halo; not supported yet (ggrust warns).

  • halo_color (str, default: None ) –

    Color of the text halo; not supported yet (ggrust warns).

Returns:

  • corr_plot –

    A new builder with the layer.

Raises:

  • SpecError –

    If type is not one of the accepted values.

palette_BrBG

palette_BrBG() -> corr_plot

Color by the ColorBrewer BrBG palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_PRGn

palette_PRGn() -> corr_plot

Color by the ColorBrewer PRGn palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_PiYG

palette_PiYG() -> corr_plot

Color by the ColorBrewer PiYG palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_PuOr

palette_PuOr() -> corr_plot

Color by the ColorBrewer PuOr palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_RdBu

palette_RdBu() -> corr_plot

Color by the ColorBrewer RdBu palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_RdGy

palette_RdGy() -> corr_plot

Color by the ColorBrewer RdGy palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_RdYlBu

palette_RdYlBu() -> corr_plot

Color by the ColorBrewer RdYlBu palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_RdYlGn

palette_RdYlGn() -> corr_plot

Color by the ColorBrewer RdYlGn palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_Spectral

palette_Spectral() -> corr_plot

Color by the ColorBrewer Spectral palette.

Returns:

  • corr_plot –

    A new builder with the palette.

palette_gradient

palette_gradient(
    low: str, mid: str, high: str
) -> corr_plot

Color by a diverging gradient from low (-1) through mid (0) to high (1).

Parameters:

  • low (str) –

    Color of correlation -1.

  • mid (str) –

    Color of correlation 0.

  • high (str) –

    Color of correlation 1.

Returns:

  • corr_plot –

    A new builder with the palette.

points

points(
    type: Literal | None = None, diag: bool | None = None
) -> corr_plot

Draw the matrix as circles sized by absolute and colored by correlation.

Parameters:

  • type ((upper, lower, full), default: "upper" ) –

    Cells to draw. Default: from the other layers.

  • diag (bool, default: None ) –

    Whether the main diagonal is drawn. Default: only for "full".

Returns:

  • corr_plot –

    A new builder with the layer.

Raises:

  • SpecError –

    If type is not one of the accepted values.

tiles

tiles(
    type: Literal | None = None, diag: bool | None = None
) -> corr_plot

Draw the matrix as square tiles filled by correlation.

Parameters:

  • type ((upper, lower, full), default: "upper" ) –

    Cells to draw. Default: from the other layers.

  • diag (bool, default: None ) –

    Whether the main diagonal is drawn. Default: only for "full".

Returns:

  • corr_plot –

    A new builder with the layer.

Raises:

  • SpecError –

    If type is not one of the accepted values.

Points sized by the correlation, with the values on top

Only the lower triangle, without the weakest correlations