Iterate

2013-07-16T19:39:12Z

GeoffreyWoollard:

'''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:
*'''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)
*'''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.
<source lang="python">
# 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
</source>

====Example====
*The following example fills an array, '''stored.names''' with the names of all the residues.
<source lang="python">
# create the global variable between Python and PyMOL
stored.names = []
# get all of the names
iterate (all),stored.names.append(name)
</source>

====Example====
*The following prints the b-factors for all atoms around residue #1.
<source lang="python">
iterate resi 1, print round(b,2)
</source>
====Example - b and resi ====
Just copy and paste this directly into command line
<source lang="python">
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)
</source>

====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.
<source lang="python">
# 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)
</source>

=== PYMOL API ===

<source lang="python">
cmd.iterate(string selection, string expression, int quiet=1, dict space=None)
</source>

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:

<source lang="python">
myspace = {'names': []}
cmd.iterate('(all)', 'names.append(name)', space=myspace)
</source>

User defined functions can also be included in the namespace:

<source lang="python">
def myfunc(resi,resn,name):
print '%s`%s/%s' % (resn ,resi, name)

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

===SEE ALSO===
[[Iterate_State]], [[Alter]], [[Alter_State]], [[Color]], [[Color#Color_by_Spectrum_Example|Coloring with different color sprectrums]].

[[Category:Commands|Iterate]]

PyMOL Wiki - User contributions [en]

Iterate