Query-driven visualization

MolGFX does not define a second selection language. Every representation target and select statement uses a MolFrame query unchanged; see Writing queries and commands.

Use a raw query for a one-off representation. Use a named selection when several visual operations should follow the same molecular region.

import molframe
import molgfx

structure = molframe.read("4hhb.cif").infer_bonds()
scene = molgfx.Scene(structure)

scene.add(molgfx.rep.cartoon(target="protein"))
scene.add(molgfx.rep.spacefill(target="resname HEM"))

Name a visual selectionCopy Anchor Link

In a Session, select NAME, QUERY stores the query under $NAME. It is a declarative definition, not a frozen list of atom rows.

select heme, resname HEM
select pocket, byres (within 5 of $heme) and protein

Use the named selection in visual commands:

show spacefill, $heme
show ball_and_stick radius=0.25 as pocket, $pocket
color orange, $pocket
focus $heme

• $heme and $pocket name selections.
• @pocket names the layer created by as pocket.
• show creates or reveals a representation; color changes its appearance; focus records the region a viewer should frame.

Redefining select pocket, … retargets visual layers and color rules that use $pocket. The scene stays coherent without reconstructing unrelated representations.

Build a pocketCopy Anchor Link

Pass this program to Session.execute():

select heme, resname HEM
select pocket, byres (within 5 of $heme) and protein
show cartoon, protein
show spacefill color=orange, $heme
show ball_and_stick radius=0.25 as pocket, $pocket
color chain, @pocket
focus $heme

A multi-statement program is validated as one atomic scene edit. If one statement is invalid, the scene does not change.

Completion, history and undoCopy Anchor Link

• Session.completions(text, cursor) offers MolFrame query keywords and your named selections after a command comma (not yet the values in the structure, such as residue names).
• Session.history lists the programs that ran.
• Undo/redo reverse or restore a complete successful program.
• Errors identify their source span and may offer a spelling suggestion.

Picking reports the semantic entity under a pixel through Renderer.pick; it does not create or edit a selection. Click, lasso, or selection-editor interfaces belong to the application above the MolGFX scene API.

Interaction and verification boundaryCopy Anchor Link

Dollar-prefixed selection references are dynamic MolFrame query dependencies; at-prefixed layer references identify retained visual layers. They are intentionally distinct. Selection mutations belong to the Session transaction and history path, while hover is local, latest-only presentation state and must not enter undo history. A semantic pick carries structure and topology identity, instance provenance, and generation checks; stale or non-atom picks are rejected rather than reinterpreted as atom rows.

The query and command examples above are documentation examples; this page does not certify any browser or device run.