Queries¶

Combining predicates¶

Selection predicates can be combined with boolean operators. For example , you might want to select all C atoms with crystallographic occupancy higher than 50. These atoms must match the predicate ele=C in addition to the predicate occ>50. In the query language this can be written as:

model.Select('ele=C and occ>50')

Compact forms are available for several selection statements. For example, to select all arginines and aspargines, one could use a statement like:

arg_and_asn = model.Select('rname=ARG or rname=ASN')

However, this is rather cumbersome as it requires the word rname to be typed twice. Since the only difference between the two parts of the selection is the argument that follows the word rname, the statement can also be written in an abbreviated form:

arg_and_asn = model.Select('rname=ARG,ASN')

Another example: to select residues with numbers in the range 130 to 200, one could use the following statement

center = model.Select('rnum>=130 and rnum<=200')

or alternatively use the much nicer syntax:

center = model.Select('rnum=130:200')

This last statement is completely equivalent to the previous one. This syntax can be used when the selection statement requires a range of integer values within a closed interval.

Distance Queries¶

The query

around_center = model.Select('5 <> {0,0,0}')

selects all chains, residues and atoms that lie with 5 Å to the origin of the reference system ({0,0,0}). The <> operator is called the ‘within’ operator. Instead of a point, the within statements can also be used to return a view containing all chains, residues and atoms within a radius of another selection statement applied to the same entity. Square brackets are used to delimit the inner query statement.

around_hem = model.Select('5 <> [rname=HEM]')
model.Select('5 <> [rname=HEM and ele=C] and rname!=HEM')

Bonds and Queries¶

When an EntityView is generated by a selection, it includes by default only bonds for which both connected atoms satisfy the query statement. This can be changed by passing the parameters EXCLUSIVE_BONDS or NO_BONDS when calling the Select method. EXCLUSIVE_BONDS adds bonds to the EntityView when at least one of the two atoms falls within the boundary of the selection. NO_BONDS suppresses the bond inclusion step completely.

Whole Residue Queries¶

If the parameter MATCH_RESIDUES is passed when the Select method is called, the resulting EntityView will include whole residues for which at least one atom satisfies the query. This means that if at least one atom in the residue falls within the boundaries of the selection, all atoms of the residue will be included in the View.

More Query Usage¶

The high level interface for queries are the Select methods of the EntityHandle and EntityView classes. By passing in a query string, a view consisting of a subset of the elements is returned.

Queries also offer a second interface: IsAtomSelected(), IsResidueSelected() and IsChainSelected() take an atom, residue or chain as their argument and return true or false, depending on whether the element fulfills the predicates.

Generic Properties in Queries¶

The query language can also be used for numeric generic properties (i.e. float and int), but the syntax is slightly different. To access any generic properties, it needs to be specified that they are generic and at which level they are defined. Therefore, all generic properties start with a g, followed by an a, r or c for atom, residue or chain level respectively.

# set generic properties for atom, residue, chain
atom_handle.SetFloatProp("testpropatom", 5.2)
resid_handle.SetFloatProp("testpropres", 1.1)
chain_handle.SetIntProp("testpropchain", 10)

# query statements
sel_a = e.Select("gatestpropatom<=10.0")
sel_r = e.Select("grtestpropres=1.0")
sel_c = e.Select("gctestpropchain>5")

Since generic properties do not need to be defined for all parts of an entity (e.g. it could be specified for one single AtomHandle), the query statement will throw an error unless you specify a default value in the query statement which can be done using a ‘:’ character:

# if one or more atoms have no generic properties

sel = e.Select("gatestprop=5")
# this will throw an error

# you can specify a default value:
sel = e.Select("gatestprop:1.0=5")
# this will run through smoothly and use 1.0 as
# the default value for all atoms that do not
# have the generic property 'testprop'

Using this method, you will be warned if a generic property is not set for all atoms, residues or chains unless you specify a default value. So, be careful when you do.

Properties of Chains¶

cname/chain (str) Chain name

Properties of Residues¶

rname (str): Residue name

rnum (int): Residue number. Currently only the numeric part is honored.

rtype (str): Residue type as given by the DSSP code (e.g. “H” for alpha helix, “E” for extended), “helix” for all helix types, “ext” or “strand” for all beta sheets or “coil” for any type of coil (see SecStructure).

rindex (int): Index of residue handle in chain. This index is the same for views and handles.

peptide (bool): Whether the residue is peptide linking.

protein (bool): Whether the residue is considered to be part of a connected protein.

rbfac (float): average B (temperature) factor of residue

ligand (bool) Whether the residue is a ligand.

water (bool) Whether the residue is water.

Properties of Atoms¶

aname (str): Atom name

ele (str): Atom element

occ (float): Atom occupancy

abfac (float): Atom B-factor

x (float): X coordinate of atom.

y (float): Y coordinate of atom.

z (float): Z coordinate of atom.

aindex (int): Atom index

ishetatm (bool): Whether the atom is a heterogenous atom.

acharge (float): Atom charge