Peptide sequence grammar

The peptide grammar turns a sequence string into HELM, resolving crosslinks and connection points against a monomer library. Molecule.from_peptide_sequence wraps it; use parse_peptide_sequence directly when you want the parsed metadata alongside the HELM.

from helmshaker import Molecule, MonomerLibrary

library = MonomerLibrary()
library.load_from_file("monomers.json")  # your dictionary, or one pulled from TMR

Molecule.from_peptide_sequence("CAAAC", crosslinks="C:1-C:5", monomer_library=library).to_helm()
# PEPTIDE1{C.A.A.A.C}$PEPTIDE1,PEPTIDE1,1:R3-5:R3$$$V2.0

Sequence syntax

Form	Example	Meaning
Modified FASTA	CAXRN	One character per residue
Dot-delimited	C.A.Nle.R.N	Multi-character symbols, one per residue
Chain separator	CAAAC\|GGKR	Two chains, PEPTIDE1 and PEPTIDE2
Modifier	modifiers="X3=Nle"	Position 3, written X, is the monomer Nle
N/C caps	detected from the sequence	Terminal caps such as ac and am

X is the placeholder for "a non-natural monomer named elsewhere". Either spell the monomer inline with the dot-delimited form, or write X and resolve it with a X{n}=code modifier. Both reach the same HELM.

Crosslink syntax

A crosslink is MONOMER:POSITION-MONOMER:POSITION, comma-separated for several:

C:2-C:7                 disulfide between the cysteines at 2 and 7
C:2-C:7,MeC:9-C:15      two bridges

Positions are 1-based over the whole sequence. The monomer name is checked against the residue at that position, so a typo fails rather than silently bridging the wrong pair.

By default the grammar picks the attachment points from the monomer definitions in the library. Pass crosslink_connections to pin a specific R-group pair when a monomer offers more than one plausible choice.

Custom monomers must be in the library

Nle, MeC, beta-Ala and anything else non-natural has to exist in the monomer_library you pass, or the grammar cannot resolve its connection points. Pull the right dictionary first.

API reference

Peptide sequence-grammar to HELM engine.

Converts a peptide sequence string (plus optional crosslinks and sequence-modifier strings) into a HELM2.0 string with metadata, using a MonomerLibrary for connection-point data. Ported from the PepRe (cdd_peptide_reg) grammar.

PeptideGrammarResult dataclass

Result of :func:parse_peptide_sequence.

Exposes the HELM string, sequence metadata, and the parsed crosslink/modifier objects (which carry per-item errors and warnings).

crosslink_error_count: int property

Number of crosslink errors found during parsing.

crosslink_warning_count: int property

Number of crosslink warnings found during parsing.

modifier_errors: List[Dict[str, Any]] property

Errors for any invalid sequence modifiers.

Crosslink dataclass

A single crosslink.

__str__()

Return the string representation of the crosslink.

Crosslinks

Wraps the crosslinks in an array, manages access, and generates HELM for the links.

error_count: int property

Return the number of errors.

warning_count: int property

Return the number of warnings.

add_error(link_str, error)

Add an error to the appropriate crosslink.

get_link_index(link)

Return the index of the given link, given a string repr of the link, or -1 if not found.

__str__()

Return the string representation of the crosslinks.

get_helm()

Build the helm for the crosslinks.

This is painfully complicated because it supports isopeptides without adding any new, specific syntax for connection points. In situations where the correct connection point is ambiguous, it guesses and issues a warning. There are many unit tests for this code: look there for the boundaries of this algorithm.

SequenceData dataclass

First pass sequence parsing data bag.

Terminuses dataclass

Encapsulate peptide terminuses.

parse_peptide_sequence(sequence, crosslinks='', modifiers='', monomer_library=None, lib=None, crosslink_connections=None)

Convert a peptide sequence (with optional crosslinks/modifiers) to HELM2.0.

Orchestrates: extract sequence data -> parse dotted modifiers (from the sequence) plus any explicit modifier string -> parse crosslinks -> run the core converter.

Parameters:

Name	Type	Description	Default
sequence	str	A modified-FASTA sequence (e.g. CAXRXN) or a dot-delimited sequence with non-natural monomers (e.g. C.A.Nle.R.MeC.N). Chains are separated by |.	required
crosslinks	str	Optional crosslinks string, e.g. C:2-C:7,MeC:9-C:15.	''
modifiers	str	Optional explicit sequence-modifier string, e.g. X3=Nle,X5=MeC.	''
monomer_library	Optional[MonomerLibrary]	A MonomerLibrary used for connection points and CHEM detection.	None
lib	Optional[str]	Optional library identifier (name@version). When given, a {lib=name@version} marker is written into the HELM annotations field.	None
crosslink_connections	Optional[Dict[str, List[str]]]	Optional R-group choice per crosslink, keyed by :func:crosslink_token ("1-9", low position first) and valued [low-position R, high-position R] (e.g. ["R3", "R3"]). Pins an otherwise ambiguous crosslink to those connection points instead of leaving the assembler to pick. Entries for an N-to-C link, or for a position shared by two crosslinks, are ignored, and asking for a point the backbone holds errors the link; see :func:_pin_crosslink_connections.	None

Returns:

Name	Type	Description
PeptideGrammarResult	PeptideGrammarResult	The HELM string plus metadata and parsed crosslink/modifier
	PeptideGrammarResult	objects.

crosslink_token(link)

Position-pair key for a crosslink, low position first (e.g. "1-9").

Keys crosslink_connections by position rather than by monomer code so a substitution at either end cannot invalidate the mapping.