Skip to content

modifications.md

Latest commit

 

History

History
209 lines (164 loc) · 8.29 KB

modifications.md

File metadata and controls

209 lines (164 loc) · 8.29 KB
Raw

Modification system

MolTranscode resolves peptide annotations to explicit molecular structures. Its notation is a documented, structure-resolving subset inspired by ProForma 2.0; it is not a general ProForma parser and does not turn an unsupported mass delta into a guessed structure.

Accepted notation

[N-terminal-name]-PEP[R-esidue-modification]TIDE-[C-terminal-name]
  • Uppercase residues are L amino acids; lowercase residues are D amino acids.
  • One side-chain modification and optional [NMe] may be assigned to a residue.
  • Bracketed terminal names are preferred. Built-in short forms such as Ac- and -NH2 remain available, and a custom alias can also be used as a short form when peptide input is explicit.
  • Names and aliases are case-insensitive; underscores and spaces normalize to hyphens.
  • Controlled-vocabulary accessions are site-aware. An accession is accepted only at registered residues and termini.

Run moltranscode formats --json to inspect the active registry.

Built-in controlled-vocabulary aliases

The built-in structures include aliases for selected records in the Unimod modification database. Site specificity is part of the lookup:

Accession Built-in meaning and supported sites
UNIMOD:1 Acetyl: N terminus, K, S, T, Y
UNIMOD:4 Carbamidomethyl: C
UNIMOD:7 Deamidated: N/Q; citrullination: R
UNIMOD:21 Phospho: S/T/Y
UNIMOD:34, 36, 37 Methyl/Dimethyl/Trimethyl at supported sites
UNIMOD:35 Oxidation: M/C
UNIMOD:40 Sulfo: S/T/Y
UNIMOD:64, 747, 1363 Succinyl/Malonyl/Crotonyl: K
UNIMOD:121 GlyGly remnant: K

These aliases resolve to MolTranscode's explicit structural conventions; they do not mean that all specificities or neutral losses recorded by Unimod are implemented.

Built-in non-natural residue presets

The GUI exposes a conservative catalogue of alpha-amino acids whose structures can be generated by replacing a side chain without changing MolTranscode's standard peptide backbone:

Preset Carrier notation Preset Carrier notation
Norvaline (Nva) V[Norvaline] Norleucine (Nle) M[Norleucine]
Ornithine (Orn) K[Ornithine] Diaminobutyric acid (Dab) K[Dab]
Diaminopropionic acid (Dap) K[Dap] Homoserine (Hse) S[Hse]
Homocysteine (Hcy) C[Hcy] Selenocysteine (Sec) C[Sec]
Citrulline (Cit) R[Cit] 4-Fluorophenylalanine F[4F-Phe]
4-Azidophenylalanine (pAzF) F[pAzF] Propargylglycine (Pra) A[Pra]
Cyclohexylalanine (Cha) F[Cha] tert-Leucine (Tle) L[Tle]

The carrier is an internal attachment template, not a claim that the preset is a modification of that biological residue. Bracketed names are used because there is no universal one-letter code for arbitrary non-natural amino acids. For a broader curated side-chain resource, see SwissSidechain and the scope discussion in Scientific basis.

JSON registry schema

Use examples/custom_modifications.json as a working template. custom-modifications.schema.json is supplied for editor validation. Runtime validation is built in and does not require a JSON Schema package.

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

Attachment semantics

Fragments are not standalone modified amino-acid SMILES. They must be one sanitizable connected SMILES fragment and must not contain . or a wildcard atom.

  • side_chain_smiles replaces the entire side-chain branch attached to the residue alpha carbon. For lysine, ordinary CCCCN therefore represents the beta-through-epsilon branch.
  • d_side_chain_smiles is the corresponding branch for the D residue. It is optional except for modified D-Ile and D-Thr, whose side chains contain a second stereocenter.
  • prefix_smiles is placed immediately before the first residue nitrogen. For example, CCC(=O) produces an N-propionyl peptide.
  • terminus_smiles replaces the final C(=O)O group and includes its carbonyl carbon. For example, C(=O)NC produces a C-terminal methylamide.

Each final graph is parsed and sanitized by RDKit. Sanitization catches invalid valence and syntax, but it cannot prove that a valid graph matches the intended chemistry.

Layering and overrides

Repeat --mod-config to layer registries in command-line order:

moltranscode convert 'Prop-AK[AzK]-NHMe' --from peptide --to smiles \
  --mod-config lab-mods.json --mod-config project-mods.json

A definition or alias collision is rejected by default. Set "override": true in a registry only when deliberate replacement is required. This setting applies to that whole file, so keep override files small and review them as source data.

Unknown keys, invalid residues, empty fragments, malformed aliases, and unsupported schema versions are rejected. The optional description field is accepted as human-readable provenance but is not used during structure construction.

Python registration API

Load JSON:

from moltranscode import convert, load_modification_registry

registry = load_modification_registry(["lab-mods.json", "project-mods.json"])
smiles = convert(
    "Prop-AK[AzK]-NHMe",
    "peptide",
    "smiles",
    modification_registry=registry,
)

Or register definitions programmatically:

from moltranscode import ModificationRegistry, convert, default_modification_registry

registry: ModificationRegistry = default_modification_registry()
registry.register_side_chain(
    name="AzidoLys",
    residue="K",
    side_chain_smiles="CCCCN=[N+]=[N-]",
    aliases=("AzK",),
)
result = convert("AK[AzK]", "peptide", "smiles", modification_registry=registry)

Registry instances are mutable by design. Create one during application initialization and treat it as read-only while conversions run; call clone() before making request-specific changes.

Graphical workbench and registry builder

Install and launch the optional local interface:

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

The Streamlit application supports English and Simplified Chinese. Its main workbench accepts one input at a time, includes a residue-position peptide modification editor, and can convert formats or generate descriptors and fingerprints. A separate library tab validates each custom definition against the same runtime loader used by the CLI, imports existing registries, and downloads schema-versioned JSON. See the GUI guide.

All processing occurs in the local Python process; the application does not send molecular structures to MolTranscode or another hosted service.

For a headless or remote development environment:

moltranscode gui --no-browser --host 127.0.0.1 --port 8765

Binding to a non-loopback interface may expose the application to other machines. Add appropriate network access controls before doing so, especially when working with confidential structures.

Provenance and contribution rules

Archive custom JSON files alongside generated outputs and record the MolTranscode and RDKit versions. A proposed built-in definition should include:

  1. a controlled-vocabulary or primary-literature reference;
  2. supported residue/terminus sites;
  3. attachment structure, formal charge, tautomer, and stereochemical conventions;
  4. formula or exact-mass regression tests and RDKit sanitization tests;
  5. explicit limitations such as unspecified sulfur or alkene stereochemistry.

ProForma 2.0 describes broader syntax, including ambiguity, labile modifications, glycans, cross-links, and mass shifts: LeDuc et al., Nature Methods (2022). Those annotations require a separate syntax and structure-resolution layer before MolTranscode can safely emit one molecular graph.