# ANCOM-BC Tutorial

#### Huang Lin\(^1\)

#### \(^1\)NIEHS, Research Triangle Park, NC 27709, USA

#### April 30, 2024

    knitr::opts_chunk$set(message = FALSE, warning = FALSE, comment = NA,
                          fig.width = 6.25, fig.height = 5)
    library(ANCOMBC)
    library(tidyverse)
    library(DT)
    options(DT.options = list(
      initComplete = JS("function(settings, json) {",
      "$(this.api().table().header()).css({'background-color':
      '#000', 'color': '#fff'});","}")))

# 1. Introduction

Analysis of Compositions of Microbiomes with Bias Correction (ANCOM-BC) (Lin and Peddada 2020) is a methodology of differential abundance (DA) analysis for microbial absolute abundances. ANCOM-BC estimates the unknown sampling fractions, corrects the bias induced by their differences through a log linear regression model including the estimated sampling fraction as an offset terms, and identifies taxa that are differentially abundant according to the variable of interest. For more details, please refer to the ANCOM-BC paper.

# 2. Installation

Download package.

    if (!requireNamespace("BiocManager", quietly = TRUE))
        install.packages("BiocManager")
    BiocManager::install("ANCOMBC")

Load the package.

    library(ANCOMBC)

# 3. Example Data

The HITChip Atlas dataset contains genus-level microbiota profiling with HITChip for 1006 western adults with no reported health complications, reported in (Lahti et al. 2014). The dataset is available via the microbiome R package (Lahti et al. 2017) in phyloseq (McMurdie and Holmes 2013) format. In this tutorial, we consider the following covariates:

- Continuous covariates: “age”

- Categorical covariates: “region”, “bmi”

- The group variable of interest: “bmi”

  - Three groups: “lean”, “overweight”, “obese”

  - The reference group: “obese”

    data(atlas1006, package = "microbiome")
    tse = mia::makeTreeSummarizedExperimentFromPhyloseq(atlas1006)

    # subset to baseline
    tse = tse[, tse$time == 0]

    # Re-code the bmi group
    tse$bmi = recode(tse$bmi_group,
                     obese = "obese",
                     severeobese = "obese",
                     morbidobese = "obese")
    # Subset to lean, overweight, and obese subjects
    tse = tse[, tse$bmi %in% c("lean", "overweight", "obese")]

    # Note that by default, levels of a categorical variable in R are sorted
    # alphabetically. In this case, the reference level for `bmi` will be
    # `lean`. To manually change the reference level, for instance, setting `obese`
    # as the reference level, use:
    tse$bmi = factor(tse$bmi, levels = c("obese", "overweight", "lean"))
    # You can verify the change by checking:
    # levels(sample_data(tse)$bmi)

    # Create the region variable
    tse$region = recode(as.character(tse$nationality),
                        Scandinavia = "NE", UKIE = "NE", SouthEurope = "SE",
                        CentralEurope = "CE", EasternEurope = "EE",
                        .missing = "unknown")

    # Discard "EE" as it contains only 1 subject
    # Discard subjects with missing values of region
    tse = tse[, ! tse$region %in% c("EE", "unknown")]

    print(tse)

    class: TreeSummarizedExperiment
    dim: 130 873
    metadata(0):
    assays(1): counts
    rownames(130): Actinomycetaceae Aerococcus ... Xanthomonadaceae
      Yersinia et rel.
    rowData names(3): Phylum Family Genus
    colnames(873): Sample-1 Sample-2 ... Sample-1005 Sample-1006
    colData names(12): age sex ... bmi region
    reducedDimNames(0):
    mainExpName: NULL
    altExpNames(0):
    rowLinks: NULL
    rowTree: NULL
    colLinks: NULL
    colTree: NULL

# 4 ANCOM-BC Implementation

