Selection Algebra

From PyMOLWiki
(Redirected from Selection)
Jump to navigation Jump to search
show spheres, solvent and chain A
show spheres, solvent or chain A

PyMOL's selection language allows to select atoms based on identifiers and properties. Many commands (like color, show, etc.) take an atom selection argument to only operate on a subset of all atoms in the scene. Example:

PyMOL>show spheres, solvent and chain A

Selections can be made more precise or inclusive by combining them with logical operators, including the boolean and, or, and not. The boolean and selects only those items that have both (or all) of the named properties, and the boolean or selects items that have either (or any) of them.

Selection Operator/Modifier Table

Selection operators and modifiers are listed below. The dummy variables s1 and s2 stand for selection-expressions such as "chain a" or "hydro."

Operator Aliases Description
all * All atoms currently loaded into PyMOL
none Empty selection
enabled Atoms from enabled objects
Named selections
sele Named selection or object "sele", but only if it doesn't conflict with the name of another operator
%sele Named selection or object "sele"       Recommended, avoids ambiguity
?sele Named selection or object "sele", or empty selection if "sele" doesn't exist
not S1 ! Inverts selection
S1 and S2 & Atoms included in both S1 and S2
S1 or S2 | Atoms included in either S1 or S2
S1 S2 implicit or
S1 and (S2 or S3) Parentheses for evaluation order control
first S1 First atom in S1 (single atom selection)
last S1 Last atom in S1 (single atom selection)
Identifiers   (see also Selection Macros)
model 1ubq m. Atoms from object "1ubq"
chain C c. Chain identifier "C"
segi S s. Segment identifier "S" (label_asym_id from mmCIF)
resn ALA r. Residue name "ALA"
resi 100-200 i. Residue identifier between 100 and 200
name CA n. Atom name "CA"
alt A Alternate location "A"
index 123 idx. Internal per-object atom index (changes with sorting)
id 123 ID column from PDB file
rank 123 Per-object atom index at load time (see also retain_order)
pepseq ACDEF ps. Protein residue sequence with one-letter code "ACDEF" (see also FindSeq)
label "Hello World" Atoms with label "Hello World" (new in PyMOL 1.9)
Identifier matching
S1 in S2 Atoms in S1 whose identifiers name, resi, resn, chain and segi all match atoms in S2
S1 like S2 Atoms in S1 whose identifiers name and resi match atoms in S2
Entity expansion
Important: All "by"-operators have a weak priority, so (byres S1 or S2) is actually identical to (byres (S1 or S2)) and not to ((byres S1) or S2)
byobject S1 Expands S1 to complete objects
bysegi S1 bs. Expands S1 to complete segments
bychain S1 bc. Expands S1 to complete chains
byres S1 br. Expands S1 to complete residues
bycalpha S1 bca. CA atoms of residues with at least one atom in S1
bymolecule S1 bm. Expands S1 to complete molecules (connected with bonds)
byfragment S1 bf.
byring S1 All rings of size ≤ 7 which have at least one atom in S1 (new in PyMOL 1.8.2)
bycell S1 Expands selection to unit cell
Bond expansion
bound_to S1 bto. Atoms directly bonded to S1, may include S1
neighbor S1 nbr. Atoms directly bonded to S1, excludes S1
S1 extend 3 xt. Expands S1 by 3 bonds connected to atoms in S1
Proximity   (see also comparison of distance operators)
S1 within 12.3 of S2 w. Atoms in S1 that are within 12.3 Angstroms of any atom in S2
S1 around 12.3 a. Atoms with centers within 12.3 Angstroms of the center of any atom in S1
S1 expand 12.3 x. Expands S1 by atoms within 12.3 Angstroms of the center of any atom in S1
S1 gap 1.2 Atoms whose VDW radii are separated from the VDW radii of S1 by a minimum of 1.2 Angstroms.
S1 near_to 12.3 of S2 nto. Same as within, but excludes S2 from the selection (and thus is identical to S1 and S2 around 12.3)
S1 beyond 12.3 of S2 be. Atoms in S1 that are at least 12.3 Anstroms away from S2
partial_charge < 1.2 pc.
formal_charge = 1 fc.
b < 100.0 B-factor less than 100.0
q < 1.0 Occupancy less than 1.0
ss H+S Atoms with secondary structure H (helix) or S (sheet)
elem C e. Atoms of element C (carbon) = 12 < 12.3 in 12+34
stereo R Chiral R/S stereo center with label R (only Incentive PyMOL 1.4-1.8)
bonded Atoms which have at least one bond
protected see protect
fixed fxd. see flag
restrained rst. see flag
masked msk. see mask
flag 25 f. Atoms with flag 25, see flag
Chemical classes
organic org. Non-polymer organic compounds (e.g. ligands, buffers)
inorganic ino. Non-polymer inorganic atoms/ions
solvent sol. Water molecules
polymer pol. Protein or Nucleic Acid
polymer.protein Protein (New in PyMOL 2.1)
polymer.nucleic Nucleic Acid (New in PyMOL 2.1)
guide Protein CA and nucleic acid C4*/C4'
hetatm Atoms loaded from PDB HETATM records
hydrogens h. Hydrogen atoms
backbone bb. Polymer backbone atoms (new in PyMOL 1.6.1)
sidechain sc. Polymer non-backbone atoms (new in PyMOL 1.6.1)
metals Metal atoms (new in PyMOL 1.6.1)
donors don. Hydrogen bond donor atoms
acceptors acc. Hydrogen bond acceptor atoms
visible v. Atoms in enabled objects with at least one visible representation
rep cartoon Atoms with cartoon representation
color blue Atoms with atom-color blue (by color index)
cartoon_color blue Atoms with atom-level cartoon_color setting (by color index)
ribbon_color blue Atoms with atom-level ribbon_color setting (by color index)
Non molecular
center Pseudo-atom at the center of the scene
origin Pseudo-atom at the origin of rotation
state 123 Atoms with coordinates in state 123
present pr. Atoms with coordinates in the current state
x < 12.3 Atoms with model-space x coordinate less than 12.3
y < 12.3 Atoms with model-space y coordinate less than 12.3
z > 12.3 Atoms with model-space z coordinate greater than 12.3
Atom typing
text_type TT tt. Auto-assigned in Incentive PyMOL 1.4-1.8)
numeric_type 123 nt.

