differentialTest {corncob}

Identify differentially-abundant and differentially-variable taxa

Description

Identify differentially-abundant and differentially-variable taxa

Usage

differentialTest(
  formula,
  phi.formula,
  formula_null,
  phi.formula_null,
  data,
  link = "logit",
  phi.link = "logit",
  test,
  boot = FALSE,
  B = 1000,
  sample_data = NULL,
  taxa_are_rows = TRUE,
  filter_discriminant = TRUE,
  fdr_cutoff = 0.05,
  fdr = "fdr",
  full_output = FALSE,
  inits = NULL,
  inits_null = NULL,
  try_only = NULL,
  verbose = FALSE,
  robust = FALSE,
  ...
)

Arguments

formula

an object of class formula without the response: a symbolic description of the model to be fitted to the abundance

phi.formula

an object of class formula without the response: a symbolic description of the model to be fitted to the dispersion

formula_null

Formula for mean under null, without response

phi.formula_null

Formula for overdispersion under null, without response

data

a data frame containing the OTU table, or phyloseq object containing the variables in the models

link

link function for abundance covariates, defaults to "logit"

phi.link

link function for dispersion covariates, defaults to "logit"

test

Character. Hypothesis testing procedure to use. One of "Wald", "LRT" (likelihood ratio test), or "Rao".

boot

Boolean. Defaults to FALSE. Indicator of whether or not to use parametric bootstrap algorithm. (See pbWald and pbLRT).

B

Optional integer. Number of bootstrap iterations. Ignored if boot is FALSE. Otherwise, defaults to 1000.

sample_data

Data frame or matrix. Defaults to NULL. If data is a data frame or matrix, this must be included as covariates/sample data.

taxa_are_rows

Boolean. Optional. If data is a data frame or matrix, this indicates whether taxa are rows. Defaults to TRUE.

filter_discriminant

Boolean. Defaults to TRUE. If FALSE, discriminant taxa will not be filtered out.

fdr_cutoff

Integer. Defaults to 0.05. Desired false discovery rate.

fdr

Character. Defaults to "fdr". False discovery rate control method, see p.adjust for more options.

full_output

Boolean. Opetional. Defaults to FALSE. Indicator of whether to include full bbdml model output for all taxa.

inits

Optional initializations for model fit using formula and phi.formula as rows of a matrix. Defaults to NULL.

inits_null

Optional initializations for model fit using formula_null and phi.formula_null as rows of a matrix. Defaults to NULL.

try_only

Optional numeric. Will try only the try_only taxa, specified either via numeric input or character taxa names. Useful for speed when troubleshooting. Defaults to NULL, testing all taxa.

verbose

Boolean. Defaults to FALSE; print status updates for long-running analyses

robust

Should robust standard errors be used? If not, model-based standard errors are used. Logical, defaults to FALSE.

...

Optional additional arguments for bbdml

Details

See package vignette for details and example usage. Make sure the number of columns in all of the initializations are correct! inits probably shouldn't match inits_null. To use a contrast matrix, see contrastsTest.

Value

An object of class differentialTest. List with elements p containing the p-values, p_fdr containing the p-values after false discovery rate control, significant_taxa containing the taxa names of the statistically significant taxa, significant_models containing a list of the model fits for the significant taxa, all_models containing a list of the model fits for all taxa, restrictions_DA containing a list of covariates that were tested for differential abundance, restrictions_DV containing a list of covariates that were tested for differential variability, discriminant_taxa_DA containing the taxa for which at least one covariate associated with the abundance was perfectly discriminant, discriminant_taxa_DV containing the taxa for which at least one covariate associated with the dispersion was perfectly discriminant, data containing the data used to fit the models. If full_output = TRUE, it will also include full_output, a list of all model output from bbdml.

Examples

# data frame example
data(soil_phylum_small_sample)
data(soil_phylum_small_otu)
da_analysis <- differentialTest(formula = ~ DayAmdmt,
                                phi.formula = ~ DayAmdmt,
                                formula_null = ~ 1,
                                phi.formula_null = ~ DayAmdmt,
                                test = "Wald", boot = FALSE,
                                data = soil_phylum_small_otu,
                                sample_data = soil_phylum_small_sample,
                                fdr_cutoff = 0.05,
                                try_only = 1:5)

# phyloseq example (only run if you have phyloseq installed)
## Not run: 
data_phylo <- phyloseq::phyloseq(phyloseq::sample_data(soil_phylum_small_sample),
phyloseq::otu_table(soil_phylum_small_otu, taxa_are_rows = TRUE))
da_analysis <- differentialTest(formula = ~ DayAmdmt,
                               phi.formula = ~ DayAmdmt,
                               formula_null = ~ 1,
                               phi.formula_null = ~ DayAmdmt,
                               test = "Wald", boot = FALSE,
                               data = data_phylo,
                               fdr_cutoff = 0.05,
                               try_only = 1:5)

## End(Not run)