## 4.1 Run ancombc function

    out = ancombc(data = tse, assay_name = "counts",
                  tax_level = "Family", phyloseq = NULL,
                  formula = "age + region + bmi",
                  p_adj_method = "holm", prv_cut = 0.10, lib_cut = 1000,
                  group = "bmi", struc_zero = TRUE, neg_lb = TRUE, tol = 1e-5,
                  max_iter = 100, conserve = TRUE, alpha = 0.05, global = TRUE,
                  n_cl = 1, verbose = TRUE)

    res = out$res
    res_global = out$res_global

    # ancombc also supports importing data in phyloseq format
    # tse_alt = agglomerateByRank(tse, "Family")
    # pseq = makePhyloseqFromTreeSummarizedExperiment(tse_alt)
    # out = ancombc(data = NULL, assay_name = NULL,
    #               tax_level = "Family", phyloseq = pseq,
    #               formula = "age + region + bmi",
    #               p_adj_method = "holm", prv_cut = 0.10, lib_cut = 1000,
    #               group = "region", struc_zero = TRUE, neg_lb = TRUE, tol = 1e-5,
    #               max_iter = 100, conserve = TRUE, alpha = 0.05, global = TRUE,
    #               n_cl = 1, verbose = TRUE)

## 4.2 ANCOMBC primary result

Result from the ANCOM-BC log-linear model to determine taxa that are differentially abundant according to the covariate of interest. It contains: 1) log fold changes; 2) standard errors; 3) test statistics; 4) p-values; 5) adjusted p-values; 6) indicators whether the taxon is differentially abundant (TRUE) or not (FALSE).

### LFC

    tab_lfc = res$lfc
    col_name = c("Taxon", "Intercept", "Age", "NE - CE", "SE - CE",
                 "US - CE", "Overweight - Obese", "Lean - Obese")
    colnames(tab_lfc) = col_name
    tab_lfc %>%
      datatable(caption = "Log Fold Changes from the Primary Result") %>%
      formatRound(col_name[-1], digits = 2)

### SE

    tab_se = res$se
    colnames(tab_se) = col_name
    tab_se %>%
      datatable(caption = "SEs from the Primary Result") %>%
      formatRound(col_name[-1], digits = 2)

### Test statistic

    tab_w = res$W
    colnames(tab_w) = col_name
    tab_w %>%
      datatable(caption = "Test Statistics from the Primary Result") %>%
      formatRound(col_name[-1], digits = 2)

### P-values

    tab_p = res$p_val
    colnames(tab_p) = col_name
    tab_p %>%
      datatable(caption = "P-values from the Primary Result") %>%
      formatRound(col_name[-1], digits = 2)

### Adjusted p-values

    tab_q = res$q
    colnames(tab_q) = col_name
    tab_q %>%
      datatable(caption = "Adjusted p-values from the Primary Result") %>%
      formatRound(col_name[-1], digits = 2)

### Differentially abundant taxa

    tab_diff = res$diff_abn
    colnames(tab_diff) = col_name
    tab_diff %>%
      datatable(caption = "Differentially Abundant Taxa from the Primary Result")

### Bias-corrected abundances

To obtain bias-corrected abundances, the following steps can be taken:

Step 1: Calculate the estimated sample-specific sampling fractions, in log scale.

Step 2: Correct the log observed abundances by subtracting the estimated sampling fraction from the log observed abundances of each sample.

It is important to note that we can only estimate sampling fractions up to an additive constant, meaning that only the difference between bias-corrected abundances is meaningful. Additionally, taxon-specific biases are not taken into account in the calculation of bias-corrected abundances, as it is assumed that these biases vary across taxa but remain constant across samples within a taxon.

    samp_frac = out$samp_frac
    # Replace NA with 0
    samp_frac[is.na(samp_frac)] = 0
    # Add pesudo-count (1) to avoid taking the log of 0
    log_obs_abn = log(out$feature_table + 1)
    # Adjust the log observed abundances
    log_corr_abn = t(t(log_obs_abn) - samp_frac)
    # Show the first 6 samples
    round(log_corr_abn[, 1:6], 2) %>%
      datatable(caption = "Bias-corrected log observed abundances")