Comparison of distance operators

There are serveral very similar operators that select by pairwise atom distances. The following table lists the details how they differ.

Syntax 1: s1 operator X of s2
Syntax 2: s1 and (s2 operator X)

operator distance is ... measured from includes s2 syntax notes
near_to ≤ X center never 1 equivalent to "around"
within ≤ X center if matches s1 1
beyond > X center never 1
gap > X center+vdw never 2
around ≤ X center never 2 equivalent to "near_to"
expand ≤ X center always 2

Language Properties

  • names and keywords are case-insensitive unless ignore_case is set
  • names and keywords can be abbreviated to non-ambiguous prefixes

Best practice recommendation: Only write case-sensitive, non-abbreviated selection expressions. That way your scripts will be robust against run-time configuration and future changes to the language (like addition of new keywords).


Logical selections can be combined. For example, you might select atoms that are part of chain a, but not residue number 125:

# selects atoms that are part of chain A, but not residue number 125.
select chain A and (not resi 125)

# The following two selections are equivalent, 
select (name CB or name CG1 or name CG2) and chain A

# select c-beta's, c-gamma-1's and c-gamma-2's 
# that are in chain A.
select name CB+CG1+CG2 and chain A

# select all residues within 5 Ang. or any organic small molecules
select br. all within 5 of organic

# select helices
select ss 'H'

# select anything shown as a line
select rep lines

# select all residues with a b-factor less than 20, within 3 angstroms of any water
select br. b<20 & (all within 3 of resn HOH)

# select anything colored blue
select color blue

# select the 1st arginine
select first resn ARG

# select 1foo's segment G's chain X's residue 444's alpha carbon
select 1foo/G/X/444/CA
# same thing
select 1foo and segi G and c. X and i. 444 and n. CA

# select the entire object that residue 23's beta caron is in:
select bo. i. 23 and n. CA

# select the molecule that chain C is in
select bm. c. C

Like the results of groups of arithmetic operations, the results of groups of logical operations depend on which operation is performed first. They have an order of precedence. To ensure that the operations are performed in the order you have in mind, use parentheses:

byres ((chain A or (chain B and (not resi 125))) around 5)

PyMOL will expand its logical selection out from the innermost parentheses.

See Also