--- title: "Getting Started with MiCARA" author: - name: Safa Bushnaq affiliation: Oxford Brookes University, Oxford, UK email: 19397747@brookes.ac.uk package: MiCARA date: "`r Sys.Date()`" output: BiocStyle::html_document: toc: true toc_float: true vignette: > %\VignetteIndexEntry{Getting Started with MiCARA} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r init, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ## 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: ```{r install, eval = FALSE} if (!requireNamespace("BiocManager", quietly = TRUE)) { install.packages("BiocManager") } BiocManager::install("MiCARA") ``` Load the package: ```{r setup} 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`). ```{r validate-step, eval = TRUE} # 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" ) ``` **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`. ```{r validate-bioc, eval = FALSE} # 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. ```{r impute-step, eval = TRUE} # Optional: Impute remaining missing metadata values (<30%) micara_obj <- impute_metadata(micara_obj) ``` ### Step 3: Differential Abundance Analysis `run_diff_abundance()` runs bias-corrected log-linear models across taxa, pathways, or both simultaneously using ANCOM-BC2. ```{r diff-step, eval = TRUE} # 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 ) # Inspect significant taxa head(diff_results$taxa$significant) # Inspect significant pathways head(diff_results$pathways$significant) ``` ### 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. ```{r interactions, eval = TRUE} # 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 ) # inspect available disease cohorts in the output list names(interactions) ``` ```{r inspect-diagnostics} # View cohort-level analysis summary and covariate usage attr(interactions, "summary") # View analysis settings and CLR transformation diagnostics attr(interactions, "settings") # 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) } ``` ### Step 5: Visualize Taxa-Pathway Interactions Use `plot_interaction_sankey()` to display interactive D3 networks connecting significant taxa to functional pathways: ```{r plot-sankey, eval = TRUE} # 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) 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") )) ``` ## Optional: global interaction correction ```{r global interaction correction, eval = TRUE} # Apply global FDR correction across all disease cohorts interactions_global <- compute_global_fdr(interactions) # 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 ``` ```{r sessionInfo} sessionInfo() ```