Basics

Launching

By Mouse

Microsoft Windows: Click on the Start menu, follow it to Programs, and then release the mouse on PyMOL.

By Command

Unix:

Edit pymol.com in the PyMOL distribution and make sure PYMOL_PATH points to the actual location of the distribution. Enter ./pymol.com to start pymol. You will probably want to create a link "pymol" from this file in to a "bin" directory in your path so that you can launch the program anywhere by simply entering pymol.

Microsoft Windows: Run "c:\program files\delano scientfic\pymol\pymolwin.exe"

NOTE: Command line options can be included under both Windows and Unix to automatically open files and launch scripts. See "launching" in the reference section for more information on these options.

PyMOL's Windows

Viewer Window

PyMOL Viewer window with Internal GUI enabled (Default).

The PyMOL Viewer represents the heart of the PyMOL system. This is a single OpenGL window where all 3D graphics are displayed and where all direct user interaction with 3D models takes place. This window also contains a simple graphical interface known as the "internal" GUI. The internal GUI has a primitive text display and command input capability as well as an object list, buttons, and a series of pop-up menus. When using the PyMOL Viewer, you can hit ESC anytime to toggle between text and graphics mode.

The PyMOL Viewer can be run all by itself, and it provides the complete capability of the PyMOL core system. However, many tasks can be made easier and more efficient through use of external menus and controls. Such objects are found in External GUI windows.

External GUI Windows

The default external GUI included with PyMOL.

By default, PyMOL comes with a single external GUI window which provides a standard menu bar, an output region, a command input field, and a series of buttons. One important advantage of the external GUI window is that standard "cut and paste" functions for text will only work within external GUIs, and not within in the PyMOL Viewer. Furthermore, you must use Ctrl-X, Ctrl-C, and Ctrl-V to cut, copy, and paste because a standard Edit menu has not yet been implemented.

Notes For Developers: External GUIs are the foundation for modularity and customizability in the PyMOL system. These windows constitute independent processes (or threads) which can control the behavior of PyMOL, and potentially interact with other programs. They are completely customizable at the Python scripting level, and mutiple external GUIs can exist at once (within the restrictions of Tkinter and wxPython).

External GUIs communicate with PyMOL through the Python API (Application Programming Interface). Those of you who want to link up you own programs with PyMOL should generally use a separate external GUI window to control the interaction, rather than changing internal PyMOL code. That way the programs will continue to work together even while development on each program proceeds independently. The internal GUI and all external GUI windows can be enabled and disabled using simple command line options (see reference for "launching").

Loading PDB Files

Using the External GUI:

The default external GUI provides the standard File:Open... menu option and dialog box which you can use to select the file you wish to open.

Using Commands:

   SYNTAX

      load <filename>

   EXAMPLE

      load test/dat/pept.pdb

PyMOL after loading a PDB file.

By default, the name of the object will be the same as the prefix on the file. If you want a different name, then you must specify it on the command line using a comma after the filename:

   SYNTAX

      load <filename>, <object-name>

   EXAMPLE 

      load test/dat/pept.pdb, test       

Manipulating the View

Mouse control is the primary control device, and keyboard modifier keys (SHIFT, CTRL, SHIFT+CTRL) are used in order to modulate mouse behavior. A three button mouse is required for PyMOL, but common mice such as the Microsoft Intellimouse and Microsoft Wheel Mouse will work just fine under Windows.

Basic Mouse Control

Here is a table of the basic mouse button/keyboard combinations for view manipulation:

When using PyMOL on a laptop, it may be necessary to attach an external mouse or reassign the particular mouse controls you plan to use onto the reduced set of buttons that you have available internally (see reference on the "button" command).

Free Rotation

Virtual Sphere.

Free rotation works as if there is an invisible sphere in the center of the scene. When you click and drag on this sphere, it is as if you put your finger onto it and moved it in approximately the same manner. If you click outside the sphere, then you get rotation about the Z-axis alone. Generally, the view will be easiest to control by either clicking in the center of the scene and moving outwards (mostly XY-rotation), or by clicking and draging around the edge of the screen and moving in a circular fashion (Z-rotation).

Moving Clipping Planes

Control of clipping planes.

PyMOL's clipping plane control is somewhat unusual and may take a few minutes to get used to. Instead of having separate controls for the front and back clipping planes, controls are combined into a single mode where up-down mouse motion moves the front (near) clipping plane and left-right mouse motion controls the back (far) clipping plane.

The advantage of the PyMOL clipping plane control is that tedious tandem manipulations of the clipping planes now becomes quite trivial through the diagonal motions shown below.

Changing the visible "wedge" by moving clipping planes in tandem.

You can also use the "clip" command to control the clipping planes.

Sessions and Scripts

Unlike other common graphics packages, PyMOL does not provide a means of saving and restoring sessions. Thus, in order to use PyMOL effectively, you must get into the habit of creating command scripts which you can then call upon as needed.

