Skip to content

pairs and Pairs

pairs

pairs: a scatterplot matrix, every pair of number columns against each other.

Each column of panels is one variable on x and each row one on y, so a variable's scale is shared along its column and its row; the diagonal shows each variable alone (a density curve or a histogram, drawn over the variable's own range so the row's scale reads for it too). Brushing a panel selects its rows in every panel (the rows are linked by their index in the data), and selected() gives them as rows of the data.

The plot is a Trellis of the data reshaped: a row per pair of variables and row of the data, faceted by the y variable (rows) and the x variable (columns).

GRID module-attribute

GRID = 128

Points along a diagonal density curve.

DIAG_GREY module-attribute

DIAG_GREY = '#8c8c8c'

The diagonal's colour when the points are coloured by numbers.

Pairs

Pairs(
    data: Any,
    columns: Sequence[str] | None = None,
    *,
    color: str | None = None,
    diag: Diag | None = "auto",
    corner: bool = False,
    bins: int = 20,
    size: float = 3.0,
    opacity: float = 0.6,
    tooltip: Sequence[str] = (),
    palette: str
    | Sequence[str]
    | Mapping[str, str]
    | None = None,
    height: int | None = None,
    panel_height: int | None = None,
    title: str = "",
    subtitle: str = "",
    caption: str = "",
    labels: Mapping[str, str] | None = None,
    legend: str = "auto",
    theme: str | Theme | None = None,
    renderer: str = "auto",
)

Bases: Trellis

A scatterplot matrix (anytrellis.pairs): a Trellis whose selected() gives rows of the data, and whose panels are named "<y column> · <x column>".

selected

selected(layer: str | int | None = None) -> Any

The selected rows of the data, as the same kind of table; none selected: no rows.

pairs

pairs(
    data: Any,
    columns: Sequence[str] | None = None,
    *,
    color: str | None = None,
    diag: Diag | None = "auto",
    corner: bool = False,
    bins: int = 20,
    size: float = 3.0,
    opacity: float = 0.6,
    tooltip: Sequence[str] = (),
    palette: str
    | Sequence[str]
    | Mapping[str, str]
    | None = None,
    height: int | None = None,
    panel_height: int | None = None,
    title: str = "",
    subtitle: str = "",
    caption: str = "",
    labels: Mapping[str, str] | None = None,
    legend: str = "auto",
    theme: str | Theme | None = None,
    renderer: str = "auto",
) -> Pairs

A scatterplot matrix: each pair of columns plotted against each other, x by column and y by row, with each variable alone on the diagonal.

from anytrellis import pairs

p = pairs(penguins, ["bill_length_mm", "bill_depth_mm", "body_mass_g"], color="species")
p                     # brush a panel: its rows light up in every panel
p.selected()          # the brushed rows of the data

Parameters:

  • data (Any) –

    The table (Polars, PyArrow, pandas, DuckDB, Ibis, or a dict of arrays).

  • columns (Sequence[str] | None, default: None ) –

    The number columns, in order (default: every number column but color).

  • color (str | None, default: None ) –

    A colour column (categories: a colour each, and a curve or a bar each on the diagonal; numbers: a colormap) or one colour.

  • diag (Diag | None, default: 'auto' ) –

    The diagonal: "density" (a density curve, per colour), "hist" (a histogram, stacked by colour), "auto" (density with a colour column, otherwise a histogram) or None (empty).

  • corner (bool, default: False ) –

    Only the panels below the diagonal (each pair once), and the diagonal.

  • bins (int, default: 20 ) –

    The diagonal histograms' bins.

  • size (float, default: 3.0 ) –

    Point diameter in CSS pixels.

  • opacity (float, default: 0.6 ) –

    The points' opacity, 0 to 1.

  • tooltip (Sequence[str], default: () ) –

    More columns shown on hover (the plotted columns and color always are).

  • palette (str | Sequence[str] | Mapping[str, str] | None, default: None ) –

    Colours for a category colour column: as for Trellis.

  • height (int | None, default: None ) –

    The plot's height in CSS pixels (default: square panels).

  • panel_height (int | None, default: None ) –

    Each panel's height in CSS pixels (default: square panels).

  • title (str, default: '' ) –

    A title over the plot.

  • subtitle (str, default: '' ) –

    A line or two under the title.

  • caption (str, default: '' ) –

    A note under the plot (the source, a footnote).

  • labels (Mapping[str, str] | None, default: None ) –

    Names to show for columns, {"bill_length_mm": "Bill length (mm)"}: on the strips, in the legend and the tooltips. Panels keep the columns' names (open("bill_depth_mm · bill_length_mm")).

  • legend (str, default: 'auto' ) –

    As for Trellis.

  • theme (str | Theme | None, default: None ) –

    As for Trellis.

  • renderer (str, default: 'auto' ) –

    As for Trellis.

Pairs

Pairs(
    data: Any,
    columns: Sequence[str] | None = None,
    *,
    color: str | None = None,
    diag: Diag | None = "auto",
    corner: bool = False,
    bins: int = 20,
    size: float = 3.0,
    opacity: float = 0.6,
    tooltip: Sequence[str] = (),
    palette: str
    | Sequence[str]
    | Mapping[str, str]
    | None = None,
    height: int | None = None,
    panel_height: int | None = None,
    title: str = "",
    subtitle: str = "",
    caption: str = "",
    labels: Mapping[str, str] | None = None,
    legend: str = "auto",
    theme: str | Theme | None = None,
    renderer: str = "auto",
)

Bases: Trellis

A scatterplot matrix (anytrellis.pairs): a Trellis whose selected() gives rows of the data, and whose panels are named "<y column> · <x column>".

selected

selected(layer: str | int | None = None) -> Any

The selected rows of the data, as the same kind of table; none selected: no rows.