Smiles Structure Representation Handling

---
name: smiles-structure-representation-handling
description: Use when you have generated a TPs object (via generateTPs) containing transformation products with structural information and need to export these structures for MetFrag database creation, suspect screening list construction, or chemical similarity filtering.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3346
  edam_topics:
  - http://edamontology.org/topic_0154
  - http://edamontology.org/topic_3172
  tools:
  - patRoon
  - MetFrag
  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
---

# SMILES structure representation handling

## Summary

Extract, validate, and format SMILES strings from transformation product (TP) and parent compound objects for downstream chemical database generation and MS-based screening workflows. This skill ensures structural information is accurately represented and compatible with external tools like MetFrag.

## When to use

You have generated a TPs object (via generateTPs) containing transformation products with structural information and need to export these structures for MetFrag database creation, suspect screening list construction, or chemical similarity filtering. Trigger: structural data is available for TPs and you require a standardized chemical representation format compatible with external tools.

## When NOT to use

- TPs object contains no structural information (no SMILES available for any TP); convertToMFDB will fail or produce incomplete output.
- You require 3D conformer information or stereochemistry beyond what SMILES representation encodes; SMILES is a linear notation and does not capture 3D spatial geometry.
- Parent compound structures are needed regardless of TP structural availability; patRoon's convertToMFDB enforces inclusion only when TP structures exist.

## Inputs

- TPs object (generated by generateTPs) containing transformation products with SMILES
- parent compound set (optional, from patRoon data accessors)

## Outputs

- CSV file with MetFrag-compatible database format (name, SMILES columns)
- validated SMILES strings for all exported compounds

## How to apply

Extract parent and TP SMILES strings from the TPs object using patRoon's products() and parents() accessors. Validate SMILES strings for chemical validity and ensure all TPs contain structural information before including parents (parents are only included when structural data exists for TPs). Format the combined parent/TP data into a CSV table with two columns: compound name and SMILES, conforming to MetFrag database schema. Write to a local CSV file and verify column presence and SMILES validity before downstream use. The constraint that parents require TP structural information ensures data integrity and consistency in the exported database.

## Related tools

- **patRoon** (Core workflow environment; provides generateTPs(), products(), parents() accessors and convertToMFDB() function for SMILES extraction and formatting.) — https://github.com/rickhelmus/patRoon
- **MetFrag** (Downstream consumer of the generated database; requires CSV input with name and SMILES columns for compound annotation against MS/MS data.)

## Examples

```
convertToMFDB(TPs, includeParents = TRUE, output = 'tp_database.csv')
```

## Evaluation signals

- CSV file contains exactly two columns with headers 'name' and 'SMILES' (or equivalent MetFrag schema).
- All SMILES strings in the output are valid chemical notation (parseable by RDKit or CDK).
- Row count equals sum of parent records (when includeParents=TRUE and TP structures exist) plus all TP records.
- No null or empty SMILES values in output when TP structural data was available in the input object.
- CSV is readable by MetFrag without schema validation errors.

## Limitations

- SMILES representation does not preserve stereochemical or 3D conformer information; if stereoisomers or 3D spatial information is critical, additional molecular descriptors or file formats (MOL, SDF) are required.
- Parent compounds are only included in the output when structural information is available for at least one TP; if all TPs lack SMILES, parents are excluded even if includeParents=TRUE.
- SMILES validity depends on upstream generateTPs algorithm quality; incorrect or incomplete structure generation by BioTransformer, CTS, or library sources will propagate through to the CSV output.

## Evidence

- [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] 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] 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] 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."