Skip to content

README.md

Latest commit

 

History

History
274 lines (217 loc) · 10.6 KB

README.md

File metadata and controls

274 lines (217 loc) · 10.6 KB
Raw

MolTranscode

简体中文

CI Python License: MIT

MolTranscode is an auditable, batch-friendly toolkit for transcoding molecular representations without hiding chemical ambiguity. It connects peptide and protein sequences, small-molecule formats, line notations, descriptors, and fingerprints through one Python API and command-line interface.

Molecular representations are not universally lossless. SMILES stores a molecular graph, not a FASTA header, residue numbering, conformational ensemble, pH, or experimental context. An arbitrary SMILES string therefore cannot be claimed to have one uniquely recoverable peptide sequence.

Highlights

  • Inputs: peptide/protein sequences, FASTA, peptide HELM, SMILES, InChI, SELFIES, MOL, SDF, PDB, CSV, TSV, TXT, and JSONL
  • Outputs: canonical/isomeric SMILES, InChI, InChIKey, SELFIES, MOL, SDF, PDB, and metadata-assisted FASTA/sequence/HELM
  • Linear L/D peptide construction with explicit termini, backbone N-methylation, curated PTMs, and site-aware Unimod aliases
  • Layerable JSON registries and a Python API for custom side-chain and terminal structures
  • Optional bilingual browser workbench for one-at-a-time conversion, visual peptide modification, fingerprints, descriptors, result history, and custom registry editing
  • Morgan, RDKit path, MACCS, Atom Pair, Topological Torsion, and sequence k-mer fingerprints
  • Formula, exact mass, MolLogP, TPSA, HBD/HBA, rotatable-bond, heavy-atom, and charge descriptors
  • Optional PubChem PUG-REST name resolution, kept separate from deterministic local conversion
  • Per-record status and error fields for resilient batch processing

Installation

MolTranscode supports Python 3.10 and newer.

git clone https://github.com/PerinMu/MolTranscode.git
cd MolTranscode
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .

For development:

python -m pip install -e '.[dev]'
pytest
ruff check .

Install the optional graphical workbench:

python -m pip install -e '.[gui]'
moltranscode gui

The interface opens locally at http://localhost:8501. It does not upload structures to a remote service. Use --no-browser, --host, or --port when a different launch configuration is needed.

Quick start

# Standard and modified peptides; lowercase residues are D amino acids
moltranscode convert ACDY --from peptide --to smiles
moltranscode convert 'Ac-AK[Dimethyl]S[Phospho]M[Oxidation]-NH2' \
  --from peptide --to smiles

# Site-aware controlled-vocabulary aliases
moltranscode convert 'AS[UNIMOD:21]M[UNIMOD:35]K[UNIMOD:121]' \
  --from peptide --to inchikey

# Small-molecule representations
moltranscode convert 'CC(=O)Oc1ccccc1C(=O)O' --from smiles --to inchi
moltranscode convert 'InChI=1S/CH4/h1H4' --from inchi --to canonical-smiles
moltranscode convert '[C][C][O]' --from selfies --to smiles

# Fingerprints and descriptors
moltranscode fingerprint 'CCO' --from smiles --kind morgan --format hex
moltranscode fingerprint MKWVTFISLL --from sequence --kind kmer --bits 512 --k 3
moltranscode describe 'K[Succinyl]' --from peptide

# Inspect the active format and modification registry
moltranscode formats
moltranscode formats --json

Automatic input detection is deliberately conservative. For example, CC can mean ethane SMILES or a two-cysteine peptide, so MolTranscode asks for an explicit --from value.

Peptide notation and built-in modifications

MolTranscode accepts a documented, structure-resolving ProForma-inspired subset. It supports controlled-vocabulary names and selected accessions, but does not claim complete ProForma 2.0 compliance.

Termini and backbone

Notation Structure represented
[Acetyl]-PEPTIDE or Ac-PEPTIDE N-terminal acetylation
[Formyl]-PEPTIDE N-terminal formylation
[Myristoyl]-PEPTIDE N-terminal myristoylation
[Palmitoyl]-PEPTIDE N-terminal palmitoylation
PEPTIDE-[Amide] or PEPTIDE-NH2 C-terminal amidation
PEPTIDE-[MethylEster] C-terminal methyl ester
PEPTIDE-[EthylEster] C-terminal ethyl ester
PEPTIDE-[Hydrazide] C-terminal hydrazide
A[NMe] Backbone N-methylation; unavailable on Pro

Side chains

Sites Built-in modification names
S, T, Y Phospho, Sulfo, Acetyl
S, T Methyl
M Oxidation, Dioxidation
C Oxidation, SulfinicAcid, SulfonicAcid, Persulfide, Methyl, Carbamidomethyl
N, Q Deamidated
R Citrullination
K Methyl, Dimethyl, Trimethyl, Acetyl, Succinyl, Malonyl, Crotonyl, GlyGly, Carbamyl
Y Nitro

