Launching PyMOL

File for startup commands

Linux:
Whenever PyMol starts, a '.pymolrc' file containing commands is run. All you need to do is create ".pymolrc" and place it in your home directory. Alternatively, you can instead create ".pymolrc.py" which contains actual Python code instead of just PyMOL commands.

Windows:
On Windows, use 'pymolrc', 'pymolrc.py' or 'pymolrc.pym'.

Launching PyMOL from an external program

If PYMOL_PATH, LD_LIBRARY_PATH, and TCL_LIBRARY are correctly defined, then you can launch PyMOL from an external Python program as shown in examples/devel/start_pymol.py.

NOTE: This approach is not recommended, since the PyMOL launching process is subject to change without warning. The recommended approach is to just use PyMOL as your python interpreter:

pymol -r <script.py>
pymol -qcr <script.py>

Running PyMOL in batch mode

To perform PyMOL commands from stdin (file, pipe) without opening an OpenGL window, try:

pymol -qc

Suppressing PyMOL output

Just type:

feedback disable,all,actions
feedback disable,all,results

cmd.feedback("disable","all","actions")
cmd.feedback("disable","all","results")

Launching Python programs

Running a Python script from PyMOL, usually the command:

run script.py

pymol example.py     # synchronous, in PyMOL module
pymol -r example.py  # synchronous in __main__ module
pymol -l example.py  # asychronous in a new module

run example.py        # synchronous in pymol module
run example.py,main   # synchronous in __main__ module

spawn example.py        # asychronous in a new module
spawn example.py,global # asychronous in the PyMOL module
spawn example.py,main   # asychronous in the __main__ module

Displaying biochemical Properties

Selecting secondary structures

Examples:

 select helix, (ss h)
 select sheet, (ss s)
 select loop, (ss l+'')

Color by atom type from a script

The "util" module contains a number of functions that color the atoms according to type, with different colors for the C atoms. For instance,

  util.cbay three

Displaying double bonds

You can try going into lines mode and turning on the valence display:

hide
show lines
set valence, 0.1

Calculating dihedral angles

The get_dihedral function requires four single-atom selections to work:

get_dihedral prot1///9/C, prot1///10/N, prot1///10/CA, prot1///10/C

Adding hydrogen bonds

Regarding H-bonds. There isn't a built-in function yet, but you can show H-bonds between two objects using atom selections so long as hydrogens are present in both molecules. If you don't have hydrogens, you can use h_add on the proteins or provide ligands with valence information and then use h_add.

Two examples are below. For clarity, they draw dashes between the heavy atoms and hide the hydrogens.

Assign color by B-factor

Polar surface area

For a solvent accessible PSA approximation:

set dot_density, 3
remove hydro
remove solvent
show dots
set dot_solvent, on
get_area elem N+O
get_area elem C+S
get_area all

set dot_density, 3
remove hydro
remove solvent
set dot_solvent, off
get_area elem N+O
get_area elem C+S
get_area all

Display solvent accessible surface

Using the surface display mode, PyMOL doesn't show the solvent accessible surface, rather it shows the solvent/protein contact surface. The solvent accessible surface area is usually defined as the surface traced out by the center of a water sphere, having a radius of about 1.4 angstroms, rolled over the protein atoms. The contact surface is the surface traced out by the vdw surfaces of the water atoms when in contact with the protein.

PyMOL can only show solvent accessible surfaces using the dot or sphere representations:

for dots:

show dots
set dot_mode,1
set dot_density,3

for spheres:

alter all,vdw=vdw+1.4
show spheres

Displaying the C-Alpha trace of proteins

hide
show ribbon
set ribbon_sampling,1

set ribbon_trace,1

Displaying the Phosphate backbone of nucleic acids

Should you ever want to show the phosphate trace of a nucleic acid molecule:

def p_trace(selection="(all)"):
    s = str(selection)
    cmd.hide('lines',"("+s+")")
    cmd.hide('spheres',"("+s+")")
    cmd.hide('sticks',"("+s+")")
    cmd.hide('ribbon',"("+s+")")
    cmd.show('cartoon',"("+s+")")
    cmd.set('cartoon_sampling',1,"("+s+")")
    cmd.set('cartoon_tube_radius',0.5,"("+s+")")
cmd.extend('p_trace',p_trace)

p_trace (selection)

Align proteins with CA fit

If the proteins have significant homology, then you can use the align command:

align prot1////ca,prot2

