PyMOL Users Manual

4/8/2016PyMOL Users ManualContents Previous NextCommand Syntax and Atom SelectionsSyntaxA 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 EP 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. Asfor zoom, the default selection-expression is all:S Y N T A Xc o l o r c o l o r-n a m ec 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 nE X A M P L E SP 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-expressionsSelection-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 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 inthe PDB, and the identifier gives the name (ca for alpha carbons, cb for beta carbons, etc). A handful of selection-expression s don't require identifiers, but most do. PyMOL uses several logical operators to increase the generality or specificity 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 SelectionsAtom selections can be named for repeated use by using the select command:S Y N T A Xs 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 EP 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 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:E X A M P L E/newman/user/S0220commands.html1/64/8/2016PyMOL Users Manual/newman/user/S0220commands.html2/6P 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 bP 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 EP 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 defined are included in the selection, even if atoms which are loaded subsequently fall within the selection criterion:E X A M P L EP 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 EP 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 SelectorsThe very simplest selection-expression s are single-word selectors. These selectors do not take identifiers; they are complete by themselves.Single Word Selector Short FormSelector Descriptionall *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 representationpresent pr.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:E X A M P L E SP 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 Selectors4/8/2016PyMOL Users Manual/newman/user/S0220commands.html3/6PyMOL 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 inE X A M P L EP y M O L > s e l e c t n t e r m , r e s i 1+2+3or, alternatively, it may take a range given with a dash:E X A M P L EP y M O L > s e l e c t n t e r m , r e s i 1-3However, 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:E X A M P L EP 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 identifiers:MatchingProperty Selector Short Form SelectorIdentifier and Examplesymbole.chemical-symbol-listlist of 1- or 2-letter chemical symbols from the periodic tableP y M O L > s e l e c t p o l a r , s y m b o l o +nname n.atom-name-listlist of up to 4-letter codes for atoms in proteins or nucleic acidsP 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 dresnr.residue-name-listlist of 3-letter codes for amino acidsP 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 nor list of up to 2-letter codes for nucleic acidsP y M O L > s e l e c t b a s e s , r e s n a +gresii.residue-identifier-listlist of up to 4-digit residue numbersP y M O L > s e l e c t m u l t s 10, r e s i 1+10+100+1000residue-identifier-rangeP y M O L > s e l e c t n t e r m , r e s i 1-10alt altalternate-conformation-identifier-list list of single lettersP y M O L > s e l e c t a l t c o n f , a l t a +""chain c.chain-identifier-listlist of single letters or sometimes numbersP y M O L > s e l e c t f i r s t c h , c h a i n asegi s.segment-identifier-listlist of up to 4 letter identifiersP y M O L > s e l e c t l i g a n d , s e g i l i gflag f.flag-numbera single integer from 0 to 31P y M O L > s e l e c t f 1, f l a g 0numeric_type nt.type-number a single integerP y M O L > s e l e c t t y p e 1, n t . 5text_type tt.type-stringa list of up to 4 letter codesP 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 Cid idexternal-index-number a single integerP y M O L > s e l e c t i d n o , i d 23index idx.internal-index-number a single integerP y M O L > s e l e c t i n t i d , i n d e x 11secondary-structure-type4/8/2016PyMOL Users Manual/newman/user/S0220commands.html4/6ss ss list of single lettersP 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 identifiers:NumericSelectorShort FormArgument &Examplebbcomparison-operator b-factor-value a real numberP y M O L > s e l e c t f u z z y , b > 10q qcomparison-operator occupancy-value a real numberP y M O L > s e l e c t l o w c h a r g e s , q <0.50formal_charge fc.comparison-operator formal charge-value an integerP y M O L > s e l e c t d o u b l e s , f c . = -1partial_charge pc.comparison-operator partial charge-value a real numberP y M O L > s e l e c t h i c h a r g e s , p c . > 1Details of the atom and residue name formats can be found in the official guide to PDB file formats,/pdb/docs/format/pdbguide2.2/guide2.2_frame.html.Selection AlgebraSelections 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 s 1 and s 2 stand for selection-expressions such as "chain a" or "hydro."Operator Short formEffectnot s 1! s 1Selects atoms that are not included in s 1P y M O L > s e l e c t s i d e c h a i n s , ! b bs 1 and s 2s 1 & s 2Selects atoms included in both s 1 and s 2P 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 ns 1 or s 2s 1 | s 2Selects atoms included in either s 1 or s 2P 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 ns 1 in s 2s 1 in s 2Selects atoms in s 1 whose identifiersname, resi, resn, chain and segi all match atoms in s 2P 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 ts 1 like s 2s 1 l. s 2Selects atoms in s 1 whose identifiers name and resi match atoms in s 2P 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 ts 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 5s 1 around X s 1 a. X Selects atoms with centers within X Angstroms of the center of any atom in s 1P 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 5s 1 expand Xs 1 e. XExpands s 1 by all atoms within X Angstroms of the center of any atom in s 1P 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 3s 1 within X of s 2 s 1 w. X of s 2Selects atoms in s 1 that are within X Angstroms of the s 2P 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 10byres s 1br. s 1Expands selection to complete residuesP 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 10byobject s 1bo. s 1Expands selection to complete objectsP 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 sneighbor s 1nbr. s 1Selects atoms directly bonded to s 1P 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 10Logical 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 E4/8/2016PyMOL Users ManualP 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 eP 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 first. 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 MacrosMacros make it possible to represent a long atom selection phrase such asP 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 ain 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 aAn 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:/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 rThese 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: /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 eE X A M P L E SP y M O L>z o o m/p e p tP 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/aP y M O L>c o l o r p i n k,/p e p t/l i g/a/10P 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 aIf 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: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 rc h a i n-ide n t if 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 rs 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 ro 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 rE X A M P L E SP y M O L>z o o m10/c bP y M O L>s h o w s p h e r e s,a/10-12/c aP y M O L>s h o w c a r t o o n,l i g/b/6+8/c+oP y M O L>c o l o r p i n k,p e p t/e n z/c/3/nYou can also omit fields between slashes. Omitted fields 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 rc h a i n-ide n t if 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 rE X A M P L E SP 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 eP 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 /newman/user/S0220commands.html5/64/8/2016PyMOL Users Manualhelp in the interpretation of error messages.Calling Python from within PyMOLSingle-line Python statements can be issued directly within PyMOL. For example:P y M O L>p r i n t1+23Full 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 eP 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 w1052982734.94Multi-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.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,b1524334251NOTE: 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/newman/user/S0220commands.html6/6。