MetMashR is an R/Bioconductor package for integrating, harmonising and processing metabolite annotations from multiple sources using modular, reproducible workflows.
Summary
Metabolomics is the analysis of small molecules, or metabolites, in biological and environmental samples (e.g. blood, urine and water). Liquid chromatography–mass spectrometry (LC–MS) is widely used in metabolomics and produces complex datasets from which thousands of LC–MS features can be detected. Computational annotation tools attempt to associate these features with candidate chemical compounds, but different tools may produce conflicting annotations, use inconsistent compound names or identifiers, or report multiple candidates for a single feature.
MetMashR integrates and harmonises metabolite annotations from multiple sources. It imports annotation outputs into a common structure and provides modular tools for cleaning, standardising, filtering, prioritising and combining annotations, as well as enriching them with information from resources such as PubChem, ChEBI, KEGG and LIPID MAPS. These steps can be combined into reproducible workflows that can be reused and applied consistently across analyses. MetMashR was developed primarily for LC–MS annotation workflows, but its modular framework can also be extended to other analytical platforms.
Documentation and resources
Documentation: https://computational-metabolomics.github.io/MetMashR/
-
Bioconductor
-
GitHub
- Source code: https://github.com/computational-metabolomics/MetMashR
- Bug reports and feature requests: https://github.com/computational-metabolomics/MetMashR/issues
Vignettes and case studies
- Getting started with MetMashR: an introduction to annotation sources, workflow steps, REST API lookups, dictionaries and combining records.
- Extending MetMashR with custom sources and workflow steps: how to create your own annotation sources and workflow steps.
- Evaluating metabolite annotations using standard mixtures: a case study combining Compound Discoverer and LipidSearch annotations of mixtures of chemical standards, and assessing them against the known contents of the mixtures.
- Exploring chemical classes and pathway coverage in MTox700+: a case study combining the MTox700+ database of toxicologically relevant metabolites with other databases (e.g. PathBank) to explore its chemical and biological coverage.
-
Adapting the Metabolites Merging Strategy with MetMashR: a case study reproducing a published annotation-merging strategy as a
MetMashRworkflow.
Installation
To install the release version from Bioconductor:
if (!require("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("MetMashR")To install the development version from GitHub:
if (!require("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_github("computational-metabolomics/MetMashR")Quick start
This example uses LipidSearch annotations that are included with the package. The workflow imports the annotations, keeps only the higher-confidence ones (grades A and B), then combines duplicate annotations of the same lipid into a single record.
library(MetMashR)
# annotation source: a LipidSearch output file
AT <- ls_source(
source = system.file(
"extdata/MTox/LS/MTox_2023_HILIC_POS.txt",
package = "MetMashR"
)
)
# workflow
WF <-
# step 1: import the annotations
import_source() +
# step 2: keep annotations with grade A or B
filter_labels(
column_name = "Grade",
labels = c("A", "B"),
mode = "include"
) +
# step 3: combine records for the same lipid, counting how many there were
combine_records(
group_by = "LipidName",
default_fcn = fuse_unique(separator = "; "),
fcns = list(count = count_records())
)
# apply the workflow to the annotation source
WF <- model_apply(WF, AT)
# the processed annotations
predicted(WF)
head(predicted(WF)$data[, c("LipidName", "Grade", "count")])
# the annotations after any individual step, e.g. after filtering
predicted(WF[2])The Getting started with MetMashR vignette describes these and many other workflow steps in detail.
Maintainer
Gavin Rhys Lloyd University of Birmingham g.r.lloyd@bham.ac.uk
For bug reports and feature requests, please use the GitHub issue tracker.