While some would consider lack of save/restore functionality to be a big drawback, it was not incorporated into PyMOL's basic design because it would have significantly complicated the program code and because most serious computational scientists prefer to use scripts . Scripts allow you to apply the same basic solution to a given problem over and over again in new situations. Even through there is more work involved in creating scripts, the future reuse makes up for it in the long run.

Currently, scripts need to be created separately using a text editor and then sourced (using "@") from within PyMOL. It makes sense to have a program like emacs, jot, or notepad available in a separate window while using PyMOL. Commands can then be cut and paste between the two programs. Development of an automatic script-recording capability is planned which would achieve something similar to save/restore and make script writing much more efficient.

PyMOL expects commands scripts to have a ".pml" extension (although this is not strictly required in all cases, it is good practice). Once created, scripts can be executed in several ways. Under Windows, scripts can be run in a new PyMOL session by double clicking on the script's icon. Alternatively, you can run a script using the File menu's Run option. You can also:

   SYNTAX

      @<script-file-name>

   EXAMPLE

      PyMOL> @my_script.pml

or (2) include it on the command-line when launching the program:

   SYNTAX

      pymol <script file>

   EXAMPLE (Windows)

      C:\> pymol.bat my_script.pml

   EXAMPLE (Unix)

      unix> ./pymol.com my_script.pml

NOTE: PyMOL is also fully scriptable using Python, but that is an advanced topic.

Atom Selections

Origins

Atom selections are central to how PyMOL works and are functionally interchangeable with objects in most cases. For example, you can use the color command to change an object's color, and you can use that same command to change the color of a selection of atoms.

   EXAMPLES

      color blue,pept                 # colors pept blue

      color red,(name ca)             # color alpha-carbons red 

To use PyMOL beyond the most basic level, you must learn at least one of PyMOL's atom selection languages.

Hierarchical Atom Selections

PyMOL provides an ultra-concise hierarchical atom selection syntax which utilizes slashes to denote the hierarchy. The heirarchy is as follows:

   model/segment/chain/residue/atom

Note that all hierarchical selections must contain at least one slash (/) character and hierarchical selections which contain a comma (,) must have surrounding parentheses in order to indicate that they are not separate arguments to a command.

Hierarchical selections are interpreted left-to-right if they have a preceeding slash, and right-to-left if they do not.

   EXAMPLE FORMS
                           residue/atom
                     chain/residue/atom
                     chain/residue/
            /segment/chain//
      /model/segment/chain
      /model//chain
      /model//chain/residue
      model///residue/
      model////atom

      ... etc.

   EXAMPLE USAGE
  
      select bb,*/ca

      color red, e/4:8/    # color residues 4 through 8 red in chain E

      zoom ( 42/c,n,o )    # zoom in on atom C,N,O in residue 42

      zoom ( /prot/e )     # zoom in on segment E of model "prot"

Algebraic Atom Selections

Algebraic atom selections are always surrounded by parentheses "(...)"

 EXAMPLE SELECTIONS

      (name ca or name c or name n or name o or name h)  # X-PLOR or PyMOL
      
      (name ca,c,n,o,h)                                  # PyMOL

      (n;ca,c,n,o,h)                                     # Equivalent PyMOL

Object names are valid symbols within atom selections

      load 1fc2.pdb, fc_comp

      color yellow,(fc_comp and elem C)  # color carbons yellow in fc_comp object

Hierarchical atom selections can be included in algebraic selections. For example:

      color green,( 10:100/ca and his/ )         # these are all equivalent...

      color green,( 10:100/ca and resn his )    

      color green,( resi 10:100 and name ca and his/ )

      color green,( resi 10:100 and name ca and resn his ) 

Named Selections

PyMOL goes beyond the X-PLOR selection syntax by introducing the concept of "named" selections. These are atom selections whose names, once defined, appear in the Internal GUI names list and can be treated like independent objects in many cases. Named selections can span multiple objects and will survive any changes made to the molecular structure. They can also be referred to by name in subsequent atom selections.

   EXAMPLES

      load fc.pdb
      load pept.pdb

      select backbone = (name ca,c,n,o,h)  # Create named selection "backbone"
                                           # which covers atoms in both objects.

      color red, backbone                  # Colors the selection red.

Named selections are distinguished from objects in the Internal GUI object list by a surrounding set of parentheses, and the options available available differ slightly between objects and selections.

NOTE: Named selections are static. Only atoms which exist at the time the selection is defined are considered part of a selection, even if atoms which are loaded subsequently would fall within the given criterion (NOTE: A mechanism for "refreshing" named selections is planned but does not yet exist).

Selection Algebra

Selections can be arbitrarily complex and contain complicated alebraic constructs.

Note that in the following tables, semicolons ";" in abbreviations are significant and are required (where shown) in order to delimit the abbreviation.

Operators:

