Skip to content

scale_color_distiller

scale_color_distiller(
    type: Literal["seq", "div", "qual"] | None = None,
    palette: str | int | None = None,
    direction: int = -1,
    name: str | None = None,
    breaks: Breaks | None = None,
    labels: Labels | None = None,
    limits: Limits | None = None,
    na_value: Color | None = None,
    guide: Guide | None = None,
    trans: Transform | None = None,
    format: str | None = None,
    *,
    oob: Oob | None = None,
    rescaler: Rescaler | None = None,
) -> FeatureSpec

Map continuous color with a ColorBrewer palette as a smooth gradient.

The palette's 7-color set is interpolated (ggplot2 scale_colour_distiller), where scale_color_brewer cuts continuous data into the palette's bins.

Parameters:

  • type ((seq, div, qual), default: "seq" ) –

    Palette family; needed with a palette index.

  • palette (str or int, default: None ) –

    Palette name (e.g. "Blues", "RdBu") or 0-based index within type (as scale_color_brewer). Default: Blues.

  • direction ((-1, 1), default: -1 ) –

    -1 (as ggplot2) puts the palette's last color at the low end, so a sequential palette is darkest for the smallest values.

  • name (str, default: None ) –

    Legend title.

  • breaks (list, default: None ) –

    Values that get a colorbar tick.

  • labels (list of str or dict, default: None ) –

    One label per break (a dict maps breaks to labels).

  • limits (list, default: None ) –

    [low, high] data range. Data outside the limits gets na_value.

  • oob ((censor, squish), default: "censor" ) –

    What data outside limits maps to: na_value or the end color.

  • rescaler (callable, default: None ) –

    rescaler(x, to, from_): maps the data x (a polars Series of the finite values, in transformed units) from from_ (the scale's range) to to ((0.0, 1.0)) before the palette is applied; results outside to get na_value. Default: linear. Not in lets-plot (ggplot2 rescaler).

  • na_value (str, default: None ) –

    Color of missing data and data outside limits.

  • guide (str or FeatureSpec, default: None ) –

    "colorbar", "legend", "none", or a guide spec.

  • trans (str, default: None ) –

    Transformation of the data ("log10", "sqrt", ...), as in scale_color_continuous.

  • format (str, default: None ) –

    Label format (".2f", "{.1f} %").

Returns:

  • FeatureSpec –

    The scale.

Examples:

>>> from ggrust import *
>>> data = {"x": [1, 2, 3, 4], "y": [3, 1, 4, 2], "speed": [10, 20, 30, 40]}
>>> plot = ggplot(data, aes("x", "y", color="speed")) + geom_point(size=6)
>>> plot = plot + scale_color_distiller(palette="Spectral")

Light to dark with direction=1, over wider limits:

>>> base = ggplot(data, aes("x", "y", color="speed")) + geom_point(size=6)
>>> plot = base + scale_color_distiller(palette="Greens", direction=1, limits=[0, 60])

Light to dark with direction=1, over wider limits