Compound structure representation

compound-structure-representation

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Encode chemical structures as SMILES strings and spectroscopic metadata (precursor m/z, charge, adduct) into Compound objects for downstream mass spectrometry analysis. This skill is essential for initializing structured chemical representations that link molecular topology to experimental ionization and fragmentation data.

When to use

When you have experimental MS/MS data (peak lists, precursor m/z, charge state, adduct type) paired with a chemical structure (SMILES or structural identifier), and need to create a unified Compound object for spectral alignment, modification-site prediction, or comparative fragmentation analysis. Use this skill as the first step before running ModiFinder or any tool that requires both molecular identity and tandem mass spectra.

When NOT to use

• Peak list is already aggregated into a feature table or consensus spectrum without individual precursor information.
• SMILES or structural annotation is unavailable and only spectral similarity (not structure-aware alignment) is needed.
• Input spectra require custom preprocessing parameters (e.g., different mz_tolerance or peak-filtering thresholds) not compatible with ModiFinder defaults.

Inputs

• Peak list (list of [m/z, intensity] pairs)
• Precursor m/z (float)
• Precursor charge state (integer)
• Adduct annotation (string, e.g., '[M+H]+', '[M-H]-')
• SMILES string (str)

Outputs

• Compound object with normalized spectrum and structural metadata
• Preprocessed peak array with applied tolerance and intensity filtering
• RDKit molecule object for visualization and atom indexing

How to apply

Instantiate a Compound object by providing: (1) a peak list formatted as [[m/z, intensity], ...]; (2) precursor_mz (float); (3) precursor_charge (integer); (4) adduct string (e.g., '[M+H]+', '[M-H]-'); and (5) SMILES string (required for known compounds, optional for modified compounds). Apply default preprocessing during construction with mz_tolerance=0.01, ppm_tolerance=40, ratio_to_base_peak=0.01, and normalize_peaks=True to standardize peak representation. The SMILES encoding ensures that structural features (atoms, bonds, functional groups) can be mapped to fragment ions during spectral alignment and enable per-atom modification-site probability calculation.

Related tools

• ModiFinder (Consumes Compound objects to perform tandem mass spectral alignment and modification-site probability prediction.) — https://github.com/Wang-Bioinformatics-Lab/ModiFinder_base
• RDKit (Parses SMILES strings into molecule objects and enables structure visualization and atom indexing.) — http://www.rdkit.org/
• GNPS Compound class (Alternative constructor to fetch pre-annotated compounds from GNPS using accession identifiers.) — https://github.com/Wang-Bioinformatics-Lab/ModiFinder_base

Examples

main_compound = Compound(spectrum=[[101.02, 999], [119.03, 500]], precursor_mz=200.05, precursor_charge=1, adduct='[M+H]+', smiles='CC(=O)O'); mod_compound = Compound(spectrum=[[101.02, 450], [135.04, 999]], precursor_mz=216.04, precursor_charge=1, adduct='[M+H]+', smiles=None)

Evaluation signals

• Compound object is instantiated without error and contains all required attributes: spectrum (normalized peak list), precursor_mz, precursor_charge, adduct, SMILES.
• Peak intensities are normalized (maximum intensity = 1.0 or equivalent); small peaks below ratio_to_base_peak=0.01 threshold are removed.
• RDKit molecule object is valid: SMILES parses without errors, atom count and connectivity match chemical formula.
• Precursor m/z and charge state satisfy chemical plausibility checks (e.g., charge consistent with adduct type, precursor m/z > 0).
• Compound pair (known + modified) can be passed to ModiFinder without type errors; generate_probabilities() executes successfully.

Limitations

• SMILES parsing requires valid SMILES syntax; invalid or non-standard SMILES will raise RDKit exceptions.
• Default preprocessing (mz_tolerance=0.01, ppm_tolerance=40) may be too strict for low-resolution or high-noise spectra, potentially removing valid fragments.
• Precursor m/z and charge state must be experimentally accurate; misassignment will propagate incorrect neutral mass and fragment hypotheses to downstream ModiFinder calculations.
• Adduct annotation must match the ion type present in the MS/MS data; incorrect adduct specification will misalign theoretical fragments to observed peaks.

Evidence

• [other] Instantiate a ModiFinder object with the known compound, modified compound, and default CosineAlignmentEngine and MAGMaAnnotationEngine.: "Retrieve the known and modified compounds from GNPS using their accession identifiers via the Compound class constructor, applying default preprocessing (mz_tolerance=0.01, ppm_tolerance=40,"
• [readme] ModiFinder requires two spectrum objects: main_compound with SMILES, precursor_mz, precursor_charge, adduct; mod_compound with same metadata.: "ModiFinder requires two spectrum objects:

main_compound = Compound(
    spectrum=s1_peaks,
    precursor_mz=s1_prec_mz,
    precursor_charge=s1_charge,
    adduct=s1_adduct,"
- [intro] Compound objects link spectral data to molecular structure for modification-site localization.: "ModiFinder is a tool for site localization of structural modifications using MS/MS data."