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.

Making Stereo Views
Ray trace the first image:

ray 2000,2000,angle-3
(the 2000,2000 will give you an image 2000 by 2000 pixels).
png image_left.png

Then

ray 2000,2000,angle=3
png image_right.png

Then, put the two pictures side by side in an image editing program.
Final result:
HAV Active Site

To make the labels appear I added them manually in the image editing program.

Working with hetatm
Working with the hetatms is very similar to working with the amino acid residues. In the pdb file, the following is an example of the hetatm section:
HETATM 1670  O   HOH A   1       0.691  -1.567 -15.850  1.00 18.77           O  
HETATM 1671  O   HOH A   2     -10.542   0.382   4.070  1.00 13.89           O  
HETATM 1672  O   HOH A   3       4.967 -15.635   3.543  1.00 19.50           O  
HETATM 1673  O   HOH A   4       4.694  -6.762   7.739  1.00 19.57           O  
HETATM 1674  O   HOH A   5      -0.692 -21.507  10.416  1.00 24.44           O
HOH is like the residue name so to show all the waters you would type:
"show spheres, (resn HOH)"

to show water molecule #1, type:
"show spheres, (resi 1)"

BUT... water molecule 1 and amino acid residue 1 both show up as spheres.
To show just the water molecule type:
"show spheres, (resi 1 and hetatm)"

To show just the amino acid residue type:
"show spheres, (resi 1 and not hetatm)"

I think pdb files are not supposed to act this way but I am not sure. However, it is still a valid example of manipulating atoms.

When you look at a structure and need to decide what the water molecule is called <shift> and <ctrl> and click on the atom doesn't seem to work for me. The only way I can think of (besides another program?) is to look at half the water molecules, see if you molecule of interest is in the group, divide that group in half and look again.
i.e. 61 water molcules in the structure:
"show spheres, (resi 1:30 and hetatm)"
is the water molceule in that group? yes.
"hide all"
"show spheres, (resi 1:15 and hetatm)"
etc.
Tedious but I am interested if someone has a better way.

Another hetatm section of a file:
HETATM 6512  CHA BCL C   1      61.844  97.378  47.104  1.00 23.82           C  
HETATM 6513  CHB BCL C   1      64.218  99.662  50.687  1.00 23.41           C  
HETATM 6514  CHC BCL C   1      60.313 102.227  51.650  1.00 22.57           C  
HETATM 6515  CHD BCL C   1      57.829  99.686  48.328  1.00 18.71           C  
HETATM 6516  N A BCL C   1      62.729  98.636  49.003  1.00 24.03           N
"show sticks, (resn BCL)"
"show spheres, (resn BCL and name CHA)"

Making Hydrogen Bonds
When the distance command is used, it appears as the yellow dashed line as seen in the figure above:
the command is distance (atom 1),(atom  2). This gives yout he distance between two atoms but it also shows as a nice dotted line.
For an example, see below.

To make the image above, the following code was used:
load c:\1hav.pdb
hide all
create active, (resi 172,44)
create around, (resi 84,143)
create v6, (resi 6 and hetatm)
create v29, (resi 29 and hetatm)
show sticks, active
show sticks, around
color red, active
color green, around
set sphere_scale=0.2
show spheres, v6
show spheres, v29
distance (v29),(v6)
distance (resi 84 and name O),(v6)
distance (resi 44 and name ND1),(v6)
set ray_trace_fog=0
bg_color white
set depth_cue=0

Useful image settings
To set the surface transparency,
set transparency, 0.6
To make the cartoon figure transparent:
set cartoon_transparency, 0.6
Making a cartoon often results in a smoothing of the loops and sheets. When you view individual residues, they may appear to float above the strand.
To eliminate this:
set cartoon_flat_sheets, 0
set cartoon_smooth_loops, 0

Colour by B-factor: using Python scripts
Robert L. Campbell has created a very nice Python script that can colour a selection by B factor. The script can be downloaded atb_factor his page: http://adelie.biochem.queensu.ca/~rlc/work/pymol/, this page has several other scripts but the b factor script is called color_b.py. Briefly, the B factor describes how much motion a residue of a structure has and this information is present in the pdb file. More 'floppy' sections of crystal will have a higher B factor.

When using the Python script you first need to load it into PyMOL. To do this type: "run c:\color_b.py" or whatever the path is to the script file you have downloaded. Once the Python script has been loaded into PyMOL, you can use the command(s) the script describes either from the command line or in your own PyMOL scripts. The instructions at the beginning of the Python script describe it's usage. They are:
AUTHOR 

	Robert L. Campbell

USAGE

	color_b(selection='sel',ramp=0 or 1, rainbow=0 or 1, nbins=10)

	This function allows coloring of a selection as a function
	of B-value, either in a range of hues from blue through magenta
	to red (rainbow=0, the default) or in the colors of the rainbow
	(rainbow=1).  The division of B-value ranges can either be as a
	histogram (equal-sized B-value increments leading to unequal numbers
	of atoms in each bin: ramp=0) or as a ramp of B-value ranges with an
	equal number of atoms in each group (ramp=1).

	usage:
	  from within PyMOL do "run color_b.py" to load the function definition.  
		Then you can use for example:

		    color_b('(c;a or c;b)',ramp=1,rainbow=1,nbins=30)

		to color chains A and B with the rainbow colors in 30 colors of equal 
		numbers of atoms in each color.

	"""
More usage examples:

color_b('all',ramp=1,rainbow=0,nbins=10)
color_b('resi 1:30',ramp=0,rainbow=0,nbins=30)

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.

This page created by Carly Huitema, June 20, 2002.
Last updated May 17, 2004.
Thanks to Frederic Vaillancourt for editing and rendering tips and the mailling list for further ideas.