### Visualization for age

    df_lfc = data.frame(res$lfc[, -1] * res$diff_abn[, -1], check.names = FALSE) %>%
        mutate(taxon_id = res$diff_abn$taxon) %>%
        dplyr::select(taxon_id, everything())
    df_se = data.frame(res$se[, -1] * res$diff_abn[, -1], check.names = FALSE) %>%
      mutate(taxon_id = res$diff_abn$taxon) %>%
        dplyr::select(taxon_id, everything())
    colnames(df_se)[-1] = paste0(colnames(df_se)[-1], "SE")

    df_fig_age = df_lfc %>%
      dplyr::left_join(df_se, by = "taxon_id") %>%
      dplyr::transmute(taxon_id, age, ageSE) %>%
      dplyr::filter(age != 0) %>%
      dplyr::arrange(desc(age)) %>%
      dplyr::mutate(direct = ifelse(age > 0, "Positive LFC", "Negative LFC"))
    df_fig_age$taxon_id = factor(df_fig_age$taxon_id, levels = df_fig_age$taxon_id)
    df_fig_age$direct = factor(df_fig_age$direct,
                            levels = c("Positive LFC", "Negative LFC"))

    p_age = ggplot(data = df_fig_age,
               aes(x = taxon_id, y = age, fill = direct, color = direct)) +
      geom_bar(stat = "identity", width = 0.7,
               position = position_dodge(width = 0.4)) +
      geom_errorbar(aes(ymin = age - ageSE, ymax = age + ageSE), width = 0.2,
                    position = position_dodge(0.05), color = "black") +
      labs(x = NULL, y = "Log fold change",
           title = "Log fold changes as one unit increase of age") +
      scale_fill_discrete(name = NULL) +
      scale_color_discrete(name = NULL) +
      theme_bw() +
      theme(plot.title = element_text(hjust = 0.5),
            panel.grid.minor.y = element_blank(),
            axis.text.x = element_text(angle = 60, hjust = 1))
    p_age

### Visualization for BMI

    df_fig_bmi = df_lfc %>%
      filter(bmioverweight != 0 | bmilean != 0) %>%
      transmute(taxon_id,
                `Overweight vs. Obese` = round(bmioverweight, 2),
                `Lean vs. Obese` = round(bmilean, 2)) %>%
      pivot_longer(cols = `Overweight vs. Obese`:`Lean vs. Obese`,
                   names_to = "group", values_to = "value") %>%
      arrange(taxon_id)
    lo = floor(min(df_fig_bmi$value))
    up = ceiling(max(df_fig_bmi$value))
    mid = (lo + up)/2
    p_bmi = df_fig_bmi %>%
      ggplot(aes(x = group, y = taxon_id, fill = value)) +
      geom_tile(color = "black") +
      scale_fill_gradient2(low = "blue", high = "red", mid = "white",
                           na.value = "white", midpoint = mid, limit = c(lo, up),
                           name = NULL) +
      geom_text(aes(group, taxon_id, label = value), color = "black", size = 4) +
      labs(x = NULL, y = NULL, title = "Log fold changes as compared to obese subjects") +
      theme_minimal() +
      theme(plot.title = element_text(hjust = 0.5))
    p_bmi

## 4.3 ANCOMBC global test result

Result from the ANCOM-BC global test to determine taxa that are differentially abundant between at least two groups across three or more different groups. In this example, we want to identify taxa that are differentially abundant between at least two regions across CE, NE, SE, and US. The result contains: 1) test statistics; 2) p-values; 3) adjusted p-values; 4) indicators whether the taxon is differentially abundant (TRUE) or not (FALSE).

