geom_bracket

geom_bracket(mapping=None, *, data=None, stat=None, position=None, show_legend=None, manual_key=None, sampling=None, orientation=None, label_format=None, na_text=None, nudge_x=None, nudge_y=None, nudge_unit=None, size_unit=None, bracket_shorten=None, tiplength_unit=None, color_by=None, **other_args)

Annotate a plot with labeled brackets to highlight relationships or groupings between categories or ranges.

Parameters:

mappingFeatureSpec

Set of aesthetic mappings created by aes() function. Aesthetic mappings describe the way that variables in the data are mapped to plot “aesthetics”.

datadict or Pandas or Polars DataFrame

The data to be displayed in this layer. If None, the default, the data is inherited from the plot data as specified in the call to ggplot.

statstr, default=’identity’

The statistical transformation to use on the data for this layer, as a string. Supported transformations: ‘identity’ (leaves the data unchanged), ‘count’ (counts number of points with the same x-axis coordinate), ‘bin’ (counts number of points with the x-axis coordinate in the same bin), ‘smooth’ (performs smoothing - linear default), ‘density’ (computes and draws kernel density estimate), ‘sum’ (counts the number of points at each location - might help to work around overplotting).

positionstr or FeatureSpec, default=’identity’

Position adjustment. Either a position adjustment name: ‘dodge’, ‘jitter’, ‘nudge’, ‘jitterdodge’, ‘fill’, ‘stack’ or ‘identity’, or the result of calling a position adjustment function (e.g., position_dodge() etc.).

show_legendbool, default=False

True - show legend for this layer.

manual_keystr or layer_key

The key to show in the manual legend. Specify text for the legend label or advanced settings using the layer_key() function.

samplingFeatureSpec

Result of the call to the sampling_xxx() function. To prevent any sampling for this layer pass value “none” (string “none”).

orientationstr, default=’x’

Specify the axis that the geom should run along. Possible values: ‘x’, ‘y’.

label_formatstr

Format used to transform text label mapping values to a string. Examples:

• ‘.2f’ -> ‘12.45’

• ‘Num {}’ -> ‘Num 12.456789’

• ‘TTL: {.2f}$’ -> ‘TTL: 12.45$’

For more info see Formatting.

na_textstr, default=’n/a’

Text to show for missing values.

nudge_xfloat

Horizontal adjustment to nudge geometry by.

nudge_yfloat

Vertical adjustment to nudge geometry by.

size_unit{‘x’, ‘y’, ‘min’, ‘max’}

Relate the size of the text to the length of the unit step along one of the axes. ‘x’ uses the unit step along the x-axis, ‘y’ uses the unit step along the y-axis. ‘min’ uses the smaller of the unit steps along the x- and y-axes. ‘max’ uses the larger of the unit steps along the x- and y-axes. If None, no fitting is performed.

bracket_shortenfloat, default=0

Symmetrically shorten the bracket by shifting both ends toward the center. Expect values between 0 and 1, where 0 corresponds to no shortening and 1 to a fully collapsed bracket.

tiplength_unit{‘res’, ‘identity’, ‘size’, ‘px’}, default=’size’

Unit for lenstart and lenend aesthetics. Possible values:

• ‘res’: the unit equals the smallest distance between data points along the corresponding axis;

• ‘identity’: a unit of 1 corresponds to a difference of 1 in data space;

• ‘size’: a unit of 1 corresponds to the diameter of a point with size=1;

• ‘px’: the unit is measured in screen pixels.

nudge_unit{‘identity’, ‘size’, ‘px’}, default=’identity’

Units for x and y nudging. Possible values:

• ‘identity’: a unit of 1 corresponds to a difference of 1 in data space;

• ‘size’: a unit of 1 corresponds to the diameter of a point with size=1;

• ‘px’: the unit is measured in screen pixels.

color_by{‘fill’, ‘color’, ‘paint_a’, ‘paint_b’, ‘paint_c’}, default=’color’

Define the color aesthetic for the geometry.

other_args

Other arguments passed on to the layer. These are often aesthetics settings used to set an aesthetic to a fixed value, like color=’red’, fill=’blue’, size=3 or shape=21. They may also be parameters to the paired geom/stat.

Returns:

LayerSpec

Geom object specification.

Notes

