# ancombc2: Analysis of Compositions of Microbiomes with Bias Correction... In FrederickHuangLin/ANCOMBC: Microbiome differential abudance and correlation analyses with bias correction

 ancombc2 R Documentation

## Analysis of Compositions of Microbiomes with Bias Correction 2 (ANCOM-BC2)

### Description

Determine taxa whose absolute abundances, per unit volume, of the ecosystem (e.g., gut) are significantly different with changes in the covariate of interest (e.g., group). The current version of `ancombc2` function implements Analysis of Compositions of Microbiomes with Bias Correction (ANCOM-BC2) in cross-sectional and repeated measurements data. In addition to the two-group comparison, ANCOM-BC2 also supports testing for continuous covariates and multi-group comparisons, including the global test, pairwise directional test, Dunnett's type of test, and trend test.

### Usage

```ancombc2(
data,
assay_name = "counts",
tax_level = NULL,
fix_formula,
rand_formula = NULL,
pseudo = 0,
pseudo_sens = TRUE,
prv_cut = 0.1,
lib_cut = 0,
s0_perc = 0.05,
group = NULL,
struc_zero = FALSE,
neg_lb = FALSE,
alpha = 0.05,
n_cl = 1,
verbose = FALSE,
global = FALSE,
pairwise = FALSE,
dunnet = FALSE,
trend = FALSE,
iter_control = list(tol = 0.01, max_iter = 20, verbose = FALSE),
em_control = list(tol = 1e-05, max_iter = 100),
lme_control = lme4::lmerControl(),
mdfdr_control = list(fwer_ctrl_method = "holm", B = 100),
trend_control = list(contrast = NULL, node = NULL, solver = "ECOS", B = 100)
)
```

