Skip to content

compare_means

Tables of group comparisons with p-values (ggpubr's compare_means), tested in Rust.

Not in lets-plot; in R it is ggpubr::compare_means(). compare_means() tests the groups of a response column and returns one row per comparison, ready for stat_pvalue_manual(). The tests (t.test, wilcox.test, anova, kruskal.test) and p.adjust give R's p-values; ggpubr is GPL, ggrust implements the statistics, not its code.

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

ColumnNotFoundError

ColumnNotFoundError(
    message: str,
    *,
    column: str,
    available: list[str],
    path: str = "",
)

Bases: ggrust.errors.DataError

Raised when a mapping refers to a column that is not in the data.

Parameters:

  • message (str) –

    The full message, listing the available columns and a close match.

  • column (str) –

    The missing column.

  • available (list of str) –

    Names of the columns the data has.

  • path (str, default: "" ) –

    Spec path of the mapping that names the column, e.g. "layers[0].mapping.x".

Examples:

>>> from ggrust import *
>>> from ggrust.errors import ColumnNotFoundError
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> chart = ggplot(data, aes("wieght", "mpg")) + geom_point()
>>> try:
...     svg = chart.to_svg()
... except ColumnNotFoundError as error:
...     print(error.column, error.available)
wieght ['weight', 'mpg']

SpecError

SpecError(
    message: str, *, path: str = "", reason: str = ""
)

Bases: ggrust.errors.GgrustError, builtins.ValueError

Raised when the plot specification holds an invalid value.

Parameters:

  • message (str) –

    The full message, including the location.

  • path (str, default: "" ) –

    Spec path of the offending value, e.g. "layers[0].size" or "theme.axis_text.size"; empty when the error concerns the whole spec.

  • reason (str, default: "" ) –

    What was wrong and what is accepted, without the location.

Examples:

>>> from ggrust import *
>>> from ggrust.errors import SpecError
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> chart = ggplot(data, aes("weight", "mpg")) + geom_point(shape="star")
>>> try:
...     svg = chart.to_svg()
... except SpecError as error:
...     print(error.path)
layers[0].shape

UnsupportedValueError

UnsupportedValueError(
    message: str, *, path: str = "", reason: str = ""
)

Bases: ggrust.errors.SpecError, builtins.TypeError

Raised when a spec holds a value of a type the engine cannot receive.

Parameters:

  • message (str) –

    The full message, including the location.

  • path (str, default: "" ) –

    Spec path of the value.

  • reason (str, default: "" ) –

    What was wrong, without the location.

Examples:

>>> from ggrust import *
>>> from ggrust.errors import UnsupportedValueError
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> chart = ggplot(data, aes("weight", "mpg")) + geom_point(size=object())
>>> try:
...     svg = chart.to_svg()
... except UnsupportedValueError as error:
...     print(error.path)
layers[0].size

as_arrow

as_arrow(data: object) -> ArrowStreamExportable

Return data as an object exporting __arrow_c_stream__.

Parameters:

  • data (object) –

    A polars DataFrame or LazyFrame, pandas DataFrame, pyarrow Table, any table object exporting __arrow_c_stream__, or a mapping of column names to sequences / numpy arrays / Series.

Returns:

  • ArrowStreamExportable –

    data itself when it already exports Arrow, otherwise a polars DataFrame.

Raises:

  • TypeError –

    If data is a Series or none of the accepted kinds.

Notes

The pandas index is dropped, as lets-plot ignores it.

compare_means

compare_means(
    formula: str,
    data: PlotData,
    *,
    method: Literal = "wilcox.test",
    paired: bool = False,
    group_by: str | Sequence[str] | None = None,
    ref_group: str | None = None,
    p_adjust_method: Literal = "holm",
) -> pl.DataFrame

Test the groups of a column against each other and list the p-values.

As compare_means in the R package ggpubr. formula is "y ~ group": the values of y are split by the levels of group (their order of first appearance, or the categories of a polars Enum or pandas Categorical). Two-group tests ("wilcox.test", "t.test") compare every pair of levels, or each level with ref_group; "anova" and "kruskal.test" test all levels at once. With group_by, the tests run within each of its groups.

Parameters:

  • formula (str) –

    "response ~ group", two column names of data, e.g. "len ~ dose".

  • data (DataFrame or dict) –

    The data: polars, pandas, an Arrow table or a dict of columns.

  • method ((test, test, anova, test), default: "wilcox.test" ) –

    Wilcoxon rank sum (signed rank when paired), Welch's t test, one-way ANOVA or Kruskal-Wallis. ggpubr's aliases ("t", "wilcox", "aov", "kruskal", ...) work too.

  • paired (bool, default: False ) –

    Paired two-group tests; the values of two levels pair up in row order.

  • group_by (str or list of str, default: None ) –

    Columns to split the data by first; the result starts with them.

  • ref_group (str, default: None ) –

    A level to compare every other level with, or ".all." to compare each level with all values. Two-group tests only.

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

    Adjustment of p.adj over all rows (R p.adjust): "holm", "hochberg", "hommel", "bonferroni", "BH" (or "fdr"), "BY" or "none".

Returns:

  • DataFrame –

    One row per comparison: the group_by columns, .y. (the response name), group1 and group2 (level names, two-group tests only), p, p.adj (2 significant digits, as ggpubr), p.format (R's format.pval(p, digits = 2)), p.signif (**** <= 1e-4, *** <= 0.001, ** <= 0.01, * <= 0.05, else ns, from the unadjusted p) and method.

Raises:

  • SpecError –

    If the formula is malformed, an option is unknown, ref_group is not a level, or a test cannot run (constant values for a t test, paired levels of different sizes).

  • UnsupportedValueError –

    If an option has the wrong type.

  • ColumnNotFoundError –

    If a column is not in data.

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]}
>>> table = compare_means("weight ~ diet", data)
>>> table.select("group1", "group2", "p.format").rows()
[('veg', 'meat', '0.0043'), ('veg', 'fish', '0.092'), ('meat', 'fish', '0.0087')]
>>> plot = (ggplot(data, aes("diet", "weight")) + geom_boxplot()
...         + stat_pvalue_manual(table, label="p.signif", y_position=88, step_increase=0.1))

Welch's t tests of every other group against a reference group:

>>> table = compare_means("weight ~ diet", data, method="t.test", ref_group="veg")
>>> table.select("group1", "group2", "p.signif").rows()
[('veg', 'meat', '**'), ('veg', 'fish', 'ns')]
>>> plot = (ggplot(data, aes("diet", "weight")) + geom_boxplot()
...         + stat_pvalue_manual(table, label="p.adj", y_position=88, step_increase=0.1))

did_you_mean

did_you_mean(word: str, candidates: Iterable[str]) -> str

Return "; did you mean 'x'?" for the closest candidate, or "".

Same rule as the engine's suggestions: about one edit (insertion, deletion, substitution or swap of neighbours) per three letters, none for one- and two-letter words; case differences alone always match. No suggestion when several candidates are equally close or word starts several of them.

Parameters:

  • word (str) –

    The misspelt name.

  • candidates (iterable of str) –

    The accepted names.

Returns:

  • str –

    The suggestion, ready to append to a message.

format_r_numbers builtin

format_r_numbers(values, digits)

Numbers as R's format(x, digits) prints each (as.character with 15).

Welch's t tests of every other group against a reference group