adjust.data.by.covariates {LDM}

Adjusting data (distance matrix and OTU table) by covariates

Description

This function produces adjusted distance matrix and OTU table (if provided) after removing the effects of covariates (e.g., confounders). Observations with any missing data are removed.

Usage

adjust.data.by.covariates(
  formula = NULL,
  data = .GlobalEnv,
  otu.table = NULL,
  tree = NULL,
  dist.method = "bray",
  binary = FALSE,
  dist = NULL,
  square.dist = TRUE,
  center.dist = TRUE,
  scale.otu.table = TRUE,
  center.otu.table = TRUE,
  freq.scale.only = FALSE
)

Arguments

formula

a symbolic description of the covariate model in the form ~ model, where model is specified in the same way as for lm or glm. For example, ~ a + b specifies a model with the main effects of covariates a and b, and ~ a*b, equivalently ~ a + b + a:b, specifies a model with the main effects of a and b as well as their interaction.

data

an optional data frame, list or environment (or object coercible by as.data.frame to a data frame) containing the covariates. If not found in data, the covariates are taken from environment (formula), typically the environment from which adjust.data.by.covariates is called. The default is .GlobalEnv.

otu.table

the n.obs by n.otu matrix of read counts. If provided, an adjusted (and column-centered) OTU table at the frequency (i.e., relative abundance) scale and an adjusted (and columnn-centered) OTU table at the arcsin-root-transformed frequency scale are output. If provided, it is also used for calculating the distance matrix unless the distance matrix is directly imported through dist. The default is NULL.

tree

a phylogenetic tree. Only used for calculating a phylogenetic-tree-based distance matrix. Not needed if the calculation of requested distance does not require a phylogenetic tree, or if the distance matrix is directly imported through dist. The default is NULL.

dist.method

method 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". The default is "bray". For more details, see the dist.method argument in the ldm function.

binary

the "binary" parameter in vegdist. The default is FALSE.

dist

a distance matrix. Can be either an object of class "dist" or "matrix". The elements of the distance matrix will be squared and then the matrix will be centered if the default choices square.dist=TRUE and center.dist=TRUE are used. If dist=NULL, the distance matrix is calculated from the otu.table, using the value of dist.method (and tree if required). The default is NULL.

square.dist

a logical variable indicating whether to square the distance matrix. The default is TRUE.

center.dist

a logical variable indicating whether to center the distance matrix as described by Gower (1966). The default is TRUE.

scale.otu.table

a logical variable indicating whether to scale the rows of the OTU table for the frequency scale. For count data, this corresponds to dividing by the library size to give relative frequencies. The default is TRUE.

center.otu.table

a logical variable indicating whether to center the columns of the OTU table. The OTU table should be centered if the distance matrix has been centered. Applied to both OTU tables at frequency and transformed scales. The default is TRUE.

freq.scale.only

a logical variable indicating whether to provide adjusted frequency-scale OTU table only (not adjusted OTU table at the arcsin-root transformed frequency scale). The default is FALSE.

Value

a list consisting of

adj.dist

the (squared/centered) distance matrix after adjustment of covariates.

y.freq

the (column-centered) frequency-scale OTU table after adjustment of covariates.

y.tran

the (column-centered) arcsin-root-transformed OTU table after adjustment of covariates.

Author(s)

Yi-Juan Hu <[e-mail]>, Glen A. Satten <[e-mail]>

Examples

adj.data <- adjust.data.by.covariates(formula= ~ Sex + AntibioticUse, data=throat.meta,
                                      otu.table=throat.otu.tab5, dist.method="bray")