### Arguments

 `data` the input data. A `phyloseq`, `SummarizedExperiment`, or `TreeSummarizedExperiment` object, which consists of a feature table (microbial count table), a sample metadata, a taxonomy table (optional), and a phylogenetic tree (optional). The row names of the metadata must match the sample names of the feature table, and the row names of the taxonomy table must match the taxon (feature) names of the feature table. See `?phyloseq::phyloseq`, `?SummarizedExperiment::SummarizedExperiment`, or `?TreeSummarizedExperiment::TreeSummarizedExperiment` for more details. It is highly recommended that the input data are in low taxonomic levels, such as OTU or species level, as the estimation of sampling fractions requires a large number of taxa. `assay_name` character. Name of the count table in the data object (only applicable if data object is a `(Tree)SummarizedExperiment`). Default is "counts". See `?SummarizedExperiment::assay` for more details. `tax_level` character. The taxonomic level of interest. The input data can be agglomerated at different taxonomic levels based on your research interest. Default is NULL, i.e., do not perform agglomeration, and the ANCOM-BC2 anlysis will be performed at the lowest taxonomic level of the input `data`. `fix_formula` the character string expresses how the microbial absolute abundances for each taxon depend on the fixed effects in metadata. `rand_formula` the character string expresses how the microbial absolute abundances for each taxon depend on the random effects in metadata. ANCOM-BC2 follows the `lmerTest` package in formulating the random effects. See `?lmerTest::lmer` for more details. Default is `NULL`. `p_adj_method` character. method to adjust p-values. Default is "holm". Options include "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", "none". See `?stats::p.adjust` for more details. `pseudo` numeric. Add pseudo-counts to the data. Default is 0 (no pseudo-count addition). `pseudo_sens` logical. Whether to perform the sensitivity analysis to the pseudo-count addition. Default is `TRUE`. See `Details` for a more comprehensive discussion on this sensitivity analysis. `prv_cut` a numerical fraction between 0 and 1. Taxa with prevalences less than `prv_cut` will be excluded in the analysis. For instance, suppose there are 100 samples, if a taxon has nonzero counts presented in less than 10 samples, it will not be further analyzed. Default is 0.10. `lib_cut` a numerical threshold for filtering samples based on library sizes. Samples with library sizes less than `lib_cut` will be excluded in the analysis. Default is 0, i.e. do not discard any sample. `s0_perc` a numerical fraction between 0 and 1. Inspired by Significance Analysis of Microarrays (SAM) methodology, a small positive constant is added to the denominator of ANCOM-BC2 test statistic corresponding to each taxon to avoid the significance due to extremely small standard errors, especially for rare taxa. This small positive constant is chosen as `s0_perc`-th percentile of standard error values for each fixed effect. Default is 0.05 (5th percentile). `group` character. The name of the group variable in metadata. `group` should be discrete. Specifying `group` is required for detecting structural zeros and performing multi-group comparisons (global test, pairwise directional test, Dunnett's type of test, and trend test). Default is NULL. If the `group` of interest contains only two categories, leave it as NULL. `struc_zero` logical. Whether to detect structural zeros based on `group`. Default is FALSE. See `Details` for a more comprehensive discussion on structural zeros. `neg_lb` logical. Whether to classify a taxon as a structural zero using its asymptotic lower bound. Default is FALSE. `alpha` numeric. Level of significance. Default is 0.05. `n_cl` numeric. The number of nodes to be forked. For details, see `?parallel::makeCluster`. Default is 1 (no parallel computing). `verbose` logical. Whether to generate verbose output during the ANCOM-BC2 fitting process. Default is FALSE. `global` logical. Whether to perform the global test. Default is FALSE. `pairwise` logical. Whether to perform the pairwise directional test. Default is FALSE. `dunnet` logical. Whether to perform the Dunnett's type of test. Default is FALSE. `trend` logical. Whether to perform trend test. Default is FALSE. `iter_control` a named list of control parameters for the iterative MLE or RMEL algorithm, including 1) `tol`: the iteration convergence tolerance (default is 1e-02), 2) `max_iter`: the maximum number of iterations (default is 20), and 3)`verbose`: whether to show the verbose output (default is FALSE). `em_control` a named list of control parameters for the E-M algorithm, including 1) `tol`: the iteration convergence tolerance (default is 1e-05) and 2) `max_iter`: the maximum number of iterations (default is 100). `lme_control` a list of control parameters for mixed model fitting. See `?lme4::lmerControl` for details. `mdfdr_control` a named list of control parameters for mixed directional false discover rate (mdFDR), including 1) `fwer_ctrl_method`: family wise error (FWER) controlling procedure, such as "holm", "hochberg", "bonferroni", etc (default is "holm") and 2) `B`: the number of bootstrap samples (default is 100). Increase `B` will lead to a more accurate p-values. See `Details` for a more comprehensive discussion on mdFDR. `trend_control` a named list of control parameters for the trend test, including 1) `contrast`: the list of contrast matrices for constructing inequalities, 2) `node`: the list of positions for the nodal parameter, 3) `solver`: a string indicating the solver to use (default is "ECOS"), and 4) `B`: the number of bootstrap samples (default is 100). Increase `B` will lead to a more accurate p-values. See `vignette` for the corresponding trend test examples.

### Details

A taxon is considered to have structural zeros in some (>=1) groups if it is completely (or nearly completely) missing in these groups. For instance, suppose there are three groups: g1, g2, and g3. If the counts of taxon A in g1 are 0 but nonzero in g2 and g3, then taxon A will be considered to contain structural zeros in g1. In this example, taxon A is declared to be differentially abundant between g1 and g2, g1 and g3, and consequently, it is globally differentially abundant with respect to this group variable. Such taxa are not further analyzed using ANCOM-BC2, but the results are summarized in the overall summary. For more details about the structural zeros, please go to the ANCOM-II paper. Setting `neg_lb = TRUE` indicates that you are using both criteria stated in section 3.2 of ANCOM-II to detect structural zeros; otherwise, the algorithm will only use the equation 1 in section 3.2 for declaring structural zeros. Generally, it is recommended to set `neg_lb = TRUE` when the sample size per group is relatively large (e.g. > 30).

Like other differential abundance analysis methods, ANCOM-BC2 log transforms the observed counts. However, to deal with zero counts, a pseudo-count is added before the log transformation. Several studies have shown that differential abundance results could be sensitive to the choice of pseudo-count (Costea et al. (2014); Paulson, Bravo, and Pop (2014)), resulting in an inflated false positive rate. To avoid such false positives, we conduct a sensitivity analysis and provide a sensitivity score for each taxon to determine if a particular taxon is sensitive to the choice of pseudo-count. The larger the score, the more likely the significant result is a false positive.

