bio-data-visualization-statistical-annotation

Version Compatibility

Reference examples tested with: ggpubr 0.6+, ggsignif 0.6+, rstatix 0.7+, statannotations 0.6+ (Python), seaborn 0.13+.

Before using code patterns, verify installed versions match. If versions differ:

• R: packageVersion('<pkg>') then ?function_name
• Python: pip show <package> then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Statistical Annotation

"Add p-values to my plot" -> Render pairwise group comparisons as brackets with the correct statistical test (parametric vs non-parametric, paired vs unpaired, independent vs nested), adjusted for multiple testing, with rendering of significance as either numerical p OR asterisks. The choices that matter: which test is appropriate for the data, what multiple-testing adjustment applies, and whether to show n.s. (non-significant) results.

• R: ggpubr::stat_compare_means, ggsignif::geom_signif, rstatix::t_test/wilcox_test
• Python: statannotations.Annotator, scipy.stats directly

The Single Most Important Modern Insight -- The Test Must Match the Data

Tool defaults are NOT data-appropriate. ggpubr::stat_compare_means(method='t.test') uses Welch's two-sample t-test assuming approximate normality and unequal variances. This is wrong when:

1. Data are non-normal and N is small (<30): use Mann-Whitney U (method='wilcox.test').
2. Data are paired: use paired t-test or paired Wilcoxon (paired = TRUE).
3. Comparing >2 groups: ANOVA / Kruskal-Wallis with post-hoc, not all-pairs t-test (multiple-testing penalty).
4. Data are nested (cells within patients, replicates within samples): linear mixed model, NOT pairwise test.

The bracket-and-asterisk visual is the same; the underlying statistics are not. Choose the test deliberately.

Decision Tree for Test Selection

Question	Recommended test	Function
2 unpaired groups, normal, N≥30	Welch t-test	t.test(), stat_compare_means(method='t.test')
2 unpaired groups, non-normal or small N	Mann-Whitney U (Wilcoxon rank-sum)	wilcox.test(), stat_compare_means(method='wilcox.test')
2 paired groups	Paired t-test OR Wilcoxon signed-rank	paired = TRUE
3+ groups, normal	One-way ANOVA + Tukey HSD post-hoc	aov(), TukeyHSD()
3+ groups, non-normal	Kruskal-Wallis + Dunn post-hoc	kruskal.test(), dunn.test()
Nested data (cells in patients)	Linear mixed model	lme4::lmer()
Time-course / repeated measures	Repeated-measures ANOVA OR LMM	nlme::lme()
Two-way factorial	Two-way ANOVA + interaction term	aov(y ~ a*b)
Survival / time-to-event	Log-rank, NOT t-test	survdiff()
Categorical outcome	Chi-square OR Fisher exact	chisq.test(), fisher.test()