Gut microbiome studies increasingly measure both which microbes are present (taxonomic profiles, for example from MetaPhlAn) and what they can do (functional pathway profiles, for example from HUMAnN) on the same samples. A natural question is which disease-associated taxa are linked to disease-associated pathways. Answering it is not straightforward: host and study factors such as age, BMI, sex or cohort can shift both a taxon and a pathway, producing correlations that have nothing to do with disease, and testing every taxon against every pathway creates a heavy multiple-testing burden.
MiCARA addresses this in two layers:
run_diff_abundance()): ANCOM-BC2 identifies taxa and
pathways that differ between each disease group and the reference group,
adjusting for confounders and, across cohorts, for study as a random
effect.compute_residualCLR_correlations()): within each disease,
only the differentially abundant taxa and pathways are kept. Their
CLR-transformed abundances are residualised on the confounders, and
Spearman correlations between the residuals are tested with
Benjamini–Hochberg correction.Input validation (validate_inputs()), optional
imputation of missing covariates (impute_metadata()), an
optional global FDR correction across diseases
(compute_global_fdr()) and interactive Sankey diagrams
(plot_interaction_sankey()) complete the workflow.
MiCARA builds on Bioconductor infrastructure: it uses ANCOM-BC2 from
the ANCOMBC package and accepts (Tree)SummarizedExperiment
and MultiAssayExperiment objects, so data from
curatedMetagenomicData or imported with mia can be analysed directly. It
adds to the existing Bioconductor microbiome tools a disease-focused,
confounder-adjusted analysis of the links between taxonomic and
functional profiles.
mia::getCrossAssociation() computes associations
between the features of two experiments, such as taxa and pathways, but
does not adjust them for covariates.adjust_batch(), lm_meta())
corrects batch effects and performs meta-analytic differential abundance
across studies.MMUPHin and MaAsLin test features against metadata, not associations between two feature tables. What MiCARA adds is the combination of both steps in one workflow:
MiCARA includes a small simulated dataset of 30 samples (15
healthy, 15 Case, from two studies).
example_metadata holds disease status, age category, BMI,
gender and study. example_taxa holds 20 taxa and
example_pathways 10 pathways, as Poisson counts with mean
50 and 100 respectively. The following signal was injected in the Case
samples: Taxon_1, Taxon_2 and Taxon_3 were multiplied by 8, 10 and 6,
and Pathway_2 by 7. Pathway_1 was generated from Taxon_1 (twice its
count plus Poisson noise), so it is also enriched in Case and correlated
with Taxon_1. The workflow below should therefore find these taxa and
pathways enriched in Case and recover a positive Taxon_1–Pathway_1
association. The script that generates the data is in
inst/scripts/generate_example_data.R.
Once MiCARA is accepted, it can be installed from Bioconductor:
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("MiCARA")Load the package:
MiCARA is designed to be flexible depending on your dataset’s completeness and clinical reporting requirements.
validate_inputs() ensures sample ID alignment across
taxonomic matrices, pathway matrices, and sample metadata. It checks
relative vs. absolute abundances, flags high-missingness covariates
(>30%), and records retained confounders. By default, common
covariates (age, gender, BMI, study name, body site) are recognised by
name; to adjust for other variables, list them in confounders, for
example confounders = c(“age”, “BMI”, “antibiotics”). The QC report
lists any metadata columns that are not used.
Recommended input. Taxa and pathway tables have one row per feature and one column per sample.
humann_renorm_table --units relab) and CPM are
recognised automatically; for HUMAnN’s default RPK output, set
pathways_scale = "rpk". Stratified rows and the
UNMAPPED/UNINTEGRATED rows are removed automatically.sample_id, disease and,
ideally, number_reads (sequencing depth). With
number_reads, relative abundances are rescaled to a
count-like scale for ANCOM-BC2. These are count-scaled abundances, not
read counts (see the section “Abundance scales” in
?validate_inputs).# Load example dataset included in MiCARA
data("example_taxa", package = "MiCARA")
data("example_pathways", package = "MiCARA")
data("example_metadata", package = "MiCARA")
# Validate inputs and filter unusable covariates
micara_obj <- validate_inputs(
taxa = example_taxa,
pathways = example_pathways,
metadata = example_metadata,
disease_col = "disease"
)
#>
#> ========== MiCARA Input QC ==========
#> Samples retained: 30
#> Diseases retained: 2
#> Diseases removed: None
#> Taxa scale detected: counts
#> Pathway scale detected: counts
#> Covariates retained: age_category, BMI, gender, study_name
#> Covariates removed: None
#> Columns not used: None
#> =====================================Starting from Bioconductor objects.
validate_inputs() also accepts
(Tree)SummarizedExperiment objects, for example from
curatedMetagenomicData or
mia::importMetaPhlAn() and
mia::importHUMAnN(), or a MultiAssayExperiment
holding both tables. The sample metadata are then taken from
colData.
# One (Tree)SummarizedExperiment for taxa and one for pathways
micara_obj <- validate_inputs(taxa = tse_taxa, pathways = tse_pathways)
# A MultiAssayExperiment holding both: name its taxa and pathway experiments
micara_obj <- validate_inputs(mae, experiments = c(taxa = "metaphlan", pathways = "humann"))Missing covariate values would otherwise lead to samples being
dropped during model fitting (complete-case analysis).
impute_metadata() imputes them with MICE. It performs
single imputation: one completed dataset is used for the downstream
analysis, so p-values do not include the uncertainty from the imputation
(see ?impute_metadata). Pooling across multiple imputations
is planned for a future release.
When to use impute_metadata():
validate_inputs().When to skip it:
If you skip imputation, downstream functions check the requested covariates for missing values and drop or warn about problematic ones before model fitting.
run_diff_abundance() runs bias-corrected log-linear
models across taxa, pathways, or both simultaneously using
ANCOM-BC2.
# Run differential abundance on both feature types
diff_results <- run_diff_abundance(
micara_obj = micara_obj,
feature_type = c("taxa", "pathways"),
reference_level = "healthy",
use_robust = TRUE
)
#> [Info] Setting 'healthy' as the reference level for disease comparisons.
#> [Info] Re-leveling 'disease' with reference level: 'healthy'
#>
#> ========== Running ANCOM-BC2 (taxa) ==========
#> Fixed formula: age_category + BMI + gender + disease
#> Random formula: (1 | study_name)
#> Reference level: healthy
#> Method / Alpha: BH / 0.05
#> ---------------------------------------------------
#> The imported data is in a generic 'matrix'/'data.frame' format.
#> Warning: The group variable has < 3 categories
#> The multi-group comparisons (global/pairwise/dunnet/trend) will be deactivated
#> Warning: The number of taxa used for estimating sample-specific biases is: 20
#> A large number of taxa (>50) is required for the consistent estimation of biases
#> Loading required package: foreach
#> Loading required package: rngtools
#> Conducting sensitivity analysis for pseudo-count addition to 0s ...
#> For taxa that are significant but do not pass the sensitivity analysis,
#> they are marked in the 'passed_ss' column and will be treated as non-significant in the 'diff_robust' column.
#> For detailed instructions on performing sensitivity analysis, please refer to the package vignette.
#> Significant taxa identified per disease comparison (robust flags):
#> Case: 3
#> ---------------------------------------------------
#> [Info] Re-leveling 'disease' with reference level: 'healthy'
#>
#> ========== Running ANCOM-BC2 (pathways) ==========
#> Fixed formula: age_category + BMI + gender + disease
#> Random formula: (1 | study_name)
#> Reference level: healthy
#> Method / Alpha: BH / 0.05
#> ---------------------------------------------------
#> The imported data is in a generic 'matrix'/'data.frame' format.
#> Warning: The group variable has < 3 categories
#> The multi-group comparisons (global/pairwise/dunnet/trend) will be deactivated
#> Warning: The number of pathways used for estimating sample-specific biases is: 10
#> A large number of pathways (>50) is required for the consistent estimation of biases
#> Conducting sensitivity analysis for pseudo-count addition to 0s ...
#> For taxa that are significant but do not pass the sensitivity analysis,
#> they are marked in the 'passed_ss' column and will be treated as non-significant in the 'diff_robust' column.
#> For detailed instructions on performing sensitivity analysis, please refer to the package vignette.
#> Significant pathways identified per disease comparison (robust flags):
#> Case: 2
#> ---------------------------------------------------
# Inspect significant taxa
head(diff_results$taxa$significant)
#> feature disease lfc se p q direction
#> 1 Taxon_1 Case 2.008631 0.09349275 2.799587e-17 1.866391e-16 enriched
#> 2 Taxon_2 Case 2.189056 0.09271032 3.437782e-18 6.875564e-17 enriched
#> 3 Taxon_3 Case 1.737435 0.08229026 1.877619e-17 1.866391e-16 enriched
# Inspect significant pathways
head(diff_results$pathways$significant)
#> feature disease lfc se p q direction
#> 1 Pathway_1 Case 2.028429 0.07869975 4.762844e-19 2.381422e-18 enriched
#> 2 Pathway_2 Case 1.941612 0.06969169 7.245243e-20 7.245243e-19 enrichedAfter identifying robust differentially abundant features, compute_residualCLR_correlations() evaluates taxon–pathway interactions within each disease cohort: 1. Performs Centered Log-Ratio (CLR) transformations on full feature matrices. 2. Filters to disease-specific significant taxa and pathways. 3. Residualizes feature abundances against host covariates (e.g., age_category, BMI, gender, study_name) using QR decomposition. 4. Computes pairwise Spearman correlations on residuals and applies Benjamini-Hochberg (BH) adjustment within each cohort.
# Compute residual correlations per disease
interactions <- compute_residualCLR_correlations(
micara_obj = micara_obj,
diffab_obj = diff_results,
covariates = c("age_category", "BMI", "gender", "study_name"),
q_cutoff = 0.05,
r_cutoff = 0.20,
verbose = TRUE
)
#> [MiCARA] CLR-transforming complete taxa and pathway matrices.
#> [MiCARA] Case: 3 taxa x 2 pathways = 6 tested pair(s); 1 retained link(s).
#>
#> ========== MiCARA Residual Correlation Summary ==========
#> Cohort: Case (Status: analysed)
#> - Samples: 15 | Residual DF: 10
#> - Features Tested: 3 taxa x 2 pathways (6 pairs)
#> - Retained Links: 1 (1 pos, 0 neg)
#> - Covariates Used: age_category, BMI, gender, study_name
#> ----------------------------------------------------------
# inspect available disease cohorts in the output list
names(interactions)
#> [1] "Case"# View cohort-level analysis summary and covariate usage
attr(interactions, "summary")
#> disease status reason n_samples residual_df n_taxa_tested n_pathways_tested
#> 1 Case analysed <NA> 15 10 3 2
#> n_pairs_tested n_significant_links n_positive_links n_negative_links
#> 1 6 1 1 0
#> covariates_used covariates_dropped
#> 1 age_category, BMI, gender, study_name
# View analysis settings and CLR transformation diagnostics
attr(interactions, "settings")
#> $covariates_requested
#> [1] "age_category" "BMI" "gender" "study_name"
#>
#> $cor_method
#> [1] "spearman"
#>
#> $p_adjust_method
#> [1] "BH_within_disease"
#>
#> $q_cutoff
#> [1] 0.05
#>
#> $r_cutoff
#> [1] 0.2
#>
#> $threshold_rule
#> [1] "q < q_cutoff and abs(rho) > r_cutoff"
#>
#> $taxa_pseudocount
#> [1] 13
#>
#> $pathway_pseudocount
#> [1] 36.5
#>
#> $taxa_all_zero_removed
#> character(0)
#>
#> $pathway_all_zero_removed
#> character(0)
#>
#> $min_samples_per_disease
#> [1] 10
#>
#> $min_residual_df
#> [1] 3
#>
#> $retain_all_pairs
#> [1] TRUE
#>
#> $skipped_no_pathways
#> character(0)
#>
#> $skipped_no_taxa
#> character(0)
# Find the first analyzed cohort dynamically
analyzed_cohorts <- names(interactions)[sapply(interactions, function(x) is.list(x) && x$status == "analysed")]
if (length(analyzed_cohorts) > 0) {
first_cohort <- analyzed_cohorts[1]
message("Displaying links for cohort: ", first_cohort)
head(interactions[[first_cohort]]$links)
}
#> Displaying links for cohort: Case
#> taxon pathway rho p q direction
#> 1 Taxon_1 Pathway_1 0.95 6.086258e-08 3.651755e-07 positiveUse plot_interaction_sankey() to display interactive D3
networks connecting significant taxa to functional pathways:
# Interactive visualization. direction = "both" returns a list with one
# diagram per direction ($positive and/or $negative); print an element to show it.
sankeys <- plot_interaction_sankey(
interactions = interactions,
disease = names(interactions)[1], # Target disease cohort (e.g., "UC")
direction = "both", # Options: "positive", "negative", or "both"
top_n_per_pathway = 5, # Top N correlated taxa per pathway
font_size = 12, # Text label size in pixels
node_width = 35 # Width of Sankey block nodes
)
names(sankeys)
#> [1] "positive"
sankeys$positive
# Optional: save interactive HTML and static PNG files. They go to a temporary folder.
invisible(plot_interaction_sankey(
interactions = interactions,
disease = names(interactions)[1],
save_path = file.path(tempdir(), "sankey_network")
))
#> `google-chrome`, `chromium-browser` and `chrome` were not found. Try setting the `CHROMOTE_CHROME` environment variable to the executable of a Chromium-based browser, such as Google Chrome, Chromium or Brave or adding one of these executables to your PATH.
#> Warning: Failed to export static PNG image (headless browser unavailable): Invalid path to Chrome
#> Note: The interactive .html file was saved successfully.# Apply global FDR correction across all disease cohorts
interactions_global <- compute_global_fdr(interactions)
#>
#> ========== MiCARA Global FDR Summary ==========
#> Method: BH
#> Global q cutoff: 0.05
#> Correlation cutoff: abs(rho) > 0.2
#> Total tested taxon-pathway pairs: 6
#> Globally significant associations: 1
#> Case: 1 global link(s)
#> -----------------------------------------------
# Plot Sankey network using global significance cutoffs
sankeys_global <- plot_interaction_sankey(
interactions = interactions_global,
disease = names(interactions_global)[1],
significance = "global",
direction = "both",
top_n_per_pathway = 5
)
sankeys_global$positivesessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] doRNG_1.8.6.3 rngtools_1.5.2 foreach_1.5.2 MiCARA_0.99.3
#> [5] BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] Rdpack_2.6.6 gridExtra_2.3.1 gld_2.6.8
#> [4] sandwich_3.1-3 readxl_1.6.0 rlang_1.3.0
#> [7] magrittr_2.0.5 multcomp_1.4-32 otel_0.3.0
#> [10] e1071_1.7-17 compiler_4.6.2 vctrs_0.7.3
#> [13] gsl_2.1-9 quadprog_1.5-8 stringr_1.6.0
#> [16] shape_1.4.6.1 pkgconfig_2.0.3 fastmap_1.2.0
#> [19] backports_1.5.1 energy_1.7-12 promises_1.5.0
#> [22] rmarkdown_2.32 tzdb_0.5.0 ps_1.9.3
#> [25] haven_2.5.5 nloptr_2.2.1 purrr_1.2.2
#> [28] jomo_2.7-6 glmnet_5.2 xfun_0.62
#> [31] cachem_1.1.0 jsonlite_2.0.0 later_1.4.8
#> [34] pan_2.0 data.tree_1.2.0 broom_1.0.13
#> [37] parallel_4.6.2 cluster_2.1.8.3 DescTools_0.99.60
#> [40] R6_2.6.1 bslib_0.12.0 stringi_1.8.9
#> [43] RColorBrewer_1.1-3 boot_1.3-32 rpart_4.1.27
#> [46] jquerylib_0.1.4 cellranger_1.1.0 ANCOMBC_2.15.1
#> [49] numDeriv_2016.8-1.1 Rcpp_1.1.2 iterators_1.0.14
#> [52] knitr_1.52 zoo_1.9-1 base64enc_0.1-6
#> [55] readr_2.2.0 igraph_2.3.4 Matrix_1.7-6
#> [58] splines_4.6.2 nnet_7.3-21 tidyselect_1.2.1
#> [61] rstudioapi_0.19.0 yaml_2.3.12 websocket_1.4.4
#> [64] doParallel_1.0.17 codetools_0.2-20 processx_3.9.0
#> [67] lattice_0.23-1 tibble_3.3.1 lmerTest_3.2-1
#> [70] withr_3.0.3 S7_0.2.2 evaluate_1.0.5
#> [73] foreign_0.8-92 survival_3.8-12 proxy_0.4-29
#> [76] pillar_1.11.1 BiocManager_1.30.27 mice_3.19.0
#> [79] checkmate_2.3.4 reformulas_0.4.4 generics_0.1.4
#> [82] chromote_0.5.1 hms_1.1.4 ggplot2_4.0.4
#> [85] scales_1.4.0 rootSolve_1.8.2.4 minqa_1.2.8
#> [88] gtools_3.9.5 class_7.3-24 glue_1.8.1
#> [91] Hmisc_5.3-1 lmom_3.3 webshot2_0.1.2
#> [94] maketools_1.3.2 tools_4.6.2 sys_3.4.3
#> [97] data.table_1.18.6.1 lme4_2.1-0 forcats_1.0.1
#> [100] Exact_3.3 buildtools_1.0.0 fs_2.1.0
#> [103] mvtnorm_1.4-2 grid_4.6.2 tidyr_1.3.2
#> [106] rbibutils_2.4.1 colorspace_2.1-4 networkD3_0.4.1
#> [109] nlme_3.1-172 htmlTable_2.5.0 Formula_1.2-6
#> [112] cli_3.6.6 expm_1.0-1 dplyr_1.2.1
#> [115] gtable_0.3.6 sass_0.4.10 digest_0.6.39
#> [118] TH.data_1.1-5 htmlwidgets_1.6.4 farver_2.1.2
#> [121] htmltools_0.5.9 lifecycle_1.0.5 httr_1.4.9
#> [124] mitml_0.4-5 MASS_7.3-66