Chemical structure representation conversion

chemical-structure-representation-conversion

Summary

Convert between different chemical structure representations (e.g., SMILES to InChI) using RDKit as a local compute backend within MSMetaEnhancer. This skill enables offline chemical metadata enrichment of .msp files without relying on external web services.

When to use

When you have .msp mass spectrometry metadata containing chemical identifiers (e.g., compound names or SMILES strings) and need to compute derived chemical properties (e.g., InChI, InChIKey, molecular formula) locally without network latency or service availability constraints.

When NOT to use

• When the input .msp file already contains all required chemical metadata (e.g., InChI, formula, InChIKey are already present).
• When the source identifier is ambiguous or contains drawing/image data that RDKit cannot parse into a valid molecular structure.
• When network latency is acceptable and you need access to curated, validated chemical databases (use web service converters like PubChem or IDSM instead).

Inputs

• SMILES string
• source chemical identifier (name, InChI, CAS number, or other structure format)
• ComputeConverter class template

Outputs

• InChI string
• InChIKey string
• molecular formula
• canonical SMILES
• chemical metadata dictionary

How to apply

Create a new ComputeConverter subclass in MSMetaEnhancer/libs/converters/compute/ that inherits from ComputeConverter and defines a conversions list with source and target attributes (e.g., 'smiles' to 'inchi'). Implement conversion methods using RDKit functions (e.g., Chem.MolFromSmiles to parse SMILES, Chem.inchi.MolToInchi to generate InChI) and call create_top_level_conversion_methods with asynch=False to expose those conversions as top-level methods. Return converted data as a dictionary with target attribute keys. Register the converter in MSMetaEnhancer/libs/converters/compute/init.py and validate with pytest tests that verify converter instantiation, conversion accuracy against reference SMILES inputs, and output chemical correctness before running the full MSMetaEnhancer annotation pipeline.

Related tools

• RDKit (Local molecular structure parser and converter; implements Chem.MolFromSmiles, Chem.inchi.MolToInchi, and related cheminformatics transformations)
• MSMetaEnhancer (Container application that registers and orchestrates converters (both web and compute) to enrich .msp mass spectrometry metadata) — https://github.com/RECETOX/MSMetaEnhancer
• pytest (Test framework for validating converter instantiation, conversion accuracy, and chemical correctness before integration)

Examples

from MSMetaEnhancer.libs.converters.compute import RDKit; from MSMetaEnhancer.libs.utils.ConverterBuilder import ConverterBuilder; ConverterBuilder.register([RDKit]); app.annotate_spectra(services=['RDKit'], jobs=[('name', 'inchi', 'RDKit'), ('inchi', 'inchikey', 'RDKit')])

Evaluation signals

• Converter class instantiates without errors and is successfully imported in MSMetaEnhancer/libs/converters/compute/init.py.
• Conversion methods execute without raising exceptions on reference SMILES inputs (e.g., benzene 'c1ccccc1').
• Output dictionary structure matches expected keys (e.g., 'inchi', 'inchikey', 'formula') and values are non-empty strings.
• Chemical correctness: output InChI/InChIKey/formula matches known reference values for test molecules (e.g., benzene InChI='InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H').
• Pytest suite passes: all existing tests still pass and new converter tests execute successfully.

Limitations

• RDKit conversion accuracy depends on input SMILES validity; malformed or non-standard SMILES strings will fail to parse.
• Local compute approach scales linearly with number of conversions and cannot leverage distributed caching or batch optimization of web services.
• Conversion is synchronous (asynch=False); does not integrate with MSMetaEnhancer's asynchronous annotation pipeline for network-based converters.
• RDKit does not support all chemical formats or edge cases that specialized web services (CIR, CTS, PubChem) may handle (e.g., stereochemistry rendering, rare element support).

Evidence

• [other] Create a new Python file in MSMetaEnhancer/libs/converters/compute/ that inherits from ComputeConverter: "Create a new Python file in MSMetaEnhancer/libs/converters/compute/ that inherits from ComputeConverter."
• [other] Define the conversions list with source and target attributes (e.g., 'smiles' to 'inchi'): "Define the conversions list with source and target attributes (e.g., 'smiles' to 'inchi') and call create_top_level_conversion_methods with asynch=False."
• [other] Implement conversion methods using RDKit to perform local molecular structure transformations: "Implement conversion methods using RDKit to perform local molecular structure transformations (e.g., parse SMILES strings with RDKit Chem.MolFromSmiles and generate InChI with Chem.inchi.MolToInchi)."
• [other] Return converted data as a dictionary with target attribute keys.: "Return converted data as a dictionary with target attribute keys."
• [other] Register the new converter in MSMetaEnhancer/libs/converters/compute/init.py by importing and adding to all.: "Register the new converter in MSMetaEnhancer/libs/converters/compute/init.py by importing and adding to all."
• [other] Create a pytest test file that validates converter instantiation and tests conversion accuracy: "Create a pytest test file that validates converter instantiation and tests conversion accuracy against reference SMILES inputs, verifying output structure and chemical correctness."
• [other] MSMetaEnhancer uses RDKit as a reference implementation for implementing ComputeConverter subclasses: "MSMetaEnhancer uses RDKit as a reference implementation for implementing ComputeConverter subclasses that perform local chemical structure conversions."
• [readme] It adds metadata like SMILES, InChI, and CAS number fetched from the following services: "It adds metadata like SMILES, InChI, and CAS number fetched from the following services: [CIR], [CTS], [PubChem], [IDSM], and [BridgeDb]."