Suspect List Format Conversion

---
name: suspect-list-format-conversion
description: Use when you have generated a set of transformation products (TPs) from
  one or more parent compounds using generateTPs (via BioTransformer, CTS, or PubChemLite
  library algorithms) and need to screen for these TPs in your LC-HRMS feature data.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3096
  edam_topics:
  - http://edamontology.org/topic_0218
  - http://edamontology.org/topic_3520
  - http://edamontology.org/topic_3172
  tools:
  - patRoon
  - generateTPs
  - screenSuspects
  - BioTransformer
  - CTS
  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
---

# Reconstruct suspect-list conversion with convertToSuspects for TP screening input

## Summary

Convert a transformation product (TP) object generated by generateTPs into a structured suspect list data.frame compatible with downstream screenSuspects screening. This enables systematic screening of predicted or library-derived TP candidates against LC-HRMS features.

## When to use

You have generated a set of transformation products (TPs) from one or more parent compounds using generateTPs (via BioTransformer, CTS, or PubChemLite library algorithms) and need to screen for these TPs in your LC-HRMS feature data. Apply this skill when you require a standardized suspect list format that matches the input requirements of screenSuspects, particularly when combining TP candidates with optional parent compound records for multi-stage screening workflows.

## When NOT to use

- The TP object was not generated by generateTPs or lacks required structural/formula metadata — convertToSuspects depends on specific TP object attributes and will fail or return incomplete records if data is malformed or missing.
- You are screening for a single static set of known suspects with pre-defined mass lists — use native suspect list loading (e.g., read.csv) instead; convertToSuspects is specific to TP workflows.
- Your downstream analysis does not require screenSuspects or uses a different screening tool with incompatible suspect list format — convertToSuspects is tightly coupled to patRoon's screenSuspects function.

## Inputs

- TP object (class 'transformationProducts' from patRoon::generateTPs output)
- parents() accessor results (optional; extracted from TP object if includeParents=TRUE)

## Outputs

- suspect list data.frame with columns: name, chemical identifier (SMILES or formula), optional adduct/mass columns
- data.frame formatted for input to patRoon::screenSuspects

## How to apply

Load the TP object (output from generateTPs) into convertToSuspects and set the includeParents parameter based on whether you wish to include parent compound records alongside transformation products. The function extracts parent and TP identifiers, names, and chemical descriptors (SMILES, InChIKey, or molecular formula) from the TP object, then reformats them into a data.frame with required columns: name, chemical identifier (SMILES or formula), and optional adduct/mass columns. Validate that the resulting data.frame structure matches the standard suspect screening format (same columns and data types expected by screenSuspects). The returned suspect list is then suitable for immediate input to screenSuspects for matching against detected features. Key decision: set includeParents=TRUE only if you intend to screen for parent compounds in addition to TPs; otherwise use FALSE to reduce computational load and false-positive burden during screening.

## Related tools

- **patRoon** (Provides convertToSuspects function and TP/suspect list object model; implements the full TP screening workflow) — https://github.com/rickhelmus/patRoon
- **generateTPs** (Upstream function that generates the TP object (input to convertToSuspects); wraps BioTransformer, CTS, or PubChemLite algorithms) — https://github.com/rickhelmus/patRoon
- **screenSuspects** (Downstream function that accepts the formatted suspect list output from convertToSuspects and screens LC-HRMS features against it) — https://github.com/rickhelmus/patRoon
- **BioTransformer** (Upstream TP prediction algorithm; can be specified in generateTPs(algorithm='biotransformer') to generate input TPs)
- **CTS** (Upstream TP prediction algorithm; can be specified in generateTPs(algorithm='cts') to generate input TPs)

## Examples

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

## Evaluation signals

- Output data.frame contains expected columns (name, SMILES or formula, and optional adduct/mass); structure matches schema required by screenSuspects
- If includeParents=TRUE, output includes both TP records (extracted from TP object) and parent compound records (from parents() accessor); if FALSE, output contains only TPs
- All rows in output data.frame have non-null values for required columns (name and chemical identifier); optional columns may be NA where not applicable
- Row count and composition reflect input TP object size and includeParents setting (e.g., if TP object has 50 TPs and includeParents=TRUE with 3 parents, output should have ≥53 rows)
- Output can be directly passed to screenSuspects without format conversion errors (e.g., screenSuspects(fGroups, convertToSuspects(TPs, includeParents=TRUE), ...) executes without exception)

## Limitations

- convertToSuspects requires that the input TP object contains structural information (SMILES, InChIKey, or formula); TP objects generated without chemical descriptors cannot be converted to a valid suspect list
- The function does not validate chemical descriptor quality or uniqueness; duplicate SMILES/formulas in the output may lead to redundant screening hits and increased computational burden in screenSuspects
- includeParents parameter is a binary toggle with no fine-grained control; users cannot selectively include only specific parent compounds or apply additional filtering during the conversion step
- TP naming and metadata depend on the quality and detail of the upstream TP generation algorithm (BioTransformer, CTS, PubChemLite); poorly annotated or synthetic TP records may result in confusing or uninformative suspect list entries

## 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 and TP identifiers, names, and chemical identifiers (SMILES, InChIKey, or formula) from the TPs object. Format extracted data into a suspect list data.frame with required columns (name, SMILES or formula, and optional adduct/mass columns).: "Extract parent and TP identifiers, names, and chemical identifiers (SMILES, InChIKey, or formula) from the TPs object. Format extracted data into a suspect list data.frame with required columns"
- [other] If includeParents=TRUE, append parent compound records to the suspect list using parents() function.: "If includeParents=TRUE, append parent compound records to the suspect list using parents() function."
- [other] Validate suspect list structure matches the format required by screenSuspects (same as standard suspect screening format).: "Validate suspect list structure matches the format required by screenSuspects (same as standard suspect screening format)."
- [other] suspects <- convertToSuspects(TPs, includeParents = TRUE): "suspects <- convertToSuspects(TPs, includeParents = TRUE)"