One of the more powerful features of PyMOL is that it supports Python scripting. This gives you the power to use most of the Python libraries to write programs and then send the results back into PyMOL. Some useful extensions to PyMOL can be found in our Script Library.
General PyMOL scripting is done in Python. It's really quite simple, just write your function (following a couple simple rules) and then let PyMOL know about it by using the cmd.extend command. Here's the simple recipe for writing your own simple scripts for PyMOL:
To write them:
- Write the function, let's call it doSimpleThing, in a Python file, let's call the file pyProgram.py.
- Add the following command to the end of the pyProgram.py file
To use them:
- simply import the script into PyMOL:
- Then, just type the name of the command: doSimpleThing and pass any needed arguments.
That's it. Your script can, through Python, import any modules you need and also edit modify objects in PyMOL.
Getting PyMOL Data into your Script
To get PyMOL data into your script you will need to somehow get access to the PyMOL objects and pull out the data. For example, if you want the atomic coordinates of a selection of alpha carbon atoms your Python function may do something like this (see also iterate_state):
# Import PyMOL's stored module. This will allow us with a # way to pull out the PyMOL data and modify it in our script. # See below. from pymol import stored def functionName( userSelection ): # this array will be used to hold the coordinates. It # has access to PyMOL objects and, we have access to it. stored.alphaCarbons =  # let's just get the alpha carbons, so make the # selection just for them userSelection = userSelection + " and n. CA" # iterate over state 1, or the userSelection -- this just means # for each item in the selection do what the next parameter says. # And, that is to append the (x,y,z) coordinates to the stored.alphaCarbon # array. cmd.iterate_state(1, selector.process(userSelection), "stored.alphaCarbons.append([x,y,z])") # stored.alphaCarbons now has the data you want. ... do something to your coordinates ...
Getting Data From your Script into PyMOL
Usually this step is easier. To get your data into PyMOL, it's usually through modifying some object, rotating a molecule, for example. To do that, you can use the alter or alter_state commands. Let's say for example, that we have translated the molecular coordinates from the last example by some vector (we moved the alpha carbons). Now, we want to make the change and see it in PyMOL. To write the coordinates back we do:
# we need to know which PyMOL object to modify. There could be many molecules and objects # in the session, and we don't want to ruin them. The following line, gets the object # name from PyMOL objName = cmd.identify(sel2,1) # Now, we alter each (x,y,z) array for the object, by popping out the values # in stored.alphaCarbons. PyMOL should now reflect the changed coordinates. cmd.alter_state(1,objName,"(x,y,z)=stored.alphaCarbons.pop(0)")
Here's a script I wrote for cealign. It takes two selections of equal length and computes the optimal overlap, and aligns them. See Kabsch for the original code. Because this tutorial is for scripting and not optimal superposition, the original comments have been removed.
def optAlign( sel1, sel2 ): """ @param sel1: First PyMol selection with N-atoms @param sel2: Second PyMol selection with N-atoms """ # make the lists for holding coordinates # partial lists stored.sel1 =  stored.sel2 =  # full lists stored.mol1 =  stored.mol2 =  # -- CUT HERE sel1 = sel1 + " and N. CA" sel2 = sel2 + " and N. CA" # -- CUT HERE # This gets the coordinates from the PyMOL objects cmd.iterate_state(1, selector.process(sel1), "stored.sel1.append([x,y,z])") cmd.iterate_state(1, selector.process(sel2), "stored.sel2.append([x,y,z])") # ...begin math that does stuff to the coordinates... mol1 = cmd.identify(sel1,1) mol2 = cmd.identify(sel2,1) cmd.iterate_state(1, mol1, "stored.mol1.append([x,y,z])") cmd.iterate_state(1, mol2, "stored.mol2.append([x,y,z])") assert( len(stored.sel1) == len(stored.sel2)) L = len(stored.sel1) assert( L > 0 ) COM1 = numpy.sum(stored.sel1,axis=0) / float(L) COM2 = numpy.sum(stored.sel2,axis=0) / float(L) stored.sel1 = stored.sel1 - COM1 stored.sel2 = stored.sel2 - COM2 E0 = numpy.sum( numpy.sum(stored.sel1 * stored.sel1,axis=0),axis=0) + numpy.sum( numpy.sum(stored.sel2 * stored.sel2,axis=0) ,axis=0) reflect = float(str(float(numpy.linalg.det(V) * numpy.linalg.det(Wt)))) if reflect == -1.0: S[-1] = -S[-1] V[:,-1] = -V[:,-1] RMSD = E0 - (2.0 * sum(S)) RMSD = numpy.sqrt(abs(RMSD / L)) U = numpy.dot(V, Wt) # ...end math that does stuff to the coordinates... # update the _array_ of coordinates; not PyMOL the coords in the PyMOL object stored.sel2 = numpy.dot((stored.mol2 - COM2), U) + COM1 stored.sel2 = stored.sel2.tolist() # This updates PyMOL. It is removing the elements in # stored.sel2 and putting them into the (x,y,z) coordinates # of mol2. cmd.alter_state(1,mol2,"(x,y,z)=stored.sel2.pop(0)") print "RMSD=%f" % RMSD cmd.orient(sel1 + " and " + sel2) # The extend command makes this runnable as a command, from PyMOL. cmd.extend("optAlign", optAlign)
Basic Script Body
Want an easy block of working code to start your function from? Just copy/paste the following into your Python editor and get going!
# # -- basicCodeBlock.py # from pymol import cmd, stored def yourFunction( arg1, arg2 ): ''' DESCRIPTION Brief description what this function does goes here ''' # # Your code goes here # print "Hello, PyMOLers" print "You passed in %s and %s" % (arg1, arg2) print "I will return them to you in a list. Here you go." return (arg1, arg2) cmd.extend( "yourFunction", yourFunction );
Python Version Supported by PyMOL
Scripts used within PyMOL can only be written using the current version of Python that is supported by your version of PyMOL. To determine which version of Python you can use, type the following command into PyMOL:
Note that this version of Python is not necessarily related to the version that you may have installed on your system.
This command can also be used to ensure that code you are distributing can be supported by the user's system.