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. Iterates typically takes a second per thousand atoms.

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

• model: the pymol object label (appearing in the selection panel on the right)
• name: the atom name
• resn: the residue name
• resi: the residue identifier (residue number) as a string, including optional insertion code
• resv: the residue identifier (residue number) as an integer, excluding insertion code
• chain: the chain name
• alt: alternate Locations
• elem: the chemical element
• q:occupancy
• b: the B Factor
• segi: segment identifier (columns 73-76 in PDB file)
• 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: automatic mol2 atom typing (Incentive PyMOL 1.4+)
• stereo: automatic stereochemical R/S label (Incentive PyMOL 1.4+)
• ID: PDB atom id (not guaranteed to be unique!)
• vdw: Van der Waals radius
• ss: secondary structure
• color: color index
• p: property object to access user-defined properties like p.abc (Incentive PyMOL 1.7+)

Important: All strings in the expression must be explicitly quoted.

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 atoms.

# 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 - b and resi

Just copy and paste this directly into command line

show_as cartoon ;
cmd.spectrum("b", "blue_white_red", "n. CA") ;
m1 = [] ;
iterate (all and n. CA),m1.append((b,resi,chain)) ;
zero = [] ;
[zero.append(i) for i,val in enumerate(m1) if val[0]==0] ;
m2 = [i for j,i in enumerate(m1) if j not in zero] ;
for j,i,k in m2: print j,i,k
bmax,resimax,chainmax =  max(m2, key=lambda p: p[0]) ;
bmin,resimin,chainmin =  min(m2, key=lambda p: p[0]) ;
cmd.ramp_new("R2", "* n. CA", range=[0, bmin, bmax], color="[blue, white, red ]") ;
for b,resi,chain in m2: cmd.label("chain %s and resi %s and n. CA"%(chain,resi), "b=%3.2f"%b)

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.