PyMOL: A (not so) short tutorial
Sambra Redick, June, 2003 modified from time to time by Harold Erickson (last updated Nov-2005)
First the bad news. There is no manual for Warren DeLano’s PyMOL for Mac OSX.
Now the good news: There is a good, detailed manual for the PC version, and the PyMOL commands are essentially identical on all platforms, aside from the information that tells the software how to find files- the paths. This means that the PyMOL for Windoze manual (userman.pdf) is sufficient to understand the PyMOL-specific commands. I’ll try to cover the important OSX-specific commands here. Many useful OSX commands are covered in Jim Hu’s OSX adaptation ( of Carly Huitema’s Windoze tutorial. Jim’s tutorial is a bit longwinded if you have experience with RasMol, so I’ve tried to make a true 30 minute tutorial (but I didn’t succeed).
Subscriptions: DeLano asks for users to pay an annual subscription. $50 a year or $137 for three years seems quite reasonable for a single academic user. He says the program (but not the manual) is free if you only use PyMol to look at published pdb files, but I imagine that he wants you to pay if you use the program to make figures for publications. Note that program is free to students.
Pymol opens two windows, the PyMOL viewer and PyMOL (the command console). Normally you will keep the viewer window active (click anywhere on it) and you can type commands in the single line shown there. The console has a record of all commands. Just below the record box in the PyMOL window, there is a command entry box- type commands here (this box is the only one that works to paste from the clipboard). There is also a command line at the bottom of the PyMOL viewer window. This command line is particularly useful because it behaves like a true UNIX command line, that is the up arrow recalls previously-typed commands, eliminating the need to retype lengthy pathnames and commands. Regardless of which command line you use, the command and the resulting confirmations, error messages or other responses are displayed in the command record box in the PyMOL window (and in the text window that you get when you toggle the graphics window with the escape key).
Loading pdb files
Although pdb files can be loaded from the command line, they are also easily loaded by choosing “Open” from the File menu. One IMPORTANT POINT: in order to be recognized by PyMOL, pdb coordinate files must have the .pdb filename extension- if necessary, pull all of your coordinate files into a folder and write a script to add the extension to all.
Setting background color
When an image opens, it is in a format that has been called a standard. I prefer a white background to the standard black. To change background color, type (in either command line)
bg_color white
Yes, that is an underline between the “g” and “c” and it is necessary.
The FAQ suggests you also turn off depth cueing and fog
set depth_cue=0
set ray_trace_fog=0
Or disable "Depth Cue & Ray Trace Fog" from the Settings menu in the external GUI.
Viewing molecules
On the right side of the PyMOL viewer window, there is a menu with the name of the protein your have loaded listed under the everpresent (all). To the right of the protein name are five pull-down menus. The first, marked by a diamond includes the delete and duplicate commands. The second and third are the “Show” and “Hide” menus. These contain the same options, allowing you to show or hide many different representations of the molecule. In this show/hide scheme lies a major difference from RasMol: you can show multiple representations of the same molecule simultaneously. Practically speaking, this means that if you are showing a molecule as spheres, every other view will be obscured by the larger spheres.
The fourth menu is the label menu, for assigning labels to various features.
The fifth menu is the color menu. the options include several variations on CHNOS coloring, three different rainbow schemes, and the single color choices. Although you can easily apply single colors (or any (RGB)-defined color) via the command line, I’ve not found a way to apply the CHNOS or rainbow colors via the command line.
Available colors: red, green, blue, yellow, violet, cyan, salmon, lime, pink, slate, magenta, orange, marine, olive, purple, teal, forest, firebrick, chocolate, white, wheat, grey.
The menu options apply to the entire molecule when you are on that line. If you are on a selection they apply to everything in that selection.
Rotating and moving molecules – mouse commands
PyMol uses a three button mouse, and if you have this there is all kind of flexibility in what you can do. Hold down the left button and the cursor will rotate the molecule in three dimensions. If you click outside the molecule, it only rotates in the Z plane.
Hold down the right button and the molecule gets larger or smaller as you move the cursor up and down. The bottom right of the view screen lists what each mouse button does, and it is different with shft, ctrl-shft, etc. If you click on “3 button viewing” it changes the assignments of all the ctrl, shift, etc actions and is in a mode called “3 button editing.”
But most Mac users are used to using only the single left mouse button. One feature that you can’t access with that button is moving the molecule in X-Y. You can assign this function with the following command
button left,shft,move
Then hold down the left button and the shift and the molecule will move in X-Y. This defaults frequently, so be prepared to reset it. Also, there are all sorts of things you can move, including single atoms, beta strands, etc. Go to the instructions for these features.
Working with selected atoms
To change the way selected atoms are represented, use the show command, e.g.
show spheres, all (or use the Show pull down on the right side of the graphics menu. (This will apply to the whole molecule or the indicated selection.)
You must deliberately hide a view, it doesn’t disappear when you show another, i.e.
hide spheres, all (or use the Hide pull down on the right side of the graphics menu)
To apply a color from the command line, type
color colorname, all (replacing colorname with the desired color)
For any of these commands (show, hide, color), you can apply to selected atoms or residues. In all cases, type the command up to the comma as above, then follow with (resi ###,###) or (resi ###:###) to indicate residues by number (###). You can either use commas or colon, I’ve found no way to use both in one set of parentheses. Also, you can’t put spaces between numbers inside the parentheses) e.g.
show spheres, (resi 21)
color blue, (resi 21)
show spheres, (resi 209,210)
show spheres, (resi 207-212)
To apply these commands to nucleotide, put the following in the parenthesis, (resn gdp) (or whatever nucleotide you want to view). e.g.
show sticks, (resn gdp)
color yellow, (resn gdp)
Note: resn means residue name. You can color all his residues with
color green, (resn his)
Clicking and Picking atoms – measuring distances
One of the most useful features is what’s called “menu” on the 3-button viewing panel. Put the arrow on a position of interest and double-click the left button. A powerful menu will appear, and on the top line the residue and the atom you have clicked are identified. Below you have options to show or hide spheres (at the level of the residue (or several other levels), color, etc.
If you want to find the distance between two atoms go to the Wizard menu on the upper window. Select measurement, and a line will appear “click first atom.” Click this and then click the second atom when prompted, and the distance will appear. (Sometimes simple clicking doesn’t work, and you need to PkAt by holding cntl and clicking with the middle mouse button.) You probably need to set bg_color black to see the yellow number; you may also need to hide spheres if it is hidden. A new object will appear on the right, dist01. The number will only appear when it is highlighted.
An alternative way to determine the distance is to pick each of them, using the PkAt function. On the default 3-button mouse this is done with cntl-middle. Click on an atom in the first aa, then repeat on the second aa. They will show up on the right panel as (pk1) and (pk2). Highlight both of them and type
dist Or type
distance (pk1), (pk2) (note the positioning of the comma).
A new object will appear on the right, dist01.
Scripts and sessions
Scripting saves you the trouble of retyping commands to get a frequently used view. Essentially, you enter the commands in a file in the same order that you would type them, then give the file a name ending in .pml (PyMol file). To call the script use the Run command on the file menu.
Harold, using the latest 2005 version can’t get scripts to work when typing them directly from Word or TextEdit. However here is what does work. Type your commands initially in PyMol and have PyMol save them as a log file. To do this, at the beginning of the session go to “Log” on the file menu and give a name for the log file (and specify where to put it). When you are finished type
log_close. Or exit PyMol
The program will then save the commands as a script file (I don’t know how the program decides where to put it (assuming you don’t specify a path), you will need to search for it afterwards.) Note that the commands do not include any rotations or movements of the molecule. I have found that I could open this script file in TextEdit and make at least some additions, save it and it then worked in PyMol. If I copied all the commands to a new text file and saved that it didn’t work. So start with a script file made initially by PyMol and try your additions and changes in it. One further note: the log file does not automatically record any rotations or movements of the molecule. To save this type “get-view” on the command line before you finish.
Another powerful feature is “save session.” After you have manipulated the molecule to get a view that you like and want to return to, chose “save session” and you will get a window to save. Give it a name, e.g., FtsZ front consAA, and the program will add a .pse extension. Later when you want to return to that view chose “Open” from the File menu and open the saved session. One minor problem is that the commands used to make the original are not saved, only the final configuration. If you may want to modify the commands, use the log/script feature.
Align is a neat feature. With two similar molecules loaded, give each a simple name like mbp1 and mbp2. Then type
align mbp1, mbp2
Making figures
To make the graphics that rival Molscript, PyMol must make a rendering into a ray tracing. Optimizing the image takes a series of commands and is best handled by writing a script that can be edited at each use to give unique filenames. (See Jim Hu’s tutorial and the PyMol manual, pg 32 and 107).
Here is our preferred script.
set depth_cue=0
set ray_trace_fog=0
set orthoscopic=1
set antialias=1 (these two are not needed, they are on by default.
ray 800,600
or
ray 2400,2400
What does this all mean?
The first two lines are Jim Hu’s suggestions for white backgrounds- I’ve blindly followed them, but I do understand a few parts now. Setting depth cue to 0 means that the residues don’t fade as they get farther back from the plane of the screen- but some people prefer this perspective, =1 turns it on. Setting orthoscopic to 1 makes the output precisely mirror what is shown in the viewer window. Setting antialias to 1 (i.e. “ON”) gives smoothed images.
ray 800,600 starts the ray tracing for a particular resolution. After about 20-60 sec the program will apologize for not displaying the image and ask you to enter “png <filename>” to save the image. Better is to use the “Save image” option on the file menu.
You can specify the resolution of the image with the numbers. Jim recommends ray 2400 x 2400, but this takes up to 20 min. 1600,1200 takes only 1-2 min and produces a fine image, you don’t need more; it makes a 700 kb png file, which will be 6 mb when opened in photoshop. 800,600 is also very nice, takes only 30 sec (but can take a couple of min for larger structures) and gives a 200 kb png file (2 mb in photoshop). This is probably sufficient for any publication. 400,300 produces a 100 kb file that is poor quality, but useful for experimenting.
The viewer won’t be able to display the high resolution image. The latest version has a save image command on the file menu that lets you save it anywhere, wonderful improvement over typing paths. FYI, the .png filetype is supported by PowerPoint with no translation necessary, and the files can be opened in photoshop.
If you just need a rough preview image, you can also write a png file of the flat (not ray-traced image). Click on the image screen to bring back the molecule.
Movies:
Simple Examples
Here a static structure is subject to a gentle rock. The following statements create a sixty frame movie which simply rocks the protein by 10 degrees.
load test/dat/pept.pdb # load a structure
mset 1 x60 # define the movie
util.mrock(1,60,10,1,1) # issues mdo commands to create +/- 10 deg. rock over 60 frames
In this next example, the protein is rotated through a full 360 sweep about the Y-axis over 120 frames
load test/dat/pept.pdb # load a structure
mset 1 x120 # define the movie
util.mroll(1,120,1) # issues mdo commands to create full rotation over 120 frames
Complex Examples
The following is a Python program (with a .py or .pym extension) which uses a Python loop to load a large number of numbered PDB files, and then configures PyMOL to show them both forwards and backwards.
from glob import glob
from pymol import cmd
file_list = glob("mov*.pdb"):
for file in file_list
cmd.load(file,"mov")
cmd.mset("1 -%d -2"%len(file_list))
Previewing Ray-traced Movie Images
PyMOL has the ability to cache a series of images in RAM and to play them back at a much higher rate than they could be rendered originally. This is most-useful for ray-traced images, but it can also be used with OpenGL images.
cache_frames
The cache_frames option controls whether or not PyMOL saves frames in memory. Its usage is demonstrated in the following script. NOTE: caching images takes a tremendous amount of memory, so you should use the "viewport" command to shrink the window before utilizing this option.
viewport 320,240
load test/dat/pept.pdb
orient
hide
show sph
mset 1 x30
util.mrock 1,30,3,1,1
set ray_trace_frames=1
set cache_frames=1
mplay
mclear
Once you have loaded a set of frames into RAM, the frames will remain there until you run the "mclear" command, even if you manipule that model. You can also press the mclear button on the external GUI window.
mclear # flushes the frame cache
Saving movies
mpng
You can save movie images to numbered PNG format files with a common prefix. If you want each frame to be ray-traced, you should turn on raytracing of frames, turn off caching, and clear the cache (see the Movie Menu or use the following commands).
set ray_trace_frames=1
set cache_frames=0
mclear
Then go to “movies” and save as quicktime with options. Compression=0
You can save the movie using the "mpng" command, or you can save it from the "File" menu. Either way, you must provide a prefix which will be used to create numbered PNG files.
mpng mov # will create mov0001.png, mov0002.png, etc.
If you are compressing movies using Adobe Premiere (recommended for best quality), you will probably want to convert the files using ImageMagick or a similar package into a format that Premiere is capable of reading (such as ".tga" - targa format).