moleculekit.representations module#

moleculekit.representations.LABEL_FIELD_ALIASES = {'atomname': 'name', 'chainid': 'chain', 'residueindex': 'resid', 'residuename': 'resname'}#

Other viewers’ names for the per-atom fields a label can write, so a representation written for one of them labels the same thing here.

moleculekit.representations.MOLSTAR_STYLES = {'atomlabel': 'label', 'backbone': 'backbone', 'ballandstick': 'ball_and_stick', 'cartoon': 'cartoon', 'cpk': 'ball_and_stick', 'ellipsoid': 'ellipsoid', 'formalcharges': 'formal_charge', 'gaussiansurface': 'gaussian_surface', 'label': 'label', 'labels': 'label', 'licorice': 'ball_and_stick', 'line': 'line', 'lines': 'line', 'molecularsurface': 'molecular_surface', 'newcartoon': 'cartoon', 'point': 'point', 'points': 'point', 'putty': 'putty', 'quicksurf': 'gaussian_surface', 'spacefill': 'spacefill', 'surf': 'molecular_surface', 'vdw': 'spacefill'}#

Representation styles, and the Mol* representation each one draws as. The names are VMD’s, since that is the vocabulary mol.reps has always used.

moleculekit.representations.MOLSTAR_THEMES = {'atomid': 'atom-id', 'beta': 'uncertainty', 'chain': 'chain-id', 'chainid': 'chain-id', 'element': 'element-symbol', 'elementindex': 'element-index', 'elementsymbol': 'element-symbol', 'entityid': 'entity-id', 'hydrophobicity': 'hydrophobicity', 'illustrative': 'illustrative', 'index': 'sequence-id', 'modelindex': 'model-index', 'moleculetype': 'molecule-type', 'name': 'element-symbol', 'occupancy': 'occupancy', 'polymerid': 'polymer-id', 'residuename': 'residue-name', 'resname': 'residue-name', 'secondarystructure': 'secondary-structure', 'sequenceid': 'sequence-id', 'structureindex': 'structure-index', 'uncertainty': 'uncertainty'}#

Colouring modes, and the Mol* colour theme each one selects. Keys are matched with spaces, hyphens and underscores removed, so “Secondary Structure” and “SecondaryStructure” are the same mode. Our own docstrings used the second spelling, which fell through to being read as a colour name and drew a garbage uniform colour.

class moleculekit.representations.Representations(mol, notify=True)#

Bases: object

Class that stores representations for Molecule.

Parameters:

  • mol (Molecule) – The Molecule object for which the representations are stored.

  • notify (bool) – Whether changes are reported to registered viewer backends. False for the staging list view() collects its arguments in, which is not the molecule’s own set of representations and would otherwise be announced as if it were.

Examples

>>> from moleculekit.molecule import Molecule
>>> mol = tryp.copy()
>>> mol.reps.add('protein', 'NewCartoon')
>>> print(mol.reps)
rep 0: sel='protein', style='NewCartoon', color='Name'
>>> mol.view()
>>> mol.reps.remove()
add(sel=None, style=None, color=None, frames=None, opacity=None, size=None, c_atom_color=None, size_theme=None, label_fields=None, label_style=None, visibility=None, update_sel_every_frame=None)#

Adds a new representation for Molecule.

Parameters:

  • sel (str | ndarray | None) – Atom selection (string, boolean mask, or integer index array) for the representation. See more here

  • style (str | None) – Representation style, in either vocabulary. VMD’s NewCartoon, Cartoon, Licorice, CPK, VDW, Lines, Surf, QuickSurf, Points, Putty, Labels and FormalCharges, or Mol*’s cartoon, ball-and-stick, spacefill, line, molecular-surface, gaussian-surface, point, putty, backbone, ellipsoid and atom-label (also label) for the same things. Spacing, case and hyphens are ignored, and anything else is rejected rather than drawn as something it is not. Labels writes each atom’s name beside it and FormalCharges writes +1/-1 on atoms carrying one, both on top of another representation that draws the atoms; neither reaches VMD or NGL. A name from neither list is passed to the VMD backend as written, so VMD’s own styles still work there.

  • color (str | int | None) – Coloring mode (str) or ColorID (int), in either vocabulary. VMD’s Name, Element, Chain, ResName, Index, Secondary Structure, Hydrophobicity, Molecule Type, Atom ID, Beta and Occupancy, or Mol*’s element-symbol, chain-id, residue-name, sequence-id, secondary-structure, hydrophobicity, molecule-type, atom-id, uncertainty (the B factor, which VMD calls Beta), occupancy, element-index, entity-id, polymer-id, model-index, structure-index and illustrative. Any SVG colour name or #rrggbb string gives a uniform colour, as does a VMD ColorID.

  • frames (list | None) – List of frames to visualize with this representation. If None it will visualize the current frame only.

  • opacity (float | None) – Opacity of the representation. 0 is fully transparent and 1 is fully opaque.

  • size (float | None) – Scales the drawn size: stick and sphere radius, surface probe, point size, label text. Each style keeps its own sensible size at 1.

  • c_atom_color (str | None) – Colour for carbon atoms only, leaving nitrogen, oxygen and the rest their element colours. Takes an SVG colour name, a #rrggbb string, or one of chain-id, entity-id, model-index, structure-index. Ignored unless the representation is coloured by element, which is what it modifies.

  • size_theme (str | None) – How sizes are decided before size scales them: physical for atomic radii, uniform for one size everywhere, or uncertainty for the B factor. Each style picks a sensible one, so this is only worth setting to override it.

  • label_fields (str | list | None) – What a Labels representation writes beside each atom: any per-atom fields of the molecule, such as name, element, resname, resid, chain or index, joined by spaces. Without it the label is the atom name alone.

  • label_style (dict | None) – Cosmetics for a Labels representation: border_width, border_color, bg_color, bg_opacity, bg_margin, offset_x, offset_y and offset_z. Keys left out keep their defaults, and any other key is rejected.

  • visibility (bool | None) – Whether to draw this representation. A hidden one keeps its place in the list, so it can be switched back on by index.

  • update_sel_every_frame (bool | None) – Whether an interactive viewer re-evaluates the selection on every trajectory frame, which is what a coordinate-dependent selection such as within 5 of resname BEN needs to follow the structure. A rendered image is one frame, so this does not reach it.

