statannot

0.2.3 verified Fri May 01 auth: no python maintenance

A Python library to add statistical annotations (e.g., p-value brackets) on existing boxplots/barplots generated by seaborn. Current version 0.2.3, supports Python >=3.5. Maintenance mode; last release in 2020.

pip install statannot

Common errors

error from statannot import add_stat_annotation ImportError: cannot import name 'add_stat_annotation' ↓

cause The module name is 'statannot' (no 's' at the end). If the community fork 'statannotations' is installed, the import path differs.

fix

Install correct package: pip install statannot, then import from statannot (not statannotations).

error TypeError: add_stat_annotation() got an unexpected keyword argument 'pvalue_format' ↓

cause Using old argument name 'pvalue_format' which was renamed to 'text_format' in v0.2.0.

fix

Replace 'pvalue_format' with 'text_format' in the function call.

error ValueError: Invalid test name: t-test ↓

cause The 'test' parameter value is not an exact match to the supported test strings.

fix

Use a valid test string: 't-test_ind', 't-test_paired', 'Mann-Whitney', etc.

error Annotation appears incorrectly placed or off the chart ↓

cause The library does not automatically adjust y-limits. Annotations may be placed at y-values beyond the current axis limits.

fix

Manually set y-axis limits after adding annotations: ax.set_ylim(top=max_y + some_buffer).

Warnings

deprecated Library is in maintenance mode, no updates since 2020. Consider using statannotations (note the 's' at the end) which is actively maintained. ↓

fix Switch to statannotations: pip install statannotations, import from statannotations.

gotcha The 'box_pairs' parameter requires tuples of category names (strings) exactly as they appear in the data. Mismatched case or whitespace will silently produce no annotations. ↓

fix Ensure exact string matching of category names; use df['column'].unique() to verify.

breaking As of v0.2.0, the API changed: 'text_format' replaced 'pvalue_format' and 'verbose' parameter was added. If upgrading from <0.2.0, update function calls. ↓

fix Replace pvalue_format='star' with text_format='star'.

gotcha The 'test' parameter is case-sensitive. 't-test_ind' works, 't-test' does not. Incorrect values raise ValueError without a clear message. ↓

fix Use one of the supported tests: 't-test_ind', 't-test_paired', 'Mann-Whitney', 'Mann-Whitney-gt', 'Mann-Whitney-ls', 'Wilcoxon', 'Kruskal', 'ANOVA', 'Kruskal_Dunn'.

gotcha The 'comparisons_correction' parameter only accepts None or 'Bonferroni'. Using any other string will not raise an error but will be ignored. ↓

fix Use comparisons_correction=None or 'Bonferroni' only.

Imports

statannot
wrong
```
import statannot
```
correct
```
from statannot import add_stat_annotation
```
Direct import of the module does not expose the main function; use explicit import of add_stat_annotation.

Quickstart

Add statistical annotation (p-value brackets) to a seaborn boxplot.

import seaborn as sns
import matplotlib.pyplot as plt
from statannot import add_stat_annotation

df = sns.load_dataset("tips")
ax = sns.boxplot(x="day", y="total_bill", data=df)
add_stat_annotation(ax, data=df, x="day", y="total_bill",
                    test='t-test_ind', comparisons_correction=None,
                    box_pairs=[("Thur", "Fri"), ("Thur", "Sat")],
                    text_format='star', verbose=0)
plt.show()