Contents Previous Next

Command Syntax and Atom Selections

Syntax

A typed PyMOL command always starts with a keyword that calls PyMOL to execute an action. It ends with a carriage return ("enter" on your keyboard).

The simplest commands consist of a keyword alone. For example, typing quit will end your PyMOL session. The quit command never takes an argument.

Many commands have default arguments, so you can type the keyword alone and PyMOL will supply the rest. For example, the default argument to zoom is the selection-expression all:

  
EXAMPLE
   
   PyMOL> zoom                    # All visible representations
                                  # are included in the view. 

For some keywords, certain arguments are required and others are supplied by default. For example, the keyword color requires one argument, the color-name. As for zoom, the default selection-expression is all:

SYNTAX
      
   color color-name  
      
   color color-name, selection-expression       

EXAMPLES
      
   PyMOL> color red               # All the representations
                                  # are colored red.    
      
   PyMOL> color red, name ca      # Only the representations of
                                  # atoms named c-alpha are colored red.                                             
When you type a command that has more than one argument, color color-name, selection-expression in this case, a comma must separate the arguments.

Selection-expressions are an essential type of keyword argument. They can be simple or complex, with several different kinds of syntax.

Selection-expressions

Selection-expressions stand for lists of atoms in arguments that are subject to PyMOL commands. You can name the selections to facilitate their re-use, or you can specify them anonymously (without names). Object and selection names may include the upper or lower case characters A/a to Z/z, numerals 0 to 9, and the underscore character (_). Characters to avoid include:

! @ # $ % ^ &* ( ) ' " [ ] { } \ | ~ ` <> . ? / 

Selection-expressions describe the class of atoms you are referencing. Most of them require identifiers to complete the specification. For example, the selector resi references biopolymer residues by sequence number, and the identifier gives the number. The selector name references atoms according to the names described in the PDB, and the identifier gives the name (ca for alpha carbons, cb for beta carbons, etc). A handful of selection-expressions don't require identifiers, but most do.

PyMOL uses several logical operators to increase the generality or specificity of selection-expressions. Logical combinations of selectors can get complex, so PyMOL accepts short forms and macros that express them with a minimum of keystrokes. This section describes named-selections, and then gives the syntax for making selections in a progression from simple one-word selectors to complex combinations of selectors, using macros and short forms.

Named Atom Selections

Atom selections can be named for repeated use by using the select command:

SYNTAX
      
   select  selection-name, selection-expression   
                                           # The  selection-name and  
                                           # the  selection-expression 
                                           # are both arguments to select 
                                           # so they are separated by a comma. 
                                           
EXAMPLE

   PyMOL> select bb, name c+o+n+ca   # Create an atom selection named "bb"
                                     # including all atoms named 
                                     # "C","O","N", or "CA";
   PyMOL> color red, bb              # color the selection red,
   PyMOL> hide lines, bb             # hide the line representation,
   PyMOL> show sticks, bb            # show it using the stick representation,
   PyMOL> zoom bb                    # and zoom in on it.

In this case, the selection-expression is the property selector name, which takes the list of identifiers ca+c+n+o to complete the specification. Property selectors and their identifiers are discussed below.

Named atom selections appear in the PyMOL names list in the control panel. They are distinguished from objects by a surrounding set of parentheses. The control panel options available under the diamond menu differ between objects and atom-selections, because objects and named selections play slightly different roles in PyMOL. Named selections are pointers to subsets of data that are found under an object name. After an object is deleted, the data are no longer available, unless you reload the object. Any named selections that refer to atoms in that object will no longer work. But when named selections are deleted, the data are still available under the object name. Disabling objects eliminates them from the viewer, but disabling named-selections just turns off the pink dots that highlight them in the viewer.

Atom-selections, named or not, can span multiple objects:

EXAMPLE

   PyMOL> load $PYMOL_PATH/test/dat/fc.pdb                                      
   PyMOL> load $PYMOL_PATH/test/dat/pept.pdb

   PyMOL> select alpha_c, name ca      # The named selection "alpha_c" 
                                         # is created -- it includes atoms
                                         # in both "fc" and "pept" objects.
   PyMOL> color red, name ca             # "CA" atoms in both objects
                                         # are colored red.                                      

Named selections will continue working after you have made changes to a molecular structure:

