geom_mark_hull ¶

Outline each group of points with a concave hull, optionally with a callout.

As geom_mark_hull in the R package ggforce: for clusters on a UMAP or any scatter plot. Each group (each fill, color or group value) gets the concave hull of its points (in screen space), grown by expand, with corners rounded by radius. Map label (bold) and/or description (wrapped) to add a callout outside the marks, joined to its mark by a connector.

Parameters:

• mapping (FeatureSpec, default: None ) –

  Aesthetic mapping from aes(). Needs x and y; also reads label, description and filter (a boolean column: True rows are outlined, the others only keep callouts away).

• 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 or FeatureSpec, default: None ) –

  lets_plot sampling; accepted and ignored, as ggrust draws every row.

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

  Accepted for lets_plot compatibility; marks have no tooltips yet.

• expand (float, default: 5 ) –

  Millimetres the mark extends beyond its points.

• radius (float, default: 2.5 ) –

  Corner radius in millimetres (at most expand).

• concavity (float, default: 2 ) –

  How concave the hull may be: 1 is very concave, larger values approach the convex hull.

• label_margin (float or list of 4 floats, default: 2 ) –

  Margin inside the callout box in millimetres (top, right, bottom, left).

• label_width (float, default: None ) –

  Fixed callout width in millimetres; the label wraps to it too.

• label_minwidth (float, default: 50 ) –

  Width in millimetres the description wraps to (when wider).

• label_hjust (float or list of 2 floats, default: 0 ) –

  Horizontal justification of the label and the description.

• label_fontsize (float or list of 2 floats, default: 12 ) –

  Font size in points of the label and the description.

• label_family (str or list of 2 str, default: "sans" ) –

  Font family of the label and the description.

• label_lineheight (float or list of 2 floats, default: 1 ) –

  Line height of the label and the description.

• label_fontface (str or list of 2 str, default: ["bold", "plain"] ) –

  Font face of the label and the description.

• label_fill (str, default: "white" ) –

  Callout background color.

• label_colour (str or list of 2 str, default: "black" ) –

  Text color of the label and the description (also label_color).

• label_buffer (float, default: 10 ) –

  Distance in millimetres the callouts keep from the marks.

• con_colour (str, default: "black" ) –

  Connector color (also con_color).

• con_size (float, default: 0.65 ) –

  Connector width, in size units (ggforce's 0.5 mm).

• con_type ((elbow, straight, none), default: "elbow" ) –

  Connector shape.

• con_linetype (str or int, default: "solid" ) –

  Connector line type.

• con_border ((one, all, none), default: "one" ) –

  The connector also draws the callout's near edge ("one"), its whole outline ("all") or nothing.

• con_cap (float, default: 3 ) –

  Gap in millimetres between the connector's end and the mark.

• na_rm (bool, default: None ) –

  True removes rows with missing values silently.

• **other_args (Any) –

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

Returns:

• LayerSpec –

  The layer.

Raises:

• SpecError –

  If a length is negative, concavity is not positive, or con_type / con_border is not one of the accepted names.

• UnsupportedValueError –

  If a length or concavity is not a number.

Examples:

>>> from ggrust import *
>>> import numpy as np
>>> generator = np.random.default_rng(3)
>>> data = {"x": np.concatenate([generator.normal(0, 1, 150), generator.normal(5, 1, 150)]),
...         "y": np.concatenate([generator.normal(0, 1, 150), generator.normal(3, 1, 150)]),
...         "cluster": ["T cells"] * 150 + ["B cells"] * 150}
>>> plot = (ggplot(data, aes("x", "y"))
...         + geom_mark_hull(aes(fill="cluster", label="cluster"))
...         + geom_point(aes(color="cluster"), size=1.5)
...         + expand_limits(x=[-6, 11], y=[-5, 9]))