addDefaults()#

Add the representations a viewer draws when none are set.

Adding any representation replaces the automatic scene wholesale, so colouring one ligand otherwise costs the cartoon and everything else. This writes that scene out as ordinary entries to edit, reorder or remove. They describe the molecule as it is when this is called, so call it again after adding or removing atoms.

Examples

>>> mol = tryp.copy()
>>> mol.reps.addDefaults()
>>> mol.reps.remove(1)          # drop the waters, ligand and ions
>>> mol.reps.add("resname BEN", "VDW", color=0)
append(reps)#

Append the representations of another Representations object.

Parameters:

reps (Representations) – The Representations object whose representations will be appended to this one.

Raises:

RuntimeError – If reps is not a Representations object.

describe(rep)#

Describe one representation for a viewer backend.

The same description a Mol* scene is built from, plus what only a live viewer can act on: the selection it was written as, which a viewer following a trajectory re-evaluates frame by frame and resolved atom indices cannot express, and the two flags that mean nothing to a single rendered image.

Parameters:

rep (_Representation) – The representation to describe.

Returns:

described – Its style, colour, opacity, sizes, labels, selection, visibility and per-frame flag, or None if the selection matched no atoms.

Return type:

dict | None

list()#

Print all currently stored representations.

Prints, for each representation, its index, atom selection, style and color. Equivalent to printing the Representations object directly.

remove(index=None)#

Removed one or all representations.

Parameters:

index (int | None) – The index of the representation to delete. If none is given it deletes all.

update(index, sel=None, style=None, color=None, frames=None, opacity=None, size=None, c_atom_color=None, size_theme=None, label_fields=None, label_style=None, visibility=None, update_sel_every_frame=None)#

Change one representation in place, leaving the rest of it alone.

Only what is given is changed, so recolouring a representation does not cost its size or its selection. Its position in the list is kept, which is what makes it addressable by index at all: removing and re-adding would move it to the end and renumber everything after it.

Parameters:

Examples

>>> mol = tryp.copy()
>>> mol.reps.add("protein", "NewCartoon", "Secondary Structure")
>>> mol.reps.update(0, color="Chain")
>>> mol.reps.update(0, visibility=False)      # keep it, stop drawing it
moleculekit.representations.VMD_COLORS = {'atomid': 'Index', 'chainid': 'Chain', 'elementsymbol': 'Name', 'residuename': 'ResName', 'secondarystructure': 'Structure', 'sequenceid': 'ResID', 'uncertainty': 'Beta'}#

The VMD coloring method each colouring mode corresponds to. Modes VMD has no equivalent for (hydrophobicity, molecule type) are sent as written and VMD rejects them, which is what it did before any of these were accepted here.

moleculekit.representations.VMD_STYLES = {'ballandstick': 'CPK', 'gaussiansurface': 'QuickSurf', 'line': 'Lines', 'molecularsurface': 'Surf', 'point': 'Points', 'spacefill': 'VDW'}#

The VMD representation each Mol* style name corresponds to. VMD’s own names are sent as written, so only the Mol* spellings need translating.

moleculekit.representations.canonical_label_field(field)#

The molecule’s own name for a label field.

Parameters:

field (str) – A field name, in any viewer’s spelling.

Returns:

name – The name the molecule stores that field under.

Return type:

str