Selection operators and modifiers are listed below in decreasing order to precedence.

The order of precidence rules for the above operators mean that the following atoms selections are equivalent:

      (byres chain a or chain b and not resi 125 around 5)

      (byres ((chain a or (chain b and (not resi 125))) around 5))

Some additional operations are shown below, but you can probably ignore them for now.

Simple Keyword Selectors:

   EXAMPLE 

      hide (hydro)  # hide all hydrogen atoms

Property Selectors:

Where plural arguments are indicated for property selectors, multiple values can be provided so long as they are separated by only commas (and no spaces). In each case, the implied operation is a logical OR with implicit priority.

   EXAMPLE

      (name cb,cg1,cg2 and chain A)                   # is equivalent to

      ((name cb or name cg1 or name cg2) and chain A) 

Ranges are separated by a colon ":", and currently only one range can be given to those selectors which accepts ranges.

      (resi 100:120)

Currently, the only valid comparison operators are: "<",">" , and "=". More will be added.

      (b > 10)

The basic property selectors are:

Shown below are some advanced property selectors which can probably be ignored for now:

Actions on Objects and Selections

Using the Internal GUI:

The internal GUI allows you to perform a number of actions directly on objects or selections through a set of pop-up menus which appear to the right of every object or selection name. The four menus are:

• Action (Diamond): Common actions you might perform, such as zooming or deleting.
• Show [S]: Show various representations, such as spheres or surfaces.
• Hide [H]: Hide various representations.
• Label [L]: Label atoms according to varvious properties.
• Color (Rainbow): Color atoms, by atom type or uniformly.

Example pop-up "Show" menu.

You can experiment with most of the actions in the pop-up menus in the interal GUI to learn how they work. However, certain actions, such as showing surfaces and meshes, can be time consuming to compute on large structures. Thus, you may want to experiment using the PDB file of a small peptide.

Named atom selections work well with the internal GUI because it is often easiest to identify a specific set of atoms using the selection language and then use the internal GUI menus to change the representation and appearance of those atoms. For example, the following figure can be prepared using the script below or by just creating a named atom selection on the command-line and peforming the rest of the actions using the GUI.

Generating figures using the GUI with named atom selections.

      load test/dat/pept.pdb # or load this file using the external GUI's File menu.

      orient pept             # or select "orient" from pept's Action menu.

      select sc = (!n;c,n,o)  # this selection includes all sidechain bonds.

      show sticks, sc         # or select "sticks" from sc's Show menu.           

      hide lines, pept        # or select "lines" from pept's Hide menu.

      show ribbon, pept       # or select "ribbon" from pept's Show menu.

      ray                     # or click "ray trace" on the external GUI.

Using Commands on Objects and Selections

All actions performed by the internal GUI have command-line equivalents.

In general, PyMOL commands which take an object as an argument can also take a named selection or even an inline selection. For example, all three of the color commands below will have the same result:

      load test/dat/pept.pdb    # create object "pept"
      select vals = (pept and r;val) # creates named selection "vals"          

      color yellow,(pept and r;vals) # color inline selection which uses an object name

      color yellow,vals              # color named selection

      color yellow,(vals)            # color inline selection which uses a named selection

However, there are some exceptions, such as with object and selection deletion, where it is necessary to specify the object or selection name explicity without surrounding parenthesis.

      load test/dat/pept.pdb          # creates object "pept"
      select vals = (pept and r;val)  # creates named selection "vals"
      
      delete (vals)       # invalid: implies delection of an inline selection.
      delete (pept)       # invalid: same problem; deleting "(vals)" not "vals"

      delete vals         # valid: destroys the selection, but the object is unchanged.
      delete pept         # valid: deletes the object and all associated atoms.

Essential Commands

The meaning of show, hide, zoom, color are probably obvious. Delete is used to remove entire objects. In contract, remove is used to remove only a subset of atoms within objects. The origin command redefines the center of rotation in space about the indicated object or selection without changing the current view.

For more information on the individual commands, use "help command-name" or consult the reference section of the manual.

   EXAMPLES

   # How do I zoom in on residue 100? 

      zoom (resi 100) 

   # How do I color the molecule white? 

      color white
     
   # How do I color residues 50, 54, and 58 green?

      color green, (resi 50,54,58) 

   # How do I color residues 60 to 90 yellow?

      color yellow, (resi 60:90)

   # How do I show a surface on model "lig"?

      show surface, lig

   # How do I show a cartoon representation on model "prot"?

      show cartoon, prot

   # How do I show a helix-like representation on residues 14:30?

      cartoon oval, (resi 14:30)

   # How do I show a CPK-style space filling representation?

      show spheres

   # How do I hide hydrogens?

      hide (hydro)

   # How do I get rid of hydrogens permanently?

      remove (hydro)

   # How do I delete an object named "prot"?
 
      delete prot

Copyright © 2001 DeLano Scientific. All rights reserved.