Skip to content

scientific-basis.md

Latest commit

 

History

History
133 lines (103 loc) · 7.98 KB

scientific-basis.md

File metadata and controls

133 lines (103 loc) · 7.98 KB
Raw

Scientific basis, representation choices, and limitations

1. Why this is not literally “anything to SMILES”

SMILES is a line notation for a molecular graph. It can encode atoms, bonds, formal charges, isotopes, and stereochemistry, but it does not inherently preserve database provenance, FASTA headers, residue numbering, conformational ensembles, biological assemblies, pH, or experimental conditions. The OpenSMILES specification is the syntax reference used when discussing SMILES behavior in this project.

Consequences:

  • protein sequence → SMILES chooses a specific covalent structure, termini, stereochemistry, and protonation representation;
  • SMILES → sequence is only offered when residue/monomer metadata survives the conversion;
  • canonical SMILES is canonical only with respect to a particular toolkit and configuration;
  • a fingerprint is a lossy feature vector and must never be used as an identity key.

For cross-database identity exchange, Standard InChI/InChIKey is often a better companion to SMILES. IUPAC describes InChI as a non-proprietary identifier intended to connect chemical data sources: IUPAC InChI overview.

2. Peptides and modifications

The original script directly concatenated amino-acid SMILES fragments. This project keeps that useful transparent strategy for mixed L/D peptides and selected PTMs, but validates every resulting molecule with RDKit.

The annotation syntax is inspired by ProForma 2.0. ProForma is a community standard for expressing specific proteoforms and peptidoforms, including terminal modifications, controlled-vocabulary terms, mass shifts, ambiguity, glycans, cross-links, and isotopes. The current parser implements only the structure-resolvable subset listed in the README. It accepts selected site-aware Unimod names/accessions and custom structure registries, but rejects constructs whose mass annotation cannot be mapped to one unambiguous molecular graph.

Primary reference: LeDuc et al., “ProForma 2.0: Unifying the Encoding of Proteoforms and Peptidoforms,” Nature Methods (2022), doi:10.1038/s41592-021-01196-8.

Unimod is used as a controlled-vocabulary reference for selected built-in aliases. MolTranscode implements only explicitly tested site/structure combinations; accepting one Unimod accession does not imply support for every specificity, neutral loss, or isotopic variant in that record. See the Unimod database and the modification-system documentation.

For complex, non-natural biomolecules, HELM is a better scalable abstraction than raw atom-level SMILES. HELM was designed for peptides, proteins, nucleic acids, chemical modifiers, and conjugates. RDKit's current HELM reader supports a peptide subset, which is the scope exposed here.

Primary reference: Zhang et al., “HELM: A Hierarchical Notation Language for Complex Biomolecule Structure Representation,” J. Chem. Inf. Model. (2012), doi:10.1021/ci3001925. See also the RDKit molecule file API for the exact FASTA/HELM capabilities of the installed RDKit release.

MolTranscode's non-natural-residue presets are a small, structure-tested convenience catalogue, not a comprehensive monomer ontology. They cover alpha-amino acids whose side chains can be substituted without changing the standard peptide-backbone template. SwissSidechain provides a broader curated molecular and structural resource for non-natural side chains: Gfeller et al., “SwissSidechain: a molecular and structural database of non-natural sidechains,” Nucleic Acids Research (2013), doi:10.1093/nar/gks991. IUPAC-IUB amino-acid nomenclature recommendations are the reference for conventional symbols and also document the limits of the one-letter system. There is no universal one-letter alphabet for arbitrary non-natural monomers, so MolTranscode emits explicit bracketed names such as M[Norleucine] rather than inventing new single-letter codes.

Structural conventions in version 0.2

  • uppercase residues are L and lowercase residues are D;
  • termini are neutral NH2/COOH unless acetylated/amidated;
  • phosphates are written as neutral phosphoric-acid forms, not as a pH-dependent microspecies;
  • histidine uses one explicit tautomer from the residue template;
  • M[Oxidation] means methionine sulfoxide but does not assign sulfur stereochemistry;
  • Lys methylation is placed on the epsilon nitrogen;
  • K[Crotonyl] does not assign alkene E/Z geometry;
  • terminal and side-chain registry fragments replace documented attachment regions rather than being merged as disconnected complete molecules;
  • multiple simultaneous side-chain modifications on one residue are rejected;
  • no disulfide, cyclic peptide, cross-link, glycan, or ambiguous localization is inferred.

These conventions are representation choices, not claims about the dominant solution-state microstate. A future standardization layer should expose charge/tautomer policy explicitly.

Custom registry files are executable only in the chemical sense: MolTranscode reads them as data and never evaluates Python or shell code, but a syntactically valid fragment can still encode the wrong chemical structure. Registry files, references, and checksums should therefore be treated as part of result provenance.

3. Molecular representations and fingerprints

RDKit provides parsing, sanitization, canonicalization, descriptors, and fingerprint generators. The implementation uses the generator API for Morgan, Atom Pair, and Topological Torsion fingerprints and exposes RDKit path and MACCS keys as additional baselines. Consult the RDKit Book fingerprint notes for toolkit-specific details.

Morgan fingerprints are closely related to extended-connectivity fingerprints, which were designed for molecular characterization and structure–activity modeling:

Rogers and Hahn, “Extended-Connectivity Fingerprints,” J. Chem. Inf. Model. (2010), doi:10.1021/ci100050t.

Fingerprint parameters (kind, bit length, radius, RDKit version) are part of the data provenance. Bit collisions mean two different molecules can share a folded fingerprint.

SELFIES is provided as an alternative molecular string representation useful in generative machine learning. Its design maps SELFIES strings to chemically valid graphs under its semantic constraints:

Krenn et al., “Self-referencing embedded strings (SELFIES): A 100% robust molecular string representation,” Machine Learning: Science and Technology (2020), doi:10.1088/2632-2153/aba947.

4. Name resolution

Chemical names, trade names, and CAS-like identifiers are database lookups rather than deterministic graph conversions. resolve-name therefore calls PubChem PUG-REST and keeps this network-dependent operation separate from local parsing. Users should verify the returned structure for ambiguous names. Service reference: Kim et al., “An update on PUG-REST,” Nucleic Acids Research (2018), doi:10.1093/nar/gky294, and the PubChem PUG-REST documentation.

5. Validation expectations

Automated validation should include:

  1. RDKit sanitization for every generated graph;
  2. expected formula/charge checks for representative PTMs;
  3. stereochemical regression tests for L/D residues and Ile/Thr side-chain centers;
  4. round trips only where the source model preserves enough information;
  5. comparison against curated HELM/ProForma structures before expanding the PTM registry.

Publication datasets should store the original input, normalized output, tool version, RDKit version, parameters, status, and error columns.