Selected site-aware aliases include UNIMOD:1, UNIMOD:4, UNIMOD:7, UNIMOD:21, UNIMOD:34, UNIMOD:35, UNIMOD:36, UNIMOD:37, UNIMOD:40, UNIMOD:64, UNIMOD:121, UNIMOD:747, and UNIMOD:1363. The same accession can resolve differently by site: R[UNIMOD:7] is represented as citrulline, while N[UNIMOD:7] and Q[UNIMOD:7] are represented as deamidated residues.

Custom modification channel

Custom registries extend the structure library without editing MolTranscode source code. They are JSON files whose values are attachment-aware SMILES fragments, not mass deltas.

{
  "schema_version": 1,
  "override": false,
  "side_chain_modifications": [
    {
      "name": "AzidoLys",
      "residue": "K",
      "side_chain_smiles": "CCCCN=[N+]=[N-]",
      "aliases": ["AzK"]
    }
  ],
  "n_terminal_modifications": [
    {
      "name": "Propionyl",
      "prefix_smiles": "CCC(=O)",
      "aliases": ["Prop"]
    }
  ],
  "c_terminal_modifications": [
    {
      "name": "MethylAmide",
      "terminus_smiles": "C(=O)NC",
      "aliases": ["NHMe"]
    }
  ]
}

Use one registry, or layer several in command-line order:

moltranscode convert 'Prop-AK[AzK]-NHMe' --from peptide --to smiles \
  --mod-config examples/custom_modifications.json

moltranscode formats --json --mod-config lab-mods.json --mod-config project-mods.json

Built-in definitions cannot be replaced silently. A registry must set "override": true to replace an existing site/name pair. Modified D-isoleucine or D-threonine definitions must provide d_side_chain_smiles so the second stereocenter is explicit. Every final molecule is sanitized by RDKit; registry provenance should be archived with generated data.

See Modification system for the schema, attachment semantics, safety rules, and Python registration API.

Graphical single-entry workbench

Run moltranscode gui to open the optional English/Chinese interface. It is designed for manual, non-batch work and provides:

  • one-at-a-time input for peptides, sequences, SMILES, InChI, SELFIES, HELM, and structure blocks;
  • visual residue-position PTM selection, N/C termini, backbone N-methylation, D-residue notation, and an editable generated peptide annotation;
  • structure-tested non-natural alpha-amino-acid presets including Nle, Orn, Dab, Dap, Hse, Hcy, Sec, Cit, 4F-Phe, pAzF, Pra, Cha, and Tle;
  • selectable molecular output formats, fingerprints, or descriptor calculation;
  • responsive result cards with untruncated formula, exact mass, charge, canonical SMILES, a 2D drawing, and downloads;
  • persistent session history with JSON/CSV export while additional entries are submitted;
  • custom side-chain/N-terminal/C-terminal forms with immediate validation and registry import/export.
  • an in-app input guide, scope warnings, and links to the primary standards and reference databases.

The interface exports the same schema accepted by --mod-config; no separate GUI-only project format is introduced. See the GUI guide for the complete workflow.

Batch conversion

moltranscode convert proteins.fasta --file --from fasta --to smiles --output out.csv
moltranscode convert compounds.csv --file --column structure \
  --from smiles --to inchikey --output out.csv
moltranscode convert examples/modified_peptides.csv --file --column sequence \
  --from peptide --to smiles --output peptides.jsonl

CSV/TSV/JSONL input columns are preserved during ingestion. Result tables contain id, input, input_format, output_format, result, status, and error. One invalid record does not discard the rest of the batch unless --fail-fast is used.

Python API

from moltranscode import convert, describe, fingerprint, load_modification_registry

registry = load_modification_registry("examples/custom_modifications.json")

smiles = convert(
    "Prop-AK[AzK]-NHMe",
    "peptide",
    "smiles",
    modification_registry=registry,
)
fp = fingerprint("CCO", "smiles", kind="morgan", n_bits=2048)
properties = describe("K[Succinyl]", "peptide")

Advanced users can construct a ModificationRegistry directly and call register_side_chain(), register_n_terminus(), or register_c_terminus().

Scientific and reproducibility boundaries

  • Output depends on the RDKit version and MolTranscode parameters; record both with published data.
  • Neutral termini and neutral phosphate/sulfate acid forms are representation policies, not claims about the dominant microspecies at a particular pH.
  • M[Oxidation] does not assign sulfur stereochemistry, and K[Crotonyl] does not infer alkene E/Z geometry.
  • Mass-only deltas, ambiguous localizations, glycans, cross-links, disulfides, and cyclic peptides are rejected until a unique molecular graph can be constructed.
  • Fingerprints are lossy features, not molecular identity keys. Prefer Standard InChI/InChIKey for identity exchange.
  • resolve-name queries PubChem; synonyms can be ambiguous and should be checked against the returned structure.

Read Scientific basis and the Roadmap before using the tool in a publication workflow.

Project layout

src/moltranscode/      conversion, peptide, registry, I/O, and CLI modules
tests/                 chemistry, registry, batch, and CLI regression tests
examples/              FASTA, SMI, modified peptide, and custom-registry examples
docs/                  scientific conventions, modification schema, and roadmap

Contributing

New built-in modifications need an explicit attachment structure, site specificity, stereochemical policy, focused formula/structure tests, and a primary or controlled-vocabulary reference. See CONTRIBUTING.md.

License

MIT