Skip to content

guide_bins

guide_bins(
    title: str | None = None,
    *,
    show_limits: bool | None = None,
    reverse: bool | None = None,
    direction: Literal["horizontal", "vertical"]
    | None = None,
    position: Literal[
        "top", "right", "bottom", "left", "inside"
    ]
    | None = None,
    order: int | None = None,
    theme: FeatureSpec | None = None,
) -> FeatureSpec

Show a binned scale's keys touching, labelled on their edges (ggplot2).

The default guide of scale_size_binned and scale_alpha_binned: one key per bin in a single column (or row), an axis line beside them with a tick at each labelled edge, and the break values on the edges between the keys. Not in lets-plot. Scales merged into one legend (the same title) need the same bins, and a guide too large for its room is drawn as a plain legend instead. There is no ncol / nrow: the keys always form one column (or row).

Parameters:

  • title (str, default: None ) –

    Legend title.

  • show_limits (bool, default: None ) –

    Also label the two outer edges. None follows the scale's show_limits.

  • reverse (bool, default: None ) –

    True lists the bins from high to low.

  • direction ((horizontal, vertical), default: "horizontal" ) –

    Key layout of this guide; None follows theme(legend_direction=...).

  • position ((top, right, bottom, left, inside), default: "top" ) –

    Side of the plot this guide goes to, over theme(legend_position=...); "inside" puts it in the panel at theme(legend_position_inside=...) (ggplot2 3.5). Guides at one position are stacked in one block. None follows legend_position; legend_position="none" still hides every guide.

  • order (int, default: None ) –

    Place among the legends, 1 to 99, as in guide_legend.

  • theme (FeatureSpec, default: None ) –

    theme(legend_*=...) options for this guide only.

Returns:

  • FeatureSpec –

    The guide.

Raises:

  • SpecError –

    If direction, order or theme is not accepted, or show_limits is not True, False or None.

Examples:

>>> from ggrust import *
>>> data = {"x": [1, 2, 3, 4, 5], "y": [2, 4, 3, 5, 1], "score": [3, 18, 41, 66, 97]}
>>> plot = ggplot(data, aes("x", "y", size="score")) + geom_point()
>>> plot = plot + scale_size_binned(guide=guide_bins(show_limits=True))

Title the legend and lay its keys out in a row under the plot:

>>> base = ggplot(data, aes("x", "y", size="score")) + geom_point()
>>> plot = base + scale_size_binned(
...     guide=guide_bins("Score", direction="horizontal", position="bottom")
... )

Title the legend and lay its keys out in a row under the plot