Mass Spectrometry Screening Workflows

---
name: mass-spectrometry-screening-workflows
description: Use when when you have high-resolution LC-MS or GC-MS data from environmental
  samples and need to simultaneously screen for both known suspect chemicals and their
  transformation products, rather than targeting single compounds.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3802
  edam_topics:
  - http://edamontology.org/topic_0593
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0154
  tools:
  - patRoon
  - XCMS
  - OpenMS
  - BioTransformer
  - CTS
  - PubChem/PubChemLite
  - MetFrag
  - SIRIUS
  - CAMERA
  - RAMClustR
  - ProteoWizard
  techniques:
  - LC-MS
  - GC-MS
  - ion-mobility-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1186/s13321-020-00477-w
  title: patRoon
evidence_spans:
- The `generateTPs` function is used to obtain TPs for a particular set of parents.
- componTP <- generateComponents(algorithm = "tp",
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_patroon_cq
    doi: 10.1186/s13321-020-00477-w
    title: patRoon
  dedup_kept_from: coll_patroon_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1186/s13321-020-00477-w
  all_source_dois:
  - 10.1186/s13321-020-00477-w
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# Mass-Spectrometry Screening Workflows

## Summary

A comprehensive non-target analysis (NTA) workflow for environmental mass spectrometry that combines feature extraction, suspect screening, annotation, and transformation product (TP) detection into a coordinated pipeline. The workflow integrates multiple algorithms and data sources to identify and characterize known and suspected chemicals from high-resolution MS data.

## When to use

When you have high-resolution LC-MS or GC-MS data from environmental samples and need to simultaneously screen for both known suspect chemicals and their transformation products, rather than targeting single compounds. This is particularly appropriate when you have parent compound lists or libraries available and want to leverage multiple annotation algorithms to improve compound identification confidence.

## When NOT to use

- Input is already a curated list of identified compounds and no screening is needed.
- You only have low-resolution MS data or precursor m/z without MS/MS spectra, as annotation algorithms require sufficient spectral detail.
- The parent compound list is not available and you have no library data or reliable in-silico TP prediction resource.

## Inputs

- Raw MS data files (vendor format or mzML)
- Suspect list (data.frame with name, SMILES/formula, optional adduct columns)
- Parent compound list or library (for TP generation)
- Feature groups (fGroups object from feature extraction)
- Transformation product object (TPs generated by generateTPs)

## Outputs

- Feature groups with suspect screening hits (screenSuspects result)
- Suspect list with TP candidates (convertToSuspects output)
- Formula-annotated features
- Compound-annotated features with identification confidence levels
- Componentized feature groups (isotopes, adducts, homologs, TP–parent links)
- HTML report with all workflow results and prioritized identifications

## How to apply

Begin by preprocessing raw MS data (vendor format to mzML conversion and calibration), then extract and group features across replicates using algorithms such as XCMS, OpenMS, or enviPick. For parent screening, use native suspect screening with known chemical lists (by MS/MS similarity, chromatographic retention, or mass tolerance). Simultaneously or subsequently, generate transformation product candidates using generateTPs with algorithms like BioTransformer, CTS, or PubChemLite libraries. Convert TP objects to suspect list format using convertToSuspects (optionally including parent compounds), then screen for TPs in the feature data using screenSuspects. Perform formula annotation (via GenForm or SIRIUS) and compound annotation (MetFrag or SIRIUS) on detected suspects. Finally, group related features into components using componentization (RAMClustR, CAMERA, or OpenMS) to improve annotation confidence and link parents with detected TPs. Apply filtering and prioritization throughout (e.g., minSimilarity, minTPScore, retDirMatch) to reduce false positives and focus on high-confidence identifications.

## Related tools

- **patRoon** (Orchestrates entire NTA workflow, provides unified interface for feature extraction, suspect screening, TP generation/screening, annotation, and reporting) — https://github.com/rickhelmus/patRoon
- **XCMS** (Feature extraction and grouping algorithm for peak picking and retention time alignment) — https://github.com/sneumann/xcms
- **OpenMS** (Alternative feature extraction, raw data processing, and componentization algorithm) — http://openms.de/
- **BioTransformer** (In-silico prediction of biotransformation products)
- **CTS** (Chemical Transformation Simulator for prediction of environmental and metabolic TPs)
- **PubChem/PubChemLite** (Library-based source of known transformation product structures and metadata)
- **MetFrag** (In-silico MS/MS fragmentation prediction and compound annotation)
- **SIRIUS** (Formula annotation and compound annotation from MS/MS data)
- **CAMERA** (Componentization: grouping of related features (adducts, isotopes, homologs))
- **RAMClustR** (Hierarchical clustering of features into components based on MS/MS similarity)
- **ProteoWizard** (MS format conversion (vendor to mzML) and raw data pretreatment)

## Examples

```
suspects <- convertToSuspects(TPs, includeParents = TRUE); fGroupsScr <- screenSuspects(fGroups, suspects, onlyHits = TRUE)
```

## Evaluation signals

- Feature extraction produces consistent feature groups across replicate analyses with expected isotope and adduct patterns (detected by CAMERA or OpenMS componentization).
- Suspect screening returns features with mass error within specified tolerance (typically ≤ 5 ppm for HRMS) and chromatographic/MS/MS similarity scores above configured thresholds (e.g., cosine > 0.7).
- TP screening successfully links detected TP features to parent features via componentization (retDirMatch filter validates retention time and MS pattern consistency).
- Identification confidence levels are automatically assigned and reflect annotation agreement: features with matches from both formula and compound annotation algorithms receive higher confidence than single-algorithm matches.
- Final HTML report displays hierarchical parent–TP relationships, annotation source provenance, and filtering statistics (e.g., number of features retained after blank filtering, intensity thresholds).

## Limitations

- TP prediction and screening depend on availability and quality of transformation product data; predicted TPs from in-silico tools may not capture all environmentally or biologically relevant transformations.
- Annotation confidence relies on spectral quality (MS/MS signal-to-noise) and presence of reference spectra or reliable predictors; low-abundance features or those lacking diagnostic fragments may remain unidentified despite correct mass match.
- Isomer discrimination is limited; convertToSuspects and screening may not distinguish between structural isomers sharing the same SMILES canonical form or InChIKey, leading to ambiguous annotations.
- Workflow is optimized for hyphenated MS techniques (LC–MS/GC–MS); ion mobility separation (IMS) support added in patRoon 3.0+ requires additional configuration and CCS reference data.
- Computational cost scales with sample size and algorithm choice; parallel processing via future package helps but large studies may require high-memory computing environments.

## Evidence

- [intro] patRoon aims to provide comprehensive mass spectrometry based non-target analysis (NTA) workflows for environmental analysis: "`patRoon` aims to provide comprehensive mass spectrometry based non-target analysis (NTA) workflows for environmental analysis"
- [other] During this step a common patRoon workflow is used to screen for the parent chemicals of interest. Data is obtained of potential TPs for the parents of interest. The TPs may originate from a library or predicted in-silico. A suspect screening is performed to find the TPs in the analysis data. In the step the parent features are linked with the TP features.: "During this step a common `patRoon` workflow is used to screen for the parent chemicals of interest. Data is obtained of potential TPs for the parents of interest. The TPs may originate from a"
- [other] convertToSuspects converts a TP object into a suspect list format that can be used as input for screenSuspects, with an optional includeParents parameter to include parent compounds in addition to transformation products.: "convertToSuspects converts a TP object into a suspect list format that can be used as input for screenSuspects, with an optional includeParents parameter to include parent compounds in addition to"
- [other] Screening for TPs, i.e. chemicals that are formed from a parent chemical by e.g. chemical or biological processes, has broad applications.: "Screening for TPs, i.e. chemicals that are formed from a _parent_ chemical by e.g. chemical or biological processes, has broad applications."
- [readme] patRoon combines established software tools with novel functionality in order to provide comprehensive NTA workflows. The different algorithms are provided through a consistent interface, which removes the need to know all the details of each individual software tool and performing tedious data conversions during the workflow.: "`patRoon` combines established software tools with novel functionality in order to provide comprehensive NTA workflows. The different algorithms are provided through a consistent interface"
- [readme] Fully open-source (GPLv3), REUSE compliant. Developed on Windows, Linux and macOS. S4 classes and generics are used to implement a consistent interface to all supported algorithms.: "S4 classes and generics are used to implement a consistent interface to all supported algorithms"