PyMOL Users Manual

4/8/2016PyMOL Users Manual

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:

E X A M P L E

P y M O L>z o o m#A l l v i s i b l e r e p r e s e n t a t i o n s

#a r e i n c l u d e d i n t h e v i e w.

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:

S Y N T A X

c o l o r c o l o r-n a m e

c o l o r c o l o r-n a m e,s e l e c t i o n-e x p r e s s i o n

E X A M P L E S

P y M O L>c o l o r r e d#A l l t h e r e p r e s e n t a t i o n s

#a r e c o l o r e d r e d.

P y M O L>c o l o r r e d,n a m e c a#O n l y t h e r e p r e s e n t a t i o n s o f

#a t o m s n a m e d c-a l p h a a r e c o l o r e d r e d.

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-expression s are an essential type of keyword argument. They can be simple or complex, with several different kinds of syntax.

Selection-expressions

Selection-expression s 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-expression s describe the class of atoms you are referencing. Most of them require identi?ers to complete the speci?cation. For example, the selector resi references biopolymer residues by sequence number, and the identi?er gives the number. The selector name references atoms according to the names described in

the PDB, and the identi?er gives the name (ca for alpha carbons, cb for beta carbons, etc). A handful of selection-expression s don't require identi?ers, but most do. PyMOL uses several logical operators to increase the generality or speci?city of selection-expression s. 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:

S Y N T A X

s e l e c t s e l e c t i o n-n a m e,s e l e c t i o n-e x p r e s s i o n

#T h e s e l e c t i o n-n a m e a n d

#t h e s e l e c t i o n-e x p r e s s i o n

#a r e b o t h a r g u m e n t s t o s e l e c t

#s o t h e y a r e s e p a r a t e d b y a c o m m a.

E X A M P L E

P y M O L>s e l e c t b b,n a m e c+o+n+c a#C r e a t e a n a t o m s e l e c t i o n n a m e d"b b"

#i n c l u d i n g a l l a t o m s n a m e d

#"C","O","N",o r"C A";

P y M O L>c o l o r r e d,b b#c o l o r t h e s e l e c t i o n r e d,

P y M O L>h i d e l i n e s,b b#h i d e t h e l i n e r e p r e s e n t a t i o n,

P y M O L>s h o w s t i c k s,b b#s h o w i t u s i n g t h e s t i c k r e p r e s e n t a t i o n,

P y M O L>z o o m b b#a n d z o o m i n o n i t.

In this case, the selection-expression is the property selector name, which takes the list of identi?ers ca+c+n+o to complete the speci?cation. Property selectors and their identi?ers 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:

E X A M P L E

https://www.360docs.net/doc/3211374720.html,/newman/user/S0220commands.html1/6

4/8/2016PyMOL Users Manual

https://www.360docs.net/doc/3211374720.html,/newman/user/S0220commands.html

2/6

P y M O L > l o a d $P Y M O L _P A T H /t e s t /d a t /f c .p d b P y M O L > l o a d $P Y M O L _P A T H /t e s t /d a t /p e p t .p d b

P y M O L > s e l e c t a l p h a _c , n a m e c a # T h e n a m e d s e l e c t i o n "a l p h a _c " # i s c r e a t e d -- i t i n c l u d e s a t o m s # i n b o t h "f c " a n d "p e p t " o b j e c t s . P y M O L > c o l o r r e d , n a m e c a # "C A " a t o m s i n b o t h o b j e c t s # a r e c o l o r e d r e d .

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

E X A M P L E

P y M O L > l o a d $P Y M O L _P A T H /t e s t /d a t /p e p t .p d b P y M O L > s e l e c t b b , n a m e c +o +n +c a # T h e n a m e d s e l e c t i o n "b b " # i s c r e a t e d . P y M O L > c o u n t _a t o m s b b # P y M O L c o u n t s 52 a t o m s i n "b b ." P y M O L > r e m o v e r e s i 5 # A l l a t o m s i n r e s i d u e 5 a r e r e m o v e d # f r o m t h e o b j e c t "p e p t ." P y M O L > c o u n t _a t o m s b b # N o w P y M O L c o u n t s # t h e r e m a i n i n g 48 a t o m s i n "b b ."

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

E X A M P L E

