Brief PyMOL tutorial

LMB Bioinformatics workshop, January, 2006

 This tutorial will concentrate on some basics of using a Mac version known as MacPyMOL.  The advantage of this version is that it is self-contained and can be easily downloaded and started on your Mac.  It also has some features that make creating movies very simple.  One disadvantage is that user-written plugins that have a variety of handy applications are not incorporated.  In order to have full access to these, you will have to install the HybridX11 version of Pymol. 


Installing MacPyMOL

 If you do not already have  MacPyMOL on your Mac, please click on the "download" link above.  Choose the version appropriate to your Mac (I am assuming this is a G4 or a G5 running Tiger, 10.4.x).  Let Stuffit Expander open the file.  In your default download directory (Probably the Desktop), you shoud see the MacPyMOL icon ().  Move this icon to your Applications folder and put a link to it in your Dock. 

To simplify use of this tutorial, it is assumed that you are using Firefox as a web browser  and that your download preferences for Firefox are set to download files to the Desktop.

Using MacPyMol interactively

In this tutorial, we will make a single figure interactively.  I have also included a sample script that uses many common commands for generating PyMOL pictures.  The script is annotated with comments denoted by the # character.

 The purpose here is not to explain every detail of using PyMOL.  To really get familiar with PyMOL can require a great deal of time.  This is only meant to represent a fast way to get started.

 For further details, please consult the PyMOL user manual or PyMOL reference manual.

Getting coordinate files

The most common way that structures are loaded into PyMOL is to read the Protein Data Bank (PDB) file. 

Fetch a PDB file corresponding to the PH domain from beta-spectrin (PDB id 1e8x) by following our tutorial for the PDB database. 

A PDB file for the GLUE domain of Vps36 that will be relevant to the lab workshop that we will be doing next week can be downloaded by clicking here.  This structure will be released upon publication.  Please do not distribute it.

 Quickstart introduction to MacPyMOL

Start MacPyMOLby clicking on its icon in the Dock ( ).  This will start MacPyMOL and  you will have two windows.  One is the so-called "GUI" where you will type PyMOL commands

 The other is the viewer window where you will see the molecules displayed


 Load a PDB file into MacPyMOL

To load the PDB file that you downloaded from the PDB database, click on the "Open" option under the "File" menu of the GUI.

Select the file 1BTN.pdb file that you downloaded from PDB. 

By default, the molecule will be displayed in stick representation and coloured by atom type. 

You can see the name of the object listed in the menu to the right of the viewer window.  By default, the object will be called the same name as the PDB file loaded. 

 You can perform various actions on the object by clicking on the 'A" to the right of the object name.  This will open the Action menu.

For example, you can rename the object from the cumbersome 1BTN to something easier to remember such as "spectrin" by using the "rename object" item.

Manipulate the view of the molecule

You will need a three-button mouse to effectively use PyMOL.   If you do not have one, I will provide one for this tutorial.

Most molecular visualization tools use the same axis convention:  X meanss the horizontal axis, Y means vertical and Z is an axis that is perpendicular to the surface of the screen.

Rotation around X or Y:  Left mouse button and drag
Rotation around Z: Place the cursor toward the left or right edge of the PyMOL Viewer window and then left button and drag
Translate (move) X or Y: Middle button and drag (Note: if it gets stuck with the middle button, press alt and left button to get unstuck)
Zoom (move Z): Right button and drag up-down

All of these and many more mouse functions are summarised in a very short manner in the Box to the right bottom of the viewer window.  By default, the top line of this box reads "Mouse Mode 3-Button Viewing".

 You can use the menu items ASHLC next to the "spectrin" or any other object in the right-hand part of the viewer window to generate various actions (A), show various representations (S), hide various representations (H), manipulate labels (L) or change the colors (C).

Hide the complicated default line representation by clicking on H (hide) next the object "spectrin" and choosing "hide lines". 

You should now see a lot of dots representing waters and ligands.  Hide these also by choosing H and "nonbonded" in the submenu.

Changing the representation of the molecule

Make a cartoon representation of the "spectrin" object by choosing S (show) and submenu "cartoon". 

You can change the look of the cartoon by choosing Setting and then Cartoon.  For example, you can select the  Highlight Color.  This makes the edges of the strands and the inside surface of the helices a second color (grey by default).

Try various representations of the molecule by clicking on S (show) next to spectrin then choosing a representation (lines, sticks, ribbons, surface etc).  Note that one representation does not replace another but is added on top of another.  Representations are only removed by using the corresponding entry in the H (hide) menu.  For the surface representation it can take a few seconds to display, depending on how fast your Mac is.

Under the A, there is also a menu of various "preset" styles that you can apply to an object.  Probably the most useful is the preset/publication.  You can try running through these presets to see what is available.  The find action can also be useful for quickly identifying protein/ligand contacts.

Identifying atoms or residues on the screen

To show the identity of an atom, double click with the left button on any point in the molecule.   This brings up a menu that allows you to do various actions to the atom, residue, chain or molecule of which the selection is a part.

