View settings, and selecting items

You can select an atom, bond, or residue by right-clicking on it. Only one of these selection categories can be used at a time. To change which, use the View/Sel level dropdown in the view section of the UI. Hotkeys for cyling: ; and '. You can deselect an item by right-clicking it again, selecting another item, or pressing the Esc key. Pressing Esc with nothing selected deactivates the active molecule. You can cycle through items using the next atom (or next bond, next residue etc, depending on the view/selection level), or their hotkeys, Left arrow and Right arrow.

Selecting multiple atoms

To select multiple items, hold shift while selecting. This can be used in the molecule editor to create covalent bonds, or more generally, to see info from multiple atoms at once. It's also the selection mode entered in atom searches when there is more than one matching result.

Selected items are rendered in red.

In addition to affecting selection behavior, View/Sel level also changes the color scheme of the displayed molecule. In Residue mode, it colors each residue together instead of color coding by atom.

Selection expressions

Open Selections / layers. Enter an expression and press Enter or click Select / preview. Use Shift+Enter for a new line. Expressions search all loaded objects, including hidden objects.

Molchanica supports most commonly used PyMOL selection syntax. References: official PyMOL operator table, PyMOL selection algebra, and PyMOL selection commands. The supported forms and limits are listed below.

Build selections without syntax

Use Build a selection with controls (expanded by default). Click types, objects, chains, residue types, and elements to toggle them. Choices within a row use OR; different rows use AND. No choices in a row means that row does not restrict the selection. Clearing every filter selects no atoms.

Controls	Generated expression (examples)
Protein; Alpha carbons	(protein) and (protein and name CA)
Chains A and B; oxygen	(chain "A" or chain "B") and (elem "O")
Acidic	(resn "ASP" or resn "GLU")
Residue numbers: 100-120	resi "100-120"
Exclude water; exclude hydrogens	not hydrogens and not solvent
Protein; within 4 Å of ligands; whole residues	byres ((protein) and (all within 4 of (ligand)))

Controls replace the expression box and preview immediately. Invert selects the complement. Reset controls / select all explicitly selects all atoms; Select none clears the selection. For of picked atoms, the target is captured when you choose it. Capture picked atoms updates that target. You can edit the generated expression directly.

Commands and names

The select prefix is optional. Supplying name, expression saves or updates a named selection. Without a name, an expression only changes the current selection.

elem O
select elem O
select alpha_carbons, protein and name CA
select acidic_res, resn ASP+GLU
binding_loop, chain A and resi 100-120
select active_site, byres (protein within 4 of ligand)

alpha_carbons
%acidic_res and chain A
?optional_selection or resn HIS
sele and not hydrogens

alpha_carbons, acidic_res, binding_loop, and active_site are example names you define, not built-in biological annotations. %name explicitly references a name; ?name returns an empty selection if it does not exist. Bare object names work too; model explicitly selects an object.

Names start with a letter or underscore and contain letters, digits, and underscores. Reserved selection keywords cannot be names. Names, keywords, and text matching are case-insensitive.

Save / update name uses the separate name field. Saved expressions are reevaluated against loaded objects; any sele in a saved expression captures the picked atoms at save time. Named selections and representation layers are saved with preferences. A selection cannot be deleted while another saved selection or layer references it.

Identifiers, lists, and wildcards

Text values accept + lists and * wildcards. Quote paths or values containing spaces. resi, id, and index accept inclusive numeric ranges and + lists.

model receptor
receptor and chain A
model "C:\structures\my receptor.cif"
model "receptor*" and name CA
chain A
chain "A"
chain A+B
chain ""
resi 100-120
resi 10+25+100-120
resn ASP+GLU
resn HOH+WAT
name CA
name CA+CB+CG*
elem C+N+O
id 12+25-30
index 1-10
alt A+B
alt "" or alt A

id uses file atom serial numbers; index is the current 1-based index within each object. Residue numbers are file residue numbers, rather than positions in the residue list. Object matching checks the identifier, custom name, path, filename, and filename stem.

Boolean combinations

chain A and resi 100-120
protein and not hydrogens
resn ASP or resn GLU
(chain A or chain B) and name CA
chain A & !solvent
chain A | chain B
name CA name CB

! / not invert, & / and intersect, and | / or combine. and binds more tightly than or. Adjacent expressions imply or: name CA name CB means name CA or name CB. Use parentheses to make grouping explicit.

Chemical classes

all
none
enabled
present
protein
polymer.protein
nucleic
polymer.nucleic
polymer
ligand
organic
inorganic
lipid
solvent
water
hydrogens
backbone
sidechain
guide
metals
hetatm
bonded