P y M O L > l o a d $P Y M O L _P A T H /t e s t /d a t /p e p t .p d b P y M O L > s e l e c t s t a t i c _d e m o , p e p t # T h e n a m e d s e l e c t i o n "s t a t i c _d e m o " # i s c r e a t e d t o r e f e r e n c e a l l a t o m s . P y M O L > c o u n t _a t o m s s t a t i c _d e m o # P y M O L c o u n t s 107 a t o m s # i n "s t a t i c _d e m o ." P y M O L > h _a d d # P y M o l a d d s h y d r o g e n s i n # t h e a p p r o p r i a t e p l a c e s P y M O L > c o u n t _a t o m s s t a t i c _d e m o # P y M O L s t i l l c o u n t s 107 a t o m s # i n "s t a t i c _d e m o ," P y M O L > c o u n t _a t o m s # e v e n t h o u g h i t c o u n t s 200 a t o m s # i n "p e p t ."

Named selections can also be used in subsequent atom selections:

E X A M P L E

P y M O L > s e l e c t b b , n a m e c +o +n +c a # A n a t o m s e l e c t i o n n a m e d "b b " # i s m a d e , c o n s i s t i n g o f a l l # a t o m s n a m e d "C ","O ","N ", o r "C A ." P y M O L > s e l e c t c _b e t a _b b , b b o r n a m e c b # A n a t o m s e l e c t i o n n a m e d "c _b e t a _b b " # i s m a d e , c o n s i s t i n g o f # a l l a t o m s n a m e d "C ", "O ", "N ", "C A " o r "C B ."

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-expression s are single-word selectors. These selectors do not take identi?ers; they are complete by themselves.

Single Word Selector Short Form

Selector Description

all *All atoms currently loaded into PyMOL none none No atoms (empty selection)hydro h.All hydrogen atoms currently loaded into PyMOL hetatm het All atoms loaded from Protein Data Bank HETATM records visible v.All atoms in enabled objects with at least one visible representation

present pr.

All atoms with de?ned 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:

E X A M P L E S

P y M O L > c o l o r b l u e , a l l # I t a l l t u r n s b l u e . P y M O L > c o l o r b l u e , * P y M O L > h i d e h y d r o # R e p r e s e n t a t i o n s o f a l l P y M O L > h i d e h . # h y d r o g e n a t o m s a r e h i d d e n . P y M O L > s h o w s p h e r e s , h e t a t o m # A l l t h e a t o m s d e f i n e d a s H E T A T O M S P y M O L > s h o w s p h e r e s , h e t # i n t h e P D B i n p u t f i l e # a r e r e p r e s e n t e d a s s p h e r e s .

Property Selectors

4/8/2016PyMOL Users Manual

https://www.360docs.net/doc/3211374720.html,/newman/user/S0220commands.html

3/6

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

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

E X A M P L E

P y M O L > s e l e c t n t e r m , r e s i 1+2+3

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

E X A M P L E

P y M O L > s e l e c t n t e r m , r e s i 1-3

However, you will get an error message if you try to combine a list and a range in an identi?er to a resi as in "select mistake, resi 1-3+6."The identi?er for a blank ?eld in an input ?le is and empty pair of quotes:

E X A M P L E

P y M O L > s e l e c t u n s t r u c t , s s "" # A n a m e d s e l e c t i o n i s c r e a t e d # t o c o n t a i n a l l a t o m s t h a t a r e n o t a s s i g n e d # a s e c o n d a r y s t r u c t u r e .

Most property selector s select matches to their identi?ers:

Matching

Property Selector Short Form Selector

Identi?er and Example

symbol

chemical-symbol-list

list of 1- or 2-letter chemical symbols from the periodic table

P y M O L > s e l e c t p o l a r , s y m b o l o +n

name n.

atom-name-list

list of up to 4-letter codes for atoms in proteins or nucleic acids

P y M O L > s e l e c t c a r b o n s , n a m e c a +c b +c g +c d

resn

residue-name-list

list of 3-letter codes for amino acids

P y M O L > s e l e c t a a s , r e s n a s p +g l u +a s n +g l n

or list of up to 2-letter codes for nucleic acids

P y M O L > s e l e c t b a s e s , r e s n a +g

resi

residue-identi?er-list

list of up to 4-digit residue numbers

P y M O L > s e l e c t m u l t s 10, r e s i 1+10+100+1000

residue-identi?er-range

P y M O L > s e l e c t n t e r m , r e s i 1-10

alt alt

alternate-conformation-identi?er-list list of single letters

P y M O L > s e l e c t a l t c o n f , a l t a +""

chain c.

chain-identi?er-list

list of single letters or sometimes numbers

P y M O L > s e l e c t f i r s t c h , c h a i n a

segi s.

segment-identi?er-list

list of up to 4 letter identi?ers

P y M O L > s e l e c t l i g a n d , s e g i l i g

?ag f.

?ag-number