EXAMPLE

   PyMOL> load $PYMOL_PATH/test/dat/pept.pdb                                      
   PyMOL> select bb, name c+o+n+ca     # The named selection "bb" 
                                       # is created.        
                                       
   PyMOL> count_atoms bb               # PyMOL counts 52 atoms in "bb."   
   
   PyMOL> remove resi 5                # All atoms in residue 5 are removed 
                                       # from the object "pept."  
                                       
   PyMOL> count_atoms bb               # Now PyMOL counts
                                       # the remaining 48 atoms in "bb."                                                                                                                                            

Named selections are static. Only atoms that exist at the time the selection is defined are included in the selection, even if atoms which are loaded subsequently fall within the selection criterion:

EXAMPLE

   PyMOL> load $PYMOL_PATH/test/dat/pept.pdb      
   
   PyMOL> select static_demo, pept    # The named selection "static_demo" 
                                      # is created to reference all atoms.  
                                      
   PyMOL> count_atoms static_demo     # PyMOL counts 107 atoms 
                                      # in "static_demo."   
                                      
   PyMOL> h_add                       # PyMol adds hydrogens in
                                      # the appropriate places
                                      
   PyMOL> count_atoms static_demo     # PyMOL still counts 107 atoms
                                      # in "static_demo,"
   PyMOL> count_atoms                 # even though it counts 200 atoms
                                      # in "pept." 

Named selections can also be used in subsequent atom selections:

EXAMPLE

   PyMOL> select bb, name c+o+n+ca   # An atom selection named "bb"
                                     # is made, consisting of all 
                                     # atoms named "C","O","N", or "CA."
                                           
   PyMOL> select c_beta_bb, bb or name cb   
                                     # An atom selection named "c_beta_bb"
                                     # is made, consisting of 
                                     # all atoms named "C", "O", "N", "CA" or "CB."  

Note that the word "or" is used to select all atoms in the two groups, "bb" and "cb." The word "and" would have selected no atoms because it is interpreted in its boolean logical sense, not its natural language sense. See the subsection on "Selection Algebra" below.

Single-word Selectors

The very simplest selection-expressions are single-word selectors. These selectors do not take identifiers; they are complete by themselves.
Single Word
Selector
Short Form
Selector
Description
all*All atoms currently loaded into PyMOL
nonenoneNo atoms (empty selection)
hydroh.All hydrogen atoms currently loaded into PyMOL
hetatmhetAll atoms loaded from Protein Data Bank HETATM records
visiblev.All atoms in enabled objects with at least one visible representation
presentpr.All atoms with defined coordinates in the current state
(used in creating movies)

The selector none won't come up much when you are typing commands directly into PyMOL, but it is useful in programming scripts.

As the table shows, many single-word selectors have short forms to save on typing. Some short forms must be followed by a period and a space, in order to delimit the word. Short forms and long forms have the same effect, so choose the form that suits you:

   
EXAMPLES 

   PyMOL> color blue, all          # It all turns blue.
   PyMOL> color blue, *
   
   PyMOL> hide hydro               # Representations of all 
   PyMOL> hide h.                  # hydrogen atoms are hidden.
   
   PyMOL> show spheres, hetatom    # All the atoms defined as HETATOMS 
   PyMOL> show spheres, het        # in the PDB input file 
                                   # are represented as spheres.

Property Selectors

PyMOL reads data files written in PDB, MOL/SDF, Macromodel, ChemPy Model, and Tinker XYZ formats. Some of the data fields in these formats allow PyMOL to assign properties to atoms. You can group and select atoms according to these properties using property selectors and identifiers: the selectors correspond to the fields in the data files, and the identifiers correspond to the target words to match, or the target numbers to compare.

The items in a list of identifiers are separated by plus signs (+) only. Do not add spaces within a list of identifiers. The selector resi takes (+)-separated lists of identifiers, as in

   
EXAMPLE 

   PyMOL> select nterm, resi 1+2+3          

or, alternatively, it may take a range given with a dash:

   
EXAMPLE 

   PyMOL> select nterm, resi 1-3          

However, you will get an error message if you try to combine a list and a range in an identifier to a resi as in "select mistake, resi 1-3+6."

The identifier for a blank field in an input file is and empty pair of quotes:

   
EXAMPLE 

   PyMOL> select unstruct, ss ""   # A named selection is created
                                   # to contain all atoms that are not assigned 
                                   # a secondary structure.        

