pymol_tutorial

PyMOL tutorial
Gareth Stockwell
Version0.1(1st June2003) / gareth/work/pymol
Contents
1Introduction4
1.1Outline (4)
1.2Obtaining PyMOL (4)
1.3Capabilities (4)
1.3.1Comparison with other molecular graphics programs (6)
1.3.2Future development (6)
2The Basics7
2.1The PyMOL GUI (7)
2.1.1Components of the PyMOL windows (7)
2.2The PyMOL command language (7)
2.2.1Reading in coordinate files (8)
2.2.2Available representations (8)
2.2.3Selection (10)
2.2.4Displaying hydrogen bonds (12)
2.2.5Density maps (13)
2.2.6Settings (13)
2.2.7Ray tracing and images (14)
2.2.8Online help (15)
2.3Sessions,scripts and views (16)
3Advanced techniques17
3.1PyMOL as a Python interpreter (17)
3.2Extending PyMOL using the Python API (17)
3.3Movie making (18)
3.3.1Reserve space for the frames (18)
3.3.2Generate each frame in the sequence (19)
3.3.3View the results (19)
3.4Compiled Graphics Objects(CGOs) (19)
A Example scripts21
A.101_loading.pml (21)
A.202_representations.pml (21)
A.303_a_selections.pml (23)
A.403_b_selections.pml (25)
A.504_hbonds.pml (26)
2
3
A.605_maps.pml (28)
A.706_a_movie.pml (29)
A.806_b_movie.py (30)
B Links33
1.Introduction
1.1.Outline
PYMOL is a free,open-source molecular graphics package written by Warren DeLano.This tutorial is intended to demonstrate how the program can be used,and what its capabilities are.In particular,the following will be addressed:
•What is PyMOL?
•Where can you get it,and on what platforms does it run?
•What can it do?
•How does it compare to other molecular viewers?
•Some examples of how to start using the program
•Sources of other information
1.2.Obtaining PyMOL
It is available from ,with simple-to-install versions available for Windows, Mac,SGI and Linux platforms.Since the source code is available,it can in principle be run on any Unix system,as long as the OpenGL graphics library is installed.
1.3.Capabilities
PyMOL has a range of features which combine to make it a powerful visualisation system, some of which are listed here:
•Ability to manipulate multiple objects(molecules)simultaneously and independently
•Van der Waals'surface generation and rendering
•Built in ray-tracing engine
•Ability to dump screen contents as an image file(PNG format)
•Can read in density maps(CCP4or X-PLOR format)
•Isosurface generation algorithm
4
Figure1:The main PyMOL window
Figure2:The PyMOL external GUI window
•Multiple coordinate file formats supported(PDB,XYZ,MOL2...)
•Modelling functions†
•Batch mode(no GUI-useful for back-end image creation)
•Movie generation‡
•Session save facility
•Extensible API,using the Python language
†Modelling functionality at the moment is fairly primitive-there are no force fields or minimisation yet, although this is promised for a future release.
‡PyMOL can be made to output a series of frames,for example of a molecule rotating.An external program must be used to convert these into a movie format.A script to create MPEG movies
from PyMOL frames is distributed with the Unix version of this tutorial.
parison with other molecular graphics programs
Marc Saric has a useful table comparing the most commonly used programs,at http://www.marcsaric.de/molmod1.html
1.3.
2.Future development
PyMOL is in active development,with the following features among those planned for the future:•Inclusion of a RasMol script interpreter
•Force-fields for minimization during model-building
2.The Basics
2.1.The PyMOL GUI
ponents of the PyMOL windows
Figure1shows the main parts of the PyMOL window.The object list shows which objects are currently loaded;each object can be hidden by clicking on the bar containing its name.To the right of each object name are four buttons which produce drop-down menus when clicked. The first allows you to perform basic actions on any one object(delete it,center the view on it,etc).The second is the'show'menu,which turns on various representations(cartoon, wireframe,spacefill,etc).Conversely,the third menu is the'hide'menu.The last controls the colour of each object.
Figure1:Components of the main PyMOL window
2.2.The PyMOL command language
While some simple functions are available via the GUI menus,most interaction with PyMOL is via a scripting language.This is superficially similar to that used in the RasMol viewer,but substantially more complex.The basic form of a command is a keyword,followed optionally by one or more comma-separated arguments.For example:
color red,hetatm
7
colours all non-protein atoms red.By contrast,the colour command can be used without the second argument
color red
in which case all atoms are coloured red.In most cases,the first argument is specific to the command being used(e.g.a filename for load/save,or a colour name for color),while the second,if specified,is the name of the object or selection to which the command should be applied.
The most commonly used commands are listed in table1;for a full list,see the PyMOL manual.For simplicity,here not all optional arguments are listed,just the most commonly-used ones(shown between square brackets).Again,the official documentation is the place to look.
Command Function
load Read in a data file.The file type is(usually)autodetected.
save Save coordinates to a file.
select Pick out atoms/residues from an object or existing selection
delete Delete an object
color Set colour of an object
show Turn on a particular representation type(e.g.cartoon,spacefill)for an object hide Turn off a particular representation
set Alter a parameter(e.g.sphere size)
orient Center the view on a selection or object
distance Measure distance between two atoms,and draw a dashed line
Table1:Common PyMOL commands
2.2.1.Reading in coordinate files
To load in a coordinate file,simply type the following into either one of the PyMOL windows. (It is assumed that you ran the program from the root directory of the tutorial).
load data/pdb1gbv.ent,1gbv
This loads in the coordinates for human haemoglobin,giving it the identifier'1gbv',and should result in a screen looking like figure2.
2.2.2.Available representations
Now we can try some different representations of the structure.Type in
hide everything
show cartoon
and then select'by chain'in the pull-down colour menu next to1gbv.You should get a picture like that in figure3.
We can now render the different chains distinctly.Type in
Figure2:After loading in a coordinate file
Figure3:Cartoon representation
hide cartoon,chain A
show ribbon,chain A
set ribbon_width,3
Notice the use of the'set'command to make the ribbon more visible(figure4). Similarly,other representations can be used on the other chains(figure5).
hide cartoon,chain B
show spheres,chain B
hide cartoon,chain C
show sticks,chain C
Figure4:Chain A rendered as a ribbon
Figure5:Other representations
2.2.
3.Selection
The previous section demonstrated the use of simple selections;here is a bit more information on how they work.PyMOL has two selection syntaxes:hierarchical and algebraic.
For hierarchical selections,the layout is as follows:
model/segment/chain/residue/atom
The rule is that the levels are worked out left-to-right if the pattern starts with a slash,e.g. /model/segment/chain/residue/atom
and right-to-left if not,e.g.
residue/atom
is valid.Examples:
select///A/10#Select residue10in chain A
select////10-20/CA#Select atoms called CA in residues10-20(any chain)
select42/C,N#Select atoms C and N in residue42
Algebraic selections offer a bit more power,at the cost of slightly increased complexity.The idea here is to use terms(such as'chain A','resn ALA'),which are combined using standard logical operators(AND,OR,NOT).Examples:
select chain A
select chain A and resi10:20#'resi'specifies residue number
select resn ALA and name N#Select backbone nitrogens from alanine residues
select elem O and not name OH#Select all oxygen atoms except hydrox-yls
The keywords(chain,resn,resi)may be substituted with shorthands;the following are equivalent to the expressions above.
select c;A
select c;A and i;10:20
select r;ALA and n;N
select e;O and not n;OH
Similarly,the logical operators can be replaced with symbols:
select c;A
select c;A&i;10:20
select r;ALA&n;N
select e;O&!n;OH
Some other selection keywords may be of use:
around selects atoms in proximity to an existing selection,so to select the binding site of a heme residue in chain A,we may do:
select bs,(r;hem&c;a)around4
Notice that algebraic selection expressions must always be placed inside parentheses.This creates a new selection called'bs'.The previous command simply selects all atoms within 4of the ligand;if we want to select whole residues,the byres keyword should be used(see figure6).
select bs,byres(r;hem&c;a)around4
Figure6:A heme binding site,picked out using the select command
Examples of selection syntax are given in the scripts03_a_selections.pml and 03_b_selections.pml.
2.2.4.Displaying hydrogen bonds
The best way to display hydrogen bonds is to use the distance command.Note that at present,PyMOL does not contain a built-in hydrogen bond detection algorithm,so some external program must be used.Given that you know which atoms are h-bonded,the bonds can be visualised as follows:
distance dist_name,atom_1,atom_2
hide labels,dist_name
See example script04_hbonds.pml for an example of this,and figure7for the example output.
Figure7:Hydrogen bonds viewed using the distance command
2.2.5.Density maps
PyMOL provides support for loading and contouring density maps,in either CCP4or X-PLOR format.In order to load in a map,simply use the'load'command,e.g.:
load data/p4,map
This one is from a crystallisation experiment on lysozyme(PDB ID1lza).A contoured isosurface can then be generated using the'isomesh'command,which takes three arguments: the name of the surface object to be generated,the name of the map object,and the contour level.By default,maps are normalised when they are loaded,so the contour level is in 'sigmas'-i.e.number of standard deviations above the mean value.
isomesh mesh,map,2
If we now load in the coordinate file which is deposited in the PDB,we can see how well it fits the density map(figure8):
load data/pdb1lza.ent,protein
hide lines
show sticks,protein
Figure8:Coordinates for lysozyme(PDB ID1lza),shown with the electron density map contoured at2σ
2.2.6.Settings
Much of PyMOL's functionality is controlled by parameters which can be adjusted.For example, the size of spacefilling spheres generated by the'show spheres'command is controlled by the parameter sphere_scale.This can be altered globally,for example
set sphere_scale,0.5
or just for one object,e.g.
set sphere_scale,0.5,protein_A
The list of parameters is huge,and is only partly documented on the PyMOL website.In order to see all available parameters,and change them quickly,the GUI interface can be used-from the menus on the external window,select Setting->Edit All...(figure9).
Figure9:The settings window
A list of the most useful settings is shown in table2.
Setting Controls Type
antialias Whether antialiasing is used during ray-tracing boolean(0or1) fog Extent of depth-cued fog float(0-1)
normalize_ccp4_maps Whether to normalise density maps on loading boolean(0or1) sphere_scale Size of spacefilling spheres float(0-1)
sphere_transparency Transparency of spacefilling spheres float(0-1)
transparency Transparency of surfaces float(0-1)
Table2:Common PyMOL settings
2.2.7.Ray tracing and images
One of PyMOL's most useful features is its built-in ray-tracing engine.At any point during use,simply typing
ray
ray-traces the current scene.In order to save the image as a PNG file,simply type
png filename
Figure10shows the results before and after ray-tracing a protein surface.
The use of the antialias setting greatly affects the quality of ray-tracing results-but also the time taken to perform the computation.Another parameter worth experimenting with is
Figure 10:Ray tracing
ray_trace_fog -while depth-cued fog can look nice in the raw image,it is sometimes a bit overpowering after ray-tracing.
2.2.8.Online help
Help can be obtained while using the program simply by using the help command in conjunction with the name of the function on which you need help.For example,help show generates the screen showed in figure 11.
Figure 11:Displayed help on the show command.
2.3.Sessions,scripts and views
Since PyMOL supports a scripting language,commands can be provided in a plain text file. In order to run a script file,either do
pymol script_file
from the Unix command line,or from within an existing PyMOL session,
@script_file
A convenient way to save the current state of PyMOL is to use the session-save facility, accessed from File->Save Session As....
Finally,a useful feature when writing scripts is the get_view command.This produces a transformation matrix command,something like
set_view(
0.555408657,-0.818981469,0.144189119,
-0.194582075,0.040585112,0.980046809,
-0.808491051,-0.572383344,-0.136819690,
0.054594167,-0.675678492,-155.758148193,
-0.424402237,20.526487350,19.107995987,
109.416473389,209.416519165,0.000000000)
which can be pasted into a script in order to restore the current orientation at a later date.
3.Advanced techniques
3.1.PyMOL as a Python interpreter
While the PyMOL scripting language is powerful and simple to use,some tasks require features which it cannot provide-the ability to use loops and subroutines,for example.In such cases,it is usually better to communicate with PyMOL through its Python API directly. This is not as daunting as it sounds-once you get the hang of the scripting language, translating to Python is fairly straightforward.For example,consider the following two snippets. The first is in the PyMOL scripting language.
load data/pdb1atp.ent
color red,chain E
show sticks,chain I
And here it is in Python:
from pymol import*
cmd.load("data/pdb1atp.ent")
cmd.color("red","chain E")
cmd.show("sticks","chain I")
For an example of a PyMOL script written in Python,see06_b_movie.py.
3.2.Extending PyMOL using the Python API
Adding extra functionality to PyMOL using the Python API is very simple.All you have to do is define a Python subroutine,then register it with PyMOL as a command which can be executed from the viewer.An toy example should help to illustrate this.Say you want a shorthand way of loading in molecular structures from a local archive,and displaying them in cartoon form.If the files are all located at paths of the form
/data/pdb/pdb1xyz.ent
where1xyz is the identifier of the molecule,then you can write the following short Python script:
def load_pdb(pdb_id):
filename="/data/pdb/pdb"+pdb_id+".ent"
17
cmd.load(filename,pdb_id)
cmd.hide("everything",pdb_id)
cmd.show("cartoon",pdb_id)
cmd.extend("pdb",load_pdb)
The PyMOL extend command registers the load_pdb subroutine as a PyMOL comand with the name'pdb'.After running this script in PyMOL,you can type
pdb1atp
to load a particular PDB file and render it in cartoon form.By running a set of such extension scripts when PyMOL starts up,you can have all your extra commands available at all times. This can be done by adding commands to a.pymolrc file located in your home directory (Unix only),of the form
run script_name
where script_name is the file which contains the Python code for your extension.Many useful extensions have already been written,mostly to run external programs,parse the output,and display the results in PyMOL;see the links in the appendix for details.
3.3.Movie making
PyMOL can be used to generate movies,using a few simple commands.The output of movie generation in PyMOL is a series of frames,written out in the PNG image format.In order to generate a movie from them,an external program is required to encode the series of frames into an appropriate format(e.g.MPEG or AVI).Encoding approaches are platform-dependent and will not be discussed here.I only have experience of MPEG encoding under Linux;there is more information on this in the movie/subdirectory in the downloadable tutorial archive( / gareth/work/pymol).
Generating the frames themselves is fairly straightforward.Ready-made functions are provided for generating common sequences,such as rotation about one of the principle axes.There are three steps required to make a movie in PyMOL:
3.3.1.Reserve space for the frames
After loading in the molecule,execute the following command to reserve space for N frames: mset1xN
3.3.2.Generate each frame in the sequence
In order to generate a full360-degree rotation around the y-axis,over N frames,execute util.mroll(1,N,1)
Alternatively,this step may be something more involved,such as reading in the results of a molecular dynamics trajectory or a docking simulation.Or,in order to create something more complex than a simple rotation,some Python code could be used here.
3.3.3.View the results
In order to play the movie in PyMOL,either click on the play button in the VCR-like controls in the main window,or use the mplay command.To output the movie frames as a series of PNG images,type
mpng filename_root
This will generate a series of files called filename_root0001.png,filename_root0002.png,etc. Examples of how to make movies in PyMOL are shown in the example scripts 06_a_movie.pml and06_b_movie.py.
piled Graphics Objects(CGOs)
PyMOL's CGO framework allows the user to generate arbitrary3D objects,in much the same way the OpenGL primitives are created.The objects available are lines,triangles,spheres and cylinders.The following example shows a Python snippet used to generate a regular grid mesh(figure1):
from pymol.cgo import*
from pymol import cmd
#Spacing and number of gridpoints
spc=2
n=10
#Build up a CGO object
obj=[BEGIN,LINES]
for i in range(0,n+1):
obj.extend([
VERTEX,(i*spc),0,0,
VERTEX,(i*spc),0+(n*spc),0,
VERTEX,0,(i*spc),0,
VERTEX,(n*spc),(i*spc),0,
])
obj.extend([END])
#Load the CGO object into PyMOL
cmd.load_cgo(obj,"grid")
Figure1:A simple CGO script
Many examples of using CGOs are provided in the examples directory which comes with PyMOL.
1.Example scripts
This appendix contains a series of PyMOL scripts which demonstrate some of the program's features.For each script,a screenshot of the result is shown.Each script,along with its associated data files,is included in the downloadable version of this tutorial.Each script should be run from within the scripts subdirectory.
1.1.01_loading.pml
#PyMOL script to demonstrate loading in data from different file formats
#Load in data from a PDB file
#Notice that file format is automatically recognised
#The object gets given a name derived from the filename-in this case,it
#is called pdb1atp
load../data/pdb1atp.ent
color white,pdb1atp
#Pick out the ligand and highlight it
color red,(r;ATP)
show sticks,(r;ATP)
1.2.02_representations.pml
#A PyMOL script to demonstrate some of the available representations
#First we load in a molecule from a PDB file(deoxy-haemoglobin)
load../data/pdb1gbv.ent
#There are four chains in the molecule-A,B,C,D.The following shows how
#to render each one using a different representation
#First we hide everything which is currently visible
21
Figure1:Result of running01_loading.pml Protein kinase(PDB ID1atp).
hide everything
#Colour everything in standard colours(C->white,O->red etc)
util.cbaw
#Render a solid surface over chain A
#Here we use the'algebraic'selection syntax-(c;A)means chain A.More of #this later
select chain_A,(c;a)
show surface,chain_A
color marine,chain_A
#Render chain A using cartoons
select chain_B,(c;B)
show cartoon,chain_B
color lime,chain_B
#Render chain C using sticks
#This demonstrates the other type of selection syntax-the heirarchical type, #whereby slashes separate each level of the selection heirarchy(object,
#model,chain,residue,atom)-more of this later
show sticks,///C
#Render chain D using ribbons
show ribbon,(c;D)
color yellow,(c;D)
#Now we can render the haemoglobin molecules differently,in order to pick #them out from the protein.There are four haemoglobin molecules in the
#file-
#chain A,residue142
#chain B,residue147
#chain C,residue143
#chain D,residue147
select hem1,///A/142
show sticks,hem1
show spheres,hem1
set sphere_scale,0.4,hem1
color yellow,hem1
#This time the algebraic selection syntax is used.Note that terms can be #combined with logical operators(&,|,and,or)
select hem2,(c;b&i;147)
show sticks,hem2
select hem3,(r;hem and c;c)
show dots,hem3
color white,hem3
select hem4,///D/147
show lines,hem4
color green,hem4
#Clean up the display
disable hem4
1.3.03_a_selections.pml
#A PyMOL script to demonstrate the selection syntax
#This script just demonstrates using proximity selection to pick out and #highlight a ligand binding site
#Load in a PDB file(DHFR)
load../data/pdb3dfr.ent
Figure2:Result of running02_representations.pml
Haemoglobin(PDB ID1gbv).Each chain is shown using a different rendering method
#Render the protein in simple wireframe
hide everything,all
select protein,(!hetatm)
show lines,protein
color white,protein
#Pick out the methotrexate inhibitor
#Note that here we use the'create'command rather than'select'.The reason #for this is that this creates a separate object,rather than a selection on #an existing object.PyMOL treats these two entities somewhat differently-#for example,the size of rendered spheres can be set separately for each
#object(as we will do below),but not for selections within a single object create inhib,(r;mtx)
show spheres,inhib
color red,inhib
#Pick out the inhibitor binding site
#The first part of the selection simply selects everything within4A of any #atom in the inhibitor.This selection thus includes the inhibitor itself, #plus any water molecules which happen to be nearby.So it is ANDed with the #protein selection to pick out just protein atoms
select inhib_bs,(inhib expand4&protein)
show sticks,inhib_bs
show spheres,inhib_bs
color lime,inhib_bs
set sphere_scale,0.2,inhib_bs
#PyMOL will have auto-zoomed onto the newly created objects-so here we
#re-orient the view on the whole protein to admire our handiwork...
orient protein
#Clean up the view a bit
disable inhib_bs
Figure3:Result of running03_a_selections.pml
Active site of DHFR(PDB ID3dfr).The inhibitor is shown in red spacefill,with contacting atoms picked out in green.
1.4.03_b_selections.pml
#A PyMOL script to demonstrate the selection syntax
#This script demonstrates using proximity selection to pick out and
#highlight a ligand binding site,this time rendering it as a solid surface
#Load in a PDB file(DHFR)
load../data/pdb3dfr.ent
#Render the protein in simple wireframe
hide everything,all
select protein,(!hetatm)
show lines,protein
color white,protein
#Pick out the NADP cofactor
create cofactor,(r;ndp)
show sticks,cofactor
color yellow,cofactor
#Pick out the cofactor binding site
#This time,we render it as a solid surface
select cofactor_bs,(cofactor expand4&protein)
show surface,cofactor_bs
color blue,cofactor_bs
#PyMOL will have auto-zoomed onto the newly created objects-so here we
#re-orient the view on the whole protein to admire our handiwork...
orient protein
#Clean up the view a bit
disable cofactor_bs
Figure4:Result of running03_b_selections.pml
Cofactor binding site of DHFR(PDB ID3dfr).The cofactor is rendered in yellow sticks,and a solid surface has been generated over the part of the protein which contacts the NADP molecule.
1.5.04_hbonds.pml
#A PyMOL script to demonstrate rendering hydrogen bonds using dashed lines
#Load in a molecule(HIV protease complexed with a tripeptide inhibitor)
load../data/pdb1a30.ent
#Hide everything
hide everything
#Show cartoons for the protein,colouring the two chains differently
show cartoon
color lime,chain A
color pink,chain B
#Select the inhibitor
select inhib,chain C
show sticks,inhib
color red,inhib
#Select the binding site
#The'byres'keyword expands the proximity selection to consist of whole #residues
select bs,(byres inhib expand4&!inhib)
show lines,bs
#Render water molecules which are in the binding site
show nb_spheres,bs
#Add some dashed lines to represent the hydrogen bonds
distance hb1,///C/508/N,///A/27/O
distance hb2,///A/29/N,///C/506/O
distance hb3,///C/506/N,///A/29/OD2
distance hb4,///C/507/N,///A/48/O
#The following h-bond is to a water molecule
distance hb5,///C/506/N,////1076/O
#These commands clear the distance labels from the h-bonds
hide labels
#Label the residues in the binding site
#The first argument specifies which atoms are to be labelled-here,we
#specify only C-alpha atoms,so that each residue gets just one label.
#The second argument specifies the format of the label,in a pseudo-printf #format
label(bs&n;ca),"%s-%s-%s"%(chain,resn,resi)
Figure5:Result of running04_hbonds.pml
Active site of HIV protease(PDB ID1a30).The inhibitor is shown in red,with protein residues which contact it picked out as wireframes.Each contacting residue is labelled with its identity,and hydrogen bonds between the inhibitor and the protein(or solvent)are shown as dashed lines.
1.6.05_maps.pml
#PyMOL script demonstrating some of the density map functionality
#Load in a PDB file(lysozyme)
load../data/pdb1lza.ent,coords
#Set normal CPK colours and render as sticks so we can see the coordinates
#through the mesh
util.cbaw
show sticks,coords
#Load in the electron density map(CCP4format)
#This was obtained from the Uppsala Electron Density server
#http://fsrv1.bmc.uu.se/eds/
#First we make sure that map normalisation is turned on-this means that we
#can contour at sigma levels(rather than absolute values)
set normalize_ccp4_maps,1
load../data/p4,map
#Contour the map at2.0sigma across the whole cell
isomesh mesh,map,2.0
color green,mesh
#Select one residue-ASP87
select res,////87
#Create an isosurface at1.0sigma,just in the vicinity of this residue
#(only in a region with2angstrom of the selected residue)
isosurface surf,map,1,res,carve=2
#Make the isosurface semitransparent
set transparency,0.5
#Zoom out a bit so we can see it better
move z,-20
Figure6:Result of running05_maps.pml
A lysozyme molecule(PD
B ID1lza)is displayed,along with the electron density map which was used to determine the structure.
1.7.06_a_movie.pml
#PyMOL script to demonstrate generation of a movie
#Load in our molecule(lysozyme)
load../data/pdb1lza.ent
#Get the representation we want
util.cbaw
hide everything
show surface
#Reserve space for120frames
mset1x120
#Make sure that ray-tracing is turned off for movie generation-otherwise,
#this would take a LONG time
set ray_trace_frames,0
#Use a built in utility function to generate a full360-degree rotation
#round the y-axis,over120frames
util.mroll(1,120,1)
#Play the movie
mplay
Figure7:One of the frames generated while running06_a_movie.pml
1.8.06_b_movie.py
Note that this script has been written in Python,rather than in the simplified PyMOL script-ing language.Once familiar with the program,this can be used to achieve more complex tasks.
#PyMOL script to demonstrate generation of frames for a movie
#
#This time,frame ray-tracing is turned on,and at the end,the script writes。