Coloring molecules

Coloring secondary structures

Examples:

 color red, ss h
 color yellow, ss s
 color green, ss l+''

  set cartoon_discrete_colors, 1

Color by atom type from a script

The "util" module contains a number of functions that color the atoms according to type, with different colors for the C atoms. For instance,

  util.cbay three

Use CMYK-safe Colors

Some RGB triplets do have equivalents in CMYK space, and as a result, a figure that looks great on a screen can come out with unpredictable colors when printed.

Most applications do a good job with RGB-to-CMYK conversions for photos, but do not do such a good job with graphics that use pure primary colors. For example, reds are generally OK, but pure blues and greens do not translate very well.

Assign color by B-factor

Creating a Color bar

Coloring insides and outsides of helices differently

Q: does anyone know how to color the inside of helices a different color than the outsides?
A:

set cartoon_highlight_color, red

Coloring all objects differently

List the color of atoms

To retrieve the color for a residue as identified in an expression, you can either iterate over a selection from the PyMOL command line

iterate all, print color

Rendering molecules

Displaying in ball-and-stick mode

Q: I've tried several settings and commands but cannot figure out how to make a simple ball-and-stick representation of a molecule. Can it be done in Pymol?

A: Yes, but it is non-obvious:

hide lines
show sticks
show spheres
set stick_radius=0.1
set sphere_scale=0.25

Adjusting width of cartoon

Try varying the following.

For strands:
cartoon_rect_length
cartoon_rect_width

For helices:
cartoon_oval_length
cartoon_oval_width

or for "fancy" helices:
cartoon_dumbell_length
cartoon_dumbell_width
cartoon_dumbell_radius  (radius of cylinder at edge of helix ribbon)

Calculating a partial surface

There is a, until now, undocumented way to calculate a surface for only a part of an object without creating a new one:

flag ignore, not A/49-63/, set
delete indicate
show surface

rebuild

Displaying surface inside a molecule

As far as I can tell, setting ambient to zero alone doesn't quite do the job, since some triangles still get lit by the light source.
The best combination I can find is:

set ambient=0
set direct=0.7
set reflect=0.0
set backface_cull=0

util.ray_shadows("heavy")
set two_sided_lighting=1
set backface_cull=0

Displaying all states of a multiple model/NMR structure

Just go to the movies menue and click 'show all states'.

Displaying dashed lines between two atoms

I think the following commands will do what you want:

	select a, ///A/501/02
	select b, ///B/229/N
	distance d, a, b

	hide labels, d

	set dash_gap, 0.5
	set dash_radius, 0.1

Adjusting size of selection indicators

Try:

	set selection_width, 6
	set selection_width, 7

Adjusting ray trace-image size

The pymol ray tracer can generate an image of any size.

ray height,width

ray 3000,2400
png filename.png

Ray tracing maps

For better quality maps with a white background.

set ray_trace_fog,0
set ray_shadows,0
set antialias,1
ray 1600,1200
png img.png

Nive PovRay settings

Making stereo pairs

Try:

ray angle=-3
png image1.png
ray angle=3
png image2.png

Meaning of the get_view output

Of the 18 numbers in the output array,
0-8 is the 3x3 rotation matrix,
9-11 is the camera location,
12-14 is the origin of rotation,
15-16 are the clipping distances,
and 17 is the orthoscopic flag.

Viewing direction vectors

Ray-traceable labels

CGO label orientation

You could use the cmd.rotate and cmd.translate to position the labels, but it is likely to be somewhat painful. If I'm not mistaken, the rotation will always be about and axis through the origin and so you may need to translate the label into the correct position.

Thus if you have your label in an object called 'text', you could do,

  cmd.rotate(axis='x',angle=20.,object='text')

  cmd.translate(vector='[1.,2.,3.]',object='text')

Modeling with PyMOL

Saving with transformed coordinates

Translate or rotate individual objects

There is a "translate" function similar to "rotate", the docs for these don't exist yet, because the implementation isn't finished. However, feel free to use them in the following forms:

translate vector,object-name,state
   (vector needs to be something like [x,y,z])

   translate [1,0,0],pept

rotate axis,angle,object-name,state
   (axis can be either the letter x,y,z or a 3D vector [x,y,z])

   rotate x,90,pept
   rotate [1,1,1],10,pept

Moving one segment relative to the rest

Split states to objects

There is also a new command in the 0.95 series:

   split_states object-name

