permdisp — n4m.stats.permdisp

Namespace: n4m.stats · Fully-qualified: n4m.stats.permdisp · Catalog id: diagnostics.permdisp

API surface

C ABI (ABI 2): n4m_stats_permdisp. Use the linked public header for the exact signature, configuration, and result handles.

R: no current source-verified entry point was found for this catalog method.

MATLAB / Octave: no current source-verified entry point was found for this catalog method.

Explanations

Bibliographic source

Anderson (2006), Distance-based tests for homogeneity of multivariate dispersions, Biometrics 62, 245–253, https://doi.org/10.1111/j.1541-0420.2005.00440.x.

Mathematical principle

Each row’s Euclidean distance \(z_i\) to its group centroid is computed, then a one-way ANOVA \(F\) compares the groups’ mean distances. As in vegan betadisper(type = "centroid") and permutest, the Monte Carlo test permutes the ANOVA residuals \(z_i-\bar z_{g(i)}\) over all rows, refits and counts permuted \(F\ge F_{obs}-\sqrt{\epsilon}\).

Appropriate uses

Reporting whether groups differ in spread, alongside a PERMANOVA whose location test is sensitive to dispersion differences.

Limits and validation

The residual-permutation test is approximate. Dispersion differences neither validate nor invalidate exchangeability or a PERMANOVA result. Only centroids are offered (not the spatial median variant). Inputs outside the supported numerical domain (nonzero \(|x|\) in \([2^{-256},2^{256}]\), max/min nonzero \(|x|\) at most \(2^{32}\)) return N4M_ERR_UNSUPPORTED before any computation. A pseudo-F is undefined only when its residual SS is exactly zero; otherwise it is published with a resolution ratio (a conservative first-order error estimate of the residual SS divided by it) and flagged numerically unresolved when that ratio is at least 1. Workloads above 250 million operations return N4M_ERR_UNSUPPORTED.

Implementation

The ABI-2 symbol n4m_stats_permdisp in n4m/metrics.h is implemented in cpp/src/c_api/c_api_preflight.cpp and wrapped in JS/WASM by statsPermdisp. SciPy f_oneway, scikit-bio permdisp and NumPy permutation counts are pinned in parity/fixtures/permanova_v1.json, checked by cpp/tests/test_permanova.cpp.

Sources and provenance

https://doi.org/10.1111/j.1541-0420.2005.00440.x; https://github.com/GBeurier/nirs4all-methods/blob/main/cpp/src/c_api/c_api_preflight.cpp; https://github.com/GBeurier/nirs4all-methods/blob/main/parity/fixtures/permanova_v1.json

Catalog note

PERMDISP (Anderson 2006) as vegan betadisper(type=’centroid’) + permutest: Euclidean distances to group centroids, one-way ANOVA F and a seeded Monte Carlo permutation of the ANOVA residuals (PCG64, numpy.random.default_rng parity). Reference gate shared with diagnostics.permanova (parity/fixtures/permanova_v1.json, cpp/tests/test_permanova.cpp).

See also: methods index.