moleculekit.tools.glycans module

GLYCAM-06 naming tables and glycan analysis helpers.

This module holds the static tables needed to translate a PDB carbohydrate residue name (e.g. NAG, BMA, SIA) plus its glycosidic linkage positions into the corresponding 3-character GLYCAM-06 residue name (e.g. 4YB), and the inverse mapping recovering linkage positions from a GLYCAM residue name.

class moleculekit.tools.glycans.GlycanResidueInfo(linked_positions=(), anchor_res=None, anchor_atom=None, free_reducing_end=False)

Bases: object

Per-residue result of analyzeGlycanResidues().

linked_positions

Ring carbon positions at which another sugar is glycosidically linked onto this residue, sorted ascending. Empty for a sugar with no outgoing linkage (a non-reducing terminal residue).

Type:

tuple

anchor_res

Index into the caller’s residue_atom_idx list of the protein residue this sugar’s anomeric carbon is bonded to. None when this sugar’s anomeric carbon is bonded to another sugar instead of a protein anchor, or when it has a free reducing end.

Type:

int or None

anchor_atom

Name of the protein anchor atom the anomeric carbon bonds to (e.g. "ND2"), or None when anchor_res is None.

Type:

str or None

free_reducing_end

True when nothing is bonded to this residue’s anomeric carbon, regardless of whether the anomeric hydroxyl atom itself is resolved in the input structure.

Type:

bool

anchor_atom: str | None = None

anchor_res: int | None = None

free_reducing_end: bool = False

linked_positions: tuple = ()

class moleculekit.tools.glycans.SugarTemplate(letter, anomer, anomeric_carbon, anomeric_oxygen, atom_renames)

Bases: object

GLYCAM identity of one PDB carbohydrate residue name.

letter

GLYCAM one-letter sugar code. Case encodes the sugar’s configuration: upper-case is D, lower-case is L (e.g. "M" for D-mannose, "f" for L-fucose).

Type:

str

anomer

Anomeric configuration at the ring-closing carbon: "A" for alpha or "B" for beta.

Type:

str

anomeric_carbon

Atom name of the anomeric carbon, "C1" for most sugars or "C2" for sialic acids.

Type:

str

anomeric_oxygen

Atom name of the anomeric hydroxyl oxygen, "O1" for most sugars or "O2" for sialic acids.

Type:

str

atom_renames

Mapping from PDB atom name to the GLYCAM atom name it must be renamed to before building (e.g. the N-acetyl or N-glycolyl substituent atoms), empty for sugars with no such substituent.

Type:

dict

anomer: str

anomeric_carbon: str

anomeric_oxygen: str

atom_renames: dict

letter: str

moleculekit.tools.glycans.analyzeGlycanResidues(mol, bonds, residue_atom_idx)

Recover glycan-tree structure from a molecule’s bond graph.

Walks every inter-residue bond once to work out, for each sugar residue recognized in GLYCAM_SUGARS, which ring positions carry an outgoing glycosidic linkage to another sugar, and whether the sugar’s own anomeric carbon is bonded onward to a parent sugar, to a protein anchor residue (see GLYCAN_ANCHORS), or to nothing at all (a free reducing end). This is the bond-graph counterpart of glycanBondsFromNames(), meant to be called while the molecule still carries its original (e.g. CONECT-derived) bonds.

Parameters:

• mol (Molecule) – The molecule containing the candidate glycan(s).

• bonds (ndarray) – (n, 2) array of atom index pairs, e.g. mol.bonds.

• residue_atom_idx (list) – One atom-index array per residue, ordered so that the index of an entry in this list is the residue index used as a key in the returned dictionary (e.g. as built by moleculekit.util.sequenceID() or mol.getResidues(return_idx=True)).

Returns:

info – Maps residue index (into residue_atom_idx) to a GlycanResidueInfo, for every residue recognized as a sugar. Non-sugar residues are absent from the result.

Return type:

dict[int, GlycanResidueInfo]

Raises:

RuntimeError – If a sugar’s anomeric carbon, or one of a sugar’s numbered ring oxygens, is bonded to a residue that is itself a carbohydrate but absent from GLYCAM_SUGARS; if a sugar’s anomeric carbon is bonded to a protein residue GLYCAM does not support as a glycosylation anchor, or to the wrong atom of a supported one; or if a sugar’s anomeric carbon is bonded to more than one partner.

moleculekit.tools.glycans.glycamResname(resname, linked_positions)

Construct the 3-character GLYCAM-06 unit name for a sugar residue.

Combines the sugar’s GLYCAM one-letter code and anomer with a character encoding which ring positions carry outgoing glycosidic linkages, and validates the result against the set of units GLYCAM-06j actually ships.

Parameters:

• resname (str) – PDB Chemical Component Dictionary residue name of the sugar (e.g. "NAG", "BMA", "SIA"). Must be a key of GLYCAM_SUGARS.

• linked_positions (Iterable[int]) – Ring carbon positions (e.g. 2, 3, 4, 6) at which another sugar is glycosidically linked onto this one. Pass an empty iterable for a terminal (non-reducing end) sugar with no outgoing linkages.

Returns:

name – The 3-character GLYCAM-06 residue name, e.g. "4YB".

Return type:

str

Raises:

