geom_bracket_dodge#

geom_bracket_dodge(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, dodge_width=None, ngroup=None, color_by=None, **other_args)#

Annotate a plot with labeled brackets connecting dodged groups inside each category.

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.

dodge_widthfloat, default=0.95

Width used to compute bracket positions. Expected to match the dodge width used by other layers for proper alignment.

ngroupint

Total number of dodged groups per category; used to interpret istart/iend indices. By default, this value is inferred from the data when possible, but can be set explicitly if needed.

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_dodge() understands the following aesthetics mappings:

  • x or y : primary axis category for horizontal or vertical brackets, respectively.

  • y or x : bracket level (the height/position at which the bracket is drawn) for horizontal or vertical brackets, respectively.

  • istart : index of the dodged group at the bracket start. Accept integer values between 0 and ngroup - 1.

  • iend : index of the dodged group at the bracket end. Accept integer values between 0 and ngroup - 1.

  • 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 istart).

  • lenend : length of the tip at the bracket end (at iend).

Examples

 1import numpy as np
 2from lets_plot import *
 3LetsPlot.setup_html()
 4n = 50
 5np.random.seed(42)
 6box_data = {
 7    'x': ['a'] * 2 * n + ['b'] * 2 * n + ['c'] * 2 * n,
 8    'y': np.concatenate([np.random.normal(size=n, loc=0),
 9                         np.random.normal(size=n, loc=.5),
10                         np.random.normal(size=n, loc=0),
11                         np.random.normal(size=n, loc=-.5),
12                         np.random.normal(size=n, loc=0),
13                         np.random.normal(size=n, loc=.25)]),
14    'g': (['x'] * n + ['y'] * n) * 3,
15}
16bracket_data = {
17    'x': ['a', 'b', 'c'],
18    'y': [2.6, 3, 4.4],
19    'start': [0, 0, 0],
20    'end': [1, 1, 1],
21    'label': ['***', '*', 'ns'],
22}
23ggplot(box_data, aes(x='x', y='y', color='g')) + \
24    geom_boxplot(aes(fill='g'), alpha=.25) + \
25    geom_point(position=position_jitterdodge(jitter_width=.2, jitter_height=0, seed=42),
26               shape=1, size=2, alpha=.25, show_legend=False) + \
27    geom_bracket_dodge(aes(x='x', y='y', istart='start', iend='end', label='label'), data=bracket_data)
On this page