bracket

API pages include interactive (HTML) plots that would possibly not render correctly on a mobile device.

bracket(*, plot: PlotSpec | None = None, comparisons: Sequence[Sequence[str]] | None = None, test: Literal['mannwhitney', 'ttest'] = 'mannwhitney', correction: Literal['none', 'bonferroni', 'fdr_bh'] = 'fdr_bh', label: Literal['stars', 'pvalue'] = 'stars', hide_ns: bool = False, y_position: float | None = None, y_step: float | None = None, y_padding: float = 0.08, color: str | None = '#1f1f1f', label_size: float | None = None, segment_size: float = 0.5, x: str | None = None, y: str | None = None, mapping: FeatureSpec | None = None, **geom_kwargs) → DeferredLayer

Layer of stat_compare_means annotating pairwise significance between groups.

Parameters:

• plot (PlotSpec | None, default None) – If provided, brackets are computed from this plot’s data and aesthetics regardless of which plot the resulting layer is added to. When None, the layer is deferred and introspects the plot it is added to via +. Expected to be a distribution plot (e.g. violin, boxplot).

• comparisons (Sequence[Sequence[str]] | None, default None) – Specific group pairs to test, e.g. [(“A”, “B”), (“A”, “C”)]. If None, every pair of groups present in the plot is compared. “*” on either side expands to all other groups, so [(“A”, “*”)] compares A against every remaining group.

• test ({'mannwhitney', 'ttest'}, default 'mannwhitney') – Two-sided statistical test used for each pairwise comparison, as in R. ‘mannwhitney’ is the Wilcoxon rank-sum test, non-parametric and recommended for expression data; it is exact below 50 tie-free values per group (R’s wilcox.test). ‘ttest’ is Welch’s independent two-sample t-test (assumes normality).

• correction ({'none', 'bonferroni', 'fdr_bh'}, default 'fdr_bh') – Multiple-testing correction applied across the pairwise p-values.

• label ({'stars', 'pvalue'}, default 'stars') – The bracket label to draw, both from the adjusted p-value. ‘stars’ maps p-values to asterisks (**** <= 0.0001, *** <= 0.001, ** <= 0.01, * <= 0.05, ns otherwise). ‘pvalue’ prints the p-value with 2 significant digits.

• hide_ns (bool, default False) – With label=’stars’, drop the ns (not significant) brackets.

• y_position (float | None, default None) – Vertical position of the lowest bracket. If None, it is placed above the maximum y value with a gap of y_padding * y_range.

• y_step (float | None, default None) – Vertical spacing between stacked brackets. If None, defaults to y_padding * y_range.

• y_padding (float, default 0.08) – Fraction of the y range used as vertical padding above the data and as the default spacing between stacked brackets.

• color (str, default '#1f1f1f') – Color of the brackets and labels.

• label_size (float | None, default None) – Font size of the label text. If None, ggrust’s default is used.

• segment_size (float, default 0.5) – Line width of the bracket segments.

• x (str | None, default None) – The column name holding the grouping categories. If None, inferred from the plot’s x aesthetic.

• y (str | None, default None) – The column name holding the numerical values. If None, inferred from the plot’s y aesthetic.

• mapping (FeatureSpec | None, default None) – Additional aesthetic mappings for the layer, the result of aes().

• **geom_kwargs – Additional parameters for the stat_compare_means layer, e.g. tip_length.

Returns:

DeferredLayer – Pairwise significance brackets.

Raises:

• MissingAestheticError – If x or y cannot be provided explicitly or inferred from the receiving plot.

• InvalidComparisonError – If comparisons contains malformed pairs or groups not present in the plot data.

• ValueError – If test, correction or label is invalid, or there are too few observations to compute brackets.

Notes

Pairwise tests are computed by ggrust’s stat_compare_means from the plot’s retrieved DataFrame, using the x aesthetic as the grouping column and the y aesthetic as the value column.

Rows the plot dropped are absent from the test too, so a plot built with threshold compares only the observations above it.

Examples

Annotate a violin plot (or boxplot) with pairwise significance stars.

import cellestial as cl
import scanpy as sc

from ggrust import *

data = cl.datasets.pbmc3k()

violin = cl.violin(
    data,
    key="CD3D",
    fill="cell_type_lvl1",
    threshold=0.1,
)
violin + cl.bracket(y_padding=0.2)

The threshold narrows the comparison too: these p-values cover only the cells above 0.1.

Restrict the comparisons and show adjusted p-values instead of stars.

box = cl.boxplot(
    data,
    key="CD3D",
    fill="cell_type_lvl1",
    threshold=0.1,
)
box + cl.bracket(
    comparisons=[("Monocytes", "Erythroid"), ("Monocytes", "B Cells")],
    label="pvalue",
    y_padding=0.2,
)

Use “*” to compare one group against every other.

box + cl.bracket(
    comparisons=[("Lymphocytes", "*")],
    y_padding=0.2,
)

Hide non-significant brackets.

box + cl.bracket(hide_ns=True, y_padding=0.2)