RuntimeError – If resname is not in GLYCAM_SUGARS, if linked_positions is a combination _LINKAGE_CHARS has no naming character for yet, or if the constructed name is absent from GLYCAM_UNIT_NAMES (GLYCAM-06j does not ship that particular sugar/linkage combination).

moleculekit.tools.glycans.glycamUnitMask(mol)

Boolean atom mask selecting genuine GLYCAM-06j sugar unit residues.

Matching purely on a GLYCAM unit’s 3-character resname (GLYCAM_UNIT_NAMES) is unsafe: many of those codes are also real PDB Chemical Component Dictionary ligand codes with nothing to do with GLYCAM (TLA is L-(+)-tartaric acid, TMA is tetramethylammonium, PGA is 2-phosphoglycolic acid, PMA is pyromellitic acid, and others), and two more (1MA, 2MA) are also AMBER modrna08 modified-ribonucleotide names. This gates the resname match on the sugar-like composition every GLYCAM unit template actually has: the anomeric carbon the code implies (C2 for a sialic-letter unit, i.e. the middle character of the code is S or s; C1 otherwise) directly bonded to the ring oxygen GLYCAM always numbers alongside it (O6 for sialic, O5 otherwise) - see _has_glycam_ring_atoms().

For the two codes also claimed by modrna08 (1MA, 2MA), a residue is additionally required to carry no nitrogen atom. Both are mannose (M) linkage codes, so a genuine GLYCAM instance of either never has one, while every real modrna08 ribonucleotide does (its purine/pyrimidine base). This heuristic is deliberately narrow: it is NOT a general “sugars have no nitrogen” rule (GlcNAc/GalNAc/sialic-acid units all carry one from their N-acetyl group); it works only because the current collision set happens to be limited to nitrogen-free mannose codes. If GLYCAM or modrna08 ever add a colliding code on a different letter, this must be revisited - see test_glycam_modrna_collision_set_is_1ma_2ma in htmd’s tests/test_amber_builder.py, which pins today’s exact collision set and is meant to fail first if that ever changes.

Parameters:

mol (Molecule) – The molecule to scan. Assumed already renamed to GLYCAM unit names where applicable (i.e. run after glycamResname() / systemPrepare, not on raw PDB Chemical Component Dictionary names - see pdbSugarMask() for that case).

Returns:

mask – Boolean array, shape (mol.numAtoms,), True for every atom of a residue confirmed to be a genuine GLYCAM sugar unit.

Return type:

ndarray

moleculekit.tools.glycans.glycanBondsFromNames(mol)

Derive glycan connectivity from GLYCAM residue names and geometry.

Meant for the htmd builder, after the molecule has been renamed to GLYCAM unit names (see glycamResname()) and had its glycosidic bonds removed (tleap infers that connectivity from residue templates instead), so this function purposefully consults only residue names and coordinates and never mol.bonds. GLYCAM sugar units are recognized via glycamUnitMask(), which gates the resname match on the sugar’s actual composition since several GLYCAM 3-character codes collide with unrelated real PDB Chemical Component Dictionary ligand codes. For every genuine GLYCAM sugar unit, each ring position encoded in its own name (see linkedPositionsFromGlycamResname()) is resolved to the nearest anomeric carbon of another residue within GLYCAN_LINK_CUTOFF. Protein anchor residues (GLYCAM_ANCHOR_UNITS) and the free-hydroxyl cap ROH are resolved the same way, connecting into a sugar’s anomeric carbon.

Parameters:

mol (Molecule) – A molecule already renamed to GLYCAM-06 unit names, with its glycosidic bonds removed.

Returns:

pairs – List of (atom_index_1, atom_index_2) tuples, one per glycosidic or anchor bond that should be added back to the molecule.

Return type:

list

Raises:

RuntimeError – If a GLYCAM unit’s name encodes a linkage position whose O{p} atom is absent from the residue, or if a linked position or anchor atom does not have exactly one anomeric-carbon partner within GLYCAN_LINK_CUTOFF.

moleculekit.tools.glycans.linkedPositionsFromGlycamResname(resname)

Recover the linked ring positions encoded in a GLYCAM-06 residue name.

Inverse of the linkage-position character used by glycamResname(): reads the first character of resname and looks it up in the linkage-character table.

Parameters:

resname (str) – A 3-character GLYCAM-06 residue name, e.g. "4YB" or "UYB".

Returns:

positions – Sorted tuple of ring carbon positions with an outgoing glycosidic linkage, e.g. (4, 6). Empty tuple for a terminal sugar.

Return type:

tuple

moleculekit.tools.glycans.pdbSugarMask(mol)

Boolean atom mask selecting genuine un-renamed PDB sugar residues.

Companion to glycamUnitMask() for the opposite naming stage: a residue still carrying its original PDB Chemical Component Dictionary carbohydrate resname (a key of GLYCAM_SUGARS, e.g. NAG/BMA/SIA) rather than a GLYCAM-06j unit name. Used to catch a glycan that reaches a builder without first being renamed by systemPrepare. Gated on the same composition-plus-geometry check as glycamUnitMask() (see _has_glycam_ring_atoms()), so an unrelated ligand that merely happens to reuse one of these codes is not misdetected.

Parameters:

mol (Molecule) – The molecule to scan.

Returns:

mask – Boolean array, shape (mol.numAtoms,), True for every atom of a residue confirmed to be a genuine un-renamed PDB sugar.

Return type:

ndarray