Selections and color

MolGFX consumes MolFrame selections. The simplest target is a query string:

import molframe
import molgfx

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

heme = "resname HEM"
pocket = "byres (within 5 of resname HEM) and protein"
scene.add(molgfx.rep.spacefill(target=heme))
scene.add(molgfx.rep.ball_and_stick(target=pocket, radius=0.25))

To learn the query language, start with Writing queries and commands; every keyword is in the MolFrame query reference. For the command workflow that turns a query into visual layers, see Query-driven visualization. MolGFX preserves the MolFrame language rather than translating it.

Naming trapsCopy Anchor Link

• chain C, resid and resname use the author's names; label_chain, label_resid and label_resname use the mmCIF label ids. chain label:X is not syntax: it is read as a chain literally named label:X and matches nothing.
• molframe.sel.residue("GLY") takes a residue name. A number is not a residue index: sel.residue("5") means resname "5".
• A representation whose target selects no atoms is rejected with SpecError, the same way scene.pocket rejects an empty focus. Pass allow_empty=True to scene.add when an empty target is intentional.
• Ligand, nucleic acid and glycan selections are empty on a protein-only entry such as 4HHB, which only carries the heme.

try:
    scene.add(molgfx.rep.licorice(target="chain label:X"))
except molgfx.SpecError as error:
    print(error)  # names the query and explains author versus label names

scene.add(molgfx.rep.licorice(target="chain label:X"), allow_empty=True)

Color mappingsCopy Anchor Link

scene.add(molgfx.rep.cartoon(
    target="protein",
    color=molgfx.color.chain(),
))
scene.add(molgfx.rep.ball_and_stick(
    target="resname HEM",
    color=molgfx.color.element(),
))

Available mappings are uniform, element, chain, residue, secondary_structure, and property. property takes a bound scalar property, a supported ramp, and an explicit domain. Its ColorSpec.legend_json() provides legend data for an application UI.

Colouring by what the structure already knowsCopy Anchor Link

molgfx.color.metric(name) colours by a value derived from the structure, so nothing is extracted by hand. Each metric brings a default domain and ramp, which you can override:

scene.add(molgfx.rep.cartoon(target="protein", color=molgfx.color.metric("rainbow")))
scene.add(molgfx.rep.cartoon(target="protein", color=molgfx.color.metric("plddt")))

plddt reads the temperature-factor column, where predicted structures store their score; for an experimental structure use b_factor. The plddt ramp lays the four AlphaFold confidence bands (below 50, to 70, to 90, above) over a 0 to 100 domain with eleven anchors, so each band edge blends over ten score points instead of stepping. The mapping is stated, the domain is fixed, and the colour is reversible to the value through its legend.

A continuous colour is set on a representation, not on a query rule: in command text write show cartoon as main, protein and then color rainbow, @main.

A uniform colour in Python is an RGB triple or a ColorSpec: color=(178, 34, 34). In command text, a colour may also be a named colour or a hex triple: color firebrick, protein and color #b22222, protein are the same rule. The named set covers the conventional element and presentation names; any other colour is written as hex.

Colouring from your own arrayCopy Anchor Link

scene.bind_property binds one value per atom and molgfx.color.property maps it through a ramp. molgfx.by_array does both and derives the source hash from the data, so no hash is invented:

bfactors = [0.1 * index for index in range(len(structure.select("all")))]
scene.add(molgfx.rep.spacefill(target="all", color=molgfx.by_array(scene, bfactors, ramp="viridis")))

domain defaults to the data's minimum and maximum, and name to values-<hash> (property names are unique per scene). molgfx.bind_array binds without colouring. The declarative pair bind_property plus color.property remains the core and is what a stored scene contains.

Opacity and visual stateCopy Anchor Link

A representation ID gives direct scene controls:

layer = scene.add(molgfx.rep.cartoon(target="protein"))
scene.set_opacity(layer, 0.65)
scene.set_visible(layer, True)
scene.focus("resname HEM")

For reactive appearance, scene.set_interaction supports selected, hovered, focused, muted, hidden, and named custom channels. Pair a channel with a molgfx.visual.style only when your application needs state-dependent styling.