lm_meta {MMUPHin} | R Documentation

## 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 `"LOG"` (log 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 τ^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, siyuanma@g.harvard.edu

### 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

[Package MMUPHin version 1.6.2 Index]