bracket#

bracket(*, plot: PlotSpec | None = None, comparisons: Sequence[Sequence[str]] | None = None, test: Literal['mannwhitney', 'ttest'] = 'mannwhitney', alternative: Literal['two-sided', 'less', 'greater'] = 'two-sided', correction: Literal['none', 'bonferroni', 'fdr_bh'] = 'fdr_bh', label: Literal['stars', 'pvalue', 'padj'] | Sequence[Literal['stars', 'pvalue', 'padj']] = 'stars', label_format: str = '.3g', prefix: str = '', prefix_style: Literal['=', '<'] | None = '=', separator: str = ' ', threshold: float | None = None, 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 geom_bracket annotating pairwise significance between groups.

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

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.

  • test ({'mannwhitney', 'ttest'}, default 'mannwhitney') – Statistical test used for each pairwise comparison. ‘mannwhitney’ is non-parametric and recommended for expression data. ‘ttest’ is an independent two-sample t-test (assumes normality).

  • alternative ({'two-sided', 'less', 'greater'}, default 'two-sided') – The alternative hypothesis passed to the underlying test.

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

  • label ({'stars', 'pvalue', 'padj'} or sequence of those, default 'stars') – The bracket label to draw. ‘stars’ maps p-values to asterisks (**** < 0.0001, *** < 0.001, ** < 0.01, * < 0.05, ns otherwise). ‘pvalue’ prints the raw p-value and ‘padj’ prints the adjusted p-value. A sequence merges each component with a newline, e.g. label=("stars", "padj") stacks the stars on top of the adjusted p-value.

  • label_format (str, default '.3g') – Format string used when label contains ‘pvalue’ or ‘padj’.

  • prefix (str, default '') – Text prepended to the numeric p-value/padj labels. Ignored for the ‘stars’ component. When prefix_style is ‘=’ or ‘<’, the symbol is inserted between prefix and the value with whitespace around it, so prefix='p' with prefix_style='=' renders 'p = 0.001'. When prefix_style is None, prefix is used as-is, so the caller is responsible for including any symbol and spacing.

  • prefix_style ({'=', '<'} or None, default '=') – How the numeric portion of the label is rendered. ‘=’ shows the actual p-value with ' = ' inserted after prefix. ‘<’ replaces the p-value with the star-bracket threshold it falls below, with ' < ' inserted after prefix, giving 'p < 0.0001', 'p < 0.001', 'p < 0.01', or 'p < 0.05'. Non-significant comparisons render as 'p > 0.05'. None disables symbol insertion; the caller supplies any symbol via prefix.

  • separator (str, default ' ') – Separator used to join components when label is a sequence with more than one entry (e.g. ('stars', 'padj')).

  • threshold (float | None, default None) – If provided, only comparisons whose p-value (adjusted if correction is not ‘none’) is below this threshold are drawn.

  • 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, geom_bracket’s default is used.

  • segment_size (float, default 1) – 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 geom_bracket layer. For more information on geom_bracket parameters, see: https://lets-plot.org/python/pages/api/lets_plot.geom_bracket.html

Returns:

LayerSpec – Pairwise significance brackets.

Examples

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

import cellestial as cl
import scanpy as sc

from lets_plot import *

data = sc.read_h5ad("data/pbmc3k_pped.h5ad")

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

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="padj",
    y_padding=0.2,
)

Hide non-significant brackets by setting a threshold on the adjusted p-value.

box + cl.bracket(threshold=0.001,y_padding=0.2)

Adjust the label format places and add a prefix.

box + cl.bracket(
    threshold=0.05,
    label="pvalue",
    prefix="p",
    prefix_style="=",
    y_padding=0.2,
)

Use “<” notation instead.

box + cl.bracket(
    threshold=0.05,
    label="pvalue",
    prefix="p",
    prefix_style="<",
    y_padding=0.2,
)
On this page