Selector	Meaning
all, * / none	All / no atoms
enabled / present	Atoms in visible objects / all currently loaded atoms
protein, polymer.protein	Amino acid residues
nucleic, polymer.nucleic / polymer	DNA or RNA / protein plus DNA or RNA
ligand / lipid	Ligand objects and protein hetero groups / lipid objects
organic / inorganic	Non-polymer groups containing carbon / other non-polymer groups, excluding water
solvent, water	Water
hydrogens, hydro, hydrogen	Hydrogen atoms
backbone / sidechain	Polymer backbone / remaining polymer atoms
guide	Protein CA or nucleic acid C4' / C4* atoms
metals / hetatm / bonded	Metal elements / HETATM records / atoms with covalent bonds

Whole residues, chains, objects, and molecules

byres (name OD1)
byres (protein within 4 of ligand)
bychain (resi 100 and chain A)
byobject (name CA and resi 100)
bycalpha (resn ASP+GLU)
bymolecule (id 12)
byfragment (id 12)
first (resn HIS and name CA)
last (chain A and name CA)

byres, bychain, and byobject expand to complete entities. bycalpha selects protein CA atoms of touched residues. bymolecule / byfragment follow covalent connectivity. first and last select a single atom in loaded object/atom order.

The by operators have weak priority:

byres (name OD1 or name OE1)
byres name OD1 or name OE1
(byres name OD1) or name OE1

The first two expand both atom-name selections; the third expands only the OD1 selection.

Distances and bonds

Distances use current atom centers in Å, including molecule movement.

protein within 4 of ligand
byres (protein within 4 of ligand)
resn ASP within 5 of resn LYS
ligand around 4
ligand expand 4
protein near_to 4 of ligand
protein beyond 8 of ligand
neighbor (name CA)
bound_to (name CA+CB)
(name CA) extend 2

Operator	Result
S1 within D of S2	Atoms of S1 within D of S2; may include S2
S1 near_to D of S2	As above, excluding S2
S1 beyond D of S2	Atoms of S1 farther than D from every atom of S2; excludes S2
S around D	Nearby atoms, excluding S
S expand D	S plus nearby atoms
neighbor S	Directly bonded atoms, excluding S
bound_to S	Directly bonded atoms; may include atoms of S bonded to each other
S extend N	S plus atoms reached within N covalent bonds

Properties and identifier matching

q >= 0.5
occupancy < 1
partial_charge < -0.2
charge > 0
x >= 10 and x <= 20
y < 0 or z > 15
ss H
ss H+S
ss L
model reference in model mobile
model reference like model mobile

Numeric comparisons accept <, <=, >, >=, =, ==, and !=. q means occupancy; charge means partial charge. Missing values do not match. ss uses loaded helix (H), sheet (S), and remaining protein/loop (L) assignments.

in matches atom name, residue number, residue name, and chain; like matches only atom name and residue number. Segment identifiers are unavailable in both cases.

Short forms and selection macros

Full form	Short form
model, chain, resi, resn, name, elem, index	m., c., i., r., n., e., idx.
hydrogens, backbone, sidechain	h., bb., sc.
polymer, organic, inorganic, solvent, present	pol., org., ino., sol., pr.
byres, bychain, byobject, bycalpha, bymolecule, byfragment	br., bc., bo., bca., bm., bf.
neighbor, bound_to, extend	nbr., bto., xt.
within, around, expand, near_to, beyond	w., a., x., nto., be.
partial_charge, like	pc., l.

Use /object/segment/chain/resi/name, leaving unused fields empty. Without the leading slash, short macros fill fields from the right. The segment field must be empty.

/receptor//A/100/CA
receptor//A/100-120/CA
A/100/CA
100/CA
/////CA
c. A & n. CA
br. (pol. w. 4 of org.)

Compatibility limits

Selections use metadata retained by Molchanica. B factors (b), formal charges, segment IDs (segi), original load ranks, sequence patterns (pepseq), donor/acceptor classification, PyMOL flags, representations/colors, custom properties, state numbers, pseudo-atoms, ring/unit-cell expansion, and van der Waals gap are not supported. Full commands with additional PyMOL options after the expression are not supported. Use the full keywords or the short forms listed above.

Residue numbers are nonnegative integers; negative numbers and insertion codes such as 100A are not retained. Chain IDs currently come from protein objects. Standalone ligand objects may lack residue IDs and residue/atom names; use their object name or atom serial numbers. Bond selectors require loaded/inferred covalent bonds. Secondary structure depends on loaded assignments; unassigned protein atoms match ss L.

Add layer displays an expression as a representation. Pick its view and customize its color, opacity, and radius in Representation layers. Use picked selection captures the current selection as an expression; Use object… inserts an explicit object selector.

Information display

The UI displays a consise bit of data for the selected item; its contents depend on the type of selection. See the examples below:

Atom selection data:

