README.md

Macarron User Manual #

Macarron (Metabolome Analysis and Combined Annotation Ranks to pRioritize Novel bioactives) is a workflow to systematically identify and prioritize potentially bioactive (and often unannotated) small molecules in microbial community metabolomic datasets. Macarron prioritizes metabolic features as potentially bioactive in a phenotype/condition of interest using a combination of (a) covariance with annotated metabolites, (b) ecological properties such as abundance with respect to covarying annotated compounds, and (c) differential abundance in the phenotype/condition of interest.

If you have questions, please direct it to: Macarron Forum

Installation

Macarron requires R version 4.2.0 or higher. Install Bioconductor and then install Macarron:

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

BiocManager::install("Macarron")

Citation

Amrisha Bhosle, Sena Bae, Yancong Zhang, Eunyoung Chun, Julian Avila-Pacheco, Ludwig Geistlinger, Gleb Pishchany, Jonathan N. Glickman, Monia Michaud, Levi Waldron, Clary Clish, Ramnik J. Xavier, Hera Vlamakis, Eric A. Franzosa, Wendy S. Garrett, Curtis Huttenhower (2024) Integrated annotation prioritizes metabolites with bioactivity in inflammatory bowel disease Molecular Systems Biology, doi:10.1038/s44320-024-00027-8

How to Run

Macarron can be run from the command line or as an R function. Both methods require the same arguments, have the same options, and use the same default settings. The package includes the wrapper Macarron() as well as functions which perform different steps in the Macarron framework.

Input CSV files

Macarron requires 4 comma-separated, appropriately formatted input files. The files and their formatting constraints are described below.

  1. Metabolic features abundances
    • Must contain features in rows and samples in columns.
    • First column must identify features.
  2. Metabolic features annotations
    • Must contain features in rows and annotations in columns.
    • First column must identify features.
    • Second column must contain either HMDB ID or PubChem Compound Identifier (CID).
    • Third column must contain the name of the metabolite.
    • Fourth column must contain a continuous chemical property such as m/z or RT or shift/ppm.
    • Other annotations such as LC-MS method, RT, m/z, or other identifiers can be listed column 4 onward.
  3. Sample metadata
    • Must contain samples in rows and metadata in columns.
    • First column must identify samples. Sample names must overlap between the metadata file and the feture abundances file.
    • Second column must contain categorical metadata relevant to prioritization such as phenotypes, exposures or environments.
  4. Chemical taxonomy
    • First column must contain the HMDB ID or PubChem CID. IDs must be consistent between annotation and taxonomy files.
    • Second and third columns must contain chemical subclass and class of the respective metabolite.

If you do not have the chemical taxonomy file, you can generate this file using the annotation dataframe and Macarron utility decorate_ID.

Output Files

By default, all files will be stored in a folder named Macarron_output inside the current working directory. The main prioritization results are stored in prioritized_metabolites_all.csv. Another file, prioritized_metabolites_characterizable.csv is a subset of prioritized_metabolites_all.csv and only contains metabolic features which covary with at least one annotated metabolite. The columns in these output files are:

Run a demo in R

Using CSV files as inputs

Example (demo) input files can be found under inst/extdata folder of the Macarron source. These files were generated from the PRISM study of stool metabolomes of individuals with inflammatory bowel disease (IBD) and healthy "Control" individuals. Control and IBD are the two phenotypes in this example. Macarron will be applied to prioritize metabolic features with respect to their bioactivity in IBD. Therefore, in this example, the phenotype of interest is "IBD" and the reference phenotype is "Control". The four input files are demo_abundances.csv, demo_annotations.csv, demo_metadata.csv, and demo_taxonomy.csv.

library(Macarron)
prism_abundances <- system.file(
    'extdata','demo_abundances.csv', package="Macarron")
prism_annotations <-system.file(
    'extdata','demo_annotations.csv', package="Macarron")
prism_metadata <-system.file(
    'extdata','demo_metadata.csv', package="Macarron")
mets_taxonomy <-system.file(
    'extdata','demo_taxonomy.csv', package="Macarron")
prism_prioritized <- Macarron::Macarron(input_abundances = prism_abundances,
                                        input_annotations = prism_annotations,
                                        input_metadata = prism_metadata,
                                        input_taxonomy = mets_taxonomy)

Using dataframes as inputs

abundances_df = read.csv(file = prism_abundances, row.names = 1) # setting features as rownames
annotations_df = read.csv(file = prism_annotations, row.names = 1) # setting features as rownames
metadata_df = read.csv(file = prism_metadata, row.names = 1) # setting samples as rownames 
taxonomy_df = read.csv(file = mets_taxonomy)

# Running Macarron
prism_prioritized <- Macarron::Macarron(input_abundances = abundances_df,
                                        input_annotations = annotations_df,
                                        input_metadata = metadata_df,
                                        input_taxonomy = taxonomy_df)


biobakery/MACARRoN documentation built on July 1, 2024, 10:01 p.m.