Most property selectors select matches to their identifiers:

Matching
Property
Selector
Short Form
Selector
Identifier
and Example
symbol e. chemical-symbol-list
list of 1- or 2-letter chemical symbols from the periodic table
PyMOL> select polar, symbol o+n
name n. atom-name-list
list of up to 4-letter codes for atoms in proteins or nucleic acids
PyMOL> select carbons, name ca+cb+cg+cd
resn r. residue-name-list
list of 3-letter codes for amino acids
PyMOL> select aas, resn asp+glu+asn+gln 
or list of up to 2-letter codes for nucleic acids
PyMOL> select bases, resn a+g
resi i. residue-identifier-list
list of up to 4-digit residue numbers
PyMOL> select mults10, resi 1+10+100+1000
residue-identifier-range
PyMOL> select nterm, resi 1-10
alt alt alternate-conformation-identifier-list
list of single letters
PyMOL> select altconf, alt a+""
chain c. chain-identifier-list
list of single letters or sometimes numbers
PyMOL> select firstch, chain a
segi s. segment-identifier-list
list of up to 4 letter identifiers
PyMOL> select ligand, segi lig 
flag f. flag-number
a single integer from 0 to 31
PyMOL> select f1, flag 0
  numeric_type   nt. type-number
a single integer
PyMOL> select type1, nt. 5
text_type tt. type-string
a list of up to 4 letter codes
PyMOL> select subset, text_type HA+HC
id id external-index-number
a single integer
PyMOL> select idno, id 23
index idx. internal-index-number
a single integer
PyMOL> select intid, index 11
ss ss secondary-structure-type
list of single letters
PyMOL> select allstrs, ss h+s+l+""

Other property selectors select by comparison to numeric identifiers:

Numeric
Selector
Short Form Argument
&Example
b b comparison-operator b-factor-value
a real number
PyMOL> select fuzzy, b > 10
q q comparison-operator occupancy-value
a real number
PyMOL> select lowcharges, q <0.50
  formal_charge   fc. comparison-operator formal charge-value
an integer
PyMOL> select doubles, fc. = -1
  partial_charge   pc. comparison-operator partial charge-value
a real number
PyMOL> select hicharges, pc. > 1

Details of the atom and residue name formats can be found in the official guide to PDB file formats, http://www.rcsb.org/pdb/docs/format/pdbguide2.2/guide2.2_frame.html.

Selection Algebra

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. Venn diagrams show that and selects the areas of overlap, while or selects both areas.

Operators:

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

OperatorShort form Effect
not s1! s1 Selects atoms that are not included in s1
PyMOL> select sidechains, ! bb
s1 and s2 s1 & s2Selects atoms included in both s1 and s2
PyMOL> select far_bb, bb &farfrm_ten
s1 or s2 s1 | s2Selects atoms included in either s1 or s2
PyMOL> select all_prot, bb | sidechain
s1 in s2 s1 in s2Selects atoms in s1 whose identifiers
name, resi, resn, chain and segi all match atoms in s2
PyMOL> select same_atms, pept in prot
s1 like s2 s1 l. s2Selects atoms in s1 whose identifiers
name and resi match atoms in s2
PyMOL> select similar_atms, pept like prot
s1 gap X s1 gap XSelects all atoms whose van der Waals radii are separated from the van der Waals radii of s1 by a minimum of X Angstroms.
PyMOL> select farfrm_ten, resi 10 gap 5
s1 around X s1 a. XSelects atoms with centers within X Angstroms of the center of any atom in s1
PyMOL> select near_ten, resi 10 around 5
s1 expand X s1 e. XExpands s1 by all atoms within X Angstroms of the center of any atom in s1
PyMOL> select near_ten_x, near10 expand 3
  s1 within X of s   s1 w. X of sSelects atoms in s1 that are within X Angstroms of the s2
PyMOL> select bbnearten, bb w. 4 of resi 10
byres s1br. s 1Expands selection to complete residues
PyMOL> select complete_res, br. bbnear10
byobject s1bo. s1Expands selection to complete objects
PyMOL> select near_obj, bo. near_res
neighbor s1nbr. s1Selects atoms directly bonded to s1
PyMOL> select vicinos, neighbor resi 10

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

      
EXAMPLE

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

   PyMOL> select (name cb or name cg1 or name cg2) and chain A    # These two 
                                                                  # selections are 
   PyMOL> select name cb+cg1+cg2 and chain A                      # equivalent.
                                                                  # select c-beta's,
                                                                  # c-gamma-1's and 
                                                                  # c-gamma-2's 
                                                                  # that are 
                                                                  # in chain A.

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.

