Transformation product data extraction

transformation-product-data-extraction

Summary

Extract and format transformation product (TP) data from patRoon TP objects into structured outputs (suspect lists or MetFrag-compatible databases) for downstream MS-based screening and annotation. This skill bridges TP prediction with high-resolution mass spectrometry screening workflows by converting predicted or library-sourced TPs into formats compatible with suspect screening and compound annotation algorithms.

When to use

After generating or obtaining a TP object (via generateTPs with library, in-silico, or BioTransformer algorithms) that contains SMILES, InChIKey, or formula information for transformation products, and you need to screen those TPs in LC-HRMS data or annotate them using MetFrag. Use this skill when your goal is to move from TP prediction to feature-level screening or when you need to prepare TP data for mass spectrometry-based identification workflows.

When NOT to use

• Input TP object lacks structural information (no SMILES, InChIKey, or formula) — extraction will fail or produce incomplete records.
• Target workflow is parent compound screening only; use standard suspect list generation instead of TP-specific extraction.
• You require TP annotation with fragmentation spectra; this skill handles chemical structure export only, not MS/MS matching.

Inputs

• TP object (generated by generateTPs or obtained from library source) containing transformation products with structural information (SMILES, InChIKey, or molecular formula)

Outputs

• Suspect list data.frame (suitable for screenSuspects function with columns: name, SMILES or formula, optional adduct/mass)
• MetFrag-compatible CSV database file (two columns: compound name and SMILES)

How to apply

Extract parent compound identifiers, names, and chemical descriptors (SMILES, InChIKey, or formula) from the TP object using the products() and parents() accessor functions. Decide whether to include parent compounds in the output (typically TRUE for end-to-end workflows, FALSE when parents are already annotated). Format the combined data into a tabular structure: for suspect screening, create a data.frame with columns for name, SMILES or formula, and optional adduct/mass columns matching screenSuspects input requirements; for MetFrag annotation, format as a CSV with name and SMILES columns only. Validate that all chemical identifiers are non-empty and syntactically valid (e.g., SMILES parseable) before export. Write to the target output file (CSV for MetFrag, data.frame returned in-memory for suspect screening).

Related tools

• patRoon (Provides TP object class, extraction accessors (products(), parents()), and conversion functions (convertToSuspects, convertToMFDB)) — https://github.com/rickhelmus/patRoon
• screenSuspects (Downstream function that consumes the suspect list data.frame output to screen for TP features in LC-HRMS data) — https://github.com/rickhelmus/patRoon
• MetFrag (External annotation tool that consumes the MetFrag-compatible CSV database for TP structure annotation and scoring)

Examples

suspects <- convertToSuspects(TPs, includeParents = TRUE); convertToMFDB(TPs, output = "tp_database.csv", includeParents = TRUE)

Evaluation signals

• Suspect list data.frame contains all expected rows (number of TPs + optional parents matches object size) with no missing name or structure columns.
• SMILES strings in output are syntactically valid and parseable by MetFrag or cheminformatics libraries (e.g., no truncation or encoding errors).
• CSV file for MetFrag contains exactly two columns (name and SMILES) with consistent row count and no empty cells in structure column.
• When includeParents=TRUE, parent compound names and structures appear in output and are distinguishable from TP records (e.g., by name prefix or metadata column if applicable).
• Output file is readable by downstream tool (screenSuspects or MetFrag) without format errors or column mismatch warnings.

Limitations

• TP objects must contain structural information (SMILES, InChIKey, or formula); library sources lacking chemical descriptors will produce empty or incomplete output.
• Parents are only included in the output when includeParents=TRUE and structural information is available for the TPs; orphaned parent records are omitted.
• InChIKey and formula outputs are supported for suspect list generation but not for MetFrag CSV export, which requires SMILES.
• Duplicate structures (e.g., isomers with identical SMILES) are preserved in output; post-hoc deduplication must be performed separately if needed.
• No built-in validation of chemical plausibility or synthetic feasibility; output reflects predictions from underlying TP algorithms (BioTransformer, CTS, PubChemLite) which may include artefactual or low-probability products.

Evidence

• [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"
• [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 extracted data into a suspect list data.frame with required columns (name, SMILES or formula, and optional adduct/mass columns).: "Format extracted data into a suspect list data.frame with required columns (name, SMILES or formula, and optional adduct/mass columns)."
• [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)."