Getting Started with MiCARA

Introduction

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:

  1. Differential abundance (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.
  2. Confounder-adjusted taxon–pathway associations (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.

Relation to other packages

  • mia::getCrossAssociation() computes associations between the features of two experiments, such as taxa and pathways, but does not adjust them for covariates.
  • MMUPHin (adjust_batch(), lm_meta()) corrects batch effects and performs meta-analytic differential abundance across studies.
  • MaAsLin 2 and MaAsLin 3 fit multivariable models, with covariates and random effects, between features and metadata.

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:

  • taxon–pathway associations are tested only among features that are differentially abundant in each disease, which focuses the analysis and reduces the number of tests;
  • both feature types are residualised on the same confounders before correlation, so links driven by age, BMI, sex or cohort are removed;
  • multi-cohort data are handled through a study random effect in ANCOM-BC2, and per-disease and optional global FDR control are applied to the associations.

Example data

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.

Installation

Once MiCARA is accepted, it can be installed from Bioconductor:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}
BiocManager::install("MiCARA")

Load the package:

library(MiCARA)

Pipeline Workflow & Decision Points

MiCARA is designed to be flexible depending on your dataset’s completeness and clinical reporting requirements.

Step 1: Input Validation

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.

  • Taxa: MetaPhlAn relative abundances (percentages or proportions) or integer counts.
  • Pathways: unstratified HUMAnN pathway abundances. Relative abundances (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.
  • Metadata: 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"))

Step 2: Handling Missing Metadata (Optional)

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():

  • Host covariates (for example age or BMI) have low to moderate missingness, below the 30% cutoff used by validate_inputs().
  • You want to keep the sample size and statistical power.

When to skip it:

  • The metadata have no missing values.
  • Your study protocol requires a complete-case analysis.

If you skip imputation, downstream functions check the requested covariates for missing values and drop or warn about problematic ones before model fitting.

# Optional: Impute remaining missing metadata values (<30%)
micara_obj <- impute_metadata(micara_obj)
#> [Info] No eligible host confounders with missing values to impute. Returning input object unchanged.

Step 3: Differential Abundance Analysis

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  enriched

Step 4: Confounder-Adjusted Interaction Inference

After 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  positive

Step 5: Visualize Taxa-Pathway Interactions

Use 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.

Optional: global interaction correction

# 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$positive
sessionInfo()
#> 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