eCOMET-intro

Dale L. Forrister & Min-Soo Choi

2026-01-26

library(ecomet)

The Mass-spectrometry Metabolomics Object (mmo)

The mmo is a central data structure in the eCOMET package.
It is created by the GetMZmineFeature() function and contains:

• feature_data: A data frame of metabolite features and their measured values.
• feature_info: A data frame of feature definitions include mz and rt range and grouping information if feature grouping was applied in mzmine.
• metadata: Sample metadata, including grouping information.
• sirius_annot: (optional) SIRIUS/CANOPUS class annotations. Added by AddSiriusAnnot().
• custom_annot: (optional) Custom compound annotations. Added by AddCustomAnnot().
• cos.sim: (optional) Cosine similarity matrix. Added by AddChemSim().
• m2ds.sim: (optional) MS2DeepScore similarity matrix. Added by AddChemSim().
• dreams.sim: (optional) DreaMS similarity matrix. Added by AddChemSim().
• <name>.sim: (optional) Any custom feature similarity matrix. Added by AddCustomSim() with a user-supplied name.

Input file requirements

The mendatory input files for creating a mmo are:

1. MZmine feature table:

• This file is generated by MZMine (Feature list methods → Export feature list → CSV). See MZMine_documentation

2. Metadata file: A CSV file containing sample metadata, with following columns. -sample (___.mzML or equivalent filename used as input of the MZmine), -mass (the sample mass which will be used for normalization. just put 1 if not needed), -and at least one grouping info column (the experimental group for each sample). Use as input for ‘group_col’ argument of GetMZmineFeature().

Refer Inputs_MZMine below for details.

---

You can create a mmo like this:

mmo <- GetMZmineFeature( mzmine_dir = “path/to/mzmine_feature.csv”, metadata_dir = “path/to/metadata.csv”, group_col = “treatment” )

Here we load demo data that is downloaded when eCOMET is installed and create a mmo

# Locate tutorial data shipped with the eCOMET package
data_dir <- system.file(
  "extdata/tutorials/treatment_based",
  package = "ecomet"
)

stopifnot(nzchar(data_dir))  # fail loudly if package/data not installed

# Define file paths
demo_feature <- file.path(data_dir, "feature_table_demo.csv")
demo_metadata <- file.path(data_dir, "metadata_demo.csv")
demo_sirius_formula <- file.path(data_dir, "canopus_formula_summary.tsv")
demo_sirius_structure <- file.path(data_dir, "structure_identifications.tsv")
demo_dreams <- file.path(data_dir, "dreams_sim_demo.csv")
gls_db <- file.path(data_dir, "custom_DB_glucosinolates.csv")


mmo <- GetMZmineFeature(mzmine_dir=demo_feature, metadata_dir = demo_metadata, group_col = 'group', sample_col = 'sample')

Once created, you can use the mmo for normalization, annotation, statistical analysis, and visualization throughout the package.

Normalization

The raw peak area values are processed by following steps:

1. Replacing missing values (NA) with half of the minimum value for each feature or 1.

2. Normalizing by sample mass (provided in metadata).

3. Transform the data using Log, Mean-centering, and Z-score scaling.

mmo <- ReplaceZero(mmo, method = 'one') # Replace 0 and NA values by 1
mmo <- MassNormalization(mmo) # Normalize peak area by sample mass in metadata
mmo <- MeancenterNormalization(mmo) # Add mean-centered area
mmo <- LogNormalization(mmo) # Add log-transformed area
mmo <- ZNormalization(mmo) # Add Zscore

Adding Sirius/CANOPUS annotations

The results from SIRIUS/CANOPUS can be added to the mmo as mmo$sirius_annot These are used for chemical class enrichment analysis and visualization. Two files are needed:

1. structure_identifications.tsv

2. canopus_formula_summary.tsv

The above files are generated by SIRIUS/CANOPUS. See SIRIUS documentation and the Inputs_SIRIUS section at the bottom of this page for details.

mmo <- AddSiriusAnnot( mmo, structure_dir = “path/to/structure_identifications.tsv”, canopus_dir = “path/to/canopus_formula_summary.tsv” )

mmo <- AddSiriusAnnot(mmo, 
                      canopus_structuredir = demo_sirius_structure, 
                      canopus_formuladir = demo_sirius_formula)
mmo$sirius_annot

Adding chemical similarity