Altering secondary structures:

Examples:

 alter A/10:34/, ss='H'
 alter A/35:40/, ss='L'
 alter A/41:60/, ss='S'

Altering van der Waals radii

Example:

alter (elem Fe),vdw=1.8
rebuild

Altering atom coordinates

Example:

alter_state 1,(pdb1cse),x=x-10.0

Deleting bonds

Select the bond using Ctrl-right-click, then either

unbond pk1,pk2

Converting D- to L- amino acids

The inversion function was changed in version 0.95 to take advantage of multiple picked atoms. To invert a center, Ctrl-middle-click to pick the center atom as pk1 and two stationary atoms as pk2 and pk3. Then type Ctrl-E to invert.

Adding disulfide bonds

You can use the "bond" command to attach them:

bond 24/sg,26/sg
bond 56/sg,99/sg

unpick

alter cys/,name='CYX'

alter 24+26+56+99/,name='CYX'

Adding hydrogen bonds

Regarding H-bonds. There isn't a built-in function yet, but you can show H-bonds between two objects using atom selections so long as hydrogens are present in both molecules. If you don't have hydrogens, you can use h_add on the proteins or provide ligands with valence information and then use h_add.

Two examples are below. For clarity, they draw dashes between the heavy atoms and hide the hydrogens.

Protonating ligands

If your ligands come in with valid valencies and formal charges, PyMOL's h_add command can protonate ligands. (NOTE that there is a minor technical hiccup with SD-files which are loaded by default as immutable "discrete" objects.) Suffice it to say that in order to make changes to the chemical structure, an object must be loaded with the "discrete" flag set to zero.
Unfortunately, much of the molecular editing stuff remains to be documented. Here's an example sequence, but I'm not sure it will help to much...as indicated in the manual, this is immature functionality with some major gaps. Attach in particular is very limited...

# show valences
set valence=0.05

# load cysteine fragment
fragment cys

# remove hydrogens
remove (hydro)

# edit gamma S
edit cys////sg

# add hydrogen
attach H,1,1

# add planer, trivalent nitrogen onto C terminus
edit cys////C
attach N,3,3

