Skip to content

geom_shape

geom_shape(
    mapping: FeatureSpec | None = None,
    *,
    data: PlotData | None = None,
    stat: str | None = None,
    position: Position | None = None,
    show_legend: bool | None = None,
    inherit_aes: bool | None = None,
    manual_key: ManualKey | None = None,
    sampling: Sampling | None = None,
    tooltips: Tooltips | None = None,
    expand: Number | None = None,
    radius: Number | None = None,
    na_rm: bool | None = None,
    **other_args: Any,
) -> LayerSpec

Draw polygons with rounded corners, optionally grown outwards.

As geom_shape in the R package ggforce: geom_polygon (one closed shape per group, vertices in data order) whose convex corners become circular arcs of radius and whose outline is grown by expand. Concave corners stay sharp. Both lengths are in millimetres on the screen, applied after the coordinate system, so a rounded corner is round with or without coord_fixed(). A radius larger than a corner's edges allow is reduced to fit them: a rectangle with a radius of at least half its height is drawn as a stadium (a pill), for example a cell outline.

Parameters:

  • mapping (FeatureSpec, default: None ) –

    Aesthetic mapping from aes(). Needs x and y; group (or a discrete fill / color) separates the shapes.

  • data (DataFrame or dict, default: None ) –

    Layer data; inherits the plot data when None.

  • stat (str, default: None ) –

    Statistical transformation, "identity" by default.

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

    Position adjustment.

  • show_legend (bool, default: None ) –

    False hides this layer from the legend.

  • inherit_aes (bool, default: None ) –

    False ignores the plot's default mapping for this layer.

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

    This layer's key in a manual legend: a label, or layer_key().

  • sampling ((str, int or FeatureSpec), default: None ) –

    Rows to draw: a sampling_*() spec, an int n (sampling_random(n)) or "none". Default: every row.

  • tooltips (FeatureSpec or list of str, default: None ) –

    Accepted for lets_plot compatibility; shapes have no tooltips yet.

  • expand (float, default: 0 ) –

    Millimetres the shape grows beyond its vertices (non-negative).

  • radius (float, default: 0 ) –

    Corner radius in millimetres (non-negative). Larger than half the shortest side rounds that side fully.

  • na_rm (bool, default: None ) –

    True removes rows with missing values silently.

  • **other_args (Any) –

    Constant aesthetics (color, fill, alpha, size, linetype).

Returns:

  • LayerSpec –

    The layer.

Raises:

  • SpecError –

    If expand or radius is negative or not finite.

  • UnsupportedValueError –

    If expand or radius is not a number.

Examples:

>>> from ggrust import *
>>> import numpy as np
>>> generator = np.random.default_rng(1)
>>> cell = {"x": [0, 10, 10, 0], "y": [0, 0, 2, 2]}
>>> spots = {"x": generator.uniform(1, 9, 40), "y": generator.uniform(0.4, 1.6, 40)}
>>> plot = (ggplot()
...         + geom_shape(aes("x", "y"), data=cell, radius=1000, fill="#f2f2f2",
...                      color="black")
...         + geom_point(aes("x", "y"), data=spots, color="#d62728")
...         + coord_fixed())

expand grows a polygon beyond its vertices, here around a group of points:

>>> corners = {"x": [1, 5, 3], "y": [1, 1, 4]}
>>> plot = (ggplot(corners, aes("x", "y"))
...         + geom_shape(expand=8, radius=8, fill="#aec7e8", alpha=0.6)
...         + geom_polygon(fill="white", color="black")
...         + geom_point(size=4) + xlim(0, 6) + ylim(0, 5))

expand grows a polygon beyond its vertices, here around a group of points