PyMOL scripts
Queen's University Protein Function Discovery
and Department of Biomedical and Molecular Sciences
Molecular Modelling and Crystallographic Computing Facility
Crystallography and Modelling:
Other:

My PyMOL Script repository

Some PyMOL tutorials:
Links to other PyMOL scripts can be found at the PyMOL Wiki.

Included below are some PyMOL tools to create the drawing commands to show the symmetry axes for a crystal, to draw a fancier unit cell and an attempt at drawing reciprocal space in 3D.

All of these scripts require loading into PyMOL before use. You do this with the run command:
run scriptname.py
Then you can use the command according to the instructions provided.

Some of these require cctbx the Computational Crystallography Toolbox (marked with cctbx) and NumPy (Numerical Python) (numpy) and some require PyMOL version 0.8 (or higher) due to the use of the pymol.vfont module (PyMOL +v0.80). The following have only really been tested on the SVN versions of PyMOL.

Other scripts are available in my scripts page.

These programs are "free", to use share and edit, but are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. (http://creativecommons.org/licenses/by-nc-sa/4.0/) Please let me know if you find bugs or have questions about the use of them.
Name Description Dependencies Click on thumbnail to see larger image
General
pymolrc pymolrc file for use with PyMOL on MS Windows. Copy to directory pymol is installed in (normally c:\Program Files\DeLano Scientific\PyMOL\ Edit it to your preferences (particularly the run scriptname lines at the end. PyMOL +v0.97  
grepset.py grepset greps through the list of settings using a python regular expression as defined in the 're' module. It returns a list of settings/values matching the regexp. No regexp returns every setting. PyMOL +v0.97  
align_all.py Aligns all displayed models to one target using one of the "align", "super" or "cealign" commands. Options include the method to use, the target and mobile selections to be used for the alignment, creation of CGO align objects for each pair of structures (align and super only), the alignment method (align, super, cealign) and a debugging option that prints more information.  
align_allfiles.py Aligns all models read from a set of files to one target already loaded into PyMOL using the "align" command. Options include the target and mobile selections to be used for the alignment, creation of CGO align objects for each pair of structures, the alignment method (align, super, cealign) and a debugging option that prints more information.  
super_all.py Superimposes all displayed models to one target using the "super" command. Options include the target and mobile selections to be used for the superposition, creation of CGO super objects for each pair of structures and a debugging option that prints more information. This has been superceded by the new version of align_all.py, which now allows specifying "super" (or "align" or "cealign") as the method of alignment.  
align_all_to_all.py Aligns all models in a list to all other models in the list. Options include the list of models to use, a selection to use in the alignment (defaults to all C-alpha atoms), printing of the full matrix of RMSD values instead of the default upper half-matrix, the alignment method (align, super, cealign) and a debugging option that prints more information.  
align_allfiles_to_allfiles.py Aligns all models to all other models read from a set of files. Options include the list of models to use, a selection to use in the alignment (defaults to all C-alpha atoms), printing of the full matrix of RMSD values instead of the default upper half-matrix, the alignment method (align, super, cealign) and a debugging option that prints more information.  
axes_cyl.py Draw X, Y, and Z reference axes as CGO cylinders, colored red, green and blue, respectively PyMOL +v0.80  
showaxes.py plugin version of axes_cyl.py. Install with the install plugins option. PyMOL +v0.80  
color_b.py Color a selection by b-factor or occupancy (q). Options include a choice of colour gradients, 'bgr','rgb','bwr','rwb','bmr','rmb', 'gw','wg','gy','yg','gray', 'reversegray', 'user' modes ramp, (equal numbers of atoms in each color) or histogram (equal spaced color boundaries), saturation, value and nbins (the number of colors to use) and selection. User-defined gradients can also be specified by three triplets of rgb values -- see the top of the python script for more details. Or, after doing run color_b.py from within PyMOL type help(color_b) or help(color_q).  
color_by_attype.py Color by atomtype.
color_by_attype <selection>, <optional colors> 
e.g. color_by_attype model & c. a, polar_n=cyan, sulfur=green

Atom types:      Default colours:
hydrophobic      white
polar_n          marine
polar_o          salmon
positive         blue
negative         red
sulfur           yellow
  
color_by_restype.py Color by residue type.
color_by_restype <selection>, <optional colors> 
e.g. color_by_restype model, hydrophobic=wheat, polar=marine
                              
Residue groups:          Default colours
hydrophobic: AILMV     white
semipolar: C             yellow
polar: HNQST             cyan
positive: KR             blue
negative: DE             red
aromatic: FWY            magenta
proline: P               palegreen
glycine: G               green
  
data2bfactor.py Extract data produced by other programs and alter the B-factor or occupancy of a molecule within PyMOL. Usually, this would be for the purposes of colouring the object with the color_b or color_q functions (see color_b.py above). This can be done per atom or per residue for B-factor or occupancy with the four functions data2b_atom, data2b_res, data2q_atom and data2b_res, respectively. The data files are expected to have data in the format: 
  CHAIN   <RESI> <RESN> [name] <data>
where 'name' is required for the data2b_atom function and must be absent for the data2b_res function. RESI is the residue number and RESN is the residue name (as in PyMOL selection commands. CHAIN is optional.

Example atom data lines (columns must be separated by whitespace -- at least one space and/or tab character): 

      A ALA 1 N 3.5
      A ALA 1 CA 3.0
      A ALA 1 CB 3.14159
      A ALA 1 C  6.23
      A ALA 1 O    5.1
      A GLY 2 N 10.3
      A GLY 2 CA 1.714
      A GLY 2 C -0.05
      A GLY 2 O -3.12
Simply "run" the script and then issue the command data2b_atom 'mol','datafile' where 'mol' is the molecule in question and 'datafile' contains the data to be applied. Similarly for data2b_res 'mol','datafile' , data2q_atom 'mol','datafile' and data2q_res 'mol','datafile'

Alternatively, the data file may have the format: 

 ID  <data>
where 'ID' is the index of the atom to which 'data' will be applied.

This script has been extensively rewritten and improved by Thomas Holder as noted in the copyright notice. Suguru Asai has provided the update to allow reading the "ID data" formatted data file.

   
draw_cell.py Draw unitcell border with labels (and with fancy coloring!) within PyMOL. Now you can have a unitcell frame without reading in a PDB file. draw_cell.py also includes labels for the Origin and the ends of the A, B and C axes. PyMOL +v0.80
cctbx
numpy		  
draw_axes.py Draw X, Y, and Z reference axes as CGO cylinders, colored red, green and blue, respectively. The radius and length are options and default to 0.2A and 10A respectively.  
draw_cylinder_cgo.py Draw an arbitrary cylinder between two atoms. Options are the name for the CGO object, the two atoms, the radius and the colour. The two atoms, default to "(pk1)" and "(pk2)", the radius defaults to 0.1A and the colour defaults to white ("(1,1,1)"). For example: 
      draw_cylinder my_cylinder, radius=0.2, color=(0,1,1)
would draw a 0.2A radius cyan tube between the first two picked atoms. The color can also be specified by a color name (blue, red, salmon, etc.).

This function is deprecated as the the "draw_links.py" function is more comprehensive and useful.

draw_links.py Draw arbitrary CGO cylinders between pairs of atoms. This can be useful for showing domain motions, for example. If you specify a selection that includes more than one residue, it will draw links only between the C-alpha atoms of the corresponding selections. Options are the name for the CGO object, the two atoms or pairs of atoms, the radius and the colour. The two atoms, default to "(pk1)" and "(pk2)", the radius defaults to 0.1A and the colour defaults to red ("(1,0,0)"). For example: 
      draw_links 1kfu & c. l & i. 105+262+286+288, 1kxr & c. a &  i. 115+272+296+298,color=red,color2=green
would draw a 0.2A radius tube (whose colour fades from red to green) between the atoms in the first list to those in the second.
draw_plane_cgo.py Draw an arbitrary plane through 4 atoms. No least-squares fitting is performed and in fact it draws three triangles through the 4 atoms to create the plane. So if the atoms are not actually in a plane, you will see the separate triangles. Options are the name of the CGO object that is created and the colour (defaults to white and is specified as a RGB tuple, e.g. color=(1.0,.5,1.0). The 4 atoms can be specified by clicking on 4 atoms to create the "(pk1)", "(pk2)", "(pk3)", and "(pk4)" selections or by specifying the atom selections manually. For example, after picking 4 atoms, you can type: 
    draw_plane test, color=(1,0.5,0.5)
to create a light red plane passing through the 4 atoms.
draw_sphere_cgo.py Draw an arbitrary sphere centered at one atom. Options are the name for the CGO object, the radius and the colour. For example: 
    draw_sphere my_sphere, color=(0.,1,0)
vector_angle.py Calculate the angle (and distance) between two vectors specified by 4 atom selections. For example, if you pick four atoms to create the selections pk1, pk2, pk3, and pk4: 
    get_vector_angle pk1, pk2, pk3, pk4
will generate information like this: 
    Calculating angle and distance between the vectors from:
      1dvi_COM P PSD 1 PS1 to  1dvi A GLU 98 CA
    and
      1dvi_COM P PSD 1 PS1 to  1dvi A SER 270 CA
         
    Angle between    [-33.465 11.907 4.837] and [-1.936 4.874 -4.073]   is 64.33 degrees
    Distance between [-33.465 11.907 4.837] and [-1.936 4.874 -4.073]   is 0.00
helix_angle.py Calculate the angle (and distance) between two helices as specified by two selections. For example, if you want to calculate the angle between helices for residues 2-15 and 45-56 
    helix_angle 1a6m & i. 4-19, 1a6m & i. 21-35, object_name=ax, radius=.5, color=blue
will generate output like this: 
    Looking for residues in 1a6m & i. 4-19 and 1a6m & i. 21-35.
    Found 48 and 45 atoms in the two helices, respectively.
     
    Start 1 = (   0.0415,   10.6550,   21.8369) Vector 1 = (  22.7416,    7.5585,   -1.4060)
    Start 2 = (  24.6156,   21.2244,   16.6789) Vector 2 = (  -3.9801,   -5.6498,  -20.8122)
      
    Angle between helix axes: 101.39 degrees 
    Distance between helix axes:   2.92 A
and it will draw a blue, 0.5 Å-radius cylindrical CGO object called "ax".
rmsd_b.py Calculate the RMSD (root mean square deviation) for a pair of selections and copy the individual RMS deviations onto the B-values of the first selection. Note that the selections must have the same number of atoms. One easy way to achieve that is to use the alignment object in the selection. Note that only those atoms in the selections will have their B-values changed, so you may wish to alter them all to 0 first. For example, after aligning 1xnd on 1xnb (and creating the alignment object called aln_1xnd_to_1xnb) type: 
      alter 1xnb, b=0
      rmsd_b 1xnb & aln_1xnd_to_1xnb, 1xnd & aln_1xnd_to_1xnb
      color_b 1xnb & ! aln_1xnd_to_1xnb
rmsf_states.py Calculate the RMSF (root mean square fluctuation) for a set of structures in a multi-state object and modify the B-factors to contain the RMSF value. For example if you run modeller to generate 100 models and you want to depict the variation in backbone structure by colour, this script will calculate, for each residue, the root mean square deviation over all models (relative to the model in one of the states -- the reference state). The default reference state is the first state. 
      rmsf_states model, byres=1, reference_state=1
This script uses the "alter" function on the whole selection and is very fast. Unfortunately it does not work if you combine the "byres=1" option with a selection, because it will only modify the B-factors of the selection specified even with byres=1 specified.
fitting.py Calculate the RMSD and fit one selection onto another within PyMOL without regard to matching residue names, etc. This script temporarily changes the selection2 to match selection1 so that the fit will work. 
      fitting object1, selection1, object2, selection2
      e.g. fitting 1xuu, c. a & (i. 296-309 or i. 335-340), 1ame, i. 8-21 or i. 47-52
After making the changes, it calculates the RMSD and then resets the residues as they were. The script also creates a new object showing the residues/atoms that were fit.
fitting_v1.py
Older version		 Calculate the RMSD and fit one selection onto another within PyMOL without regard to matching residue names, etc. This script temporarily changes the selections to be fit into glycines and sets the residue names and chain identifiers to match so that the fit command can be used on non-identical sequences. 
  fitting object1, selection1, object2, selection2
  e.g. fitting 1xuu, c. a & i. 296-309, 1ame, i. 8-21
After making the changes, it calculates the RMSD and then resets the residues as they were. The script also creates a new object showing the residues/atoms that were fit.
make_pov.py Create an input file for povray, based on the current view. See top of script for usage hints. povray  
msms_cgo.py Display surfaces calculated with Michel Sanner's MSMS program. "Run" the script and then issue the command: msms_cgo <file_name>, where the file_name is the root of the name of the face and vert files. Options include specifying the name of the new object, and the colour of the surface. MSMS (MSMS home page)
msms_pymol.py Calculate surface areas with Michel Sanner's MSMS program. "Run" the script and then issue the command: calc_msms_area <object_name>. Options include specifying the selection within the object, the probe size, the surface point density, as well as options to keep the surface area file (keep=1) and to print the full MSMS output (debug=1). You can also draw the surface that you have calculated by specifying draw=1 (show the surface for calculated for the selection) or draw=2 (show the complete surface for the object). You can specify colours using the inside_colour and outside_colour options. MSMS (MSMS home page) msms_selection_draw.py msms_residue_area.py
msms_residue_area.py Utility program to read the atom area file output by Michel Sanner's MSMS program. (when using the "-af" option to MSMS). This can be called by my msms_pymol.py script to save the residue area output to a file. MSMS (MSMS home page)
pdb_to_xyzrn.py Utility program to convert a PDB format file to a .xyzrn format file for use as input to Michel Sanner's MSMS program. This is not needed by my msms_pymol.py script, since the conversion is built-in there. MSMS (MSMS home page)
msms_selection_draw.py Display a surface calculated with Michel Sanner's MSMS program. This surface may be precalculated outside PyMOL with MSMSor as output by my msms_similarity.py and msms_complementarity.py scripts or using the msms_pymol.py script above. MSMS (MSMS home page)
msms_sim_draw.py Draw msms surface (as written by my msms_similarity.py or msms_complementarity.py scripts as a CGO object
msms_sim_draw(vert_name,face_name,obj_name='',gradient='white-red',outside_color='grey') 		MSMS (MSMS home page)
list_contacts.py Print a list of contacts between two selections within PyMOL. 
        list_contacts <selection1>, <selection2>, cutoff=4 (default)
You may want to exclude waters, e.g.: 
        list_contacts 1abc & c. a &! r. hoh, 1abc & c. b &! r. hoh, cutoff=3.2, contact_name=1abc_contacts
list_hb.py Print a list of all hydrogen bonds within a selection within PyMOL. 
        list_hb <selection>, cutoff=3.2 (default), angle=45 (default)
      
        list_hb 1tl9 & c. b expand 6., cutoff=3.2, angle=60
or between two selections: 
        list_hb 1tl9 & c. b, 1tl9 &! c. b
list_mc_hbonds.py Print a list of only main-chain hydrogen bonds within a selection within PyMOL. 
        list_mc_hb <selection>, cutoff=3.2 (default), angle=55 (default)
Normally you will want to exclude waters, e.g.: 
        list_mc_hb 1xnb &! r. hoh, cutoff=3.2
rms_current.py Calculate the RMSD (without fitting) of one selection onto another within PyMOL without regard to matching residue names, etc. This script temporarily changes the selection2 to match selection1 so that the rms_cur command can be used. 
  rms_current object1, selection1, object2, selection2
  e.g. rms_current 1xuu, c. a & (i. 296-309 or i. 335-340), 1ame, i. 8-21 or i. 47-52
After making the changes, it calculates the RMSD and then resets the residues as they were. The script also creates a new object showing the residues/atoms that were fit.
stride_ss.py Extract the secondary structure output from the program stride that is distributed with VMD and apply it to a molecule within PyMOL.
Simply "run" the script and then issue the command stride2pymol('mol') where 'mol' is the molecule in question or to select only part of the molecule do: stride2pymol('mol','sel'), where 'sel' defines the selection using the normal pymol selection commands (be sure to include the molecule in the selection!).
This script can also be run on its own to list the secondary structure as output by stride
./stride_ss.py <file.pdb> 		stride (from VMD)  
seq_select.py Create a named selection of a particular sequence in an object. The sequence can be a regular expression.    
Modelling
build_seq.py
 Build a sequence of specified secondary structure, e.g. 
build_seq QGAADLESLGQYF, ss=helix
or 
build_seq QGAADLESLGQYF, phi=-75, psi=-35
will create an object gln, unless a (pk1) selection exists, in which case it will build onto that atom.
build_seq_phi_psi.py
 Build a sequence of specified secondary structure, where the input is provided in a plain text file formatted with each amino acid on one-line (single-letter code) followed by its phi and psi angles, all separated by spaces. For example create a file called seq_phi_psi.txt that looks like: 
      Q 30. 50.
      G -57. 60.
      A 120. 30.
      A -50. 60.
      D -57. 60.
      L -119. 113.
      E -119. 113.
      ...
and run the command 
build_seq_phi_psi seq_phi_psi.txt
This will create an object named by the first residue in the specified sequence, unless a (pk1) selection exists, in which case it will build onto that atom. It needs seq_convert.py for sequence conversion operations. 		seq_convert.py (link to info)
seq_convert.py (download script)
distance_states.py Measure distance between two atoms in multi-state objects 
 e.g. distance_states ,,[same=0]
or 
 e.g. distance_states pk1,pk2
Where you have picked an atom in each of two objects, at least one of which has multiple states. The script will loop over the states in both objects and print out the distance between the two atoms. The two atoms could be within the same object, if you wish to measure a distance within that object as a function of states, then add the "same=1" option to the command line: 
 e.g. distance_states pk1,pk2,same=1
load_models.py Load multiple PDB files into a single PyMOL object as multiple frames 
  e.g. load_models prot_*.pdb, prot
will create an object prot with a frame for each structure loaded. You can set the discrete flag to 1 to load the models into discrete states -- i.e. B-factors and secondary structure information is stored separately for each state. The default is discrete=0 
  load_models prot_*.pdb, prot, discrete=1
load_best.py Load multiple modeller output files into a single PyMOL objects ordered by best to worst "OBJECTIVE FUNCTION" You can select how many objects to load, or a cutoff in the "OBJECTIVE FUNCTION" 
  e.g. load_best prot_*.pdb, prot, level=50000
or 
  e.g. load_best prot_*.pdb, prot, number=100
You can add discrete=1 to load the models into discrete states. It requires my stats.py script. 		stats.py (link to info)
stats.py (download script)
load_sep.py Load multiple PDB files into a multiple PyMOL objects 
  e.g. load_sep prot_*.pdb, prot
will create objects with names, prot1, prot2, prot3, etc.
load_files.py Load multiple PDB files into separate objects named as the files are 
  e.g. load_sep *.pdb
will create objects named like the original pdb files.
Symmetry axis representations
list_symm.py Simply lists the symmetry operators in both "x,y,z" and numerical matrix forms for a given space group cctbx
  
draw_symops_cctbx.py Draw symmetry axes within PyMOL using the cctbx tools called from all_axes_new.py (see below) to generate the unique set of symmetry axes. Options include the radius of the tubes for the axes as well as a flag to switch between drawing one object per individual axis (individual=1), or one object per class of axis (individual=0). The former can generate many more objects. PyMOL +v0.80
cctbx
numpy
all_axes_new.py		 Image of symmetry display
The following script is called by the draw_symops_cctbx.py script to obtain the symmetry axis information, but it can also be run alone to list the information interactively in a terminal window.
all_axes.py Generate symmetry axes using the cctbx (from Ralf W. Grosse-Kunstleve of the Computational Crystallography Initiative (CCI)) cctbx
numpy
  
all_axes_new.py Generate symmetry axes using the cctbx, but modified by me a little to shorten some of the axis representations. cctbx
numpy
  
For the above draw_symops_cctbx.py script, from within PyMOL do, for example: run draw_symops_cctbx.py and then do: draw_symops object_name to draw the symmetry axes for a previously loaded object (that has symmetry information in it). Or you can draw the axes for any space group as follows: draw_symops_param((30.,40.,50.,90.,99.,90),'p21',0.5) to draw the symmetry operators for the space group p21 (with a radius of 0.5 -- 0.2 is the default radius).
Reciprocal space viewers
ewald.py Draw the Ewald sphere at the beginning and end of a data collection pass, as well as the limiting sphere and the reflections divided into categories (within the limiting sphere, outside the limiting sphere, collected, not collected and lastly part of one asymmetric unit). PyMOL +v0.80
cctbx
numpy		  
ewald_laue.py Draw the reflections that would be collected in a Laue experiment. PyMOL +v0.80
cctbx
numpy