statannotations

The statannotations.stats package provides the underlying statistical computation logic for the statannotations library. It is organized into several submodules that handle statistical tests, result encapsulation, and corrections for multiple comparisons.

Key submodules include:

• statannotations.stats.test: Contains the primary functions for performing statistical tests.
• statannotations.stats.StatTest: Defines the core classes/interfaces for statistical testing.
• statannotations.stats.StatResult: Handles the structured output and data containers for test results.
• statannotations.stats.ComparisonsCorrection: Provides mechanisms to correct p-values when performing multiple comparisons.
• statannotations.stats.utils: Contains utility functions supporting the statistical workflows.

You can install statannotations via PyPI, Conda, or by cloning the repository. To include optional dependencies for multiple testing corrections and testing, use the requirements file when installing from source.

# From PyPI
pip install statannotations

# From Conda (conda-forge channel)
conda install -c conda-forge statannotations

# From source (standard)
pip install .

# From source (with optional dependencies for multiple comparisons & testing)
pip install -r requirements.txt .

To use a custom statistical test with statannotations, you must first define a Python function that accepts two sets of data (arrays/sequences) and returns a result containing a test statistic and a p-value. This function can also accept arbitrary keyword arguments (**stats_params) which will be passed through to the underlying statistical method.

Example of a function that performs a t-test on log-transformed data:

import numpy as np
from scipy.stats import ttest_ind

def log_ttest(group_data1, group_data2, **stats_params):
    group_data1_log = np.log(group_data1)
    group_data2_log = np.log(group_data2)

    return ttest_ind(group_data1_log, group_data2_log, **stats_params)

When configuring an Annotator object, you can pass your custom StatTest instance to the .configure() method using the test parameter. This allows the annotator to use your custom logic for calculating significance between pairs.

Example usage:

annot = Annotator(<ax>, <pairs>)
annot.configure(test=custom_test, comparisons_correction=None,
                text_format='star')

Wrap your custom statistical function in a statannotations.stats.StatTest.StatTest object. This object requires three arguments:

1. func: Your custom function (e.g., log_ttest).
2. long_name: A descriptive string for the test (e.g., 'Log t-test').
3. short_name: A brief string used for labels or annotations (e.g., 'log-t').

from statannotations.stats.StatTest import StatTest

custom_long_name = 'Log t-test'
custom_short_name = 'log-t'
custom_func = log_ttest
custom_test = StatTest(custom_func, custom_long_name, custom_short_name)

The Annotator.configure() method allows you to customize how statistical tests and annotations are displayed. Key options include:

• test: The statistical test to perform (e.g., 'Mann-Whitney', 't-test_ind', 't-test_paired', 'Welch', 'Levene', 'Wilcoxon', 'Kruskal-Wallis', 'Brunner-Munzel').
• text_format: How the p-value is displayed (e.g., 'star', 'simple', or explicit p-values).
• loc: The location of the annotation (e.g., 'inside' or 'outside' the plot).
• correct_method: (Requires statsmodels) Method for multiple testing corrections (e.g., 'bonferroni', 'holm-bonferroni', 'fdr_bh', 'fdr_py').

You can also provide custom p-values directly to skip the statistical test while still applying multiple testing corrections.

To apply corrections like Bonferroni or Benjamini-Hochberg (BH), use the comparisons_correction argument in .configure().

• To replace the default * (ns) notation with just ns, set correction_format='replace'.
• To reset all configuration settings (including previously set tests and pairs) to defaults, call .reset_configuration().

# Using BH correction and replacing '(ns)' with 'ns'
annot.configure(comparisons_correction="BH", correction_format="replace")
annot.apply_and_annotate()

# Resetting configuration
annot.reset_configuration()

To only show significant results, use hide_non_significant=True in .configure(). You can also define specific significance thresholds and their corresponding text labels using pvalue_thresholds.

Example: pvalue_thresholds=[[1e-4, "****"], [1e-3, "***"], [1e-2, "**"], [0.05, "*"]].

annot.configure(
    hide_non_significant=True,
    pvalue_thresholds=[[1e-4, "****"], [1e-3, "***"], [1e-2, "**"], [0.05, "*"]]
)
annot.apply_and_annotate()

Use the loc parameter in .configure() to determine where annotations are drawn:

• loc='inside': Inside the plot area.
• loc='outside': On top of the plot area.

# Annotate inside the plot
annot.configure(test=None, loc='inside')
annot.set_pvalues([0.1, 0.1, 0.001])
annot.annotate()

To use statannotations, ensure your environment meets the following requirements:

• Python >= 3.8
• numpy >= 1.12.1
• seaborn >= 0.9
• matplotlib >= 2.2.2
• pandas >= 0.23.0
• scipy >= 1.1.0
• statsmodels (Optional: required for multiple testing corrections)

Integrated Statistical Tests

statannotations binds to scipy.stats methods for the following tests:

• Mann-Whitney
• t-test (independent and paired)
• Welch's t-test
• Levene test
• Wilcoxon test
• Kruskal-Wallis test
• Brunner-Munzel test

Multiple Testing Corrections

When statsmodels is installed, you can apply corrections via statsmodels.stats.multitest.multipletests:

• Bonferroni
• Holm-Bonferroni
• Benjamini-Hochberg
• Benjamini-Yekutieli