Skip to content

Add multivariable PERMANOVA with covariates, strata and PERMDISP - #161

Merged
skennedy8 merged 1 commit into
masterfrom
permanova-covariates
Nov 14, 2026
Merged

skennedy8 merged 1 commit into
masterfrom
permanova-covariates

Conversation

@skennedy8

@skennedy8 skennedy8 commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Requested by Sean · project thread

Description

Adds a multivariable Permutational Multivariate Analysis of Variance (PERMANOVA) as a distance-based linear model in NumPy, following vegan::adonis2.

  • permanova_model() in moonstone/analysis/permanova.py: numeric and categorical terms; by="margin" (default, each term after all the others) or "terms" (sequential, Python only); strata restricts permutations within blocks; same seed, --threads, Benjamini-Hochberg correction and too-few-permutations warning as the existing screen. Results do not depend on sample order or thread count.
  • run_permanova(..., covariates, strata, categorical, by) reuses the taxonomic-level loop. With covariates or strata, the named variables plus covariates form one model and every term is reported (adds term_type and df columns). Without them, nothing changes.
  • Permutational Analysis of Multivariate Dispersions (PERMDISP) runs for each categorical term on the same samples; numeric terms show not applicable. It is one-factor and does not adjust for the other terms (documented). The PERMDISP call is now one shared helper in beta.py.
  • CLI: new flags --covariates and --strata with --permanova. --covariates and --categorical already existed for --associate and are reused; --select and --group_column now also work with --permanova (needed for one sample per patient in the example).
  • Docs: permanova.rst has the example files, the screen and model commands, and the quoted numbers. make_examples.py adds a batch column, drawn last from its own generator so the other example files are unchanged.

Changelogs

  • New permanova_model, extended run_permanova, --covariates/--strata for --permanova
  • R reference script and outputs in tests/reference/ (permanova_adonis2.R, generated with R 4.3.3 and vegan 2.6-4); CI does not need R

Issue(s)

Fixes #152

Tests

  • Against adonis2 (terms and margin, with and without strata): R2 and pseudo-F agree to 1e-8; p-values within Monte Carlo error.
  • PERMDISP against betadisper + permutest: F differs by 0.006 (three groups, F = 0.29) and 0.003 (two groups, F near 0), the scikit-bio negative-eigenvalue difference; recorded in the test and the user guide.
  • Single categorical term matches scikit-bio; strata never move a sample out of its block; order, seed and thread independence; missing values dropped and counted; collinearity and bad-input errors; documented commands reproduce the quoted numbers.
  • Full suite: 724 passed, 2 failed (test_to_dataframe_ods and _xls, unrelated: odfpy/xlrd are in requirements-dev, which was not installed). Docs build with -W clean.

Definition of Done

  • New code is tested with unit tests
  • Documentation has been updated

…DISP (#152)

Distance-based linear model in NumPy as in vegan::adonis2: marginal ("margin",
default) or sequential ("terms") tests, numeric and categorical terms, and
permutations restricted within strata. PERMDISP runs per categorical term
(not applicable for numeric terms). CLI: --covariates and --strata with
--permanova; --covariates/--categorical/--select are reused.

Checked against adonis2 and betadisper outputs saved in tests/reference/.
@skennedy8
skennedy8 force-pushed the permanova-covariates branch from 020ad00 to a60a284 Compare November 14, 2026 14:47
@codecov

codecov Bot commented Nov 14, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.00000% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.64%. Comparing base (dce31eb) to head (a60a284).

Files with missing lines Patch % Lines
moonstone/analysis/permanova.py 94.23% 3 Missing and 3 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #161      +/-   ##
==========================================
+ Coverage   91.58%   91.64%   +0.06%     
==========================================
  Files          73       73              
  Lines        5491     5603     +112     
  Branches      917      938      +21     
==========================================
+ Hits         5029     5135     +106     
- Misses        315      318       +3     
- Partials      147      150       +3     
Files with missing lines Coverage Δ
moonstone/analysis/diversity/beta.py 96.30% <100.00%> (+0.01%) ⬆️
moonstone/main.py 93.85% <100.00%> (+0.18%) ⬆️
moonstone/analysis/permanova.py 97.20% <94.23%> (-2.80%) ⬇️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@skennedy8
skennedy8 merged commit 8e8a490 into master Nov 14, 2026
6 checks passed
@skennedy8
skennedy8 deleted the permanova-covariates branch November 14, 2026 21:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Multivariable PERMANOVA with covariates and restricted permutations

2 participants