Writing queries and commands

Two small languages work together in MolGFX:

• A query picks atoms: resname HEM, protein and chain A, byres (within 5 of resname HEM) and protein. It is MolFrame's selection language, used unchanged.
• A command does something with a query: show cartoon, protein, color orange, $pocket. Commands are text you pass to Session.execute().

In a command, the query always comes after the comma:

show cartoon, protein
│    │        └─ query: which atoms
│    └─ form: how to draw them
└─ verb: what to do

Try itCopy Anchor Link

Open a session over a structure and run a program on it:

import molframe
import molgfx

structure = molframe.read("4hhb.cif").infer_bonds()
session = molgfx.Session(structure)

show cartoon
show spacefill, resname HEM
select pocket, byres (within 5 of resname HEM) and protein
show licorice, $pocket
color orange, $pocket

Pass the program to session.execute("..."); session.completions(text, cursor) lists what could come next. To test a query without drawing anything, ask MolFrame how many atoms it selects:

len(structure.select("byres (within 5 of resname HEM) and protein"))   # 758

Queries at a glanceCopy Anchor Link

Keywords are case-insensitive; values such as residue names are not (resname HEM, not hem). not binds tightest, then and, then or; add parentheses whenever you mix and and or. Every keyword, column and operator is in the MolFrame query reference.

Names: $selection and @layerCopy Anchor Link

• select pocket, QUERY names a selection. Refer to it as $pocket in any later query. It is a definition, not a frozen list of atoms: redefining it moves everything that uses it.
• show FORM as pocket, QUERY names a layer (one drawn representation). Refer to it as @pocket in hide, remove, opacity and color.

select heme, resname HEM
select pocket, byres (within 5 of $heme) and protein
show ball_and_stick as pocket, $pocket
opacity 0.5, @pocket
select pocket, byres (within 8 of $heme) and protein   # @pocket follows

Without as, a layer is named after its form: show cartoon makes @cartoon.

RecipesCopy Anchor Link

CommandsCopy Anchor Link

Separate statements with ; or new lines. A program runs as one edit: if any statement fails, nothing changes.

Forms and their controls: cartoon (width, style), ball_and_stick (radius, bond_radius), spacefill (radius), licorice (radius, bond_radius), lines (width), points (size), surface (kind, style, probe_radius, isolevel), nucleic_acid (width), bases (radius), base_pairs (radius, bond_radius), glycan (width). Every form also takes color= and opacity=: show licorice bond_radius=0.2 color=orange, ligand.

Colours: a scheme (element, chain, residue, secondary_structure), a name (red, orange, slate, …), or #rrggbb.

Planar guidesCopy Anchor Link

plane takes a complete scene-space rectangle. Coordinates and full dimensions are in ångström; the outline width is in pixels. The normal and tangent must be non-zero and independent. The rectangle follows its owning structure placement and remains visible when molecular layers are hidden. It draws an outline, not a filled surface.

plane {"structure":1,"center":[0,0,0],"normal":[0,0,1],"tangent":[1,0,0],"size":[4,2],"color":[226,232,240,255],"width_pixels":1.6,"opacity":1}
undo
redo

The same command runs through Python Session.execute. Rust callers can add a PlaneSpec with Scene::add; patches use add_plane and remove_plane.

When something goes wrongCopy Anchor Link

Errors point at the problem and suggest a fix:

error: 'shwo' is not a command; did you mean 'show'?
  --> line 1, column 1
   | shwo cartoon, protein
   | ^^^^