Labelling  You can label every residue in the molecule by choosing the "residues" submenu under the L menu to the right of the spectrin object.  Clearly, this is not a very useful way to label a molecule.  In general, for publication-quality labels, you will add them later in an application such as Adobe Illustrator.

For the purpose of examining the molecule interactively, you can easily get only selected residues labelled.

Clear the mess of labels by choosing the "clear" submenu of the L menu next to the spectrin object.

Viewing the sequences of the molecules

You can see the sequence of the molecule by clicking on Display then Sequence On in GUI window. 

By pulling the slider under the sequence toward the right, you can see that there is Inositol 1,4,5-tetrakisphosphate (I3P) in the complex and it is labelled residue 100.  This is why the I3P residue is in the sequence viewer before residue 100 of the protein,  Often authors try to make the residue numbers unique so that such ambiguities do not occur.

Selecting parts of the structure

Select the I3P molecule in the complex by typing "select I3P=( r;I3P ) " in the command line of the GUI window. 

You could have also selected this residue by just clicking on its name in the Sequence or by clicking on the I3P in the Viewer window.  

Although the pull-down menus allow some common selections to be made without entering commands on the command line, you may find it faster to make complicated selections via  the command line.  The text box 1.0 lists some examples of commonly used commands for selecting parts of molecules.

Text Box: Text Box 1.0.  Some selection examples

select ATP=( i;2000)
# This means select residue number 2000 and call it ATP

select near_atp=( ATP expand 8 )
# select all atoms within 8 Å of any atom in the ATP

select active_site=( i;882,884,833,890 & c; A)
# select residues 882, 884, 833 and 890 of chain A and name them "active_site"

select c2domain=( i;357-522)
# select residues 300 to 500 and call them "c2domain"

select basic=( r;LYS,ARG )
# select all LYS and ARG residues and name them "basic"

select trihosphate=( r;ATP & e;P )
# select the phosphate atoms in the residue type ATP and call them "triphosphate"

select backbone=( n;CA,C,O,N )
# select atom names CA,C,O and N and call them "backbone"Manipulating a selection

 An "I3P" object is added to the right hand side of the Viewer window with the now familiar ASHLC menu next to it.

You can choose the various ASHLC options next to I3P and they will apply only to the I3P atoms.

Make a solid object of the I3P by using the "Spheres" option under the S (show) menu next to the I3P object

 You can zoom in on the I3P by choosing the "Zoom" item under the A (action) menu to the right of the I3P object.

You can select the residues near the I3P by choosing the "Around" under the Action menu then choosing a distance from the "Around" submenu.

