lm_meta: Covariate adjusted meta-analytical differential abundance...

In biobakery/MMUPHin: Meta-analysis Methods with Uniform Pipeline for Heterogeneity in Microbiome Studies

Covariate adjusted meta-analytical differential abundance testing

Description

lm_meta runs differential abundance models on microbial profiles within individual studies/batches, and aggregates per-batch effect sizes with a meta-analysis fixed/random effects model. It takes as input a feature-by-sample microbial abundance table and the accompanying meta data data frame which should includes the batch indicator variable, the main exposure variable for differential abundance testing, and optional covariates and random covariates. The function first runs Maaslin2 models on the exposure with optional covariates/random covariates in each batch. The per-batch effect sizes are then aggregated with rma.uni and reported as output. Additional parameters, including those for both Maaslin2 and rma.uni can be provided through control (see details).

Usage

lm_meta(
  feature_abd,
  batch,
  exposure,
  covariates = NULL,
  covariates_random = NULL,
  data,
  control
)

Arguments

feature_abd	feature-by-sample matrix of abundances (proportions or counts).
batch	name of the batch variable. This variable in data should be a factor variable and will be converted to so with a warning if otherwise.
exposure	name of the exposure variable for differential abundance testing.
covariates	names of covariates to adjust for in Maaslin2 differential abundance testing models.
covariates_random	names of random effects grouping covariates to adjust for in Maaslin2 differential abundance testing models.
data	data frame of metadata, columns must include exposure, batch, and covariates and covariates_random (if specified).
control	a named list of additional control parameters. See details.

Details

control should be provided as a named list of the following components (can be a subset).

normalization

character. normalization parameter for Maaslin2. See Maaslin2 for details and allowed values. Default to "TSS" (total sum scaling).

transform

character. transform parameter for Maaslin2. See Maaslin2 for details and allowed values. Default to "AST" (arcsine square root transformation).

analysis_method

character. analysis_method parameter for Maaslin2. See Maaslin2 for details and allowed values. Default to "LM" (linear modeling).

rma_method

character. method parameter for rma.uni. See rma.uni for details and allowed values. Default to "REML" (estricted maximum-likelihood estimator).

output

character. Output directory for intermediate Maaslin2 output and the optional forest plots. Default to "MMUPHin_lm_meta".

forest_plot

character. Suffix in the name for the generated forest plots visualizing significant meta-analyitical differential abundance effects. Default to "forest.pdf". Can be set to NULL in which case no output will be generated.

rma_conv

numeric. Convergence threshold for rma.uni (corresponds to control$threshold. See rma.uni for details. Default to 1e-4.

rma_maxit

integer. Maximum number of iterations allowed for rma.uni (corresponds to control$maxiter. See rma.uni for details. Default to 1000.

verbose

logical. Indicates whether or not verbose information will be printed.

Value

a list, with the following components:

meta_fits

data frame of per-feature meta-analyitical differential abundance results, including columns for effect sizes, p-values and q-values, heterogeneity statistics such as \tau^2 and I^2, as well as weights for individual batches. Many of these statistics are explained in detail in rma.uni.

maaslin_fits

list of data frames, each one corresponding to the fitted results of Maaslin2 in a individual batch. See Maaslin2 on details of these output.

control

list of additional control parameters used in the function call.

Author(s)

Siyuan Ma, [e-mail]

Examples

data("CRC_abd", "CRC_meta")
fit_meta <- lm_meta(feature_abd = CRC_abd,
                    exposure = "study_condition",
                    batch = "studyID",
                    covariates = c("gender", "age"),
                    data = CRC_meta)$meta_fits

biobakery/MMUPHin documentation built on March 30, 2024, 4:50 a.m.