Introduction to Using PyMOL 


Audience for this tutorial:
This tutorial assumes that you are using a windows OS (although most of the information would be applicable for other operating systems) and that you have no problems installing the software required. The tutorial becomes more advanced so you can skim over what is easily understood (though there may be some good points raised) until you find what is interesting.

What is PyMOL and where to find it:
 PyMOL is a free, open-source tool to visualize molecules and the homepage is located at PyMOL Sourceforge homepage. For the Windows system, the first part to install is the Python program which is necessary to run PyMOL and then to install PyMOL. These programs are found on the PyMOL project file list page. Download the required programs and install them (I won't get into which versions). Assuming these first steps are done correctly, PyMOL should be ready to use.

Data files and script files:
PyMOL reads in molecular coordinates from a .pdb file and these files can be found at sites such as the Protein Data Bank. After loading in a pdb file, it can be manipulated in PyMOL from either the menu's or from the command line. For creating images it is best to work using the command line so that your image can be reproduced exactly each time and to store the commands in a script file. In this manner, you can alter the script, reload your image and avoid having to type in all the commands over and over again or remember what menu options you used. Script files are very easy to use and are simple text files and can be created and edited using a program such as notepad.

Example molecule and script file:
To see this example, download the pdb file 1KMY.pdb and the associated script file 1KMYsetup.pml and place them directly on c: (if you want to change this, it can easily be done but for this example to work without editing they must both be on c:). The pdb file describe the crystal structure of a two-domain metalloenzyme that contains non-heme ferrous iron. This enzyme is involved in the degradation of PCB metabolites. This specific file is the crystal structure of an enzyme-substrate complex. The substrate is dihydroxybiphenyl and it is directly ligated to the iron atom via it's two hydroxyl oxygen atoms.

Open up PyMOL and in the PyMOL viewer window (the black window with the prompt PyMOL> as seen below) type "load c:\1KMY.pdb" (no quotes) and hit return. This will load the molecule directly and it can be manipulated from either the command line or using any of the menus. While this is a good way to play with the molecule, this tutorial will be focused on using the scripts so to do this first the image must be cleared. Enter the command "delete all" to remove everything. To load the script, type "@c:\1KMYsetup.pml" (the @ symbol specifies a script). The script loads the molecule and performs all the operations specified in the script file. When working on a molecule it is a good idea to have the script file and PyMOL open at the same time so that you can switch between the two. After making changes to the script, delete all in PyMOL and reload the script. These previously typed commands can be easily accessed in PyMOL by using the up arrow. In this manner, you can cycle through all previously typed commands. To view the manuplated parts of the molecule better, it can be rotated around on the screen by left clicking and dragging on the image. If you right click and drag, you can zoom in and out of the image.
After loading the image, and with some rotating you should see something that looks like this:
1KMY molecule

You can see that as compared to the original file, the script has changed some colours and highlighted the iron and the iron ligands.

Discussion of the example script file with extra info:
The script that performed these operations (which can be viewed by opening the text file in notepad) are:
load c:\1KMY.pdb,main
hide all

show cartoon, all

#colour the structure and mark the iron ligands and iron
color orange
color marine, (resi 1:134)
show spheres, (elem Fe)
color pink, (elem Fe)
show sticks, (elem Fe)
show sticks, (resi 300)
color yellow, (resi 300)
show sticks, (resi 260,210,146)
color blue, (resi 260,210,146)
Going step by step through the code:
load c:\1KMY.pdb,main
hide all
These lines first load the pdb file 1KMY.pdb and call it main (this name is for easier reference in the script file). Then, the line 'hide all' hides everything giving you a fresh screen to work with.

"Show cartoon all" shows in cartoon format the protein structure giving you the familiar ribbon and helix shape which are specified in the pdb file. If the secondary structure assignments have not been made, PyMOL can perform this for you but it is slow and not recommended and certainly not for publication. To have PyMOL perform the assignments add the command "util.ss all" before "show cartoon, all". This secondary structure assignment takes a few extra seconds.

To create comments, add the # symbol before the text and PyMOL will ignore everything after the symbol on that line. This is an easy way to test removing lines of code without actually deleting them.

The next section of code colour and change the shape of certain residues and elements. "Color orange" will colour the entire molecule orange (it could also be written as "color orange, all"). Then the next line "color marine, (resi 1:134) will colour marine all the residues from 1 to 134 (inclusive). To figure out the residue number, you can look in the pdb file or you can select the residue and check to see what PyMOL calls it (more on this later). "Show spheres, (elem Fe)" shows in the form of a sphere all the Fe elements in the figure (in this figure, there is only one). "Show sticks, (elem Fe)" and "show sticks, (resi 300)" both work similar to show spheres only they draw the molecules in a stick format. To work with a number of residues in one command, separate the individuals with a comma as in "color blue, (resi 260,210,146)".

Learning more manipulations:
First, delete all and then reload the 1KMYsetup script. The following are a list of commands to experiment with different views of the model.
"hide cartoon" - this will hide the cartoon which was drawn in the script showing only the sticks that remain.
"show sticks, all" - will show the entire model in a stick format. This is rather busy so "hide sticks" (which will get rid of everything except the iron).
Other ways of viewing all include spheres, (show spheres, all), lines, ribbon, dots, mesh and surface (these last two may take a while to display). There are other commands which can be looked up in the documentation for PyMOL.

Manipulating specific atoms or groups of atoms:
There are two ways of specifying the specific atom in PyMOL, the hierarchical atom selection and algebraric atom selection. I will be discussing the algebraric atom selection. To do this, it is necessary to know what the residue number is. This can be found by examining the pdb file or by selecting the atom in PyMOL. To select the atom of interest, zoom in the area of interest, show sticks and hold down <shift> and <ctrl> and click on the atom. In the PyMOL molecular graphics system window (the one that doesn't show the molecule) it will list what residue you have selected. You can then confirm this by colouring that residue a different colour (i.e. color blue, (resi 168)). All of this information is present in the pdb file (which you can view in a program such as word).

If you wanted to colour a specific atom of a residue a certain colour (say the CA atom of the residue - this information is standard nomenclature for pdb files and you can view the atom names in the pdb file) by typing "color blue, (resi 168 and name CA)". This also works for showing the atom i.e. "show spheres, (resi 168 and name CA)".

If you wanted to colour all of the CB atoms in the molecule blue you would type "color blue, (name CB)"

To show all the carbon atoms of residues 168, 176,9 and 54 as spheres and to colour the CA atoms purple you would type two commands: "show spheres, (resi 168,179,9,54 and elem C)" and "color purple, (resi 168,179,9,54 and name CA).

To show all the his residues in the protein as sticks you would type "show sticks, (resn his)"

Creating objects for finer manipulation:
When you create an object, you are creating a subset of your molecule that you loaded and this allows you to work more easily on a part of your molecule.
For example, load the 1KMY.pdb file. We want to create an object called binding that contains the three iron ligands (resi 260, 210 and 146), the substrate (resi 300) and the iron. To do this type: "create binding, (resi 260,210,146,300 or elem Fe). Then you can work with this object more easily. For example, to display the entire molecule as a cartoon, show the ligands, substrate and iron as spheres and colour them pink you would need the following code:
load c:\1KMY.pdb
hide all
create binding, (resi 260,210,146,300 or elem Fe)
show cartoon, all
color green
show spheres, binding
color pink, binding
(if you find yourself zoomed into the binding site, hit the home key to view the entire molecule.)

If you wanted to show the elements of binding in a ball and stick manner you would type "show sticks, binding". However, you will notice that the spheres of object binding are very large, to decrease the scale for these spheres (and only the spheres in the object "binding") you would need to type "set sphere_scale=0.3, binding". This will set the property of sphere_scale to 0.3 and only apply it to the object binding. If you wanted to change the sphere_scale for the entire figure you would need to just type, "set sphere_scale=0.3".

Another object example:
The following code will load the file 1KMY.pdb, show as a cartoon, color it blue and then color yellow and show as sticks all residues within 10 angstroms of the iron in the active site. Then it shows the iron as a purple sphere.
load c:\1KMY.pdb
hide all
show cartoon, all
color blue
create closefe, (byres (elem fe around 10))
color yellow, closefe
show sticks, closefe
show spheres, (elem Fe)
color purple, (elem Fe)
The 'byres' is necessary to show the complete residues around the Fe, otherwise "elem Fe around 10" would only include atoms within 10 angstroms of the Fe.

Getting the right view in the script:
When creating the script, it is nice to have the view come up in the right orientation. To do this, you need to get the coordinates. First, position the molecule the way you would like it to appear, this can include zooming and rotating the molecule. Once it is in the correct position, type "get_view". In the PyMOL molecular graphics system window (the one that doesn't show the molecule), a set_view command will be created for you and you simply cut and paste this text into your script.
set view example

Saving your image as a png:
After you have created your image, you may wish to save it as a picture so that you can include it in papers or presentations. The first step is to ray-trace the created scene in PyMOL and the simpliest command is to type "ray". This may take a few seconds and after the ray-trace the picture can be saved as a png by typing "png c:\filename.png".
One of the first things you may wish to change is the background colour i.e. "bg_color white". With a white background you should also include: "set depth_cue=0" and "set ray_trace_fog=0". To change the lighting of the object during a ray trace "set direct=0" (values from 0 to 1). Another value to play with during ray trace is "set orthoscopic=0".  When doing a final rendering, "set antialias=1.0" will improve resolution of the image.
To specifiy a larger image type, "ray, 2400,2400". This will give you an image 2400 by 2400 pixels. This can be used to create smaller images but with a higher resolution.  After you have a 2400 by 2400 image you can convert this to a 600 dpi image using an image editor such as photoshop which will give you a 4" by 4" high quality final image.

Finding more information:
There is a lot more to PyMOL than what has been covered in this brief tutorial. You can access the user manuals from the PyMOL home page or you can skip directly to the PyMOL manual.

This page created by Carly Huitema, June 20, 2002.
Thanks to Frederic Vaillancourt for editing and rendering tips.