Change the representation to sticks using the S menu next to the I3P (Don't forget that to see the sticks, you have to H (hide) the spheres).

 On top of your chosen representations, you see some purple dots indicating the selected atoms.  You can hide the purple dots showing what is selected by choosing "Hide Sele" from the small menu in the right-hand side of the GUI window.  This deselects the object but doesn't remove it.

 Use the C item on the ASHLC to change the colour of a selection.

Making measurements

Measuring distances To measure distances between two atoms, choose the Measurement option under the Wizard menu in the GUI window,  This creates some sub-menus to the right of the view window corresponding to various measurements that can be made. 

Choose Distances.  A message appears in the PyMOL viewer (upper left corner) saying "Please click on the first atom..." Click on an atom using left button.  A message now appears in the PyMOL viewer saying "Please click on the second atom..."

 Pick a second atom and a dotted line appears between the two atoms with the distance displayed.

 Get out of the Distance Wizard by clicking Done in the Measurement menu to the right of the viewer window.

Clipping planes

As you roll the spectrin object around using the left button, you can see how elements of the structure are cut away.  This is due to "clipping".  Clipping planes are imaginary planes in front of and behind the object.  Things that are closer or farther away are clipped. 

To make the front plane move closer or farther away, press shift and the right mouse button simultaneously while dragging up or down.  By doing the same thing, but by dragging left or right, the rear clipping plane moves.  To move both planes at the same time, drag at a 45 degree angle.

Setting the background colour

In general, black backgrounds are great on the screen, but they can make really horrible pictures for publication because they don't photocopy or print well in black and white. 

Under the Display menu, you can choose Background to change the background to a few pre-defined colours, including white.  You can also change this and many other settings by using the "setting" menu of the GUI window.

Resetting the view

If you get lost in details, you can get back to the original view by clicking Reset in the menu to the right of the GUI window

Ray tracing

You can make a higher-quality, but static image of the molecule by clicking on the "Ray" menu to the right of the GUI window.  This can take a few minutes.

Saving an image

You can save the image as a png file for incorporation in Illustrator or Powerpoint by choosing File then Save Image in the GUI window.  Type spectrin and it will save the image as spectrin.png.

Saving a pymol session

If you want to quit pymol then come back to it later, you can choose File then Save session.  This will make a file that has all of the information necessary to restart PyMOL and get back to exactly the same view/representation/selections as you had when you quit.  To use this file to restart PyMOL, use the File/Open option. 

Superimposing two structures

You can work with many molecules in PyMOL simultaneously.  In order to be able to see regions  in which two related structures agree or disagree, it is convenient to superimpose the structures.  The simplest way to do this is with the align command.

Read in the coordinates of a second PH domain.  Get the coordinates for the GRP1 PH domain by downloading PDB database entry 1FGY (just like you did for 1BTN above). 

Rename the object 1FGY to GRP1 (using the A menu to the right of the  1FGY selection).

Superimpose the GRP1 PH domain onto the spectrin PH domain typing: "align GRP1,spectrin"  in the GUI window. 

Although PyMOL does this structural alignment via an initial sequence alignment, the sequence viewer does not show the sequence alignment.  The structural superposition is most readily seen by hiding the lines for the spectrin and GRP1 (use the H option in the ASHL menu) and showing the cartoons (under the S menu).

Superimposing structures of proteins with divergent sequences

The align command works fine if the  two structures have similar sequences, but fails miserably if the sequences are more divergent, i.e., when the sequence identity is less than about 25%.

The Vps36 GLUE domain also has the fold of a PH domain, but its sequence identiy is so divergent that the align command fails.  Try it. 

Hide the lines for the GLUE domain and  show its cartoon.  Clearly, the two structures are not corectly superimposed.

DaliLite to align structures

To align structures with little or no sequence identity, it is necessary to use some tool external to PyMOL.  There are many useful options, but one which is robust and accessible as a web server is the DaliLite server ( at EBI.  This uses purely geometric features of structures for alignment.

Access the DakiLite server by clicking here.

 Superimpose the Vps36 GLUE domain onto the spectrin PH domain by entering the coordinate file for the GLUE domain (2CAY_mola.pdb) as "Second structure" (right field) and the spectrin PH domain (1BTN.pdb) as the First structure (left field).  The result is as displayed below.

Download the DaliLite result consisting of a PDB file that has the GLUE domain rotated and translated to match the spectrin PH domain.  It is called "mol2_1.pdb" by default. 

Open this coordinate file in MacPyMOL using the  File/Open menu in the GUI winbdow.

It is clear that the GLUE domain fold matches the spectrin PH domain fold even though the sequence similarity is insignificant.

MacPyMol scripts

One of the strengths of PyMOL is its powerful scripting language.  Although it can be used as a menu-driven viewing tool, by making scripts, we can make publication-quality images that can be reproduced exactly without any further typing.  These scripts are easy to modify and their intuitive structure makes them self-documenting.  Most of us make one script for every panel of a figure for publication. 

Delete everything by typing "delete all" in the command line of the GUI window.

Download a prepared sample script by clicking here (save into the same directory that you have the 1BTN.PDB coordinate file. 

If you are using the  Firefox browser as I suggested, you will probably see the text  of this file displayed in the browser.  If so, chose "Save as" from the  Firefox menu,  and save  the file as spectrin.pml in the desired location as an "Ascii text" file). 

Read this script into MacPyMOL by choosing the "Run" option under the "File" menu of the GUI window and selecting the spectrin.pml file.  Files with pymol scripts are usually created with a text editor such as emacs or TextEdit and named with a ".pml" extension at the end. 

You should now see a spectrin PH domain with some selections listed to the right.  These include the elements of secondary structure and a set of residues that the authors thought might be membrane-interacting residues.  These selections were defined in the spectrin.pml script.

 Making a movie suitable for importing into Powerpoint

Download a startupfile that will make creating some simple movies easier by clicking here. 

Open the file with Stuffit expander. 

Initialize the movie tools by typing  " run ~/Desktop/pymolstartup/" in the GUI window.

Make a simple movie that spins the molecule around a vertical axis (the "y" axis) for 360 degrees in 10 degree steps:

 On the command line of the GUI window type:

 The movie is now made. 

To control viewing the movie in pymol, use the movie controls on the bottom of the GUI window. 

Click on "Play" to play the movie and "Stop" to stop it.  Click on the ">" and  "<" buttons to move forward  or backward a single frame.

The nice thing about pymol movies is that you can change the view and representation while the movie is playing.  When you are happy, you can then save the movie as a Quicktime movie  suitable for applications such as Powerpoint. 

To save a high quality movie,  chose the "Save move as/Quicktime (More choices)" under the "File" menu in the GUI window:

 In the Compression type: menu, choose Photo – JPEG.  In the Depth: menu choose Best.  In the Quality: menu, move the slider to Best.  Save the movie as

 You should now have a QuickTime Movie.  This movie can be viewed with QuickTime movie player or incorporated into a Powerpoint presentation (using the Insert/Movies and Sounds/Movie from File menu in Powerpoint).  You can use movie-editing tools such as Adobe Premiere to adjust the speed of the movie, add titles, sound tracks, etc.


<< previous | top | next >>