a single integer from 0 to 31

P y M O L > s e l e c t f 1, f l a g 0

numeric_type nt.

type-number a single integer

P y M O L > s e l e c t t y p e 1, n t . 5

text_type tt.

type-string

a list of up to 4 letter codes

P y M O L > s e l e c t s u b s e t , t e x t _t y p e H A +H C

id id

external-index-number a single integer

P y M O L > s e l e c t i d n o , i d 23

index idx.

internal-index-number a single integer

P y M O L > s e l e c t i n t i d , i n d e x 11

secondary-structure-type

4/8/2016PyMOL Users Manual

https://www.360docs.net/doc/3211374720.html,/newman/user/S0220commands.html

4/6

ss ss list of single letters

P y M O L > s e l e c t a l l s t r s , s s h +s +l +""

Other property selector s select by comparison to numeric identi?ers:

Numeric

Selector

Short Form

Argument &Example

comparison-operator b-factor-value a real number

P y M O L > s e l e c t f u z z y , b > 10

q q

comparison-operator occupancy-value a real number

P y M O L > s e l e c t l o w c h a r g e s , q <0.50

formal_charge fc.

comparison-operator formal charge-value an integer

P y M O L > s e l e c t d o u b l e s , f c . = -1

partial_charge pc.

comparison-operator partial charge-value a real number

P y M O L > s e l e c t h i c h a r g e s , p c . > 1

Details of the atom and residue name formats can be found in the of?cial guide to PDB ?le formats,

https://www.360docs.net/doc/3211374720.html,/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 modi?ers are listed below. The dummy variables s 1 and s 2 stand for selection-expressions such as "chain a" or "hydro."

Operator Short form

Effect

not s 1! s 1Selects atoms that are not included in s 1

P y M O L > s e l e c t s i d e c h a i n s , ! b b

s 1 and s 2s 1 & s 2Selects atoms included in both s 1 and s 2

P y M O L > s e l e c t f a r _b b , b b &f a r f r m _t e n

s 1 or s 2

s 1 | s 2

Selects atoms included in either s 1 or s 2

P y M O L > s e l e c t a l l _p r o t , b b | s i d e c h a i n

s 1 in s 2s 1 in s 2

Selects atoms in s 1 whose identi?ers

name, resi, resn, chain and segi all match atoms in s 2

P y M O L > s e l e c t s a m e _a t m s , p e p t i n p r o t

s 1 like s 2s 1 l. s 2

Selects atoms in s 1 whose identi?ers name and resi match atoms in s 2

P y M O L > s e l e c t s i m i l a r _a t m s , p e p t l i k e p r o t

s 1 gap X s 1 gap X Selects all atoms whose van der Waals radii are separated from the van der Waals radii of s 1 by a minimum of X Angstroms.

P y M O L > s e l e c t f a r f r m _t e n , r e s i 10 g a p 5

s 1 around X s 1 a. X Selects atoms with centers within X Angstroms of the center of any atom in s 1

P y M O L > s e l e c t n e a r _t e n , r e s i 10 a r o u n d 5

s 1 expand X

s 1 e. X

Expands s 1 by all atoms within X Angstroms of the center of any atom in s 1

P y M O L > s e l e c t n e a r _t e n _x , n e a r 10 e x p a n d 3

s 1 within X of s 2 s 1 w. X of s 2

Selects atoms in s 1 that are within X Angstroms of the s 2

P y M O L > s e l e c t b b n e a r t e n , b b w . 4 o f r e s i 10

byres s 1br. s 1Expands selection to complete residues

P y M O L > s e l e c t c o m p l e t e _r e s , b r . b b n e a r 10

byobject s 1bo. s 1Expands selection to complete objects

P y M O L > s e l e c t n e a r _o b j , b o . n e a r _r e s

neighbor s 1

nbr. s 1

Selects atoms directly bonded to s 1

P y M O L > s e l e c t v i c i n o s , n e i g h b o r r e s i 10

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

E X A M P L E

4/8/2016PyMOL Users Manual

P y M O L>s e l e c t c h a i n a a n d(n o t r e s i125)#s e l e c t s a t o m s t h a t a r e p a r t o f

#c h a i n a,b u t n o t

#r e s i d u e n u m b e r125.

P y M O L>s e l e c t(n a m e c b o r n a m e c g1o r n a m e c g2)a n d c h a i n A#T h e s e t w o

#s e l e c t i o n s a r e

P y M O L>s e l e c t n a m e c b+c g1+c g2a n d c h a i n A#e q u i v a l e n t.

#s e l e c t c-b e t a's,

