Choose representations and colours#

Goal: control how a molecule is drawn, by view() and by render(), using mol.reps, a Representations object.

Example#

from moleculekit.molecule import Molecule

mol = Molecule("3PTB")

mol.reps.addDefaults()            # the scene you get with no representations
mol.reps.remove(1)                # drop the automatic waters/ion/ligand

mol.reps.add("protein and within 5 of resname BEN", "Surf", "Hydrophobicity",
             opacity=0.3)
mol.reps.add("resname BEN", "ball-and-stick", "element-symbol", size=0.4)
mol.reps.add("resname BEN", "Labels", "black", size=1.6)

mol.render("pocket.png", center="resname BEN", zoom=0.3)

addDefaults() writes the automatic scene out as ordinary entries you can edit, reorder or remove(). Without it, add() replaces the automatic scene entirely, so colouring one ligand costs you the cartoon and everything else.

Styles#

Each style can be written in VMD’s vocabulary or Mol*’s. Spacing, case and hyphens are ignored, so Secondary Structure, secondary-structure and SecondaryStructure are one name.

VMD name	Mol* name	Draws
`NewCartoon`, `Cartoon`	`cartoon`	Ribbon following the backbone
`Licorice`, `CPK`	`ball-and-stick`	Sticks with atoms as spheres
`VDW`	`spacefill`	Space-filling spheres
`Lines`	`line`	Bond lines, cheapest to draw
`Surf`	`molecular-surface`	Solvent-excluded surface
`QuickSurf`	`gaussian-surface`	Coarser gaussian surface, cheaper
`Points`	`point`	One dot per atom
`Putty`	`putty`	Tube thickened by B factor
`Backbone`	`backbone`	Backbone trace, proteins and nucleic acids
`Ellipsoid`	`ellipsoid`	Residues as ellipsoids
`Labels`	`atom-label`, `label`	Each atom’s name beside it
`FormalCharges`		`+1`/`-1` on atoms carrying a formal charge

Labels and FormalCharges draw text on top of another representation, so they need one that draws the atoms themselves. A style from neither column is passed to the VMD backend as written, so VMD’s own styles still work there.

Colours#

VMD name	Mol* name	Colours by
`Name`, `Element`	`element-symbol`	Chemical element
`Chain`	`chain-id`	Chain
`ResName`	`residue-name`	Residue name
`Index`	`sequence-id`	Position in the sequence
`Secondary Structure`	`secondary-structure`	Helix, sheet, coil
`Beta`	`uncertainty`	B factor, or pLDDT for predicted structures
`Occupancy`	`occupancy`	Occupancy
`Hydrophobicity`	`hydrophobicity`	Residue hydrophobicity
`Molecule Type`	`molecule-type`	Protein, nucleic, water, ligand
`Atom ID`	`atom-id`	Atom index
	`element-index`	Position along the chain, a different gradient
	`entity-id`	Entity: polymer, ligand, water
	`polymer-id`	Polymer
	`model-index`	Model
	`structure-index`	Structure
	`illustrative`	Chain, with non-carbon atoms picked out

Any SVG colour name ("red", "steelblue") or #rrggbb string gives a uniform colour, as does a VMD ColorID integer.

Size and transparency#

mol.reps.add("resname BEN", "Licorice", "Name", size=0.4)                 # thin sticks
mol.reps.add("resname BEN", "VDW", "Name", size=0.85, opacity=0.25)       # ghost spheres
mol.reps.add("resname BEN", "Licorice", "Name", c_atom_color="#66ccff")   # cyan carbons

Parameter	Meaning
`size`	Scales the drawn size: stick and sphere radius, surface probe, point size, label text. Each style keeps its own sensible size at `1`.
`opacity`	`0` is fully transparent, `1` fully opaque.
`c_atom_color`	Colours carbon only, leaving N, O and S their element colours. A colour, or one of `chain-id`, `entity-id`, `model-index`, `structure-index`. Needs an element-coloured representation, which is what it modifies.
`size_theme`	How sizes are decided before `size` scales them: `physical` for atomic radii, `uniform` for one size everywhere, `uncertainty` for the B factor. Each style picks a sensible one already.
`label_fields`	What a `Labels` representation writes beside each atom: any per-atom fields of the molecule, joined by spaces. Without it the label is the atom name.
`label_style`	Cosmetics for a `Labels` representation: `border_width`, `border_color`, `bg_color`, `bg_opacity`, `bg_margin`, `offset_x`, `offset_y`, `offset_z`.
`visibility`	`False` keeps the representation in the list but stops drawing it.

Representations layer, so a transparent VDW over a Licorice of the same selection gives sticks inside a ghost surface.

Labelling atoms#

mol.reps.add("resname BEN", "Licorice", "Name")
mol.reps.add("resname BEN", "Labels", "black",
             label_fields=["resname", "resid", "name"], size=1.4)

mol.reps.add("resname BEN", "Labels", label_fields="name", size=1.6,
             label_style={"bg_color": "#003366", "bg_opacity": 0.85, "offset_y": 1.5})

label_fields takes any per-atom fields the molecule has — name, element, resname, resid, chain, segid, beta, occupancy, index and so on — and writes them space-separated. Each label is drawn separately, so label a selection worth naming rather than a whole structure; past a couple of hundred atoms they are skipped with a warning.

Changing a representation you already added#

update() changes one entry in place and leaves the rest of it alone, so recolouring does not cost you the size or the selection. It keeps the entry where it is, which is what makes indices stable: removing and re-adding would move it to the end and renumber everything after it.

mol.reps.update(0, color="Chain")
mol.reps.update(0, visibility=False)     # keep it, stop drawing it
mol.reps.update(0, visibility=True)

Only what you pass is changed, so passing nothing changes nothing.

Gotchas#

Representations replace the automatic scene, they do not add to it. This matches the VMD backend. Use addDefaults() to start from the automatic scene, or leave mol.reps empty to get it.
Formal charge labels follow the same rule. With no representations they are drawn automatically on charged atoms; once you set any, add a FormalCharges representation to keep them. addDefaults() includes one when the molecule has a charged atom, so starting from the default scene keeps them without asking.
update_sel_every_frame is for the interactive viewer. It re-evaluates a coordinate-dependent selection such as within 5 of resname BEN on every trajectory frame. A rendered image is a single frame, so it is carried on the representation and changes nothing about the picture.
An unknown style or colour raises. It used to draw ball-and-stick or a garbage uniform colour, which looked like a deliberate picture rather than a typo.
A representation whose selection matches no atoms is dropped with a warning, and if every one matches nothing, the scene raises rather than drawing an empty image.
Putty, Labels and FormalCharges only reach Mol*. The VMD and NGL backends skip them rather than being sent a style they have no representation for.
frames only applies to the interactive viewer. A render is a single still, so add()’s frames argument has nothing to act on there.