Handouts and resources for the PyMOL tutorial

PyMOL Tutorial 2018

Understand .pdb files and make molecular graphics 💻

Handouts and resources for the PyMOL tutorial

PyMOL Tutorial 2018

Understand .pdb files and make molecular graphics 💻


I have instructed PyMOL tutorials numerous times for first year graduate students (and even occasional faculty members!). Course materials can be found in the downloads. An outline of the course contents is also provided.

Tutorial Downloads

Workshop Notes

What PyMOL does and does not do:

  • PyMOL is a molecular graphics program that is primarily designed for producing publication-quality illustrations and animations.
  • In its purest form, PyMOL is NOT used for molecular modeling, structure manipulation, or in silico experiments.
  • PyMOL is user-sponsored but runs on an open source platform.

About the PDB file format

  • The main file format you will use with PyMOL has the extension .pdb (Protein Data Bank).
  • PDB files are plain text documents and have a straightforward and consistent structure. The spacing of entries is critical to the file being read properly.
Line IdentifierDescription
TitleName of the entry
RemarksDescriptors for everything used in the project. This includes biological, chemical, physical, crystallographic, refinement, and processing parameters.
CRYS1 cardUnit cell dimensions for the crystal
Origin and Scale CardsSets the coordinate system
ATOM entriesCoordinates (see below)
ANISOU entriesOptional anisotropic temperature factor line
Terminators (TER, END)Indicates the end of chains or the end of the file
  • The bare minimum .pdb file has a CRYS1 card and atom entries.
  • Each ATOM entry has several parameters (in order):
    • atom card
    • atom number
    • atom identity
    • amino acid identity
    • chain identity
    • amino acid number
    • x, y, z, coordinates
    • occupancy (0.00-1.00)
    • temperature factor (B-factor)
    • atomic element

The PyMOL Interface

  1. Both GUI and command line driven
  2. Has two GUIs (External and Internal):
    • The external GUI is used for rendering images, creating animations, and controlling many of PyMOL’s settings.
    • The internal GUI is used for controlling exactly what objects and elements are displayed, how they are colored, and how they are positioned.
    • Think of PyMOL as a photo shoot. The internal GUI controls what your model is wearing and how the subject is positioned. The external GUI controls the settings on your camera.

PyMOL screenshot

Opening Files

  • Option 1: Go to www.pdb.org and find the PDB file you would like. Download the coordinates. Then use File >> Open to browse and open the file.
  • Option 2: Use the command line. Simply type fetch followed by the PDB code.
fetch 3SU3

Internal GUI Controls:

  1. Change molecular orientation (mouse controls)
    Mouse ButtonLeftMiddleRightWheel
    ClickPick AtomCenterMenu
    Note: These are also indicated in the lower-right corner of the internal GUI window.
  2. Changing the appearance of molecules or selections - There are 5 main buttons next to each element:
    SShow (display the selection in a certain way, i.e. 'cartoon', 'surface', etc.)
    HHide (hide certain selection features that are currently displayed)
  3. Selecting molecules, chains, atoms, or regions can be accomplished either through the command line or by pointing and clicking. Here are the three most useful ways I like:
    1. Click on the residue of interest. You will see that a (sele) object has been created in the internal GUI. You can rename this object and PyMOL will remember the selection in the future. The selection can be edited later as well.
    2. Use the external GUI can click Display >> Sequence On. This will show you the amino acid sequence of the structure. You can select residues by clicking on them.
    3. Use the select command line command. This command is very powerful, but may take some time to get the hang of.
#This will select chain A and name it “mychain”
select mychain, chain A
#This will select all c, o, n, and alpha-carbon atoms and name the selection “certainatoms”
select certainatoms, name c+o+n+ca	
#This will select everything that is both in a selection named “file1” and annotated as chain B. Note that there is no comma in this command.
select file1 and chain B
#This will select everything that is both in a selection named “file1” and annotated as chain B and then name the selection “file1chainB”
select file1chainB, file1 and chain B
  1. Distances and angles can be measured using the measurement wizard. The wizard can be found under Wizard >> Measurement.
    1. To measure distances, you will simply need to click each atom. After clicking the second atom, a dashed line and distance (in Angstroms) will appear.
    2. To measure angles, you will need to first change the measurement mode from Distances to Angles in the lower right corner of the internal GUI. Then click on three atoms. The angle will be displayed.
  2. Other useful display features:
    1. Electrostatics can be generated using the Action button for an object. Simply click Action >> generate >> vacuum electrostatics. Note that these are rather quick-and-dirty (i.e. not publishable) but can give a nice approximation of the electrostatic surface. For a publishable electrostatic surface, plug-ins are required such as APBS.
    2. Symmetry-related molecules can also be generated using the Action button. This is particularly useful if a molecule adopts a symmetric structure that is coincident with a crystallographic axis. Click Action >> generate >> symmetry mates and select a distance (5 Å is usually good enough). You can then hide the molecules that you are not interested in (or delete them altogether)
  3. Alignment
    1. One of the most useful features that PyMOL boasts is a native three-dimensional alignment algorithm.
    2. Alignment of two objects can be performed simply using the align -or- super command line commands.
    3. Note that alignments can be performed between entire structure depositions, specific chains, or even selected residues. Define your selection (described above), name them, and use the align command to superpose one molecule onto the other.
#This command attempts to move the entire PDB coordinates of PDB1 onto PDB2. This would work well for two homologous structures with one copy in the asymmetric unit
align PDB1, PDB2
#Alternatively, the super command can be used.  The results may be slightly different.
super PDB1, PDB2
#This command moves the molecule that selection1 “belongs” to onto the molecule that selection2 “belongs” to using only selection1 and selection2 to calculate the alignment. This is useful (for example) if you have two distantly-related proteins with conserved active sites.  You could select the active site residues of each, name them, and then align the molecules based only on the important residues.align PDB1, PDB2
align my_selection1, my_selection2		

External GUI Controls:

  1. Changing the background, general appearance, and rendering options can be accomplished using the eternal GUI Setting menu. These are pretty straightforward.
  2. Ray tracing will provide you with high resolution images. There are two options to initiate a ray trace: you can use the external GUI or the command line.
    1. If using the external GUI, click the Ray button at the top right corner of the GUI.
    2. The command line can also be used. The command line affords more flexibility in outputting an image of defined size.
#Ray traces the current view at 2400 x 3600 pixels
ray 2400,3600
  1. Saving images can be accomplished at any time by using the selecting File >> Save Image As in the external GUI. Alternatively, the command line can be used as below.
#Save the current view as MyImage.png
png MyImage.png
  1. Saving your PyMOL session can also be accomplished at any time by selecting File >> Save Session As. This is very useful as it will allow you to edit your work in the future.

Other things to note:

  • PyMOL has a very powerful scripting language. Everything that can be done with the GUI can be done by the command line (and more!). Scripting allows you to either save your commands as you execute them or just write code from scratch. This is invaluable when the same actions need to be performed repetitively or when something very minor changes in your coordinate.
  • There are many other graphics programs, but PyMOL seems to be the most popular. Other programs that you may hear about include RasMOL, Raster3D, MolScript, Chimera, etc. With cryoEM data becoming more and more prevalent, Chimera is especially becoming a more popular tool in the field.

http://www.rcsb.org - For downloading publicly-available coordinate files
http://pymolwiki.org - A great resource on how to use PyMOL
http://www.pymol.org - The PyMOL homepage

Jonathan Ipsaro
Senior Scientist, Structural Biology

Biochemist with a penchant for integrated structural, biophysical, and computational methods.