moleculekit.tools.backbone module#

exception moleculekit.tools.backbone.MissingBackboneError#

Bases: Exception

Raised when a residue is missing backbone atoms that cannot be reconstructed.

moleculekit.tools.backbone.chainResidueMask(mol, polymer='protein')#

Boolean atom mask over the residues of a polymer chain.

The drop-in for mol.atomselect("protein") where a residue modelled short of its backbone has to count; see _polymer_masks() for the rule. Capping groups are excluded, as atomselect excludes them: a cap belongs to the chain it caps but is not a residue of its sequence. Combine polymers the way atomselect masks combine – chainResidueMask(mol, "protein") | chainResidueMask(mol, "nucleic"), which is what polymer="both" returns.

Parameters:

  • mol (Molecule) – The molecule. Not modified.

  • polymer (str) – "protein", "nucleic", or "both".

Return type:

ndarray

moleculekit.tools.backbone.check_backbone(mol, remove_broken_terminals=True, terminal_min_heavy_atoms=4)#

Checks the backbone of all canonical aminoacids in a Molecule object and adds missing atoms if needed.

If single atoms are missing in the backbone of a residue, they will be reconstructed. If multiple atoms are missing in the backbone of a residue and the residue is at a terminal, the residue will be removed.

Parameters:

  • mol (Molecule) – The molecule to check the backbone of

  • remove_broken_terminals (bool) – Whether to remove residues that are at a terminal and have less than terminal_min_heavy_atoms heavy atoms. Default is True.

  • terminal_min_heavy_atoms (int) – The minimum number of heavy atoms required at a terminal to not be removed.

Returns:

mol – The molecule with the missing backbone atoms added

Return type:

Molecule

:raises MissingBackboneError : If the molecule has missing backbone atoms that cannot be reconstructed:

moleculekit.tools.backbone.removable_broken_terminal(mol, atoms, end)#

Whether check_backbone() would drop this residue as a broken terminal.

end is "N" or "C", naming which end of the chain the residue sits at – a missing O is forgiven at a C-terminus and a missing N at an N-terminus, as pdb2pqr caps those correctly.

Read by detectTermini so a survey does not propose a cap for a residue the build removes before capping: the two answers have to agree, and a terminus that only exists because a residue is half-modelled is not one the build has. Only a chain’s true ends qualify, which is the terminality check_backbone() itself uses – an internal gap edge is not a terminal to it, and a broken residue there is reconstructed or raised on, never dropped.

Return type:

bool

moleculekit.tools.backbone.residuePolymerStatus(mol, sel='all')#

Yield (status, (segid, chain, resid, insertion), atom_indices) per residue, in file order, with absolute atom indices.

status is one of "protein", "nucleic", "cap", "water", "ion", "lipid" or "other". One classification for every caller to read as its own purpose requires, rather than each deciding the chemistry again: segmentation wants a cap walked with the chain it caps, while a sequence, its gaps and its termini must not count a cap as a residue of the sequence. Folding "cap" into "protein" is what stopped one answer serving both.

Polymer status comes from _polymer_masks(), so a residue modelled short of its backbone keeps it. The indices index mol itself, unlike Molecule.getResidues(sel=...), whose indices count within the selection.

Parameters:

  • mol (Molecule) – The molecule. Not modified.

  • sel (str or numpy.ndarray) – Atom selection to classify. A residue with no selected atom is skipped, and one partly selected yields only its selected atoms.