Chemical similarity matrices describe pairwise structural relationships among features. Values are stored as raw similarities (0–1, higher = more similar); downstream functions convert to distance internally as needed. Once added to the mmo they are used by GetBetaDiversity(), GetAlphaDiversity() (weighted mode), and HeatmapPlot() via the distance argument.

Built-in methods: AddChemSim()

AddChemSim() reads MZmine molecular networking output files for three supported similarity types and stores the raw similarity values directly in the mmo. For datasets with more than 10,000 features a sparse matrix format is used automatically to avoid memory issues.

mmo <- AddChemSim(mmo,
  cos_dir    = "path/to/cosine_similarity.csv",
  m2ds_dir   = "path/to/ms2deepscore_similarity.csv",
  dreams_dir = "path/to/dreams_similarity.csv"
)

# Add DreaMS similarity from demo data
mmo <- AddChemSim(mmo, dreams_dir = demo_dreams)
mmo$dreams.sim[1:10, 1:10]

Pass the stored matrix to downstream functions using its short name:

beta  <- GetBetaDiversity(mmo, method = "CSCS",     distance = "dreams")
alpha <- GetAlphaDiversity(mmo, mode = "weighted",  distance = "dreams")

Custom similarity matrices: AddCustomSim()

If you have a feature similarity matrix from another tool (e.g. Tanimoto structural similarity, NPC-based scores, or any other pairwise metric), use AddCustomSim() to add it under a name of your choice.

Format requirements for the matrix:

• Square numeric matrix (or sparse dgCMatrix) with row and column names matching the feature IDs in mmo$feature_data$id.
• Values must be similarities in [0, 1]: 1 = identical, 0 = maximally different. Pass the similarity matrix directly — no conversion needed.
• Diagonal should be 1. Matrix should be symmetric.

# Example: Tanimoto structural similarity from an external tool
# tanimoto_sim_matrix is already a similarity matrix — pass directly
mmo <- AddCustomSim(mmo, sim_matrix = tanimoto_sim_matrix, name = "tanimoto")

# Use it anywhere a 'distance' argument is accepted:
beta  <- GetBetaDiversity(mmo, method = "CSCS",     distance = "tanimoto")
alpha <- GetAlphaDiversity(mmo, mode = "weighted",  distance = "tanimoto")

The matrix is stored as mmo$tanimoto.sim and the name "tanimoto" can be passed as the distance argument throughout the package.

Adding custom annotations

You can add your own custom compound annotations to the mmo as mmo$custom_annot. This is useful for adding known compound names or classes from other databases. The custom annotation file should be a CSV with three columns: 1. compound: Name of the compound 2. mz: m/z value 3. rt: Retention time (in minutes)

mmo <- AddCustomAnnot(
  mmo,
  custom_annot_dir = "path/to/custom_annotations.csv",
  mztol = 5, # m/z tolerance in ppm
  rttol = 0.2 # RT tolerance in minutes
)

##Filtering mmos based on feature list or sample list

You can provide either a list of species or features to filter the mmo. This will iterate over all sets of

#Create a new mmo containing only control samples
samples_ctrl <- mmo$metadata$sample[mmo$metadata$group == "ctrl"]

mmo_ctrl <- filter_mmo(mmo,
                       sample_list  = samples_ctrl,
                       drop_empty_feat = TRUE #This will remove any features not observed in samples
                       )

#create a new mmo only containing Flavonoid based on sirius annotations
FLVs <- mmo$sirius_annot %>% 
  filter(grepl("Flavonoid", .data[['ClassyFire#most specific class']])
  ) %>% pull(id)

mmo_FLVs <- filter_mmo(mmo,
                       feature_list = FLVs)

##Match and Filter an associated mgf file to based on the feature list in a mmo.

Once an dataset has been filtered you may want to update the associated .mgf file containing ms2 spectra prior to processing with Sirius, GNPS ect.

1. Match spectra present in an MGF against a feature list and update the mmo$feature_info.

mmo <- annotate_feature_info_ms2_from_mgf(mmo,
                                          mgf_path = "/path_to_mgf/spectra.mgf",
                                          overwrite = TRUE)
mmo$feature_info

2. Given a feature list in a mmo defined by mmo$feature_data$id read through an associated mgf file and remove features not in the list.

filter_mgf_to_mmo(mmo, 
                  mgf_path = "/path_to_mgf/spectra.mgf",
                  output_path = "/path_to_renamed_mgf/filtered_spectra_mmo_only.mgf")

---