#c-g a m m a-1's a n d

#c-g a m m a-2's

#t h a t a r e

#i n c h a i n A.

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

b y r e s((

c h a i n a o r(c h a i n b a n d(n o t r e s i125)))a r o u n d5)

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

P y M O L>s e l e c t p e p t a n d s e g i l i g a n d c h a i n b a n d r e s i142a n d n a m e c a

in a more compact form:

P y M O L>s e l e c t/p e p t/l i g/b/142/c a

An atom selection macro uses slashes to de?ne ?elds corresponding to identi?ers. The macro is used to select atoms using the boolean "and," that is, the selected atoms must have all the matching identi?ers:

/o b j e c t-n a m e/s e g i-i d e n t i f i e r/c h a i n-i d e n t i f i e r/r e s i-i d e n t i f i e r/n a m e-i d e n t i f i e r

These identi?ers form a hierarchy from the object-name at the top, down to the name-identi?er 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 ?avors: 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 ?nd the ?elds starting from the top of the hierarchy: the ?rst ?eld to the right of the slash is interpreted as an object-name; the second ?eld as an identi?er to segi; the third as an identi?er to chain, and so on. It may take any of the following forms: /o b j e c t-n a m e/s e g i-i d e n t i f i e r/c h a i n-i d e n t i f i e r/r e s i-i d e n t i f i e r/n a m e-i d e n t i f i e r

/o b j e c t-n a m e/s e g i-i d e n t i f i e r/c h a i n-i d e n t i f i e r/r e s i-i d e n t i f i e r

/o b j e c t-n a m e/s e g i-i d e n t i f i e r/c h a i n-i d e n t i f i e r

/o b j e c t-n a m e/s e g i-i d e n t i f i e r

/o b j e c t-n a m e

E X A M P L E S

P y M O L>z o o m/p e p t

P y M O L>s h o w s p h e r e s,/p e p t/l i g/

P y M O L>s h o w c a r t o o n,/p e p t/l i g/a

P y M O L>c o l o r p i n k,/p e p t/l i g/a/10

P y M O L>c o l o r y e l l o w,/p e p t/l i g/a/10/c a

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

r e s i-i d e n t i f i e r/n a m e-i d e n t i f i e r

c h a i n-i

e n t i

f i e r/r e s i-i d e n t i f i e r/n a m e-i d e n t i f i e r

s e g i-i d e n t i f i e r/c h a i n-i d e n t i f i e r/r e s i-i d e n t i f i e r/n a m e-i d e n t i f i e r

o b j e c t-n a m e/s e g i-i d e n t i f i e r/c h a i n-i d e n t i f i e r/r e s i-i d e n t i f i e r/n a m e-i d e n t i f i e r

E X A M P L E S

P y M O L>z o o m10/c b

P y M O L>s h o w s p h e r e s,a/10-12/c a

P y M O L>s h o w c a r t o o n,l i g/b/6+8/c+o

P y M O L>c o l o r p i n k,p e p t/e n z/c/3/n

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

r e s i-i d e n t i f i e r/

r e s i-i d e n t i f i e r/n a m e-i d e n t i f i e r

c h a i n-i

e n t i

f i e r//

o b j e c t-n a m e//c h a i n-i d e n t i f i e r

E X A M P L E S

P y M O L>z o o m142/#R e s i d u e142f i l l s t h e v i e w e r.

P y M O L>s h o w s p h e r e s,156/c a#T h e a l p h a c a r b o n o f r e s i d u e156

#i s s h o w n a s a s p h e r e

P y M O L>s h o w c a r t o o n,a//#C h a i n"A"i s s h o w n a s a c a r t o o n.

P y M O L>c o l o r p i n k,p e p t//b#C h a i n"B"i n o b j e c t"p e p t"

#i s c o l o r e d p i n k.

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 https://www.360docs.net/doc/3211374720.html,/newman/user/S0220commands.html5/6

4/8/2016PyMOL Users Manual

help in the interpretation of error messages.

Calling Python from within PyMOL

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

P y M O L>p r i n t1+2

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

P y M O L>i m p o r t t i m e

P y M O L>n o w=t i m e.t i m e()

P y M O L>p r i n t n o w

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 ?nal line.

P y M O L>f o r a i n r a n g e(1,6):\

P y M O L>b=6-a\

P y M O L>p r i n t a,b

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 ?rst year. We trust you to support the PyMOL project via the "honor" system, so please do your part! See Usage Terms for more information.

Contents Previous Next

https://www.360docs.net/doc/3211374720.html,/newman/user/S0220commands.html6/6