When performning pairwise directional (or Dunnett's type of) test, the mixed directional false discover rate (mdFDR) should be taken into account. The mdFDR is the combination of false discovery rate due to multiple testing, multiple pairwise comparisons, and directional tests within each pairwise comparison. For example, suppose we have five taxa and three experimental groups: g1, g2, and g3. Thus, we are performing five tests corresponding to five taxa. For each taxon, we are also conducting three pairwise comparisons (g1 vs. g2, g2 vs. g3, and g1 vs. g3). Within each pairwise comparison, we wish to determine if the abundance has increased or decreased or did not change (direction of the effect size). Errors could occur in each step. The overall false discovery rate is controlled by the mdFDR methodology we adopted from Guo, Sarkar, and Peddada (2010) and Grandhi, Guo, and Peddada (2016).

### Value

a `list` with components:

• `feature_table`, a `data.frame` of pre-processed (based on `prv_cut` and `lib_cut`) microbial count table.

• `zero_ind`, a logical `data.frame` with TRUE indicating the taxon is detected to contain structural zeros in some specific groups.

• `samp_frac`, a numeric vector of estimated sampling fractions in log scale (natural log).

• `delta_em`, estimated sample-specific biases through E-M algorithm.

• `delta_wls`, estimated sample-specific biases through weighted least squares (WLS) algorithm.

• `pseudo_sens_tab`, the results of sensitivity analysis for the pseudo-count addition.

• `res`, a `data.frame` containing ANCOM-BC2 primary result:

• columns started with `lfc`: log fold changes obtained from the ANCOM-BC2 log-linear (natural log) model.

• columns started with `se`: standard errors (SEs) of `lfc`.

• columns started with `W`: test statistics. `W = lfc/se`.

• columns started with `p`: p-values. P-values are obtained from two-sided Z-test using the test statistic `W`.

• columns started with `q`: adjusted p-values. Adjusted p-values are obtained by applying `p_adj_method` to `p`.

• columns started with `diff`: TRUE if the taxon is significant (has `q` less than `alpha`).

• `res_global`, a `data.frame` containing ANCOM-BC2 global test result for the variable specified in `group`, each column is:

• `W`, test statistics.

• `p_val`, p-values, which are obtained from two-sided Chi-square test using `W`.

• `q_val`, adjusted p-values. Adjusted p-values are obtained by applying `p_adj_method` to `p_val`.

• `diff_abn`, A logical vector. TRUE if the taxon has `q_val` less than `alpha`.

• `res_pair`, a `data.frame` containing ANCOM-BC2 pairwise directional test result for the variable specified in `group`:

• columns started with `lfc`: log fold changes.

• columns started with `se`: standard errors (SEs).

• columns started with `W`: test statistics.

• columns started with `p`: p-values.

• columns started with `q`: adjusted p-values.

• columns started with `diff`: TRUE if the taxon is significant (has `q` less than `alpha`).

• `res_dunn`, a `data.frame` containing ANCOM-BC2 Dunnett's type of test result for the variable specified in `group`:

• columns started with `lfc`: log fold changes.

• columns started with `se`: standard errors (SEs).

• columns started with `W`: test statistics.

• columns started with `p`: p-values.

• columns started with `q`: adjusted p-values.

• columns started with `diff`: TRUE if the taxon is significant (has `q` less than `alpha`).

• `res_trend`, a `data.frame` containing ANCOM-BC2 trend test result for the variable specified in `group`:

• columns started with `lfc`: log fold changes.

• columns started with `se`: standard errors (SEs).

• `W`: test statistics.

• `p_val`: p-values.

• `q_val`: adjusted p-values.

• `diff_abn`: TRUE if the taxon is significant (has `q` less than `alpha`).

Huang Lin

### References

\insertRef

kaul2017analysisANCOMBC

\insertRef

lin2020analysisANCOMBC

\insertRef

tusher2001significanceANCOMBC

\insertRef

costea2014fairANCOMBC

\insertRef

\insertRef

guo2010controllingANCOMBC

\insertRef

grandhi2016multipleANCOMBC

`ancom` `ancombc`

### Examples

```#===========Build a TreeSummarizedExperiment Object from Scratch=============
library(mia)

# microbial count table
otu_mat = matrix(sample(1:100, 100, replace = TRUE), nrow = 10, ncol = 10)
rownames(otu_mat) = paste0("taxon", 1:nrow(otu_mat))
colnames(otu_mat) = paste0("sample", 1:ncol(otu_mat))
assays = SimpleList(counts = otu_mat)

smd = data.frame(group = sample(LETTERS[1:4], size = 10, replace = TRUE),
row.names = paste0("sample", 1:ncol(otu_mat)),
stringsAsFactors = FALSE)
smd = DataFrame(smd)

# taxonomy table
tax_tab = matrix(sample(letters, 70, replace = TRUE),
nrow = nrow(otu_mat), ncol = 7)
rownames(tax_tab) = rownames(otu_mat)
colnames(tax_tab) = c("Kingdom", "Phylum", "Class", "Order",
"Family", "Genus", "Species")
tax_tab = DataFrame(tax_tab)

# create TSE
tse = TreeSummarizedExperiment(assays = assays,
colData = smd,
rowData = tax_tab)

# convert TSE to phyloseq
pseq = makePhyloseqFromTreeSummarizedExperiment(tse)

#=======================Run ANCOMBC2 Using a Real Data=======================
library(ANCOMBC)
data(dietswap)

colData(dietswap)\$bmi_group = factor(colData(dietswap)\$bmi_group,
levels = c("obese",
"overweight",
"lean"))

set.seed(123)
# Note that setting pseudo_sens = FALSE, max_iter = 1, and B = 1 is
# only for the sake of speed
# Set pseudo_sens = TRUE, and use default or larger values for max_iter and B
# for better performance
out = ancombc2(data = dietswap, assay_name = "counts", tax_level = "Phylum",
fix_formula = "nationality + timepoint + bmi_group",
rand_formula = "(timepoint | subject)",
p_adj_method = "holm", pseudo = 0, pseudo_sens = FALSE,
prv_cut = 0.10, lib_cut = 1000, s0_perc = 0.05,
group = "bmi_group", struc_zero = TRUE, neg_lb = TRUE,
alpha = 0.05, n_cl = 1, verbose = TRUE,
global = TRUE, pairwise = TRUE, dunnet = TRUE, trend = TRUE,
iter_control = list(tol = 1e-2, max_iter = 1, verbose = TRUE),
em_control = list(tol = 1e-5, max_iter = 1),
lme_control = lme4::lmerControl(),
mdfdr_control = list(fwer_ctrl_method = "holm", B = 1),
trend_control = list(contrast =
list(matrix(c(1, 0, -1, 1),
nrow = 2,
byrow = TRUE)),
node = list(2),
solver = "ECOS",
B = 1))
res_prim = out\$res
res_global = out\$res_global
res_pair = out\$res_pair
res_dunn = out\$res_dunn
res_trend = out\$res_trend

```

FrederickHuangLin/ANCOMBC documentation built on Feb. 23, 2023, 11:13 p.m.
{"ft_lang_label":"__label__en","ft_lang_prob":0.7314927,"math_prob":0.95220494,"size":12098,"snap":"2023-14-2023-23","text_gpt3_token_len":3198,"char_repetition_ratio":0.11038531,"word_repetition_ratio":0.1489011,"special_character_ratio":0.25334767,"punctuation_ratio":0.16930233,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9798446,"pos_list":[0],"im_url_duplicate_count":[null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2023-03-23T23:18:42Z\",\"WARC-Record-ID\":\"<urn:uuid:8deeb912-939e-463e-a95a-73581c95199f>\",\"Content-Length\":\"46978\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:0f55299f-4007-4779-8afa-041464848a14>\",\"WARC-Concurrent-To\":\"<urn:uuid:efe58c48-269a-4501-8acb-a901bbcb8e3b>\",\"WARC-IP-Address\":\"51.81.83.12\",\"WARC-Target-URI\":\"https://rdrr.io/github/FrederickHuangLin/ANCOMBC/man/ancombc2.html\",\"WARC-Payload-Digest\":\"sha1:BIANOGOGHJP2EJLQIDMN76JYMCKBEVUH\",\"WARC-Block-Digest\":\"sha1:I2RJKZWS7D622H3BDLERN6TESTF75PCW\",\"WARC-Identified-Payload-Type\":\"text/html\",\"warc_filename\":\"/cc_download/warc_2023/CC-MAIN-2023-14/CC-MAIN-2023-14_segments_1679296945218.30_warc_CC-MAIN-20230323225049-20230324015049-00204.warc.gz\"}"}