# edit that nitrogen
edit (elem N and neighbor cys////C)

# attach a tetrahedral methyl (note random position)
attach C,4,4

# here's an example of adding a whole residue from the library
edit cys////N
editor.attach_amino_acid("pk1","ace")

# now restore missing hydrogens (note that the names are off...)
h_add

Superposition of two molecules

Using pair_fit requires that you specify a set of paired atoms in each structure. Fortunately, you no longer have to specify each pair separately, so long as the ordering is the same in each selection (almost always true).

pair_fit ( trna10 and resid 10:15 and name P ), ( ref4 and resid 10:15 and
name P )

pair_fit prot1///11-26/CA, prot2///34-49/CA

Movies with PyMOL

Encoding video files

Assuming you have created a lot of .png files and would like to encode a .mpeg, .avi or other video format, a number of solutions are known:

Advanced PyMOL features

Meaning of the get_view output

Of the 18 numbers in the output array,
0-8 is the 3x3 rotation matrix,
9-11 is the camera location,
12-14 is the origin of rotation,
15-16 are the clipping distances,
and 17 is the orthoscopic flag.

Altering atom coordinates

Example:

alter_state 1,(pdb1cse),x=x-10.0

Translate or rotate individual objects

There is a "translate" function similar to "rotate", the docs for these don't exist yet, because the implementation isn't finished. However, feel free to use them in the following forms:

translate vector,object-name,state

   vector needs to be something like [x,y,z]

   translate [1,0,0],pept

rotate axis,angle,object-name,state

   axis can be either the letter x,y,z or a 3D vector [x,y,z]

   rotate x,90,pept
   rotate [1,1,1],10,pept

Moving one segment relative to the rest

What is in a selection?

Atom selections aren't directly exposed to Python, but you can have PyMOL build a Python list containing whatever information you need:

Using PyMOL commands:

list=[]
iterate (name ca),list.append((resi,resn))
print list

[('ASP', '1'), ('CYS', '2'), ('ALA', '3'), ('TRP', '4'), ('HIS', '5'), ('LEU',
 '6'), ('GLY', '7'), ('GLU', '8'), ('LEU', '9'), ('VAL', '10'), ('TRP', '11'),
('CYS', '12'), ('THR', '13')]

from pymol import cmd,stored
stored.list=[]
cmd.iterate("(name ca)","stored.list.append((resi,resn))")
print stored.list

[('1', 'ASP'), ('2', 'CYS'), ('3', 'ALA'), ('4', 'TRP'), ('5', 'HIS'), ('6', '
LEU'), ('7', 'GLY'), ('8', 'GLU'), ('9', 'LEU'), ('10', 'VAL'), ('11', 'TRP'),
('12', 'CYS'), ('13', 'THR')]

How does the Density Wizard work?

The answer:

What the heck is molecular sculpting?

Molecular sculpting works like a real-time energy minimizer, except that it isn't minimizing the energy. Instead, its just trying to return local atomic geometries (bonds, angles, chirality, planarity) to the configuration the molecules possess when they were first loaded into PyMOL.

To actually use this feature:

1. Load a PDB file.
2. Configure the mouse for editing (Mouse menu) or click in the mouse/key matrix box.
3. Select "auto-sculpting" from the Sculpting menu.
4. Select Sculpting from the Wizard menu.
5. Ctrl-middle-click on any atom in your protein to activate sculpting
   the green part will be free to move
   the cyan part will be a fixed cushion to provide context
   the grey part will be excluded.
6. Now perform any conformational editing operation in the green region such as:
   ctrl-left-click-and-drag on an atom
   ctrl-right-click on a bond, then ctrl-left-click-and-drag about that bond.

Right now I'm not sure the sculpting feature is more than entertainment, but my expectation is that it will become part of PyMOL's crystallographic model building system in the future.

Align proteins with CA fit

If the proteins have significant homology, then you can use the align command:

align prot1////ca,prot2

Python scripting

Launching Python programs

1. Running a Python script from PyMOL, usually the command:

run script.py

pymol example.py     # synchronous, in PyMOL module
pymol -r example.py  # synchronous in __main__ module
pymol -l example.py  # asychronous in a new module

run example.py        # synchronous in pymol module
run example.py,main   # synchronous in __main__ module

spawn example.py        # asychronous in a new module
spawn example.py,global # asychronous in the PyMOL module
spawn example.py,main   # asychronous in the __main__ module

2. Running PyMOL from a Python script requires two commands:

import pymol
pymol.finish_launching()

Using the PyMOL commandline

Are you aware that the PyMOL command line is also a Python command line? You can just use PyMOL interactively in that fashion.

PyMOL>print 1+1
2
PyMOL>from random import random
PyMOL>print random()
0.739460642143

PyMOL>print __name__
pymol

What is in a selection?

Atom selections aren't directly exposed to Python, but you can have PyMOL build a Python list containing whatever information you need:

Using PyMOL commands:

list=[]
iterate (name ca),list.append((resi,resn))
print list

[('ASP', '1'), ('CYS', '2'), ('ALA', '3'), ('TRP', '4'), ('HIS', '5'), ('LEU',
 '6'), ('GLY', '7'), ('GLU', '8'), ('LEU', '9'), ('VAL', '10'), ('TRP', '11'),
('CYS', '12'), ('THR', '13')]

from pymol import cmd,stored
stored.list=[]
cmd.iterate("(name ca)","stored.list.append((resi,resn))")
print stored.list

[('1', 'ASP'), ('2', 'CYS'), ('3', 'ALA'), ('4', 'TRP'), ('5', 'HIS'), ('6', '
LEU'), ('7', 'GLY'), ('8', 'GLU'), ('9', 'LEU'), ('10', 'VAL'), ('11', 'TRP'),
('12', 'CYS'), ('13', 'THR')]

Does a selection exist?

The function below will return true if the selection is defined.

from pymol import cmd
from types import *

def sele_exists(sele):
    sess = cmd.get_session()
    for i in sess["names"]:
        if type(i) is ListType:
            if sele==i[0]:
                return 1
    return 0

Get coordinates from Python

The actual C-langauge arrays aren't exposed, but there are at least three different ways you can modify coordinates from within Python:

Create objects from PDB strings

I thought I'd post this example, just in case anyone else cares about this:

delete all
cmd.read_pdbstr("""HEADER    CREATED BY CONVERTPROSPECT              27-JAN-02   2tnf  \
REMARK   1                                                                       \
ATOM      1  N   PRO A   9       1.895  67.213 -38.182  1.00  0.00           N   \
ATOM      2  CA  PRO A   9       1.703  68.680 -38.402  1.00  0.00           C   \
....
ATOM   1153  C   GLY A 157       6.927  59.108 -38.901  1.00  6.00           C   \
ATOM   1154  O   GLY A 157       6.700  59.292 -37.676  1.00  6.00           O   \
TER    1155      GLY A 157                                                       \
MASTER                                                                           \
END                                                                              \
""","2tnfa")
hide all
show cartoon
color grey
....

Measure distances from Python

Use Python (and the run command with .py files).

from pymol import cmd
f=open('dist.txt','w')
dst=cmd.distance('tmp','mol1///25/ha','mol1///26/ha')
f.write("%8.3f\n"%dst)
f.close()

from pymol import cmd
f=open('dist.txt','w')
atom = cmd.get_model("mol1////ha").atom
for i in range(len(atom)-1):
   sele1 = 'mol1///%s/HA'%atom[i].resi
   sele2 = 'mol1///%s/HA'%atom[i+1].resi
   dst=cmd.distance('tmp',sele1,sele2)
   f.write("%14s %14s %8.3f\n"%(sele1,sele2,dst))
f.close()

   mol1///4/HA    mol1///5/HA    4.748
   mol1///5/HA    mol1///6/HA    4.828
   mol1///6/HA    mol1///7/HA    4.861
   mol1///7/HA    mol1///8/HA    4.784
   mol1///8/HA    mol1///9/HA    4.936
   mol1///9/HA   mol1///10/HA    4.833
  mol1///10/HA   mol1///11/HA    4.933
  mol1///11/HA   mol1///12/HA    4.813

Coloring all objects differently

List the color of atoms

To retrieve the color for a residue as identified in an expression, you can either iterate over a selection from the PyMOL command line

iterate all, print color

List secondary structures

Secondary structures (both predefined and those calculated with the 'dss' command) can be exported as a long string ('HHHHLLLLSSS') with the following script:

import pymol
pymol.stored_ss = []
cmd.iterate('all', 'pymol.stored_ss.append(string.ljust(ss,1))')
print string.join(pymol.stored_ss)

Process key events from shell

The following scripts turns the view 30 deg around the y-axis, each time you press the enter key in the python shell (the original shell you started pymol from), just as an example:

#use "spawn spawn_demo.py, local" to invoke this python script from
within pymol
wait=""
i=0
while i < 12 and wait!="x":
  cmd.turn("y", 30)
  print "Press enter key to continue or x + enter to terminate"
  wait=raw_input()
  i=i+1
print "Done"

Alter key bindings

It's not GUI, but you could simply bind a function key such as F1 to a command:

cmd.set_key('F1',lambda :cmd.show('sticks'))

Viewing direction vectors

Ray-traceable labels

CGO label orientation

You could use the cmd.rotate and cmd.translate to position the labels, but it is likely to be somewhat painful. If I'm not mistaken, the rotation will always be about and axis through the origin and so you may need to translate the label into the correct position.

Thus if you have your label in an object called 'text', you could do,

  cmd.rotate(axis='x',angle=20.,object='text')

  cmd.translate(vector='[1.,2.,3.]',object='text')

3D marks on atoms

Save and load objects

There is a convenient format: ".pkl", that works like PDB, but is a Pickled copy of the PyMOL Model Class. The main advantage this has over .pdb is that it saves and restores extra properties such as secondary structure code, atom types, van der waals radii, formal and partial charges, etc.

load myprot.pdb
dss
show cartoon
alter 100-110/, ss='H'
alter 65-67,ss='L'
save myprot.pkl

load myprot.pkl
show cartoon

".pkl" has the additional advantage of being a simple molecular object useful in straight Python, outside of PyMOL. All you need to do is have a copy of PyMOL's "chempy" module available in your PYTHONPATH

from chempy import io
model = io.pkl.fromFile("myprot.pkl")
for atom in model.atom:
   print atom.name

Building ChemPy models

This is a snap. Just "run" the following Python program from within PyMOL.

from chempy.models import Indexed
from chempy import Bond, Atom
from whrandom import random
from pymol import cmd

model = Indexed()

# create some atoms

for a in range(1,11):
   at = Atom()
   at.name = "X%02d"%a
   at.coord = [random()*5,random()*5,random()*5]
   model.atom.append(at)

# now create some bonds

for a in range(1,10):
   bd = Bond()
   bd.index = [a-1,a] # zero-based indices!
   model.bond.append(bd)

# now load and label

cmd.load_model(model,"example")
cmd.label("example","name")