This section steps through a typical PyMOL session, introducing typed commands and describing how PyMOL responds to them. The details of command syntax are in the section titled "PyMOL Command Language."
The PyMOL language is case-sensitive, but upper case is not used in the current package. So just remember to type all your commands in lower case.
While you are learning PyMOL or doing complex projects, you may want to keep a record of all the commands you give in a plain text log-file that you can read and edit. To open a log-file, type the command log_open followed by a file-name:
SYNTAX
log_open log-file-name
EXAMPLE
PyMOL> log_open log1.pml
All your commands, typed or clicked, will be recorded in the log-file. You should give your log-file-name the extension ".pml" so you can load the file as a script, to repeat your commands in a new session (see the subsection titled "Sessions and Scripts" below).
To stop recording your commands, type log_close. If you don't type log_close before you exit PyMOL, your log-file will still be saved to disk.
If you just want to save the current state of your PyMOL work without concern for the steps you took and the commands you gave, you can create a session-file (see "Sessions and Scripts").
SYNTAX
load data-file-name
EXAMPLE
PyMOL> load $PYMOL_PATH/test/dat/pept.pdb
Given this command, PyMOL will open and read the file "pept.pdb,"
create and name a corresponding object, display a representation of the
object in the viewer, and add the object's name to the control panel.
By default, PyMOL names the object after the file it read. You can assign a different name to the object by typing the name in the command line:
SYNTAX
load data-file-name, object-name
EXAMPLES
PyMOL> load $PYMOL_PATH/test/dat/pept.pdb # The object is named "pept".
# PyMOL doesn't use
# the file-name extension
# ".pdb" in the object-name.
PyMOL> load $PYMOL_PATH/test/dat/pept.pdb, test # The object is named "test".
(Note that "#" is a comment character, so anything you type to the
right of "#" in a command line is not interpreted by PyMOL.)
The command for loading a file follows typical PyMOL syntax. load is a keyword; it calls PyMOL to perform a certain function. data-file-name and object-name are arguments to load. These arguments tell PyMOL what file to load and what to name it, but in general, arguments to keywords just supply information that PyMOL needs to carry out commands.
After PyMOL creates an object, you can manipulate it in the view window and control panel with your mouse, and also by typing commands. For example, you can change from the default representation, called lines, to the more hefty sticks. First get rid of the lines and then show the sticks:
SYNTAX
hide representation
show representation
EXAMPLES
PyMOL> hide lines # The object shown in lines disappears from view.
PyMOL> show sticks # The object is represented as sticks in the viewer.
Other representations are cartoons, ribbons, dots,
spheres, surfaces, and meshes (See the Section titled
"Representations").
If you want to manipulate a subset of the atoms and bonds in a molecule, you can use atom selections. PyMOL is pretty sophisticated when it comes to selecting, grouping and naming groups of atoms. For example, you can select particular residues or atoms in a binding pocket, or a hydrophobic patch, or all the alanines in a helix, and so on. The Section titled "PyMOL Command Language" gives the details for selecting interesting groups of atoms.
You can use a selection just once, or you can name it to make it easier to use again later. For example, you can zoom in on a selection "on the fly:"
SYNTAX
zoom selection-expression # Select the atoms just for zooming.
EXAMPLE
PyMOL> zoom resi 1-10 # The selector resi
# chooses amino acid residues
# given by the PDB sequence number
# identifier "1-10."
Selection-expressions range from single words to long
complicated expressions. An object-name may be a
selection-expression. The default selection-expression is
all, which refers to all the atoms that are currently loaded. If a
selection-expression is missing, PyMOL will apply the command to
all. We'll keep our selection-expressions short in this
section.
If you name the selection, you will be able to manipulate it any number of times. Object and selection names may include the upper or lower case characters (A/a to Z/z), numerals (0 to 9), and the underscore character (_). Characters to avoid include:
! @ # $ % ^ &* ( ) ' " [ ] { } \ | ~ ` <> . ? /
First, name the selection:
SYNTAX
select selection-name, selection-expression
EXAMPLES
PyMOL> select akeeper, resi 1-10 # Select the residues and name them "akeeper."
Then use it:
SYNTAX
zoom selection-name
hide representation, selection-name
show representation, selection-name
EXAMPLES
PyMOL> zoom akeeper # Zoom in on them in the viewer.
PyMOL> hide everything, akeeper # Hide their representation in the viewer.
PyMOL> show spheres, akeeper # Show them in a different representation,
# spheres, this time.
When you create a selection-name, PyMOL puts it in the control panel so you can apply control panel functions to the selection using your mouse (See the section titled "PyMOL Command Language").
Named-selections such as "akeeper" are manipulated like PyMOL objects, but objects and named-selections are fundamentally different. PyMOL creates an object-name to locate data when you load a data file. Making selections is a way of pointing to a subset of that data. To distinguish selection-names from object-names, selection-names are shown inside parentheses in the control panel.
When you delete a selection-name, the data are still found under the object-name, but the data are no longer organized as the selection. In contrast, after you delete an object, you must reload the data to have access to it again.
SYNTAX
delete selection-name
delete object-name
EXAMPLES
PyMOL> delete akeeper # "akeeper" is gone, but the object remains.
PyMOL> delete pept # The atoms and bonds in "pept" are gone.
You can apply various colors to selections and objects using typed commands. Predefined color-names are listed under the settings/colors pull-down menu. Many of them can be chosen from the control panel. See the section titled "Settings" to find out how to define more colors.
SYNTAX
color color-name # All the representations of
# loaded objects are colored.
color color-name, selection-expression # The representation of
# the selection is colored.
EXAMPLES
PyMOL> color white # Everything turns white.
# This looks fine on the
# default black background,
# but causes disappearance
# if you've changed the background to white.
PyMOL> color orange, pept # Remember that "pept" is our object-name,
# so the entire object is colored orange.
PyMOL> color green, resi 50+54+58 # The representation of
# residues numbered 50, 54 and 58
# is colored green.
PyMOL> color yellow, resi 60-90 # The representation of
# residues numbered 60 through 90
# is colored yellow.
PyMOL> color blue, akeeper # Residues numbered 1-10,
# which were collected in
# the named selection "akeeper,"
# are colored blue.
PyMOL> color red, ss h # The representations of
# helical residues
# are colored red.
PyMOL> color yellow, ss s # The representations of
# beta sheet residues
# are colored yellow.
PyMOL> color green, ss l+"" # The representations of
# loop and unassigned residues
# are colored green.
In the last three examples, the selector ss chooses secondary structures specified by h for helix, s for beta sheet strand and l+"" for loops and unspecified structures.
PyMOL can hold several objects in memory at the same time. The commands disable and enable allow you to eliminate representations of objects from the viewer while still controlling their properties with commands.
SYNTAX
enable object-name
EXAMPLE
PyMOL> load $PYMOL_PATH/test/dat/fc.pdb
PyMOL> load $PYMOL_PATH/test/dat/pept.pdb
PyMOL> disable pept # All representations of "pept"
# are removed from view.
PyMOL> color yellow, name c+o+n+ca # Backbone atoms in both "fc"
# and "pept" are colored yellow,
# but "pept" atoms
# are still not visible.
PyMOL> enable pept # "pept" atoms are visible and
# its backbone atoms are yellow.
You can also use the disable command to get rid of the pink dots that identify the last-named selection in the viewer:
SYNTAX
enable selection-name
EXAMPLE
PyMOL> select bb, name c+o+n+ca # Atoms included in the
# named-selection are indicated
# with pink dots in the viewer.
PyMOL> disable bb # The pink dots disappear,
# but the named selection "bb"
# is still visible.
PyMOL> color red, bb # You can still manipulate "bb."
You can still operate on the representations of objects that are
disabled, even with the commands show and hide. The
results will be apparent when you subsequently enable the
object.
Dragging on a molecule with the mouse is often the easiest way to manouver, but typed commands such as zoom and orient give you a different form of control, allowing computations to direct the view. zoom, as the name suggests, brings an object or selection close up in the center of the field of view. If the object or selection doesn't fit in the current view, the view opens out to include it. If it is just a small part of the current view, the view closes in to fill more of the screen with it.
SYNTAX
zoom selection-expression # The "camera" moves close
# to the selection so it fills the viewer,
# or moves further away to include
# all of the selection in the viewer
orient is a useful command when you want a fresh start in viewing the molecule. It aligns the object or selection so its largest dimension is shown horizontally, and its second largest dimension is shown vertically.
SYNTAX
orient selection-expression # The selection is aligned
# for maximum visibility in the viewer.
You can store orientations and recall them later in your PyMOL session using the command view. Storing a view only saves the viewpoint on the objects in the viewer. It does not save their representation. To store a view for later in the session, you need to "key" it, that is, to give a name or number as an argument to the command view. A second argument tells PyMOL whether you want it to store the view or recall it.
SYNTAX
view key, action # The possible actions are store and recall.
EXAMPLES
PyMOL> view v1, store # The current view is named "v1" and stored.
PyMOL> view v1, recall # The view keyed "v1" is restored.
PyMOL> view v1 # recall is the default argument to view,
# so this also recalls "v1."
The keyword view only stores an orientation for the duration of the current PyMOL session. The next section gives the recipe for saving and restoring views in different PyMOL sessions.
PyMOL saves your work in f kinds of processes: (1) Before you give a series of commands, you can initiate the process of logging your commands into plain text log-files that can later be used as scripts. (2) At any point in a PyMOL session you can save the memory state of the program by creating a session file that can later be loaded to restore that memory state. (3) You can write a graphics file to store the image you have created in the viewer for sharing or publication.
A PyMOL script is just a text file, such as a log-file, containing typed PyMOL commands separated by carriage returns. When a script is loaded into PyMOL the commands it contains are executed. PyMOL expects scripts to have ".pml" file-name extensions (this is not strictly required, but it is good practice).
You can use log-files as scripts, and you can create scripts in a text editor such as emacs, jot, or notepad. It's often useful to keep a text editor open in a separate window while using PyMOL. Commands can then be cut and pasted between the two programs.
You can open a new log-file by typing log_open log-file-name, or by clicking on "log" under the "File" menu and naming the log-file in the dialog box. You can also append commands to an existing log-file by choosing "append" or "resume" in the "File" menu. When you "resume" rather than "append," the existing log-file is first loaded as a script, and then subsequent commands are written to it.
Once you have opened a log-file in any of these ways, PyMOL will write and save all your commands, whether they are typed or given by clicking on the buttons in the GUI.
However, to store the orientation of a molecule into a log-file, you need to give the command get_view (type it or use the GUI button). You may find it convenient to get_view several times in a PyMOL session, and then edit the log-file to select the most useful views.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. PyMOL also understands "@" as the typed command that loads a script:
SYNTAX @script-file-name EXAMPLE PyMOL> @my_script.pml
You can also include the script-file-name when launching PyMOL from a command line:
SYNTAX pymol script-file-name EXAMPLE (Windows) C:\> pymol.exe my_script.pml EXAMPLE (Unix) unix> ./pymol.com my_script.pml
Once you are satisfied with the representation and orientation of your molecule, you may want to save the image in a graphics file. Before you do that, you can improve the quality of the graphics by switching from PyMOL's fast default graphics engine, OpenGL, to its ray tracer. The ray tracer is slower, but produces higher quality renderings for display and publication. Ray tracing shows how light is reflected and how shadows fall in a three-dimensional world. Ray tracing may take some minutes for a large complex object. The keyword ray calls PyMOL's raytracer to redraw and display the image in the view window (See the section titled "Ray Tracing" for more details).
To save an image to a file, raytraced or not, use the "Save Image" option in the "File" menu or type the png command:
SYNTAX
png file-name
EXAMPLE
PyMOL> png $PYMOL_PATH/pep # The file-name extension ".jpeg" is
# added. The image file "pep.jpeg" is stored
# in a path below the PyMOL installation.
The PNG file format is directly readable by PowerPoint. It can be
converted into other formats using a package like ImageMagick.
If you want to be able to return to the current state of PyMOL, then you can create a session-file (Choose "Save Session" in the "File" menu and respond to the dialog box by naming the file with a ".pse" file-name extension). This utility works like the "Save" utility in a word processing program. A PyMOL session-file is a symbolic record of the state of PyMOL's memory, including the the objects that have been loaded or created, the named-selections that have been created, and the display in the viewer.
When you open the saved session-file, PyMOL's memory returns to the state that was saved. Because a session-file represents a PyMOL memory state, opening one means that you are eliminating everything that you currently have in PyMOL's memory, and replacing it with the memory state from the session-file.
A session-file differs from a log-file or a script in a number of ways. You have to open a log-file before you give the commands you want to save, but a session-file can be created at any point. A session-file is invoked by choosing "open" under the file menu, while a log-file is "run" as a script. Also, you can't write or edit session-files, as you can log-files and scripts.
It's a good idea to create session-files at strategic points in PyMOL sessions, for example, when you decide to explore one of several options. In this way, session-files can be used to replace an "undo" utility, which PyMOL lacks. You can store any number of PyMOL states in successive session-files, and revert to them, effectively "undo"-ing the work you did since creating the session-file.
Since almost nobody likes to type, PyMOL's command-line interface includes several "shortcut" features designed to reduce typing. If you are a unix user, you will recognize the similarity with features found in tcsh or bash.
If you type the first few characters of a command and then hit TAB, PyMOL will either complete the command or print out a list of which commands match the command.
EXAMPLE
PyMOL> sel
# hitting TAB will produce
PyMOL> select
If you hit the TAB key on a blank command line, PyMOL will output a list of its commands.
Some of the files you need to load into PyMOL may have long paths and filenames. PyMOL makes it easier to load such files by automatically completing unambiguous paths and filenames when you hit the TAB key. For instance,
EXAMPLE
PyMOL> load cry
# If "crystal.pdb" exists in the current directory, hitting TAB will generate
PyMOL> load cystal.pdb
If there is some ambiguity in the filename, PyMOL will complete the name up to the point of ambiguity and then print out the matching files in the directory.
There are a small number of "fixed string" arguments to PyMOL commands. For example, in
PyMOL> show sticks
"sticks" is a fixed string argument to show. Because there is only a small set of such arguments to show, PyMOL will infer your meaning even if you only provide it with a few letters. For example
PyMOL> show st
works just as well.
Keywords are also inferred in this manner, so
PyMOL> sh st
works too, as long as show is the PyMOL only command starting with "sh".
NOTE: PyMOL's command language continues to grow and develop, so it is important to use full-length commands and string arguments in scripts. Otherwise, you could not be sure that a later command or argument would not cause your abbreviation to become ambiguous. For example, "sh st" would no longer work if a shutoff command were added to the PyMOL language.
This "Getting Started" section used the most frequent PyMOL commands in very brief examples. The section titled "Simple Examples" shows other commands that combine representations, selections and property changes. More complicated examples appear in the section titled "Cookbook and Complex Examples," and a comprehensive listing of typed commands appears in the section titled "Command and API Reference."
To see a list of the keyword commands that are available in PyMOL on your computer screen, type help and "enter" (Typing TAB and "enter" will work too). Add the keyword if you want help on a particular command:
SYNTAX
help keyword
EXAMPLE
PyMOL> help load
PyMOL responds by displaying the manual page that discribes the command
in the PyMOL viewer. Command line completion works inside of help, so
if you don't remember the full keyword, type help, the first
character or so of the keyword, and hit TAB. Python will display a list
of possible help topics.
Click inside the viewer and hit escape to toggle back and forth between the display of the manual page or the list of commands and the molecules you have loaded in PyMOL.
All the keywords that PyMOL understands are listed alphabetically and described in the "Reference" section. PyMOL commands run on top of the Python programming language and may contain Python statements. After you type in a command and hit return, PyMOL will check whether the first word is one of its keywords (or if it can be extended into a keyword). If not, PyMOL will pass the command on to the Python interpreter. PyMOL will return a Python error message if neither a PyMOL nor a Python keyword is recognized.