Skip to contents

eCOMET-intro

Dale L. Forrister & Min-Soo Choi

2026-01-26

eCOMET-intro.Rmd

The mmo object

The mmo object 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.dissim: (optional) Cosine dissimilarity matrix. Added by AddChemdist().
  • m2ds.dissim: (optional) MS2DeepScore dissimilarity matrix. Added by AddChemdist().
  • dreams.dissim: (optional) DreaMS dissimilarity matrix. Added by AddChemdist().

Input file requirements

The mendatory input files for creating an mmo object are:

  1. MZmine feature table:
  • This file is generated by MZMine (Feature list methods → Export feature list → CSV). See MZMine_documentation
  1. 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 an mmo object 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 an mmo object


# 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 object 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 object 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 dissimilarity

The chemical dissimilarity matrices (cosine, MS2DeepScore, DreaMS) can be added to the mmo object. These are used for chemical dendrograms and chemical diversity analyses.

mmo <- AddChemdist( mmo, cos_dir = “path/to/cosine_dissimilarity.csv”, m2ds_dir = “path/to/ms2deepscore_dissimilarity.csv”, dreams_dir = “path/to/dreams_dissimilarity.csv” )

# Add Dreams distance
mmo <- AddChemDist(mmo, 
                   dreams_dir = demo_dreams)

mmo$dreams.dissim[1:10,1:10]

Adding custom annotations

You can add your own custom compound annotations to the mmo object 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 MMO Objectes based on feature list or sample list

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


#Create a new mmo object 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 object 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 an MMO object.

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
  1. Given a feature list in an mmo object defined by mmofeaturedatafeature_dataid 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")