Atom Selection Macros

Macros make it possible to represent a long atom selection phrase such as

   
PyMOL> select pept and segi lig and chain b and resi 142 and name ca

in a more compact form:

   
PyMOL> select /pept/lig/b/142/ca

An atom selection macro uses slashes to define fields corresponding to identifiers. The macro is used to select atoms using the boolean "and," that is, the selected atoms must have all the matching identifiers:

   
   /object-name/segi-identifier/chain-identifier/resi-identifier/name-identifier

These identifiers form a hierarchy from the object-name at the top, down to the name-identifier at the bottom. PyMOL has to be able to recognize the macro as one word, so no spaces are allowed within it.

Macros come in two flavors: those that begin with a slash and those that don't. The presence or absence of a slash at the beginning of the macro determines how it is interpreted. If the macro begins with a slash, PyMOL expects to find the fields starting from the top of the hierarchy: the first field to the right of the slash is interpreted as an object-name; the second field as an identifier to segi; the third as an identifier to chain, and so on. It may take any of the following forms:

   
   /object-name/segi-identifier/chain-identifier/resi-identifier/name-identifier
   /object-name/segi-identifier/chain-identifier/resi-identifier
   /object-name/segi-identifier/chain-identifier
   /object-name/segi-identifier
   /object-name

EXAMPLES

   PyMOL> zoom /pept
   PyMOL> show spheres, /pept/lig/
   PyMOL> show cartoon, /pept/lig/a
   PyMOL> color pink, /pept/lig/a/10
   PyMOL> color yellow, /pept/lig/a/10/ca    

If the macro does not begin with a slash, it is interpreted differently. In this case, PyMOL expects to find the fields ending with the bottom of the hierarchy. Macros that don't start with a slash may take the following forms:

                                             resi-identifier/name-identifier
                            chain-identifier/resi-identifier/name-identifier
            segi-identifier/chain-identifier/resi-identifier/name-identifier
object-name/segi-identifier/chain-identifier/resi-identifier/name-identifier

EXAMPLES

   PyMOL> zoom 10/cb
   PyMOL> show spheres, a/10-12/ca
   PyMOL> show cartoon, lig/b/6+8/c+o
   PyMOL> color pink, pept/enz/c/3/n

You can also omit fields between slashes. Omitted fields will be interpreted as wildcards, as in the following forms:

   
   resi-identifier/
   resi-identifier/name-identifier
   chain-identifier//
   object-name//chain-identifier                
   
EXAMPLES

   PyMOL> zoom 142/                  # Residue 142 fills the viewer. 
   
   PyMOL> show spheres, 156/ca       # The alpha carbon of residue 156
                                     # is shown as a sphere     
                                     
   PyMOL> show cartoon, a//          # Chain "A" is shown as a cartoon.  
   
   PyMOL> color pink, pept//b        # Chain "B" in object "pept"
                                     # is colored pink.

Selection macros must contain at least one forward slash in order to distinguish them from other words in the selection language. Being words, they must not contain any spaces. When using macros, it is also important to understand that they are converted into long form before being submitted to the selection engine. This can help in the interpretation of error messages.

Calling Python from within PyMOL

Single-line Python statements can be issued directly within PyMOL. For example:

PyMOL> print 1 + 2
3

Full access is available to standard Python library functions, and you can assign results to symbols.

PyMOL>import time
PyMOL>now = time.time()
PyMOL>print now
1052982734.94

Multi-line blocks of Python can be included within PyMOL command scripts provided that a backslash ('\') is used for continuation on all but the final line.

PyMOL> for a in range(1,6): \
PyMOL>    b = 6 - a \
PyMOL>    print a, b 
1 5
2 4
3 3
4 2
5 1

NOTE: This manual is a PyMOL Incentive Product with a One-Year Evaluation Period. You, your school, or your employer must purchase a PyMOL License & Maintenance Subscription to cover usage beyond the first year. We trust you to support the PyMOL project via the "honor" system, so please do your part! See Usage Terms for more information.
Copyright © 2004 DeLano Scientific LLC. All Rights Reserved.

Contents Previous Next