Selections

The Selection class (and its subclasses) is used to manage collections of items derived from class Selectable. Molecules, Residues, Atoms, and Bonds are all derived from Selectable. The examples given will use these common Selectables for simplicity, but one should keep in mind that classes such as Model and PseudoBond are also Selectables and can be managed with Selections.

An important thing to understand is that a Selection is not necessarily a fixed set of Selectables. It may encapsulate an algorithm for choosing particular Selectables. For example, a Selection may be used to hold "all bonds/atoms in aromatic rings in all models". This Selection, when its contents are queried, would return differing results as models are opened/closed.

Every Selectable has an associated selection level:

Any Selectable's selection level is returned by its oslLevel() member function.

Selections typically only explicitly hold vertices and edges. Higher-level Selectables' (graphs/subgraphs) membership in a Selection is computed from member vertices/edges. Selection methods that enumerate graphs can do so based on that graph's vertices/edges either being completely or partially present in the selection, as desired. Inclusion of graphs that have no vertex or edge sub-components (such as VRML models) is explicity tracked in a selection.

Since a Selection may encapsulate an algorithm for choosing Selectables, or instead may hold a specific set of Selectables, there is no method in the class Selection for specifying the items held in the Selection. Therefore, Selection is only used as a base class and all actual selections use subclasses. The basic subclasses Chimera defines in chimera.selection are the following:

ItemizedSelection: holds a fixed set of Selectables. However, Selectables will be deleted from the selection when the model(s) containing those Selectables are closed. Therefore, sometimes it is convenient to use an ItemizedSelection to track atoms, etc., just to avoid having to write trigger-handling code yourself.

OrderedSelection: subclass of ItemizedSelection. Used in the infrequent case where the ordering of the Selectables is important (e.g. structure matching). Ordering is only maintained relative to Selectables at the same selection level.

OSLSelection: holds Selectables based on an OSL string. "OSL" stands for Object Selection Language, and a rundown of OSL syntax can be found here. Whenever Selectables are requested from an OSLSelection, the OSL string will be re-evaluated to obtain the matching Selectables. Therefore, if the string contains an attribute test, it may return different Selectables at different times.

CodeSelection: uses a Python code string to determine what is selected. The code is expected to apply functions (provided as local variables) to selected objects.

In addition to these classes, chimera.selection has many functions for manipulating the current selection shown in the Chimera graphics display. help(chimera.selection) in the IDLE shell will display information about them.

The code below demonstrates how to use a selection to hold the atoms/bonds of the protein mainchain, and then highlight them in the main Chimera graphics window.

Example BackboneSel/__init__.py

Import the standard modules used in this example.
import re

Import the Chimera modules used in this example.
import chimera
 from chimera import selection

Define a function that will select protein backbone atoms in the main Chimera graphics window
def selBackbone(op=None):

Define a regular expression for matching the names of protein backbone atoms (we do not include the carbonyl oxygens because they tend to clutter up the graphics display without adding much information).
MAINCHAIN = re.compile("^(N|CA|C)$", re.I)

The list method of chimera.openModels will return a list of currently open models, and takes several optional keyword arguments to restrict this list to models matching certain criteria. When called with no arguments, this method will return a list of all visible models, essentially models that were created by the user. Internally managed (hidden) models, such as the distance monitor pseudobondgroup, do not show up in this list. A list of hidden models can be obtained by setting the optional keyword argument hidden to True. The all argument (True/False) can be used to return a list of all open models (including both hidden and visible). Other optional arguments include:

id and subid, which restrict the returned list to models with the given id and subid, respectively, while modelTypes (a list of model types, i.e. [chimera.Molecule]) will restrict the returned list to models of a particular type.
bbAtoms = []
 for m in chimera.openModels.list(modelTypes=[chimera.Molecule]):

for a in m.atoms:
if MAINCHAIN.match(a.name):
bbAtoms.append(a)

Create a selection instance that we can use to hold the protein backbone atoms. We could have added the atoms one by one to the selection while we were in the above loop, but it is more efficient to add items in bulk to selections if possible.
backboneSel = selection.ItemizedSelection()
 backboneSel.add(bbAtoms)

Add the connecting bonds to the selection. The addImplied method of Selection adds bonds if both bond endpoint atoms are in the selection, and adds atoms if any of the atom's bonds are in the selection. We use that method here to add the connecting bonds.
backboneSel.addImplied()

Change the selection in the main Chimera window in the manner indicated by this function's op keyword argument. If op is None, then use whatever method is indicated by the Selection Mode item in Chimera's Select menu. Otherwise, op should be one of: selection.REPLACE, selection.INTERSECT, selection.EXTEND or selection.REMOVE.

-
REPLACE causes the Chimera selection to be replaced with backboneSel.
-
INTERSECT causes the Chimera selecion to be intersected with backboneSel.
-
EXTEND causes backboneSel to be appended to the Chimera selection.
-
REMOVE causes backboneSel to be unselected in the Chimera window.

if op is None:
chimera.tkgui.selectionOperation(backboneSel)
else:
selection.mergeCurrent(op, backboneSel)

Code Notes

See the Registering Selectors example for how to make the "selBackbone" function available from the Chimera Select menu.

Running the Example

The example code files must be saved in a directory named BackboneSel. To run the example, start chimera, bring up the Tools preference category (via the Preferences entry in the Favorites menu; then choosing the "Tools" preference category) and use the Add button to add the directory above the BackboneSel directory. Then type the following command into the IDLE command line:

import BackboneSel

BackboneSel.selBackbone()

This will cause the selection state of all protein backbone atoms to change, depending on the Selection Mode chosen in the Chimera Select menu. If the mode is the default ("replace"), then the protein backbone will become selected and all other atoms/bonds will become deselected.