### Test statistics

    tab_w = res_global[, c("taxon", "W")]
    tab_w %>% datatable(caption = "Test Statistics
                        from the Global Test Result") %>%
          formatRound(c("W"), digits = 2)

### P-values

    tab_p = res_global[, c("taxon", "p_val")]
    tab_p %>% datatable(caption = "P-values
                        from the Global Test Result") %>%
          formatRound(c("p_val"), digits = 2)

### Adjusted p-values

    tab_q = res_global[, c("taxon", "q_val")]
    tab_q %>% datatable(caption = "Adjusted p-values
                        from the Global Test Result") %>%
          formatRound(c("q_val"), digits = 2)

### Differentially abundant taxa

    tab_diff = res_global[, c("taxon", "diff_abn")]
    tab_diff %>% datatable(caption = "Differentially Abundant Taxa
                           from the Global Test Result")

### Visualization

    sig_taxa = res_global %>%
      dplyr::filter(diff_abn == TRUE) %>%
      .$taxon

    df_bmi = tab_lfc %>%
        dplyr::select(Taxon, `Overweight - Obese`, `Lean - Obese`) %>%
        filter(Taxon %in% sig_taxa)

    df_heat = df_bmi %>%
        pivot_longer(cols = -one_of("Taxon"),
                     names_to = "region", values_to = "value") %>%
        mutate(value = round(value, 2))
    df_heat$Taxon = factor(df_heat$Taxon, levels = sort(sig_taxa))

    lo = floor(min(df_heat$value))
    up = ceiling(max(df_heat$value))
    mid = (lo + up)/2
    p_heat = df_heat %>%
      ggplot(aes(x = region, y = Taxon, fill = value)) +
      geom_tile(color = "black") +
      scale_fill_gradient2(low = "blue", high = "red", mid = "white",
                           na.value = "white", midpoint = mid, limit = c(lo, up),
                           name = NULL) +
      geom_text(aes(region, Taxon, label = value), color = "black", size = 4) +
      labs(x = NULL, y = NULL,
           title = "Log fold changes for globally significant taxa") +
      theme_minimal() +
      theme(plot.title = element_text(hjust = 0.5))
    p_heat

# Session information

    sessionInfo()

    R version 4.4.0 beta (2024-04-14 r86421)
    Platform: x86_64-apple-darwin20
    Running under: macOS Monterey 12.7.1

    Matrix products: default
    BLAS:   /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRblas.0.dylib
    LAPACK: /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0

    locale:
    [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

    time zone: America/New_York
    tzcode source: internal

    attached base packages:
    [1] stats     graphics  grDevices utils     datasets  methods   base

    other attached packages:
     [1] doRNG_1.8.6     rngtools_1.5.2  foreach_1.5.2   DT_0.33
     [5] phyloseq_1.48.0 lubridate_1.9.3 forcats_1.0.0   stringr_1.5.1
     [9] dplyr_1.1.4     purrr_1.0.2     readr_2.1.5     tidyr_1.3.1
    [13] tibble_3.2.1    ggplot2_3.5.1   tidyverse_2.0.0 ANCOMBC_2.6.0

    loaded via a namespace (and not attached):
      [1] splines_4.4.0                   cellranger_1.1.0
      [3] rpart_4.1.23                    DirichletMultinomial_1.46.0
      [5] lifecycle_1.0.4                 Rdpack_2.6
      [7] doParallel_1.0.17               lattice_0.22-6
      [9] MASS_7.3-60.2                   crosstalk_1.2.1
     [11] MultiAssayExperiment_1.30.0     backports_1.4.1
     [13] magrittr_2.0.3                  Hmisc_5.1-2
     [15] sass_0.4.9                      rmarkdown_2.26
     [17] jquerylib_0.1.4                 yaml_2.3.8
     [19] gld_2.6.6                       DBI_1.2.2
     [21] minqa_1.2.6                     ade4_1.7-22
     [23] multcomp_1.4-25                 abind_1.4-5
     [25] zlibbioc_1.50.0                 expm_0.999-9
     [27] GenomicRanges_1.56.0            BiocGenerics_0.50.0
     [29] yulab.utils_0.1.4               nnet_7.3-19
     [31] TH.data_1.1-2                   sandwich_3.1-0
     [33] GenomeInfoDbData_1.2.12         IRanges_2.38.0
     [35] S4Vectors_0.42.0                ggrepel_0.9.5
     [37] irlba_2.3.5.1                   tidytree_0.4.6
     [39] vegan_2.6-4                     permute_0.9-7
     [41] DelayedMatrixStats_1.26.0       codetools_0.2-20
     [43] DelayedArray_0.30.0             scuttle_1.14.0
     [45] energy_1.7-11                   tidyselect_1.2.1
     [47] farver_2.1.1                    UCSC.utils_1.0.0
     [49] lme4_1.1-35.3                   gmp_0.7-4
     [51] ScaledMatrix_1.12.0             viridis_0.6.5
     [53] matrixStats_1.3.0               stats4_4.4.0
     [55] base64enc_0.1-3                 jsonlite_1.8.8
     [57] multtest_2.60.0                 BiocNeighbors_1.22.0
     [59] e1071_1.7-14                    decontam_1.24.0
     [61] mia_1.12.0                      Formula_1.2-5
     [63] survival_3.6-4                  scater_1.32.0
     [65] iterators_1.0.14                tools_4.4.0
     [67] treeio_1.28.0                   DescTools_0.99.54
     [69] Rcpp_1.0.12                     glue_1.7.0
     [71] gridExtra_2.3                   SparseArray_1.4.0
     [73] xfun_0.43                       mgcv_1.9-1
     [75] MatrixGenerics_1.16.0           GenomeInfoDb_1.40.0
     [77] TreeSummarizedExperiment_2.12.0 withr_3.0.0
     [79] numDeriv_2016.8-1.1             fastmap_1.1.1
     [81] rhdf5filters_1.16.0             boot_1.3-30
     [83] bluster_1.14.0                  fansi_1.0.6
     [85] digest_0.6.35                   rsvd_1.0.5
     [87] timechange_0.3.0                R6_2.5.1
     [89] colorspace_2.1-0                gtools_3.9.5
     [91] utf8_1.2.4                      generics_0.1.3
     [93] data.table_1.15.4               DECIPHER_3.0.0
     [95] class_7.3-22                    CVXR_1.0-12
     [97] httr_1.4.7                      htmlwidgets_1.6.4
     [99] S4Arrays_1.4.0                  pkgconfig_2.0.3
    [101] gtable_0.3.5                    Exact_3.2
    [103] Rmpfr_0.9-5                     SingleCellExperiment_1.26.0
    [105] XVector_0.44.0                  htmltools_0.5.8.1
    [107] biomformat_1.32.0               scales_1.3.0
    [109] Biobase_2.64.0                  lmom_3.0
    [111] knitr_1.46                      rstudioapi_0.16.0
    [113] tzdb_0.4.0                      reshape2_1.4.4
    [115] checkmate_2.3.1                 nlme_3.1-164
    [117] nloptr_2.0.3                    rhdf5_2.48.0
    [119] proxy_0.4-27                    cachem_1.0.8
    [121] zoo_1.8-12                      rootSolve_1.8.2.4
    [123] parallel_4.4.0                  vipor_0.4.7
    [125] foreign_0.8-86                  pillar_1.9.0
    [127] grid_4.4.0                      vctrs_0.6.5
    [129] BiocSingular_1.20.0             beachmat_2.20.0
    [131] cluster_2.1.6                   beeswarm_0.4.0
    [133] htmlTable_2.4.2                 evaluate_0.23
    [135] mvtnorm_1.2-4                   cli_3.6.2
    [137] compiler_4.4.0                  rlang_1.1.3
    [139] crayon_1.5.2                    labeling_0.4.3
    [141] plyr_1.8.9                      fs_1.6.4
    [143] ggbeeswarm_0.7.2                stringi_1.8.3
    [145] viridisLite_0.4.2               BiocParallel_1.38.0
    [147] lmerTest_3.1-3                  munsell_0.5.1
    [149] Biostrings_2.72.0               gsl_2.1-8
    [151] lazyeval_0.2.2                  Matrix_1.7-0
    [153] hms_1.1.3                       sparseMatrixStats_1.16.0
    [155] bit64_4.0.5                     Rhdf5lib_1.26.0
    [157] highr_0.10                      SummarizedExperiment_1.34.0
    [159] rbibutils_2.2.16                igraph_2.0.3
    [161] memoise_2.0.1                   bslib_0.7.0
    [163] bit_4.0.5                       readxl_1.4.3
    [165] ape_5.8

# References

Lahti, Leo, Jarkko Salojärvi, Anne Salonen, Marten Scheffer, and Willem M De Vos. 2014. “Tipping Elements in the Human Intestinal Ecosystem.” Nature Communications 5 (1): 1–10.

Lahti, Leo, Sudarshan Shetty, T Blake, J Salojarvi, and others. 2017. “Tools for Microbiome Analysis in R.” Version 1: 10013.

Lin, Huang, and Shyamal Das Peddada. 2020. “Analysis of Compositions of Microbiomes with Bias Correction.” Nature Communications 11 (1): 1–11.

McMurdie, Paul J, and Susan Holmes. 2013. “Phyloseq: An R Package for Reproducible Interactive Analysis and Graphics of Microbiome Census Data.” PloS One 8 (4): e61217.