Parent Tp Mapping Structure

---
name: parent-tp-mapping-structure
description: Use when you have generated a TP object (from generateTPs) with structural
  information (SMILES) for predicted or library-derived transformation products, and
  you need to either (1) construct a MetFrag-compatible database that preserves parent
  compound records alongside TPs, or (2) componentize.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3282
  edam_topics:
  - http://edamontology.org/topic_0091
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_3370
  tools:
  - patRoon
  - BioTransformer
  - CTS
  - PubChem
  - MetFrag
  - PubChemLite
  techniques:
  - LC-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",
- '`generateTPs(algorithm = "biotransformer", ...)` | Parents | TPs structural information'
- '`generateTPs(algorithm = "cts", ...)` | Parents | TPs with structural information'
- Library ([PubChem][PubChemLiteTR] or custom)
- convertToMFDB | Generates a [MetFrag] database for all TPs (and optionally parents,
  only for TPs with structural information)
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
---

# Parent-TP Mapping with Structural Information

## Summary

Link transformation products (TPs) back to their parent compounds using SMILES structural data, enabling traceability and post-processing prioritization in non-target screening workflows. This skill bridges TP generation and downstream MS-based suspect screening by preserving parent–TP relationships through chemical structure.

## When to use

You have generated a TP object (from generateTPs) with structural information (SMILES) for predicted or library-derived transformation products, and you need to either (1) construct a MetFrag-compatible database that preserves parent compound records alongside TPs, or (2) componentize features by linking parent and TP signals in MS data. Apply this skill when parent structural annotation is available and you aim to improve TP identification confidence through parent–TP structural similarity or when building a searchable compound database for TP suspect screening.

## When NOT to use

- TPs were generated using formula-only algorithms (library_formula, ann_form, logic) with no SMILES available; parent records cannot be reliably included.
- Your analysis aims to screen for TPs in MS data without linking to parent compounds; use convertToSuspects and screenSuspects directly instead.
- You have already compiled a suspect list from other sources and do not need to generate or map TPs structurally.

## Inputs

- TPs object (from generateTPs) with SMILES-annotated transformation products
- parent compound names and optional structural data (SMILES)
- MS feature groups (fGroups) for TP screening (when componentizing)

## Outputs

- MetFrag-compatible CSV database file (columns: compound name, SMILES)
- Filtered and ranked TP candidates with parent–TP structural similarity scores
- TP component objects linking parent features to candidate TP features

## How to apply

Extract parent names and SMILES from the TPs object using the parents() accessor, then retrieve the corresponding TP names and SMILES using the products() accessor. Optionally include parent compound records (set includeParents=TRUE) only when structural information is available for the TPs; this ensures the MetFrag database does not contain orphaned parent entries. Format the combined parent/TP records into a CSV table with columns for compound name and SMILES (MetFrag standard format). Write to a local file and verify column presence and SMILES validity before downstream use. Alternatively, when componentizing, use the parent–TP relationship to filter TP candidates by structural similarity thresholds (e.g., minSimilarity=0.5) or retention time direction matching (retDirMatch=TRUE) to prioritize genuine metabolic transformations.

## Related tools

- **patRoon** (R package providing generateTPs, convertToMFDB, filter, and componentization functions for TP generation, structural mapping, and database export) — https://github.com/rickhelmus/patRoon
- **MetFrag** (In-silico compound annotation tool that accepts the CSV database generated by convertToMFDB for TP and parent compound identification)
- **BioTransformer** (Backend algorithm for in-silico TP prediction; generates SMILES structures via patRoon's generateTPs(algorithm='biotransformer'))
- **CTS** (Backend algorithm for in-silico TP prediction; generates SMILES structures via patRoon's generateTPs(algorithm='cts'))
- **PubChemLite** (Library source for TP candidates; provides pre-computed SMILES for parent–TP relationships via patRoon's generateTPs(algorithm='library'))

## Examples

```
TPsF <- filter(TPs, minSimilarity = 0.5, removeParentIsomers = TRUE); mfdb <- convertToMFDB(TPsF, includeParents = TRUE, path = 'metfrag_db.csv')
```

## Evaluation signals

- MetFrag CSV file is readable with exactly 2 columns (compound name, SMILES) and contains both parent and TP records with valid SMILES strings (no empty or malformed entries).
- TP Score (when using ann_comp or ann_form algorithms) incorporates parent structural similarity and suspect matching; filtered results (minSimilarity, topMost) show progressive enrichment for plausible metabolic changes.
- Componentization with generateComponents(algorithm='tp') successfully links parent feature intensities (treatment='before') to TP candidate features (treatment='after') with retention time direction matching (retDirMatch=TRUE) applied when formulas are available.
- Isomer filtering (removeParentIsomers=TRUE, removeTPIsomers=TRUE) reduces duplicate parent–TP pairs; minSimilarity threshold (e.g., 0.5) removes structurally implausible candidates.
- Parent records included in the database (includeParents=TRUE) only when TPs have SMILES; absence of orphaned parent-only rows confirms constraint is enforced.

## Limitations

- Parents can only be included in the MetFrag database when structural information (SMILES) is available for the TPs; formula-only TP algorithms (library_formula, ann_form, logic) will produce databases without parent records.
- Structural similarity filtering (minSimilarity) relies on fingerprint or descriptor-based comparison; soft matches may include chemically implausible transformations if the similarity threshold is set too permissively.
- Multi-step TP predictions (generations > 1) increase computational time and may introduce cumulative structural annotation errors; validation against reference TP libraries or MS/MS spectra is recommended.
- Retention time direction matching (retDirMatch) assumes consistent metabolic behavior across samples; environmental or matrix effects can violate this assumption, leading to false negatives.
- The parent–TP mapping assumes each TP has a single parent; polymeric, cluster, or multi-step fragmentation products may not be represented accurately in the parent–TP relationship.

## 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] For ann_comp and ann_form, rank candidates by TP Score incorporating structural similarity and suspect matching.: "For ann_comp and ann_form, rank candidates by TP Score incorporating structural similarity and suspect matching."
- [other] In the step the parent features are linked with the TP features. Several post-processing functionality exists to improve and prioritize the data.: "In the step the parent features are linked with the TP features. Several post-processing functionality exists to improve and prioritize the data."
- [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] Automatic screening of TPs using library/_in-silico_ data, MS similarities and classifications. Tools to improve compound TP annotation.: "Automatic screening of TPs using library/_in-silico_ data, MS similarities and classifications. Tools to improve compound TP annotation."