Mass Spectrometry Compound Annotation Database Generation

---
name: mass-spectrometry-compound-annotation-database-generation
description: Use when after generating transformation products using generateTPs() with structural information (SMILES), when you need to screen for predicted TP compounds in environmental MS/MS data via MetFrag's in-silico fragmentation annotation.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3282
  edam_topics:
  - http://edamontology.org/topic_0625
  - http://edamontology.org/topic_3172
  tools:
  - patRoon
  - MetFrag
  - BioTransformer
  - CTS
  techniques:
  - LC-MS
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",
- convertToMFDB | Generates a [MetFrag] database for all TPs (and optionally parents, only for TPs with structural information)
- Generates a [MetFrag] database for all TPs
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 Compound Annotation Database Generation

## Summary

Generate MetFrag-compatible chemical databases from transformation product (TP) objects to enable high-resolution mass spectrometry based compound annotation and in-silico fragmentation matching. This skill bridges TP prediction workflows with spectral matching by formatting structural and chemical metadata into standardized database formats.

## When to use

After generating transformation products using generateTPs() with structural information (SMILES), when you need to screen for predicted TP compounds in environmental MS/MS data via MetFrag's in-silico fragmentation annotation. Use this when TP objects contain valid SMILES for at least the transformation products (parent SMILES are optional but recommended for structural context).

## When NOT to use

- TPs object lacks structural information (SMILES) — convertToMFDB requires valid SMILES for TPs to function correctly
- Transformation products are already annotated and you only need compound identification (not database generation for new matching)
- Input is not a patRoon TPs object or parent/TP data is not in SMILES format

## Inputs

- TPs object (transformation products) generated by generateTPs() with SMILES structural information
- Optional: parent compound names and SMILES (extracted via parents() accessor)
- Output file path (CSV destination)

## Outputs

- MetFrag-compatible CSV database file with two columns: compound name and SMILES
- Rows include all transformation products; parent compounds optionally included

## How to apply

Load a TPs object from generateTPs() containing transformation products and extract parent names, SMILES, and TP names and SMILES using the products() and parents() accessors. Optionally include parent compound records by setting includeParents=TRUE, which adds structural context but is only applied when TPs contain structural information. Format the combined parent/TP data into a two-column CSV table (compound name and SMILES in MetFrag database format). Write the formatted table to a local CSV file at the specified output path. Verify the output CSV is readable by MetFrag by checking that the name and SMILES columns are present and SMILES strings are chemically valid (e.g., no truncation, valid syntax).

## Related tools

- **patRoon** (Orchestrates TP generation and provides convertToMFDB() function for database formatting; accessors products() and parents() extract structural data from TPs objects) — https://github.com/rickhelmus/patRoon
- **MetFrag** (Accepts the generated CSV database for in-silico fragmentation and compound annotation matching against MS/MS spectra)
- **BioTransformer** (Optional upstream tool: generates TPs via generateTPs(algorithm='biotransformer', ...) that are then converted to MetFrag database format)
- **CTS** (Optional upstream tool: generates TPs via generateTPs(algorithm='cts', ...) that are then converted to MetFrag database format)

## Examples

```
convertToMFDB(TPs = generateTPs('biotransformer', parents = suspects), includeParents = TRUE, file = 'tp_database.csv')
```

## Evaluation signals

- Output CSV file exists at specified path and is readable by standard CSV parsers
- CSV contains exactly two columns with headers for compound name and SMILES
- All SMILES strings in the database are non-empty and syntactically valid (no truncation, proper bracket nesting, valid atom symbols)
- Number of rows matches expected count: total TPs + (parent compounds if includeParents=TRUE and structural data present)
- MetFrag can successfully load and parse the CSV without errors during database initialization

## Limitations

- convertToMFDB only includes parent compound records when structural information (SMILES) is available for the TPs; parents without corresponding TP SMILES are excluded
- Database generation requires all TPs to have valid SMILES; TPs with missing or malformed SMILES will cause function failure or data loss
- Output is a static CSV snapshot; database must be regenerated if new TPs are added or SMILES are corrected upstream
- No automatic validation that SMILES are chemically realistic — syntax validation occurs but not stereochemical or structural plausibility checking

## Evidence

- [other] convertToMFDB generates a MetFrag-compatible database file for all transformation products (TPs) and optionally includes parent compounds, with the constraint that parents are only included when structural information is available for the TPs.: "convertToMFDB generates a MetFrag-compatible database file for all transformation products (TPs) and optionally includes parent compounds, with the constraint that parents are only included when"
- [other] Extract parent names, SMILES, and TP names and SMILES from the TPs object using the products() and parents() accessors.: "Extract parent names, SMILES, and TP names and SMILES from the TPs object using the products() and parents() accessors."
- [other] Format the combined parent/TP data into a CSV table with columns for compound name and SMILES (MetFrag database format).: "Format the combined parent/TP data into a CSV table with columns for compound name and SMILES (MetFrag database format)."
- [other] convertToMFDB | Generates a MetFrag database for all TPs (and optionally parents, only for TPs with structural information): "convertToMFDB | Generates a MetFrag database for all TPs (and optionally parents, only for TPs with structural information)"
- [other] Verify the CSV is readable by MetFrag by checking column presence and SMILES validity.: "Verify the CSV is readable by MetFrag by checking column presence and SMILES validity."