This function performs the PERMANOVA test that can allow adjustment of
confounders and control of clustered data. It can also be used for testing
presence-absence associations based on infinite number of rarefaction replicates.
As in ldm,
permanovaFL allows multiple sets of covariates to be tested,
in the way that the sets are entered sequentially and the variance
explained by each set is that part that remains after the previous
sets have been fit. It allows testing of a survival outcome, by using the Martingale or deviance residual (from fitting a Cox model to the survival outcome and other covariates) as a covariate in the regression.
It allows multiple distance matrices and provides an omnibus test in such cases.
It also allows testing of the mediation effect of the microbiome in the pathway between the exposure(s) and the outcome(s),
where the exposure(s) and outcomes(s) are specified as the first and second (sets of) covariates.
permanovaFL(
formula,
other.surv.resid = NULL,
data = .GlobalEnv,
tree = NULL,
dist.method = c("bray"),
dist.list = NULL,
cluster.id = NULL,
strata = NULL,
how = NULL,
perm.within.type = "free",
perm.between.type = "none",
perm.within.ncol = 0,
perm.within.nrow = 0,
n.perm.max = 5000,
n.rej.stop = 100,
seed = NULL,
square.dist = TRUE,
center.dist = TRUE,
scale.otu.table = c(TRUE),
binary = c(FALSE),
n.rarefy = 0,
test.mediation = FALSE,
n.cores = 4,
verbose = TRUE
)a list consisting of
F statistics for testing each set of covariates
R-squared statistic for each set of covariates
F statistics and R-squared statistic when the last covariate is other.surv.resid
p-values for testing each set of covariates
the omnibus p-values (that combines information from multiple distance matrices) for testing each set of covariates
p-values for testing mediation
the omnibus p-values for testing mediation
when using other.surv.resid as the last covariate
when using other.surv.resid as the outcome in the mediation analysis
the combination test that combines the results from analyzing the Martingale residual and the Deviance residual (one specified in the formula and one specified in other.surv.resid)
the combination test for the mediation effect
number of permutations completed
a logical value indicating whether the stopping criterion has been met by all tests of covariates
the seed that is user supplied or internally generated, stored in case the user wants to reproduce the permutation replicates
a symbolic description of the model to be fitted in the form
of data.matrix ~ sets of covariates or data.matrix |
confounders ~ sets of covariates. The details of model specification are
given in "Details" of ldm. Additionally, in permanovaFL, the data.matrix
can be either an OTU table or a distance matrix. If it is an OTU table,
the distance matrix will be calculated internally using the OTU table, tree (if required), and
dist.method. If data.matrix is a distance
matrix (having class dist or matrix), it can be squared and//or centered by
specifying square.dist and center.dist (described below). Distance matrices are distinguished
from OTU tables by checking for symmetry of as.matrix(data.matrix).
a vector of data, usually the Martingale or deviance residuals from fitting the Cox model to the survival outcome (if it is the outcome of interest) and other covariates.
an optional data frame, list or environment (or object coercible
to a dataframe) containing the covariates of interest and confounding covariates.
If not found in data, the covariates are taken from environment(formula),
typically the environment from which permanovaFL is called. The default is .GlobalEnv.
a phylogenetic tree. Only used for calculating a
phylogenetic-tree-based distance matrix. Not needed if the calculation of
the requested distance does not involve a phylogenetic tree, or if a
distance matrix is directly imported through formula.
a vector of methods for calculating the distance measure, partial
match to all methods supported by vegdist in the vegan package
(i.e., "manhattan", "euclidean", "canberra", "bray", "kulczynski", "jaccard", "gower",
"altGower", "morisita", "horn", "mountford", "raup" , "binomial", "chao", "cao", "mahalanobis")
as well as "hellinger" and "wt-unifrac".
Not used if a distance matrix is specified in formula or dist.list.
The default is c("bray").
For more details, see the dist.method argument in the ldm function.
a list of pre-calculated distance matrices.
cluster identifiers. The default is value of NULL should be used if the observations are not in clusters (i.e., independent).
a factor variable (or, character variable converted into a factor) to define strata (groups), within which to constrain permutations. The default is NULL.
a permutation control list, for users who want to specify their permutation control list using the how function
from the permute R package. The default is NULL.
a character string that takes values "free", "none", "series", or "grid". The default is "free" (for random permutations).
a character string that takes values "free", "none", or "series". The default is "none".
a positive integer, only used if perm.within.type="grid".
The default is 0. See the documentation for the R package permute for further details.
a positive integer, only used if perm.within.type="grid".
The default is 0. See the documentation for the R package permute for further details.
the maximum number of permutations. The default is 5000.
the minimum number of rejections (i.e., the permutation statistic exceeds the observed statistic) to obtain before stopping. The default is 100.
a user-supplied integer seed for the random number generator in the permutation procedure. The default is NULL; with the default value, an integer seed will be generated internally and randomly. In either case, the integer seed will be stored in the output object in case the user wants to reproduce the permutation replicates.
a logical variable indicating whether to square the distance matrix. The default is TRUE.
a logical variable indicating whether to center the distance matrix as described by Gower (1966). The default is TRUE.
a vector of logical variables indicating whether to scale the OTU table in calculating the distance matrices in dist.method.
For count data, this corresponds to dividing by the library size to give
relative abundances. The default is TRUE.
a vector of logical values indicating whether to base the calculation of the distance matrices in dist.method on presence-absence (binary) data. The default is c(FALSE) (analyzing relative abundance data).
number of rarefactions. The default is 0 (no rarefaction).
a logical value indicating whether to perform the mediation analysis. The default is FALSE.
If TRUE, the formula takes the specific form otu.table ~ exposure + outcome or most generally
otu.table or distance matrix | (set of confounders) ~ (set of exposures) + (set of outcomes).
The number of cores to use in parallel computing, i.e., at most how many child processes will be run simultaneously. The default is 4.
a logical value indicating whether to generate verbose output during the permutation process. Default is TRUE.
Yi-Juan Hu <yijuan.hu@emory.edu>, Glen A. Satten <gsatten@emory.edu>
Hu YJ, Satten GA (2020). Testing hypotheses about the microbiome using the linear decomposition model (LDM) Bioinformatics, 36(14), 4106-4115.
Hu YJ and Satten GA (2021). A rarefaction-without-resampling extension of PERMANOVA for testing presence-absence associations in the microbiome. bioRxiv, https://doi.org/10.1101/2021.04.06.438671.
Zhu Z, Satten GA, Caroline M, and Hu YJ (2020). Analyzing matched sets of microbiome data using the LDM and PERMANOVA. Microbiome, 9(133), https://doi.org/10.1186/s40168-021-01034-9.
Hu Y, Li Y, Satten GA, and Hu YJ (2022) Testing microbiome associations with censored survival outcomes at both the community and individual taxon levels. bioRxiv, doi.org/10.1101/2022.03.11.483858.
res.perm <- permanovaFL(throat.otu.tab5 | (Sex+AntibioticUse) ~ SmokingStatus+PackYears,
data=throat.meta, dist.method="bray", seed=82955, n.perm.max=1000, n.cores=1,
verbose=FALSE)
Run the code above in your browser using DataLab