Skip to content

geom_pwc

geom_pwc(
    mapping: FeatureSpec | None = None,
    *,
    data: PlotData | None = None,
    method: Literal | None = None,
    ref_group: str | int | None = None,
    label: str | None = None,
    y_position: Number | Sequence[Number] | None = None,
    group_by: Literal["x.var", "legend.var"] | None = None,
    dodge: Number | None = None,
    step_increase: Number | None = None,
    tip_length: Number | None = None,
    bracket_nudge_y: Number | None = None,
    bracket_shorten: Number | None = None,
    p_adjust_method: Literal | None = None,
    p_adjust_by: Literal["group", "panel"] | None = None,
    hide_ns: bool | Literal["p", "p.adj"] | None = None,
    position: Position | None = None,
    show_legend: bool | None = None,
    inherit_aes: bool | None = None,
    manual_key: ManualKey | None = None,
    na_rm: bool | None = None,
    **other_args: Any,
) -> LayerSpec

Test every pair of groups and draw a labelled bracket per comparison.

As geom_pwc in the R package ggpubr (tests from rstatix). Along a discrete x, the x categories are compared pairwise and the brackets stacked above the data. When other aesthetics (color, fill) split each x into groups, those groups are compared within each x (group_by="x.var", brackets between the dodged groups), or the x categories within each group ("legend.var", brackets in the group's color). p-values are adjusted for multiple comparisons ("holm") within each set of comparisons.

Parameters:

  • mapping (FeatureSpec, default: None ) –

    Aesthetic mapping from aes(): x (categories) and y; inherits the plot's.

  • data (DataFrame or dict, default: None ) –

    Layer data; inherits the plot data when None.

  • method ((wilcox_test, t_test), default: "wilcox_test" ) –

    Wilcoxon rank sum test or Welch's t test. "wilcox.test", "t.test" and "wilcoxon" work too.

  • ref_group (str or int, default: None ) –

    Compare every other level with this one only: an x category (name or 1-based position), or with group_by="x.var" the 1-based rank of a group (1 for the first). "all" compares each level with all values (labels only).

  • label (str, default: "p.format" ) –

    What the brackets show: "p", "p.adj", "p.format", "p.adj.format", "p.signif", "p.adj.signif", "method", "n1", "n2", or a template of them in braces, e.g. "p = {p.adj.format}". p.format reads "0.0012" or "<0.0001"; p.signif reads **** (<= 1e-4) to ns (> 0.05).

  • y_position (float or list of float, default: None ) –

    Height of the first bracket (later ones step up from it), or of every bracket. Default: the top of the data.

  • group_by ((var, var), default: "x.var" ) –

    With groups within x: compare the groups at each x, or the x categories of each group.

  • dodge (float, default: 0.95 ) –

    Dodge width of the groups within x: 0.95 puts the bracket ends on the boxes of geom_boxplot and geom_violin (ggpubr's 0.8 fits its ggboxplot).

  • step_increase (float, default: 0.12 ) –

    Gap between stacked brackets, as a share of the y range.

  • tip_length (float, default: 0.03 ) –

    Bracket tip length, as a share of the y range.

  • bracket_nudge_y (float, default: 0.05 ) –

    Lift of the first bracket, as a share of the y range.

  • bracket_shorten (float, default: None ) –

    Pull both bracket ends toward the middle: 0 keeps the full width.

  • p_adjust_method (Literal, default: "holm" ) –

    R p.adjust method: "holm", "hochberg", "hommel", "bonferroni", "BH" (or "fdr"), "BY" or "none".

  • p_adjust_by ((group, panel), default: "group" ) –

    Adjust within each set of comparisons, or over all of the panel's.

  • hide_ns (bool or {p, adj}, default: False ) –

    Drop comparisons that are not significant (> 0.05): by p.adj (True or "p.adj") or by p.

  • position (str or FeatureSpec, default: None ) –

    Position adjustment.

  • show_legend (bool, default: None ) –

    True shows this layer in the legend.

  • inherit_aes (bool, default: True ) –

    False ignores the plot's default mapping.

  • manual_key (str or FeatureSpec, default: None ) –

    This layer's key in a manual legend.

  • na_rm (bool, default: None ) –

    True removes rows with missing values silently.

  • **other_args (Any) –

    Constant aesthetics of the brackets and labels, e.g. size, color.

Returns:

  • LayerSpec –

    The layer.

Raises:

Examples:

>>> from ggrust import *
>>> data = {"diet": ["veg"] * 6 + ["meat"] * 6 + ["fish"] * 6,
...         "weight": [61, 58, 66, 70, 63, 59, 72, 80, 77, 69, 85, 74,
...                    65, 68, 71, 64, 70, 66]}
>>> plot = (ggplot(data, aes("diet", "weight")) + geom_boxplot()
...         + geom_pwc(label="p.adj.signif"))

Adjusted p-values of t tests in a label template:

>>> plot = (ggplot(data, aes("diet", "weight")) + geom_boxplot()
...         + geom_pwc(method="t_test", label="p = {p.adj.format}",
...                    p_adjust_method="bonferroni"))

With groups within each x, the dodged groups are compared:

>>> from ggrust.data import penguins
>>> plot = (ggplot(penguins.drop_nulls(), aes("species", "body_mass_g", fill="sex"))
...         + geom_boxplot() + geom_pwc(label="p.signif"))

Adjusted p-values of t tests in a label template

With groups within each x, the dodged groups are compared