Bond selection data displays two lengths: Both the instantaneous, measured length, and the equilibrium length maintained by force field bonded parameter. It also includes the oscillation frequency around this length, derived from the force field.

Residue selection data:

When you select an atom or bond in a small organic molecule, that molecule is set as the active molecule.

View modes

You can use the View dropdown in the UI to select one of several visualization modes. You can toggle between them using the Left and right bracket keys Below is a summary:

• Sticks: Covalent bonds as cylinders
• Ball and stick: Covalent bonds as cylinders; atoms as spheres
• Spacefill: Spheres on each atom, with size of the atom's Van der Waal radius
• Ribbon: An abstract depiction of a protein's secondary structure; also known as cartoon.
• Surface: A transparent Van der Waals, transparent surface, overlayed over sticks
• Dots: A Van der Waal surface, depicting with dots at the vertices, and no surface mesh
• Backbone: like sticks, but with no side chains

Color codes

By default, atoms are color-coded using the typical CPK scheme. We have mimicked the specific colors used by PyMol in some cases. For example, Carbon atoms are green, oxygen atoms are red, nitrogen blue, hydrogen white. Alternate color schemes are available depending on the Vew / Sel level: If atom or bond is set, you can color atoms by partial charge. If Residue is set, you can color by the residue's position, e.g. in its polypeptide chain. In all coloring modes that represent a scalar value on a fixed range, we use the Viridis color map to smoothly display the transition. FOr example, between positive and negative charge, lipophilicity, or first and last residue.

To enable these, select the Color by q or Color by res UI items.

You can also color small molecules each a different color using the Contrast ligs button. This also uses a Viridis color scheme.

If in the Residue view/select mode, there is a dropdown displayed to select how to color residues. For example, you can color by hydrophobicity, position in sequence, or a fixed color for each residue. If viewing in Surface mode, an additional Color sfc dropdown is displayed. In most of these options, the solvent-accessible surface will be colored according to the atoms closest to it. For example, it can color by element, charge, or lipophilicity of neghboring atoms and residues. Here's an example of it colored by hydrophobicity.

Example of a small molecule colored in CPK:

The same molecule, colored by partial charge. Yellow is positive charge; purple is negative.:

Example of residues colored by position in sequence:

Proteins: Color by residue

You can color proteins by residues by selecting Residue from the View/Sel level dropdown. This will color each residue a solid color. You can select which color scheme this is from the dropdown that will appear next to it. Choose from the following options:

• AA: Each amino acid residue has its own color.
• Posit: Colored by position in the chain, using a viridis color map. From start to end, maps from yellow to purple.
• Hydro: Colored by hydrophobicity, using a viridis color map. From hydrophobic to hydrophilic.
• SIFTS: Colored by Structure Integration with Function, Taxonomy and Sequence (SIFTS) mapping, using a contrasting color map. Uses data from PDBe and UniProt. Colors the protein by entity ID, which makes chains, etc, which are copies of one another, or otherwise function similarly, colored the same. This can be a visually intuitive way to color biologically-related sections the same color.
• Chain: Each chain is colored with a different, contrasting color.

Molecule display adjustments

There are several ways to adjust how molecules are displayed. For exampl,e you can adjust the Depth and Far sliders to respectively filter out molecules too close to the camera, and fade out molecules far from it. This may be useful for examining specific residues in a protein, reducing background clutter. You can also adjust the far setting by scrolling using the mouse wheel while holding the Ctrl key.

Click Dim peptide to blend the protein's color into the background, i.e. darkening it. This makes other molecules easier to view when near the protein, without hiding it entirely.

Filters

There are several filter buttons available in the View UI toolbar. You can click this to toggle on or off various parts of molecules. Some of these are specific to proteins, and their filter controls will only display if a protein is open. For example, you can filter out side chains, water molecules, hetero atoms, or non-hetero (amino acid) atoms. You can also hide or display hydrogen atoms, and hydrogen bonds.

For proteins that have multiple chains, a button for each chain will display, with the chain's identifier (e.g. a letter). Click this to show or hide the chain.

You can also filter by location of a protein atom; use the buttons labeled near to do this. For example, you can filter by only atoms near the selected item, only near the active ligand molecule, or only near the surface of the protein. If one of these is selected, a distance slider will appear; this lets you set the distance threshold for the selected filter[s].

Searching for atoms and residues

You can use the Find input box to search for atoms or residues. It will search within the active molecule only, so prior to using it, you may need to set the active molecule by clicking its identifier in the sidebar, or seelcting an atom (etc) in it by right-clicking. Some examples of how to use this:

• Search for an atom by serial number
• Search for a residue by serial number: To do this, you must be in the Residue View/Select mode.
• Search for a residue by its amino acid identifier: Either a 3-letter identifier like Met, or a one-letter identifier like M.
• Search for a hetero residue by name.