Iterate

iterate iterates over an expression with a separate name space for each atom. However, unlike the "alter" command, atomic properties can not be altered. Thus, iterate is more efficient than alter.

Details

Iterate is a powerful tool that can be used to perform operations and aggregations using atomic selections, and store the results in any global object, such as the predefined stored object (see #PYMOL API below for usage of local objects). For example, one could iterate over all of the alpha carbons and record their B Factors, or print out all of the secondary structure classifications of all the residues.

The iterate command only has access to certain properties. Those properties are:

• name: the atom name
• resn: the residue name
• resi: the residue identifier (residue number)
• chain: the chain name
• alt
• elem: the chemical element
• q
• b: the B Factor
• segi
• type (ATOM,HETATM): the atom type
• formal_charge: the formal charge of the atom
• partial_charge: the partial charge of the atom
• numeric_type
• text_type
• ID
• vdw

All strings in the expression must be explicitly quoted. This operation typically takes a second per thousand atoms.

Note about Atom Coordinates

The coordinates of the atom are not accessible via iterate. To inspect the coordinates of the atoms, see Iterate_State.

USAGE

iterate (selection),expression

EXAMPLES

Example

• The following example calculates the net charge on an object.

# create the global variable between Python and PyMOL
stored.net_charge = 0
# sum up the stored charges of all the atoms
iterate (all),stored.net_charge = stored.net_charge + partial_charge

Example

• The following example fills an array, stored.names with the names of all the residues.

# create the global variable between Python and PyMOL
stored.names = []
# get all of the names
iterate (all),stored.names.append(name)

Example

• The following prints the b-factors for all atoms around residue #1.

iterate resi 1, print round(b,2)

Example

• The following example shows a common task in PyMOL, changing the B-factor column to display some other property. Let's assume you have a file with a list of numbers, one per line, for each alpha carbon in the protein. Furthermore, assume you want to map these values to the alpha carbons in the protein.

# set ALL b-factors to 0.
alter protName, b=0

# read the new bfactors from disk
f = open('fileName','r').readlines()

# set the alpha carbon bfactors.
alter protName and n. CA, b=f.pop(0)

# Spectrum color bfactors by alpha carbons.
spectrum b, selection=(protName and n. CA)

PYMOL API

cmd.iterate(string selection, string expression, int quiet=1, dict space=None)

When calling iterate, iterate_state, alter or alter_state from a python script, you can use the 'space' argument to pass local objects into the expression namespace.

The second example from above but without the global pymol.stored variable:

myspace = {'names': []}
cmd.iterate('(all)', 'names.append(name)', space=myspace)

User defined functions can also be included in the namespace:

def myfunc(resi,resn,name):
    print '%s`%s/%s' % (resn ,resi, name)

myspace = {'myfunc': myfunc}
cmd.iterate('(all)', 'myfunc(resi,resn,name)', space=myspace)

SEE ALSO

Iterate_State, Alter, Alter_State, Color, Coloring with different color sprectrums.