This is a read-only mirror of pymolwiki.org

Difference between revisions of "Selection Algebra"

From PyMOL Wiki
Jump to navigation Jump to search
m (fix syntax 1/2)
m (4 revisions)
 
(27 intermediate revisions by 6 users not shown)
Line 1: Line 1:
__FORCETOC__
+
[[Image:solvent-and-chain-A.png|thumb|240px|show spheres, solvent and chain A]]
 +
[[Image:solvent-or-chain-A.png|thumb|240px|show spheres, solvent or 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. Venn diagrams show that '''and ''' selects the areas of overlap, while '''or''' selects both areas.  
+
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:
  
See [http://pymol.sourceforge.net/newman/user/S0220venn.jpg simple logic Venn diagram].
+
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 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."
 
Selection operators and modifiers are listed below. The dummy variables ''s1'' and ''s2'' stand for selection-expressions such as "chain a" or "hydro."
  
<TABLE BORDER="1">
+
{| class="wikitable"
<TR><TH ALIGN="CENTER" WIDTH="100">Operator</TH><TH>Short form</TH>
+
|-
<TH>Effect</TH>
+
! Operator
</TR>
+
! Aliases
<TR><TD ALIGN="CENTER">not <I>s</I>1</TD>
+
! Description
<TD ALIGN="CENTER">!<I>s</I>1</TD>
+
|-
<TD>Selects atoms that are not included in <I>s</I>1
+
!colspan="3" style="text-align:left"| Generic
<pre>PyMOL> select sidechains, ! bb</pre>
+
|-
</TD></TR>
+
| all || *
<TR><TD ALIGN="CENTER"><I> s</I>1 and<I> s</I>2</TD>
+
| All atoms currently loaded into PyMOL
<TD ALIGN="CENTER"><I> s</I>1 &amp;<I> s</I>2</TD>
+
|-
<TD>Selects atoms included in both<I> s</I>1 and<I> s</I>2
+
| none ||
<pre>PyMOL> select far_bb, bb &amp;farfrm_ten</pre>
+
| Empty selection
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER"><I> s</I>1 or<I> s</I>2</TD>
+
| enabled ||
<TD ALIGN="CENTER"><I> s</I>1 |<I> s</I>2</TD><TD>Selects atoms included in either<I> s</I>1 or<I> s</I>2
+
| Atoms from enabled objects
<pre>PyMOL> select all_prot, bb | sidechain</pre>
+
|-
</TD></TR>
+
!colspan="3" style="text-align:left"| Named selections
<TR><TD ALIGN="CENTER"><I> s</I>1 in<I> s</I>2</TD>
+
|-
<TD ALIGN="CENTER"><I> s</I>1 in<I> s</I>2</TD><TD>Selects atoms in<I> s</I>1 whose identifiers name, resi, resn, chain and segi <strong><u>all</u></strong> match atoms in<I> s</I>2
+
| <span style="color: #999">sele</span> ||
<pre>PyMOL> select same_atms, pept in prot</pre>
+
| Named selection or object "sele", but only if it doesn't conflict with the name of another operator
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER"><I> s</I>1 like<I> s</I>2</TD><TD ALIGN="CENTER"><I> s</I>1 l.<I> s</I>2</TD><TD>Selects atoms in<I> s</I>1 whose identifiers name and resi match atoms in<I> s</I>2
+
| %<span style="color: #999">sele</span> ||
<pre>PyMOL> select similar_atms, pept like prot</pre>
+
| Named selection or object "sele" &nbsp; &nbsp; &nbsp; <span style="padding: 1px 4px; background-color: #fc3; border: 1px solid #ccc">Recommended, avoids ambiguity</span>
 
+
|-
</TD></TR>
+
| ?<span style="color: #999">sele</span> ||
<TR><TD ALIGN="CENTER"><I> s</I>1 gap<I> X</I></TD>
+
| Named selection or object "sele", or empty selection if "sele" doesn't exist
<TD ALIGN="CENTER"></TD><TD>Selects all atoms whose van der Waals radii are separated from the van der Waals radii of<I> s</I>1 by a minimum of<I> X</I> Angstroms.
+
|-
<pre>PyMOL> select farfrm_ten, resi 10 gap 5</pre>
+
!colspan="3" style="text-align:left"| Logical
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER"><I> s</I>1 around<I> X</I></TD>
+
| not <span style="color: #999">S1</span> || !
<TD ALIGN="CENTER"><I> s</I>1 a.<I> X</I></TD><TD>Selects atoms with centers within<I> X</I> Angstroms of the center of any atom in<I> s</I>1
+
| Inverts selection
<pre>PyMOL> select near_ten, resi 10 around 5</pre>
+
|-
</TD></TR>
+
| <span style="color: #999">S1</span> and <span style="color: #999">S2</span> || &
<TR><TD ALIGN="CENTER"><I> s</I>1 expand<I> X</I>
+
| Atoms included in both S1 and S2
</TD><TD ALIGN="CENTER"><I> s</I>1 x.<I> X</I></TD><TD>Expands<I> s</I>1 by all atoms within<I> X</I> Angstroms of the center of any atom in<I> s</I>1
+
|-
<pre>PyMOL> select near_ten_x, near10 expand 3</pre>
+
| <span style="color: #999">S1</span> or <span style="color: #999">S2</span> || <nowiki>|</nowiki>
</TD></TR>
+
| Atoms included in either S1 or S2
<TR><TD ALIGN="CENTER">&nbsp;<I> s</I>1 within X of<I> s</I>2&nbsp;</TD>
+
|-
<TD ALIGN="CENTER"><I> s</I>1 w. X of<I> s</I>2&nbsp;</TD><TD>Selects atoms in<I> s</I>1 that are within X Angstroms of the<I> s</I>2
+
| <span style="color: #999">S1 S2</span> ||
<pre>PyMOL> select bbnearten, bb w. 4 of resi 10</pre>
+
| implicit '''or'''
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER">&nbsp;<I> s</I>1 near_to X of<I> s</I>2&nbsp;</TD>
+
| <span style="color: #999">S1</span> and (<span style="color: #999">S2</span> or <span style="color: #999">S3</span>) ||
<TD ALIGN="CENTER"><I> s</I>1 nto. X of<I> s</I>2&nbsp;</TD><TD>Same as <i>within</i>, but excludes <i>s2</i> from the selection (and thus is identical to <code>s1 and <i>s2</i> around X</code>)
+
| Parentheses for evaluation order control
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER">&nbsp;<I> s</I>1 beyond X of<I> s</I>2&nbsp;</TD>
+
| first <span style="color: #999">S1</span> ||
<TD ALIGN="CENTER"><I> s</I>1 be. X of<I> s</I>2&nbsp;</TD><TD>Selects atoms in <i>s1</i> that are at least X Anstroms away from <i>s2</i>
+
| First atom in S1 (single atom selection)
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER">byres<I> s</I>1</TD>
+
| last <span style="color: #999">S1</span> ||
<TD ALIGN="CENTER">br.<I> s</I>1</TD><TD>Expands selection to complete residues
+
| Last atom in S1 (single atom selection)
<pre>PyMOL> select complete_res, br. bbnear10</pre>
+
|-
</TD></TR>
+
!colspan="3" style="text-align:left"| Identifiers &nbsp; <small style="font-weight: normal">(see also [[Selection Macros]])</small>
<TR><TD ALIGN="CENTER">bymolecule<I> s</I>1</TD>
+
|-
<TD ALIGN="CENTER">bm.<I> s</I>1</TD><TD>Expands selection to complete molecules
+
| model <span style="color: #999">1ubq</span> || m.
<pre>PyMOL> select complete_res, bm. bbnear10</pre>
+
| Atoms from object "1ubq"
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER">byfragment<I> s</I>1</TD>
+
| chain <span style="color: #999">C</span> || c.
<TD ALIGN="CENTER">bf.<I> s</I>1</TD><TD>Expands selection to complete fragments
+
| Chain identifier "C"
<pre>PyMOL> select complete_res, bf. bbnear10</pre>
+
|-
</TD></TR>
+
| segi <span style="color: #999">S</span> || s.
<TR><TD ALIGN="CENTER">bysegment<I> s</I>1</TD>
+
| Segment identifier "S" ('''label_asym_id''' from mmCIF)
<TD ALIGN="CENTER">bs.<I> s</I>1</TD><TD>Expands selection to complete segments
+
|-
<pre>PyMOL> select complete_res, bs. bbnear10</pre>
+
| resn <span style="color: #999">ALA</span> || r.
</TD></TR>
+
| Residue name "ALA"
<TR><TD ALIGN="CENTER">byobject<I> s</I>1</TD>
+
|-
<TD ALIGN="CENTER">bo.<I> s</I>1</TD><TD>Expands selection to complete objects>
+
| resi <span style="color: #999">100-200</span> || i.
<pre>PyMOL> select near_obj, bo. near_res</pre>
+
| Residue identifier between 100 and 200
</TD></TR>
+
|-
<TR><TD ALIGN="CENTER">bycell<I> s</I>1</TD>
+
| name <span style="color: #999">CA</span> || n.
<TD ALIGN="CENTER"></TD><TD>Expands selection to unit cell>
+
| Atom name "CA"
<pre>PyMOL> select complete_cell, bycell orig_res</pre>
+
|-
</TD></TR>
+
| alt <span style="color: #999">A</span> ||
<TR><TD ALIGN="CENTER">neighbor<I> s</I>1</TD>
+
| Alternate location "A"
<TD ALIGN="CENTER">nbr.<I> s</I>1</TD><TD>Selects atoms directly bonded to<I> s</I>1
+
|-
<pre>PyMOL> select vicinos, neighbor resi 10</pre>
+
| index <span style="color: #999">123</span> || idx.
</TD></TR>
+
| Internal per-object atom index (changes with [[sort|sorting]])
<TR><TD ALIGN="CENTER"><I> s</I>1 extend<I> X</I>
+
|-
</TD><TD ALIGN="CENTER"><I> s</I>1 xt.<I> X</I></TD><TD>Extends<I> s</I>1 by<I> X</I> bonds connected to atom in<I> s</I>1
+
| id <span style="color: #999">123</span> ||
<pre>PyMOL> select connect_x, near10 extend 3</pre>
+
| ID column from PDB file
</TD></TR>
+
|-
<tr><td align=center>pepseq <i>SEQ</i></td>
+
| rank <span style="color: #999">123</span> ||
    <td align=center>ps. <i>SEQ</i></td>
+
| Per-object atom index at load time (see also [[retain_order]])
    <td>Selects peptide sequence matching upper-case one-letter sequence <i>SEQ</i> (see also [[FindSeq]])
+
|-
<pre>PyMOL> select 1tvn and ps. FATEW</pre></td></tr>
+
| pepseq <span style="color: #999">ACDEF</span> || ps.
</TABLE>
+
| Protein residue sequence with one-letter code "ACDEF" (see also [[FindSeq]])
 +
|-
 +
| label <span style="color: #999">"Hello World"</span> ||
 +
| Atoms with label "Hello World" ''(new in PyMOL 1.9)''
 +
|-
 +
!colspan="3" style="text-align:left"| Identifier matching
 +
|-
 +
| <span style="color: #999">S1</span> in <span style="color: #999">S2</span> ||
 +
| Atoms in S1 whose identifiers ''name, resi, resn, chain'' and ''segi'' '''all''' match atoms in S2
 +
|-
 +
| <span style="color: #999">S1</span> like <span style="color: #999">S2</span> ||
 +
| Atoms in S1 whose identifiers ''name'' and ''resi'' match atoms in S2
 +
|-
 +
!colspan="3" style="text-align:left"| Entity expansion
 +
|-
 +
|colspan="3" style="background-color: #fc3"| <span id="weak-by">Important:</span> 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 <span style="color: #999">S1</span> ||
 +
| Expands S1 to complete objects
 +
|-
 +
| bysegi <span style="color: #999">S1</span> || bs.
 +
| Expands S1 to complete segments
 +
|-
 +
| bychain <span style="color: #999">S1</span> || bc.
 +
| Expands S1 to complete chains
 +
|-
 +
| byres <span style="color: #999">S1</span> || br.
 +
| Expands S1 to complete residues
 +
|-
 +
| bycalpha <span style="color: #999">S1</span> || bca.
 +
| CA atoms of residues with at least one atom in S1
 +
|-
 +
| bymolecule <span style="color: #999">S1</span> || bm.
 +
| Expands S1 to complete molecules (connected with bonds)
 +
|-
 +
| byfragment <span style="color: #999">S1</span> || bf.
 +
|
 +
|-
 +
| byring <span style="color: #999">S1</span> ||
 +
| All rings of size ≤ 7 which have at least one atom in S1 ''(new in PyMOL 1.8.2)''
 +
|-
 +
| bycell <span style="color: #999">S1</span> ||
 +
| Expands selection to unit cell
 +
|-
 +
!colspan="3" style="text-align:left"| Bond expansion
 +
|-
 +
| bound_to <span style="color: #999">S1</span> || bto.
 +
| Atoms directly bonded to S1, may include S1
 +
|-
 +
| neighbor <span style="color: #999">S1</span> || nbr.
 +
| Atoms directly bonded to S1, excludes S1
 +
|-
 +
| <span style="color: #999">S1</span> extend <span style="color: #999">3</span> || xt.
 +
| Expands S1 by 3 bonds connected to atoms in S1
 +
|-
 +
!colspan="3" style="text-align:left"| Proximity &nbsp; <small style="font-weight: normal">(see also [[#Comparison of distance operators|comparison of distance operators]])</small>
 +
|-
 +
| <span style="color: #999">S1</span> within <span style="color: #999">12.3</span> of <span style="color: #999">S2</span> || w.
 +
| Atoms in S1 that are within 12.3 Angstroms of any atom in S2
 +
|-
 +
| <span style="color: #999">S1</span> around <span style="color: #999">12.3</span> || a.
 +
| Atoms with centers within 12.3 Angstroms of the center of any atom in S1
 +
|-
 +
| <span style="color: #999">S1</span> expand <span style="color: #999">12.3</span> || x.
 +
| Expands S1 by atoms within 12.3 Angstroms of the center of any atom in S1
 +
|-
 +
| <span style="color: #999">S1</span> gap <span style="color: #999">1.2</span> ||
 +
| Atoms whose VDW radii are separated from the VDW radii of S1 by a minimum of 1.2 Angstroms.
 +
|-
 +
| <span style="color: #999">S1</span> near_to <span style="color: #999">12.3</span> of <span style="color: #999">S2</span> || nto.
 +
| Same as ''within'', but excludes S2 from the selection (and thus is identical to <code>S1 and S2 around 12.3</code>)
 +
|-
 +
| <span style="color: #999">S1</span> beyond <span style="color: #999">12.3</span> of <span style="color: #999">S2</span> || be.
 +
| Atoms in S1 that are at least 12.3 Anstroms away from S2
 +
|-
 +
!colspan="3" style="text-align:left"| Properties
 +
|-
 +
| partial_charge <span style="color: #999">< 1.2</span> || pc.
 +
|
 +
|-
 +
| formal_charge <span style="color: #999">= 1</span> || fc.
 +
|
 +
|-
 +
| b <span style="color: #999">< 100.0</span> ||
 +
| B-factor less than 100.0
 +
|-
 +
| q <span style="color: #999">< 1.0</span> ||
 +
| Occupancy less than 1.0
 +
|-
 +
| ss <span style="color: #999">H+S</span> ||
 +
| Atoms with secondary structure H (helix) or S (sheet)
 +
|-
 +
| elem <span style="color: #999">C</span> || e.
 +
| Atoms of element C (carbon)
 +
|-
 +
| p<span style="color: #999">.foo</span> = <span style="color: #999">12</span> ||
 +
|
 +
|-
 +
| p<span style="color: #999">.foo</span> < <span style="color: #999">12.3</span> ||
 +
|
 +
|-
 +
| p<span style="color: #999">.foo</span> in <span style="color: #999">12+34</span> ||
 +
|
 +
|-
 +
| stereo <span style="color: #999">R</span> ||
 +
| Chiral R/S stereo center with label R ''(only [https://pymol.org/d/media:stereochemistry Incentive PyMOL 1.4-1.8])''
 +
|-
 +
!colspan="3" style="text-align:left"| Flags
 +
|-
 +
| bonded ||
 +
| Atoms which have at least one bond
 +
|-
 +
| protected ||
 +
| see [[protect]]
 +
|-
 +
| fixed || fxd.
 +
| see [[flag]]
 +
|-
 +
| restrained || rst.
 +
| see [[flag]]
 +
|-
 +
| masked || msk.
 +
| see [[mask]]
 +
|-
 +
| flag <span style="color: #999">25</span> || f.
 +
| Atoms with flag 25, see [[flag]]
 +
|-
 +
!colspan="3" style="text-align:left"| 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
 +
|-
 +
!colspan="3" style="text-align:left"| Style
 +
|-
 +
| visible || v.
 +
| Atoms in enabled objects with at least one visible representation
 +
|-
 +
| rep <span style="color: #999">cartoon</span> ||
 +
| Atoms with cartoon representation
 +
|-
 +
| color <span style="color: #999">blue</span> ||
 +
| Atoms with atom-color blue (by color index)
 +
|-
 +
| cartoon_color <span style="color: #999">blue</span> ||
 +
| Atoms with atom-level cartoon_color setting (by color index)
 +
|-
 +
| ribbon_color <span style="color: #999">blue</span> ||
 +
| Atoms with atom-level ribbon_color setting (by color index)
 +
|-
 +
!colspan="3" style="text-align:left"| Non molecular
 +
|-
 +
| center ||
 +
| Pseudo-atom at the center of the scene
 +
|-
 +
| origin ||
 +
| Pseudo-atom at the origin of rotation
 +
|-
 +
!colspan="3" style="text-align:left"| Coordinates
 +
|-
 +
| state <span style="color: #999">123</span> ||
 +
| Atoms with coordinates in state 123
 +
|-
 +
| present || pr.
 +
| Atoms with coordinates in the current state
 +
|-
 +
| x <span style="color: #999">< 12.3</span> ||
 +
| Atoms with model-space x coordinate less than 12.3
 +
|-
 +
| y <span style="color: #999">< 12.3</span> ||
 +
| Atoms with model-space y coordinate less than 12.3
 +
|-
 +
| z <span style="color: #999">> 12.3</span> ||
 +
| Atoms with model-space z coordinate greater than 12.3
 +
|-
 +
!colspan="3" style="text-align:left"| Atom typing
 +
|-
 +
| text_type <span style="color: #999">TT</span> || tt.
 +
| ''Auto-assigned in [https://pymol.org/d/media:atomtyping Incentive PyMOL 1.4-1.8])''
 +
|-
 +
| numeric_type <span style="color: #999">123</span> || nt.
 +
|
 +
|}
  
 
== Comparison of distance operators ==
 
== Comparison of distance operators ==
Line 101: Line 326:
 
'''Syntax 2''': ''s1'' and (''s2'' operator X)
 
'''Syntax 2''': ''s1'' and (''s2'' operator X)
  
{| border=1 cellspacing=0 cellpadding=4 style="text-align:center"
+
{| border=1 cellspacing=0 cellpadding=4 style="text-align:center" class=wikitable
 
! operator !! distance is ... !! measured from !! includes s2 !! syntax !! notes
 
! operator !! distance is ... !! measured from !! includes s2 !! syntax !! notes
 
|-
 
|-
Line 116: Line 341:
 
|  expand ||  ≤ X            ||    center    ||  always    ||  2    ||
 
|  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).
  
 
== Examples ==
 
== Examples ==
 
Logical selections can be combined. For example, you might select atoms that are part of chain a, but not residue number 125:
 
Logical selections can be combined. For example, you might select atoms that are part of chain a, but not residue number 125:
 
<source lang="python">
 
<source lang="python">
# selects 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)
+
select chain A and (not resi 125)
  
 
# The following two selections are equivalent,  
 
# The following two selections are equivalent,  
select (name cb or name cg1 or name cg2) and chain A
+
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  
 
# select c-beta's, c-gamma-1's and c-gamma-2's  
 
# that are in chain A.
 
# that are in chain A.
select name cb+cg1+cg2 and chain A
+
select name CB+CG1+CG2 and chain A
  
 
# select all residues within 5 Ang. or any organic small molecules
 
# select all residues within 5 Ang. or any organic small molecules
Line 134: Line 366:
  
 
# select helices
 
# select helices
select ss 'h'
+
select ss 'H'
  
 
# select anything shown as a line
 
# select anything shown as a line
Line 146: Line 378:
  
 
# select the 1st arginine
 
# select the 1st arginine
select first resn arg
+
select first resn ARG
  
 
# select 1foo's segment G's chain X's residue 444's alpha carbon
 
# select 1foo's segment G's chain X's residue 444's alpha carbon
Line 162: Line 394:
 
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:
 
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:
  
<source lang="python">byres ((chain a or (chain b and (not resi 125))) around 5)</source>
+
<source lang="python">byres ((chain A or (chain B and (not resi 125))) around 5)</source>
  
 
PyMOL will expand its logical selection out from the innermost parentheses.
 
PyMOL will expand its logical selection out from the innermost parentheses.
  
 +
== See Also ==
 +
 +
* [[select]]
 +
* [[Selection Macros]]
 +
* [[Property_Selectors]]
 +
* [[Selection Language Comparison]] with other modelling applications
 +
* [[Identify]]
  
 
[[Category:Selector Quick Reference]]
 
[[Category:Selector Quick Reference]]
 
[[Category:Selecting|Selection Algebra]]
 
[[Category:Selecting|Selection Algebra]]

Latest revision as of 03:15, 5 March 2018

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
Generic
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
Logical
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
Properties
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)
p.foo = 12
p.foo < 12.3
p.foo in 12+34
stereo R Chiral R/S stereo center with label R (only Incentive PyMOL 1.4-1.8)
Flags
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
Style
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
Coordinates
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).

Examples

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