geom_bracket() understands the following aesthetics mappings:

• xmin or ymin : left or lower end of the bracket for horizontal or vertical brackets, respectively.

• xmax or ymax : right or upper end of the bracket for horizontal or vertical brackets, respectively.

• y or x : y-axis or x-axis coordinates for horizontal or vertical brackets, respectively.

• alpha : transparency level of a layer. Accept values between 0 and 1.

• color (colour) : color of the geometry. For more info see Color and Fill.

• size : font size.

• label : text to add.

• family : font family. For more info see Text.

• fontface : font style and weight. For more info see Text.

• hjust : horizontal text alignment relative to the x-coordinate. Possible values: 0 or ‘left’ - left-aligned (text starts at x), 0.5 or ‘middle’ (default) - text is centered on x, 1 or ‘right’ - right-aligned (text ends at x). There are two special alignments: ‘inward’ (aligns text towards the plot center) and ‘outward’ (away from the plot center).

• vjust : vertical text alignment relative to the y-coordinate. Accept either a numeric value or one of the following strings: ‘bottom’, ‘center’, or ‘top’. The numeric values 0, 0.5 (default), and 1 correspond to ‘bottom’ (bottom of text at y), ‘center’ (middle of text at y), and ‘top’ (top of text at y), respectively. There are two special alignments: ‘inward’ (aligns text towards the plot center) and ‘outward’ (away from the plot center).

• angle : text rotation angle in degrees.

• lineheight : line height multiplier applied to the font size in the case of multi-line text.

• linetype : type of the line. Accept codes or names (0 = ‘blank’, 1 = ‘solid’, 2 = ‘dashed’, 3 = ‘dotted’, 4 = ‘dotdash’, 5 = ‘longdash’, 6 = ‘twodash’), a hex string (up to 8 digits for dash-gap lengths), or a list pattern [offset, [dash, gap, …]] / [dash, gap, …]. For more info see Line Types.

• segment_color : color of the bracket line (the segments forming the bracket).

• segment_size : width of the bracket line (the segments forming the bracket).

• segment_alpha : transparency level of the bracket line. Accept values between 0 and 1.

• lenstart : length of the tip at the bracket start (at xmin for horizontal brackets, or ymin for vertical).

• lenend : length of the tip at the bracket end (at xmax for horizontal brackets, or ymax for vertical).

Examples

import numpy as np
from lets_plot import *
LetsPlot.setup_html()
n = 50
np.random.seed(42)
box_data = {
    'x': ['a'] * n + ['b'] * n + ['c'] * n,
    'y': np.concatenate([np.random.normal(size=n, loc=0),
                         np.random.normal(size=n, loc=.1),
                         np.random.normal(size=n, loc=.5)]),
}
bracket_data = {
    'xmin': ['a', 'a', 'b'],
    'xmax': ['b', 'c', 'c'],
    'y': [3.6, 4.2, 4.8],
    'label': ['*', '**', 'ns'],
}
ggplot(box_data, aes(x='x', y='y', color='x')) + \
    geom_boxplot(aes(fill='x'), alpha=.25) + \
    geom_jitter(height=0, seed=42) + \
    geom_bracket(aes(xmin='xmin', xmax='xmax', y='y', label='label'), data=bracket_data)

import numpy as np
from lets_plot import *
LetsPlot.setup_html()
n = 50
np.random.seed(42)
violin_data = {
    'x': np.concatenate([np.random.normal(size=n, loc=0),
                         np.random.normal(size=n, loc=.1),
                         np.random.normal(size=n, loc=.5)]),
    'y': ['a'] * n + ['b'] * n + ['c'] * n,
}
bracket_data = {
    'x': [-2.9, -3.3, -3.7],
    'ymin': ['a', 'a', 'b'],
    'ymax': ['b', 'c', 'c'],
    'label': ['*', '**', 'ns'],
}
ggplot(violin_data, aes(x='x', y='y', color='y')) + \
    geom_violin(aes(fill='y'), alpha=.25) + \
    geom_sina(seed=42) + \
    geom_bracket(aes(x='x', ymin='ymin', ymax='ymax', label='label'), data=bracket_data,
                 lenstart=-.1, lenend=-.1, tiplength_unit='identity', vjust=2.2,
                 color='maroon', size=9, segment_size=1.25)