permaBrioche is a statistical framework for confounding‑aware PERMANOVA and interpretable distance‑based effect‑size estimation in repeated‑measures and other blocked study designs. It is particularly motivated by microbiome and other high‑dimensional biological data, where subject‑level clustering and longitudinal sampling are common.
User manual || Tutorial || Forum
Citation:
1 Department of Statistics and Data Science, Cornell University, NY, USA
2 Harvard T. H. Chan School of Public Health, Boston, MA, USA
3 The Broad Institute of MIT and Harvard, Cambridge, MA, USA
permaBrioche is currently distributed via GitHub as part of the BioBakery ecosystem. To install the R package (including vignettes), run the following in R:
library(devtools) devtools::install_github( "biobakery/permabrioche", build_vignettes = TRUE)
browseVignettes("permabrioche")
The vignette contains:
* fully runnable examples
* detailed explanations of permutation schemes
* interpretation guidance for all effect sizes
permaBrioche requires two aligned objects:
- (a) Sample‑level metadata
A data.frame with one row per sample, containing at least:
* `subject` – repeated‑measures (blocking) ID
* `exposure` – the covariate of interest (e.g. binary treatment status or multi-level categorical factor)
* Sample Identifiers provided in one of two ways:
* row names that uniquely identify samples and are used when constructing the feature matrix, or
* a column containing unique sample IDs (specified via the `sample_id` argument, e.g. `sample_id = "sample"`)
Each subject may appear in multiple rows.
- (b) Feature matrix (`bugs`)
A matrix of features (e.g., taxa abundances):
- rows = samples
- (row names must use the same sample identifiers as the metadata)
- columns = features
With these two objects, we can create the distance matrix for permaBrioche:
- c) Distance matrix
Use vegdist to get a distance matrix with a chosen dissimilarity method:
library(vegan) dist_bc <- vegdist(bugs, method = "bray")
Depending on the method used, permaBrioche reports:
- PERMANOVA results
- pseudo‑ F statistic
- empirical permutation p‑value
- optional null‑centered R^2
Hájek distance‑based effect size:
- effect on the distance scale
- permutation‑based uncertainty
- optional decomposition into:
- location (mean / centroid shift)
- dispersion change in variability)