Manual MOLMOL 2K.1

Author: Reto Koradi

Institut für Molekularbiologie und Biophysik
ETH-Hönggerberg
CH-8093 Zürich
E-mail: molmol@mol.biol.ethz.ch

Spectrospin AG
Industriestr. 26
CH-8117 Fällanden
E-mail: molmol@spectrospin.ch

1. Introduction

2. Documentation Overview

3. Starting

4. User Interface

Main Window Elements

Executing Commands

Dialog Boxes

Using Online Help

Mouse Manipulations

5. Selection

Interactive Selection

Using Expressions

Values

Properties

Expression Syntax

Advanced Topics

6. Command List

Input/Output

Modify Molecules

Primitives

Display

Movement

User Interface

Selection

Attributes

Plotting

Calculations

Figures

Miscellaneous

7. Standard Macros

8. User Macros

9. Configuration and Customization

10. Features

11. MOLMOL Tutorial

MOLMOL Tutorial - Example 1

MOLMOL Tutorial - Example 2

MOLMOL Tutorial - Example 3

MOLMOL Tutorial - Example 4

1. Introduction

MOLMOL is a molecular graphics program for displaying, analyzing, and manipulating the three-dimensional structure of molecules, with special emphasis on biological macromolecules. The program has features that make it particularly useful for the study of protein or DNA structures determined by NMR, but most of its possibilities are useful also outside of this particular area.

MOLMOL runs on UNIX and Windows NT/95/98 and is freely available. Copyright conditions are included in the distribution, all users are required to carefully read and follow them.

The latest information about the program is always available on the MOLMOL Web Site. Links and instructions for downloading and installing the software can also be found there.

Questions and problem reports should normally be sent to the MOLMOL mailing list, subscription information and archives are available on the web site. Since the author has moved to a new job, mail sent to the address on the title page may not be answered.

2. Documentation Overview

This manual gives an introduction into using MOLMOL, and explains the basic concepts. The user is encouraged to use the online help system of the program. A list of commands can be found towards the end of this manual, the tables in that section contain links to the online help pages.

Users who prefer to learn from tutorials may want to skip to the tutorial section before reading through the complete manual. Even after completing the tutorials successfully, it is still recommended to come back to the remaining parts of the manual later, a good understanding of of the basic concepts will help you to use MOLMOL more efficiently.

The collection of online manual pages is also available as a PostScript file named ref.ps in the man subdirectory of the installation directory. All other documentation is distributed in HTML format only. For easier printing of the manual, it is available as one single file as well as as set of separate files. The contents of the two forms is identical.

3. Starting

UNIX

MOLMOL is supplied with a shell script (molmol in the top level installation directory) that processes options and arguments and sets the necessary environment variables. The following options are recognized by this shell script:
argument description
-h give list of options
-t TTY interface (no graphics)
-o name alternate input/output device
-2 stereo mode (OpenGL only)
-a display all atoms (not backbone only)
-s superimpose complete backbone
-r range superimpose given backbone range
-f file execute macro file (- for standard input)
files DG, PDB, Angle or Dump files
If the program is started without names of structure files, it will recover the saved state of the last invocation (if available) and ignore all options but -f macro.

Besides the listed options, the program will also recognize standard Xt options, like -bg color for setting the background color.

Windows

Under Windows, you will normally start MOLMOL by double-clicking its icon (a capital M in cyan and red). You may want to create a shortcut on your desktop. Right-click on the icon e. g. in Windows Explorer, select "Create Shortcut" in the menu, and drag the shortcut to a convenient location on your desktop.

The following command line options are recognized:

argument description
-stereo stereo mode
file execute macro file
If you want to use one of these options, you can either start the executable from a command prompt, or define a shortcut, and then set the argument in the properties of the shortcut (right click on icon, select "Properties", click on "Shortcut" tab, and add the argument after the executable in the "Target:" field).

You can also start MOLMOL by defining it as program to be started for files with a certain exptension (like .pdb), and then double-clicking a file with this extension.

MOLMOL also supports drag and drop for some common molecule file types. If a file with one of the following extensions is dropped into the main window of the running program, the file is loaded with the corresponding command:

extension description
.pdb ReadPdb
.ent ReadPdb
.cor ReadDg
.mol2 ReadSybyl
.ml2 ReadSybyl
.xyz ReadXyz
.ang ReadAng
.seq ReadSeq
other ReadDump

4. User Interface

This section describes how to use the most important parts of the MOLMOL user interface. We assume that you are familiar with the basic concepts of using applications with graphical user interfaces. Here you will learn about:

Main Window Elements

The following image shows a screen dump of the MOLMOL main window, with annotations for its elements. Each of them will be briefly explained in the following sections.
When you start up MOLMOL for the first time, you will see two dialogs boxes in addition to the main window. If you prefer not to see them each time you start the program, you can disable them using the
UserInterface command, and choose the option to save the program state when you quit the program. You can do the same if you do not want certain parts of the main window to appear.

Drawing Area

All graphical display of molecules (and other items) will appear here. You also use this area for interactive mouse manipulations, like zooming and rotating.

Menu

The menu contains all MOLMOL commands, you use the common navigation methods known from other programs to access commands in the menu. The following is a short overview of which kinds of commands can be found in which pulldown menu:
File
Input and output of files. This includes reading and writing of molecules in many formats, output of plots, execution of macros, and a variety of other commands.
Edit
Commands that modify molecules. This includes commands that change the covalent structure (adding and removing atoms and bonds, building molecules from residues, etc.) and commands that modify coordinates (rotation, translation, changing dihedral angles, superposition, etc.).
View
Commands that change global viewing parameters. This includes zooming, camera and light source parameters, clipping planes and fog.
Options
Commands that change various kinds of configuration options and preferences. This includes the choice whether certain dialogs are displayed, selection of stereo and animation modes, rendering options, display quality, plot parameters, and path names of configuration files.
Prop
Commands that change or list properties. Properties are boolean values that can be set for various data items, they are mainly used for Selection.
Attr
Commands that change graphics attributes, like colors, display styles, material properties, etc.
Calc
Commands that perform calculations. A large variety of calculation and analysis possibilites for molecules can be found here.
Prim
Commands that create and modify primitives. Primitives are things that can be displayed, but are not molecules. This includes annotations, schematic displays (ribbons) and surfaces.
Fig
Commands that draw figures used for the analysis of molecules. This includes Ramachandran plots, angle distribution plots, contact maps, etc.
Opt
This menu appears when optional commands are defined as part of the startup macros, and those commands are not contained in any other menu. See the section on configuration for information on how to extend the program with optional commands.
Help
Commands for access to various forms of online help.

Buttons

The buttons give quick access to some frequently used (combinations of) commands. You can use the HelpButton command to see how exactly the buttons are defined.

Command Line

As well as selecting them from the menu, all commands can also be entered on the command line. Parts of commands that are unique are completed automatically while typing. You can also enter command arguments on the command line.

Status Line

A short help message is displayed here while the mouse pointer is moved over menu entries or buttons, or when a command is entered on the command line. Some commands also display informative messages on the status line.

Break Button

Most long running commands can be interrupted by clicking the mouse on this button. The button will be active while such a command is running, inactive (grayed out) otherwise.

Executing Commands

The description of the
main window already mentioned some ways of executing commands in MOLMOL. This section gives a more complete and detailed list of how you can enter commands. Command arguments can be arbitrary expressions, as documented in the section about expression syntax.

Dialog Boxes

MOLMOL has two main kinds of dialog boxes, which are described in the following sections.

Command Arguments

When a command requiring arguments is selected in the menu (or executed by other means, as described under
Command Execution), it prompts for the arguments with a dialog. These dialogs typically contain text fields for entering strings and numerical values, radio boxes for selecting between different values of an enumerated set, and check boxes for enabling options.

These dialogs always have three buttons:

OK
Closes the dialog, and executes the command with the arguments entered.
Cancel
Closes the dialog without executing the command.
Help
Display help information for the command, leaving the dialog open.

Convenience Dialogs

There is a number of dialogs that give faster and more convenient access to frequently used operations that could also be executed by using normal commands. These dialogs are explicitly opened and closed by using a command starting with Dial: The first four dialogs in this list can be opened with one of the buttons on the right side of the main window.

These dialogs can remain open as long as you need them, commands are executed by clicking buttons within the dialog. They have two buttons at the bottom:

Close
Closes the dialog.
Help
Display help information for the dialog.

Using Online Help

MOLMOL has extensive online help possibilities, all available documentation is available online. There is a help page for each command, available in both text and HTML format. Most of the other documentation is in HTML format. Use the
HelpViewer command for selecting whether you want to see the text or HTML version of the command help pages, and to configure which browser should be used for displaying HTML.

Command Help Pages

The online help page for commands can be displayed in two different ways. The first way is to click the Help button in the argument dialog of the command. The second way is to execute the HelpCmd command. This puts the program into help mode (indicated by the prompt in front of the command line), so that the next command is not executed, but its help page is displayed instead. The first method is more convenient, but only works for commands that have arguments.

Finding Commands

If you are looking for a command, but do not know its name and cannot locate it in the menu, the HelpApropos command can be very useful. It allows you to look for commands by a keyword, and displays a list of all commands that contain this keyword in their short description, including their location in the menu and the short description.

Other Options

Explore the Help menu to find other useful options, like displaying this manual and tutorial, or listing available standard properties for selection. The Register command is also available from the Help menu, you are encouraged to register if you use MOLMOL.

Mouse Manipulations

This section describes how to use the mouse in the
drawing area. MOLMOL can only be (reasonably) used with a mouse with at least two buttons. If you have a three button mouse, the right mouse button displays a popup menu.

The usual terms will be used to describe mouse input:

click
Press one (or multiple) mouse button(s), and release them without moving the mouse.
drag
Press one (or multiple) mouse button(s), move the mouse, and release the button(s).
The following list refers to the left and middle button of a three button mouse. If your mouse has only two buttons (as is commonly the case with Windows), the second (right) button of your mouse will take the role of the middle button.
click left
Select item closest to position of mouse pointer, deselecting everything else.
click left, while holding down Shift or Ctrl key
Select item closest to position of mouse pointer in addition to already selected items.
click middle
Same as click left.
drag left
Rotate molecules, using the virtual trackball model.
drag middle
Translate molecules in direction of mouse movement.
drag left+middle
Zoom. Moving right/up zooms in, moving left/down zooms out.
When used over text labels, the middle mouse button takes on different functionality:
click middle
Toggle selection of text label.
drag middle
Move/resize text label, depending on the position within the text labels. Different zones are indicated with dashed lines, the zones on the edges/corners are for resizing, the one in the middle is for moving the label.
If you need a quick reminder of these manipulations, you can view a table with the HelpMouse command.

5. Selection

MOLMOL uses the selection-action principle wherever possible. This means that the user first selects a set of items, and then executes the command(s) that performs the desired action on the selected items. The kinds of items that can be selected are: What kind of items need to be selected for a given command is often clear from the command name, e. g. the command
ColorAtom operates on atoms, and therefore you need to select the desired atoms before executing the command. If you are uncertain about the required selection for a command, check the online help pages, the first sentence in the description normally tells you how the command operates on the selection.

Selected items do not look visually distinct in the graphical display. When you perform a selection operation, the status line will give you information about the items that were selected. You can also choose to only see the currently selected items by clicking the Show Sel. button on the right side of the main window. Use the Show All button to get back to displaying all visible items.

The following sections explain various aspects of how to make selections:

Interactive Selection

Items (like atoms or bonds) can be selected by clicking on them with the left or middle mouse button. Doing that will normally deselect all other items of the same class. To prevent that, hold down either the Shift or the Ctrl key must be pressed on the keyboard while making the selection.

For text annotations there is a difference between the function of the left and middle mouse buttons: the left mouse button only selects texts if their bottom-left corner is the nearest item, while the middle mouse button gives priority to texts and selects them whenever the position is within the text.

See the section on Mouse Manipulations for a more detailed description on how to use the mouse.

Using Expressions

When you want to select a number of items, interactive selection can be very cumbersome, especially in large molecules. MOLMOL allows you to select items using a powerful expression syntax. You can interpret these expressions as rules that an item has to satisfy to get selected.

You can use commands like SelectAtom to select items, but it is normally much more convenient to use the Selection Dialog that can be opened by clicking the Selection button on the right side of the main window.

This section gives an informal introduction into selection expressions, a more complete and precise description can be found in the section Expression Syntax.

Short Notation

While the full expression syntax is necessary for complex selections, a more compact notation is supported to make simple selections easier. In this short notation, the expression consists of three parts, all of which are optional:
  1. the character # followed by a list of molecule names and numbers
  2. the character : followed by a list of residue names and numbers
  3. the character @ followed by a list of atom names
Spaces are not allowed within such an expression. Lists of names and numbers, separated by commas, are allowed, as well as ranges of numbers, denoted by the - (minus) character. It is possible to give a list of such expressions, separated by spaces, this will select all parts.

The following are some examples of this short notation used for selecting atoms:

@CA
all atoms named CA
:10-20
all atoms in residues number 10 to 20
#1-3,5:10-20,25,LYS@N,CA,C
all atoms named N, CA or C in residues number 10 to 20 residue number 25, and residues named LYS, in molecules number 1 to 3 and 5
:10@HN :17@HA
atom named HN in residue number 10 and atom named HA in residue number 17

Selecting Everything/Nothing

Giving an empty string as selection expression selects all items. The expression '0' (a string with the digit zero as the only character) will deselect everything.

Full Expression Syntax

The full expression syntax of MOLMOL is very similar to expressions in a programming language like C. A number of values, e. g. charge for the charge of an atom or len for the length of a bond, and boolean properties, like bb for backbone, are available for each item. These can be arbitrarily combined with arithmetic and logical operators. The result of the expression must be a boolean value, all items for which the expression evaluates to true are selected.

The following are some examples of the full notation used for selecting atoms:

name = "CA" & bfactor > 3.2
atoms with name CA and B factor larger than 3.2
vdw < 1.5 | charge > 0.0
atoms with VdW radius less than 1.5 or a positive partial charge

Values

The following table lists the values that can be referenced for each kind of data item.
itemvaluetypeexplanation
molnuminteger molecule number
molnumberinteger molecule number
resnuminteger residue number
resnumberinteger residue number
primnuminteger primary number
primnumberinteger primary number
molnamestring molecule name
resnamestring residue name
atomnamestring atom name
anglenamestring angle name
atomshiftfloat chemical shift of atom
atombfactorfloat B factor of atom
atomvdwfloat van der Waals radius of atom
atomchargefloat partial charge of atom
atomheavychargefloat charges on heavy atoms
atomavgchargefloat averaged charges on heavy atoms
atomsimplechargefloat simple charges from setup file
atomdfloat distance from reference atom(s)
bondlenfloat bond length
anglevalfloat angle
distvalfloat distance
distlimitfloat limit of constraint
distviolfloat violation of constraint
distuplbool true if distance is upper limit
distlolbool true if distance is lower limit
disthbondbool true if distance is H-bond
atomattrinteger graphics attribute index
bondattrinteger graphics attribute index
distattrinteger graphics attribute index
primattrinteger graphics attribute index
You can access values of related data items by using the corresponding prefix, e. g. in an expression for atoms, you can refer to the residue number by res.num.

Properties

The following table lists builtin properties. Builtin properties are properties that are set from within the program. You are free to use them for making selections, but you should normally avoid modifying builitin properties (with the excpetion of selected, movable and displayed), some of them are used by the program itself, and the results of the user modifying them may be unpredictable.
itemnamedescription
anyall Always set for all items. Do not modify!
anyselected Set for selected items. Most commands operate on items that have this property set.
anydisplayed Only items with this property set are displayed. Can be useful for making items (especially molecules) temporarily visible/invisible, use the Molecule Dialog for a convenient way of setting it.
molmovable Only molecules with this property set are affected by interactive manipulations and commands that transform molecules. Useful for moving molecules relative to each other, use the Molecule Dialog for a convenient way of setting it.
atomvisible Set for all atoms that have a display style that makes them visible. Convenient to restrict a selection to only visible items.
bondvisible Set for all bonds that have a display style that makes them visible.
distvisible Set for all distances that have a display style that makes them visible.
primvisible Set for all primitives that have a display style that makes them visible.
The following table lists predefined properties. Predefined properties are properties whose definitions are read from a file (by default setup/PropDef in the installation directory) and evaluated whenever new data is added, e. g. a new molecule loaded.
itemnamedescription
atombb Backbone atoms of a protein or nucleic acid.
bondbb Backbone bonds of a protein or nucleic acid.
atomsc Side chain atoms of a protein or nucleic acid.
bondssc Side chain bonds of a protein or nucleic acid.
atomheavy Heavy atoms.
bondheavy Bonds between two heavy atoms.
atomheavysc Heavy side chain atoms of a protein or nucleic acid.
bondheavysc Bonds between two heavy side chain atoms of a protein or nucleic acid.
atomphos Atoms in phosphate group of a nucleic acid.
bondphos Bonds in phosphate group of a nucleic acid.
atomsugar Atoms in sugar group of a nucleic acid.
bondsugar Bonds in sugar group of a nucleic acid.
atombase Atoms in base of a nucleic acid.
bondbase Bonds in base of a nucleic acid.
atomproton Hydrogen atoms.
atomca Atoms with name CA.
atompseudo Pseudo atoms (name starting with Q).
atomlonepair Lone pair (name starting with LP).

Expression Syntax

This section explains the expressions syntax with text descriptions and examples. A formal expression syntax (in EBNF) can be found on the help page of the
SelectMol command. The page also contains a number of examples of selection expressions.

Constants

There are three types of constants: integer, floating point, and string. Integer constants are automatically converted to floating point when required by the context, e. g. when they are added to a floating point value.

Values

Depending on the context, an expression can use values of a data item. When an expression is evaluated for a data item, it can use the values of this item directly by just using their names. Values for related data items can be accessed by using the form item.value. E. g. when evaluating an expression for an atom, name refers to the name of the atom, while res.name refers to the name of the residue that the atom is part of. The relationships between different data items is explained as part of the section about advanced selection topics.

A table of available values was given in a previous section.

Properties

Properties are similar to the values described in the previous section. One main difference is that they can be defined by the user, either with commands like DefPropAtom, or by adding them to the set of standard properties, as documented in the section about configuration. Another difference to values is that the type of properties is always boolean.

A table of predefined properties was given in a previous section.

Operators

Most common arithmetic and logical operators are supported in expressions. The following table lists all operators with the type of their operands and the type of the result, in order of precedence. Operators with higher precedence are evaluated before operators with lower precedence. Evaluation of operators with the same precedence is left to right. This evaluation order can be changed by using parantheses. The table also indicates whether an operator is unary (has one operand) or binary (has two operands).
operatorkindprecedence operandresultdescription
-unary6 integerintegernumerical negation
-unary6 floatfloatnumerical negation
sqrtunary6 floatfloatsquare root
logunary6 floatfloatnatural logarithm
!unary6 boolboollogical negation
notunary6 boolboollogical negation
*binary5 integerintegermultiplication
*binary5 floatfloatmultiplication
/binary5 integerintegerdivision
/binary5 floatfloatdivision
%binary5 integerintegerremainder
+binary4 integerintegeraddition
+binary4 floatfloataddition
-binary4 integerintegersubtraction
-binary4 floatfloatsubtraction
=binary3 integerboolequal
=binary3 floatboolequal
=binary3 stringboolequal (with wildcards)
!=binary3 integerboolnot equal
!=binary3 floatboolnot equal
!=binary3 stringboolnot equal (with wildcards)
<binary3 integerboolless
<binary3 floatboolless
<=binary3 integerboolless or equal
<=binary3 floatboolless or equal
>binary3 integerboolgreater
>binary3 floatboolgreater
>=binary3 integerboolgreater or equal
>=binary3 floatboolgreater or equal
&binary2 boolboollogical and
andbinary2 boolboollogical and
|binary1 boolboollogical or
orbinary1 boolboollogical or
Note that the string comparison operators support wildcards, ? matches one character, *matches any number of characters.

Advanced Topics

Item Relationships

The data items that can be selected (moelcule, resdiue, atom, bond, angle, distance, primitive) have a hierarchy, e. g. atoms are part of residues, and residues are parts of molecules. The hierarchy is depicted in the following figure:
Thise hierarchy has a direct effect on item selection. When selecting an item, the corresponding items higher in the hierarchy are also selected. E. g. selecting an atom will automatically select the residue and molecule that the atom is part of. On the other hand, deselecting an item does not automatically deselect items higher in the hierarchy.

When traversing the currently selected items, the program will also use this hierarchy, and only traverse deeper into selected items. Because of the automatic selection of items higher in the hierarchy, this is normally transparent to the user. However, if you e. g. first select an atom, and then deselect the corresponding residue, the atom will effectively be deselected.

One way of looking at this mechanism is that selection proceeds upwards in the hierarchy (selects items that are higher), while deselection proceeds downwards (deselects items that are lower).

The hierarchy also affects how values and properties can be accessed in expressions. When an expression is evaluated for an item, the values and properties of items higher in the hierarchy can be accessed with the syntax item.name. For bonds, distances and angles, it is also possible to access the values of the atoms involved. The following table gives a full list of which related items can be accessed from a given kind of item.

itemrelateddescription
resmol molecule of residue
atomres residue of atom
atommol molecule of atom
bondres residue of bond
bondmol molecule of bond
bondatom1 first atom of bond
bondatom2 second atom of bond
bondres1 residue of first atom of bond
bondres2 residue of second atom of bond
angleres residue of dihedral angle
anglemol molecule of dihedral angle
angleatom1 first atom of dihedral angle
angleatom2 second atom of dihedral angle
angleatom3 third atom of dihedral angle
angleatom4 fourth atom of dihedral angle
distmol molecule of distance
distatom1 first atom of distance
distatom2 second atom of distance
distres1 residue of first atom of distance
distres2 residue of second atom of distance
distmol1 molecule of first atom of distance
distmol2 molecule of second atom of distance
primmol molecule of primitive (except for title)

Predicates

The previous section explained how to access values and properties of data items that are higher in the hierarchy than the item for which the expression is evaluated (current item). It is also possible to make selections based on values and properties of items on the same level or lower in the hierarchy than the current item. Since these can be any number of items, they cannot be accessed as single values, but conditions on each of them must be combined with the all or exists predicate. These predicates are directly followed by an item type and an expression in parantheses.

If the item type after the predicate is lower in the hierarchy than the current item, the evaluation will traverse downwards in the hierarchy, and evaluate the expression in parantheses for each of the desired items. E. g. if an expression for a residue is evaluated, and exists atom(expression) is encountered, this expression will be evaluated for all atoms of the residue. It must have a boolean result, the whole expression will be true if at least one of the partial expressions evaluated for the atoms yields true.

If the item type after the predicate is higher in the hierarchy than the current item, the evaluation will traverse upwards in the hierarchy until the parent of the item is encountered. From there on, the evaluation will be performed as described in the previous chapter. E. g. if an expression for an atom is evaluated, and exists bond(expression) is encountered, this expression will be evaluated for all bonds that the atom is part of. The whole expression will be true if all of the partial expressions evaluated for the bonds yield true.

The standard macros contain a few examples of using predicates. mean_sc.mac contains the following commands:

DefPropRes 'well_def' '! exists atom(heavy & bfactor > 1.0)'
SelectAtom 'res.well_def & (ca | heavysc)'
The first command is used to define the property well_def for well defined residues, specified as residues that have no heavy atoms with B factors larger than 1.0. The second command then uses this property to select the CA and heavy side chain atoms of all these well defined residues.

The following command in pdb_charge.mac selects all ASP residues that do not have an HD2 atom:

SelectRes 'name = "ASP" & ! exists atom(name = "HD2")'

6. Command List

The following tables give a complete list of MOLMOL commands. Each table entry gives the name of the command as it would be typed on the command line and a short description of the command. The command names are also links to the full description, corresponding to the online help page of the command.

The commands are listed in several groups:

Input/Output

ReadAngread DIANA dihedral angle file
ReadListAngread list of DIANA dihedral angle files
ReadDgread DG file
ReadListDgread list of DG files
ReadPdbread PDB file
ReadListPdbread list of PDB files
ReadSybylread SYBYL Mol2 file
ReadXyzread XYZ file
ReadSeqread sequence
ReadDumpread dump file
ReadLolread file with lower limits
ReadUplread file with upper limits
ReadAcoread file with angle constraints
ReadShiftread file with chemical shifts
ReadOmapread O electron density map
ReadPotread potentials for surface coloring
ReplaceDgreplace with DG file
ReplaceListDgreplace with list of DG files
ReplacePdbreplace with PDB file
ReplaceListPdbreplace with list of PDB files
ReadLibread and error check residue library
WriteAngwrite DIANA dihedral angle file
WriteDgwrite DG file
WriteSeqwrite sequence
WriteDumpwrite dump file
WriteLolwrite file with lower limits
WriteUplwrite file with upper limits
WriteLibwrite entries for residue library
WriteRotationwrite current rotation
WriteSecondarywrite macro with secondary structure

Modify Molecules

NewMolcreate new molecule
MeanMolcreate mean molecule
NameMolchange molecule name
FirstMolmove molecules to front of molecule list
RemoveMolremove molecules
AddResadd residue to molecule
ChangeReschange residue type
RemoveResremove residues
AddAtomadd new atom
AddPseudoadd new pseudo atom
FlipAtomflip atoms for better superposition
RemoveAtomremove atoms
AddBondadd bond between two atoms
RemoveBondremove bonds
AddDistadd distance between two atoms
AddHbondadd H-bond between two atoms
AddLoladd lower limit between two atoms
AddUpradd upper limit between two atoms
RemoveDistremove distances
AddAngleadd dihedral angle
RotateAnglerotate dihedral angles
SetAnglerotate dihedral angles
RemoveAngleremove angles
AddAcoadd angle constraints
RemoveAcoremove angle constraints

Primitives

AddTitleadd 2D text annotation
AddTextadd 3D text annotation
EditTextedit text annotation
SizeTextresize text
AddDrawobjadd line, rectangle or circle
MoveDrawobjmove draw object
StyleDrawobjset display style of draw objects
SetNeighset sheet neighbours of residues
AddRibbonadd ribbons (schematic drawing)
SplitRibbonsplit ribbons
TypeRibbonset type of ribbons
StyleRibbonset display style of ribbons
SizeRibbonset sizes of ribbons
PaintRibbonset coloring style of ribbons
AddPlatesadd plates for rings
SizePlateset sizes of plates
AddSurfaceadd surface
TrimSurfacecut away part of a surface
PaintSurfaceset coloring style of surfaces
AddIsosurfaceadd isosurface of potential
AddTrajecadd trajectories
StyleTrajecset display style of trajectories
AddCirclesadd circles around atoms
AddCylinderadd cylinder for schematic drawing
AddDipoleadd arrow showing dipolar moment
StyleCylinderset display style of cylinders
AddSheetadd sheet for schematic drawing
AddSolidadd solid for schematic drawing
StyleMapset display style of density map
ColorPrimchange color of primitives
TintPrimchange secondary color of primitives
LinePrimset style and width of primitive lines
ShadePrimset shading of primitives
RadiusPrimset radius of primitives
NearPrimset near clipping plane of primitives
MovePrimmove primitive
LengthPrimset length of primitives
RemovePrimremove primitive

Display

ZoomAbszoom absolute
ZoomRelzoom relative
Fullscreenswitch fullscreen display on and off
DrawSizeset size of drawing area
Stereoset stereo mode
StartRockstart rock
StopRockstop rock
StartAnimstart animation
StopAnimstop animation
BondModechoose bond display mode
BackColorchange background color
Projectionchoose projection
ClipPosset position of clipping planes
ClipSizeset distance of clipping planes
ViewAngleset view angle
Lightsetup of light source
Fogsetup of fog (depth cueing)
Renderingset rendering options
DrawDelayset drawing delay
DrawPrecset drawing precision

Movement

Centerchange rotation center
Fitcalculate structure superpositions
MoveInitundo all translations
MoveXmove molecule in X direction
MoveYmove molecule in Y direction
MoveZmove molecule in Z direction
RotateInitundo all rotations
RotateXrotate molecule around X axis
RotateYrotate molecule around Y axis
RotateZrotate molecule around Z axis
AutoScalescale/translate molecules to window size

User Interface

UserInterfaceswitch elements of user interface
DialSelectswitch selection dialog on and off
DialMolswitch molecule dialog on and off
DialColorswitch color dialog on and off
DialStyleswitch style dialog on and off
DialMeasureswitch measurement dialog on and off

Selection

SelectMolselect molecules
SelectResselect residues
SelectAtomselect atoms
SelectBondselect bonds
SelectAngleselect angles
SelectDistselect distances
SelectPrimselect primitives
DefPropMoldefine molecule property
DefPropResdefine residue property
DefPropAtomdefine atom property
DefPropBonddefine bond property
DefPropAngledefine angle property
DefPropDistdefine distance property
DefPropPrimdefine primitive property
ListSelectedMollist selected molecules
ListSelectedReslist selected residues
ListSelectedAtomlist selected atoms
ListSelectedBondlist selected bonds
ListSelectedAnglelist selected angles
ListSelectedDistlist selected distances
ListPropMollist all molecule properties
ListPropReslist all residue properties
ListPropAtomlist all atom properties
ListPropBondlist all bond properties
ListPropAnglelist all angle properties
ListPropDistlist all distance properties
ListPropPrimlist all primitive properties
SetRefset reference atoms
UndefPropundefine property

Attributes

ColorAtomset color of atoms
ColorBondset color of bonds
ColorDistset color of distances
ColorInitset initial color
TintDistset secondary color of distances
TintInitset initial secondary color
LabelAtomset format of atom label
LabelDistchoose label of distances
LabelInitset initial format of labels
LineAtomset style and width of atom lines
LineBondset style and width of bond lines
LineDistset style and width of distance lines
LineInitset initial style and width of lines
RadiusAtomset radius of atoms
RadiusBondset radius of bonds
RadiusDistset radius of distances
RadiusInitset initial radius
MaterialAtomset material properties of atoms
MaterialBondset material properties of bonds
MaterialDistset material properties of distances
MaterialPrimset material properties of primitives
MaterialInitset initial material properties
TextureAtomset texture of atoms
TextureBondset texture of bonds
TextureDistset texture of distances
TexturePrimset texture of primitives
TextureInitset initial texture
ShadeAtomset shading of atoms
ShadeBondset shading of bonds
ShadeDistset shading of distances
StyleAtomset display style of atoms
StyleBondset display style of bonds
StyleDistset display style of distances
StyleInitset initial display styles
AttrAtomlist attributes of atoms
AttrBondlist attributes of bonds
AttrDistlist attributes of distances
AttrPrimlist attributes of primitives
AttrInitlist initial attributes

Plotting

PlotUnitset unit of plot parameters
PlotParset plot parameters
PlotPsmake a PostScript plot
PlotFm3make a FrameMaker 3 plot
PlotFm4make a FrameMaker 4 plot
PlotMetamake a Windows enhanced metafile plot
PlotTiffmake a TIFF plot
PlotJpegmake a JPEG plot
PlotPngmake a PNG plot
PlotBmpmake a BMP (Windows bitmap) plot
PlotPovmake a POV-Ray plot
PlotMpovmake a MegaPov plot
PlotRibmake a RenderMan plot
PlotVrml1make a VRML 1.0 plot
PlotVrml2make a VRML 2.0 (VRML97) plot

Calculations

CalcSecondarycalculate secondary structure
CalcRmsdcalculate RMSDs and displacements
CalcMatchcalculate best matching structure parts
CalcClusterreduce number of structures
CalcSurfacecalculate solvent accessible surface
CalcPotcalculate electrostatic potential
CalcShiftcalculate ring current shifts
CalcAtomcalculate missing atom coordinates
CalcBondcalculate bonds between close atoms
CalcHbondfind H-bonds
CalcVdwfind Van der Waals violations
CalcDistfind short distances between atoms
CalcAnglecalculate angular order parameters
CalcHelixcalculate angles between helix axes
CalcAxiscalculate lengths of principal axes
CheckBondcheck number of bonds
CheckUplcheck upper limits
CheckLolcheck lower limits
CheckAcocheck angle constraints

Figures

FigRamachRamachandran plot
FigAnglesshow angle distribution bars
FigCirclesshow angle distribution circles
FigDistshow distance vs. structure number
FigContactshow contact map
FigLimitshow map of distance constraints
FigOffswitch from figure to normal display

Miscellaneous

Groupdefine molecule groups
LengthBondset length of bonds for display
HelpViewerset viewer for help files
HelpAproposlocate commands by keyword
HelpCmdget help on command
HelpMouseshow help text about using the mouse
HelpButtonshow definition of buttons
HelpPropshow definition of standard properties
HelpManualshow manual in web browser
HelpTutorialshow tutorial in web browser
HelpIndexshow HTML command index
HelpTipshow "Tip of the Day"
HelpAboutshow program version and copyright
SetUndoset the number of possible undos
Undoundo effect of last command
XMacStandexecute standard macro
XMacUserexecute user macro
RecordMacopen macro recorder
PathNamesset path names
InitAlldelete and initialize everything
Systemexecute operating system command
Registerregister as MOLMOL user
Quitquit the program

7. Standard Macros

The subdirectory macros of your MOLMOL installation contains some standard macros. Some of them are used by
buttons. All of them can be executed using the XMacStand command. These standard macros are commented, you can use them as instructive examples or basis for your own macros.
color_atom.mac
Set color of selected atoms to "standard" colors (red for O, yellow for S, etc.), e. g. for CPK model.
cpk.mac
Display currently selected parts as CPK. For selected atoms, sets color to standard color, display style to sphere and radius to VdW radius. Makes selected bonds and distances invisible.
ball_stick.mac
Display currently selected parts as ball and stick. For selected atoms, sets color to standard color, display style to sphere and radius to 0.3 times VdW radius. Sets style of selected bonds to half_cylinder.
ca_trace.mac
Display a CA trace for selected resdiues by adding a distance between CA atoms of subsequent residues.
ribbon.mac
Make ribbon drawing of selected residues. Makes selected atoms and bonds invisible.
sausage.mac
Draw spline with variable radius for bundle of structures. Calculates a mean structure, and adds a spline (ribbon) with the average displacement of the CA atoms to the mean structure as the radius.
mean_sc.mac
Draw bonds between heavy atoms of side chains of well defined residues as cones, using the B-factor of atoms as radius, draw other other side chains as sticks. Can e. g. be used for drawing side chains of the mean structure calculated as part of sausage.mac.
schem_dna.mac
Make schematic display of selected DNA/RNA residues. Only sequential residues from one strand should be selected, the macro must be invoked for each strand separately. Draws ribbon through the backbone of the strand, and displays rings as plates in a different color for each base type.
temper.mac
Set color of selected atoms and bonds based on B-factor, using a blue - red - yellow scale for values from 0 to 50.
pdb_charge.mac
Change residue types of potentially charged residues in selected molecules to properly reflect charge.
black_white.mac
Set material properties of all items, background color, and light source position for good looking black and white plot.

8. User Macros

In addition to the
standard macros supplied with MOLMOL, you can write your own macros, and execute them using the XMacUser command. The default extension for macros is .mac.

Writing Macros

You can write macros from scratch using a text editor. If the macro you plan to write is similar to one of the standard macros, you may want to start with a copy of that, or at least look at it as an example.

A more convenient way to build macros is using the macro recorder available in MOLMOL. You can start the macro recorder with the RecordMac command. It allows you to execute commands in the normal environment (using menus and dialog boxes), record them selectively, and then save the resulting macro.

A history of your session is kept in the file molmol/history of your home/profile directory. It can also serve as starting point for macros.

Defining Commands

In addition to simple sequences of commands that are immediately executed when the macro is executed, macros can also contain command definitions. A command definition has the form:
define CommandName
help one-line-help
$arg1 = default1 prompt1
..
$argN = defaultN promptN
Command1
..
CommandN
end
The name of the new command is specified after the <define keyword. This is normally followed by a short help message, introduced with the help keyword. An arbitrary number of arguments can be given, each followed by (optional) default values and prompt strings. The arguments are followed by a series of commands that define the functionality of the new command. Arguments are referenced in the form $argName or ${argName}.

The following example defines a new command for adding a partial surface:

define AddPatch
  help create partial surface for selected atoms
  $rad = 1.4 "Solvent Radius"
  DefPropAtom 'surf' 'selected'
  SelectAtom 'mol.selected'
  AddSurface (vdw) contact $rad shaded 0
  SelectAtom 'mol.selected & ! surf'
  TrimSurface ($rad + 0.1)
  SelectAtom 'surf'
end
When such a definition is encountered, the commands used for the definition are not executed, the only effect is that the definition is added to the MOLMOL command list. It can then be used like one of the builtin commands.

If you want to extend the program with your own set of commands, it is especially useful to have the macro definining them be automatically executed each time you start up the program. See the section on Configuration for a description of how to do that.

Executing Macros

You can execute macros anytime using the XMacUser command. You can also add menu entries or buttons to give you more convenient access to frequently used macros, or have them being executed automatically when you start the program, or whenever a new molecule is loaded. See the section on Configuration for a description of these possibilities.

9. Configuration and Customization

Startup Macros

One powerful way to customize and extend MOLMOL is by using macros that are automatically started each time you start the program. The following macros are executed on startup if the files exist:
  1. setup/startup.mac in the installation directory
  2. all files with the extension .mac in the directory setup/startup in the installation directory
  3. molmol/startup.mac in your home/profile directory
  4. all files with the extension .mac in the directory molmol/startup in your home/profile directory
You can use any MOLMOL command in these startup macros, but especially useful in this context are command definitions, as described in the
User Macros section. These allow you to extend the functionality of the program with your own commands. These commands will automatically be accessible from the Opt menu.

Another set of commands that is very useful for startup macros are the commands for setting default graphics attributes, like ColorInit and StyleInit. So if you would like new graphics elements to be displayed in red instead of the default blue, you can put the following command into one of your startup macros:

ColorInit 1 0 0

New Molecule Macros

By default, MOLMOL displays all newly loaded molecules in line mode. You can change that by writing a macro that gets automatically executed each time a new molecule is loaded. The program will check for such a macro in the following locations:
  1. setup/newmol.mac in the installation directory
  2. molmol/newmol.mac in your home/profile directory
While the macro is executed, the newly loaded molecules have the property new set. This makes it possible to change the display style of only the new molecule, without affecting molecules that are already loaded. E. g. if you want all new molecules to be displayed in CPK mode, put the following macro into one of the locations above:
SelectAtom 'mol.new'
SelectBond 'mol.new'
XMacStand cpk.mac

Setup Files

MOLMOL obtains a lot of configuration information from simple text files which can easily be modified or replaced. The default files can be found in the subdirectory setup of your installation. If you want to make a change for all users of the installation, you have the option to edit these files directly. The preferable and safer way to change configuration files, especially for individual users, is to make a copy of the original file e. g. to your home directory, and then use the PathNames command of MOLMOL to instruct the program to use your modified file.

The location of the following files can be changed directly with the PathNames command:

AtomRadius
Atom radii for finding bonds, a bond is detected if the distance between two atoms is less than the sum of the two radii. Used by the commands CalcBond and ReadXyz.
AtomCharge
Formal charges for atoms, each line has the format:
ResidueName AtomName Charge
The residue name can contain wildcards. These charges are used whenever the simplecharge value of an atom is accessed, e. g. for the CalcPot command.
FlipAtoms
Defines groups of atoms that can be flipped by the FlipAtom command.
RingShift
Defines paramter sets for the CalcShift command.
PdbAtoms
Name translation table to map atom names from PDB files to names in the residue library. The residue name can contain wildcards.
PropDef
Definition of predefined properties.
ColorList
Definition of color names for the color dialog.
With the MenuDir entry of the PathNames command, you can specify an alternate directory where the program looks for the following files defining the user interface:
MenuBar
List of pulldown menus in the menu bar. Each pulldown menu is defined in its own file with the extension .menu.
*.menu
Contents of pulldown menu that is part of MenuBar.
Buttons
Definition of buttons on right side of main window.
Popup
Definition of popup (righ mouse button) menu.
Valuator
Definition of sliders in valuator box.
Note that all these parts of the user interface can also be disabled completely with the UserInterface command.

Residue Libraries

The residue library works much like the other setup files explained in the previous section, its location is also set with the PathNames command, but it is so important for the operation of MOLMOL that its description was separated from the rest of the files. The residue library contains definitions of residues (monomers) that are used whenever a macromolecule is read from a file. These residue definitions contain: MOLMOL can still read files even if they contain residues that are not part of the residue library. It will display a warning, and since it does not have any connectivity information, will not display bonds for these residues. In most cases these bonds can easily be added with the CalcBond command.

When a small molecule is read with the ReadSybyl or ReadXyz command , MOLMOL will either take the connectivity information from the input file, or add the bonds automatically. Entries in the residue library are not necessary in this case, only the ATOMTYPES section of the residue library is used.

The format of the residue library corresponds to the one used by the program DYANA, it is documented in the manual which is accessible from the web page. Three libraries are distributed with MOLMOL, all of them contain standard amino acids and nucleic acids.

amber94.lib
Standard geometry minimized with the AMBER94 force field, naming conventions from DYANA.
dyana.lib
Original DYANA library.
pdb.lib
Like amber94.lib, but using PDB naming conventions.
MOLMOL uses amber94.lib by default. If you frequently read PDB files and do not use DYANA, it may be preferable to use pdb.lib. If you decide to do that, you should disable the use of the default PdbNames file. The following command will do that:
PathNames '' '' '' '' '0' '' '/usr/local/molmol/setup/pdb.lib' '' ''
If you need to add entries to the residue library, the WriteLib command of MOLMOL can help you doing this. After you modify the library, it is a good idea to check it with the ReadLib command.

10. Features

11. MOLMOL Tutorial

This document shows the use of MOLMOL in some examples. It is meant to be used together with the manual (users guide). Each example will first show a picture and give commented step by step instructions on how it can be created.

Notation

The commands are listed with all arguments in the way they appear in the log window and history. They can be entered on the command line in this form, but this is not what you would normally do. Every command can be activated from a pulldown menu, and the arguments can be entered in the dialog box that will appear. If this is the preferred way, it will be indicated with the notation Menu->Submenu->Entry below the command. Frequently used commands or combinations can also be activated from the buttons on the right side of the window. This is indicated by Button:name. Some actions are normally done with the mouse, this is indicated by Mouse. Other actions are most convenietly carried out by using one of the dialog boxes, this is indicated by Dialog:name. The dialogs can be opened by clicking the corresponding buttons (selection, style, color).

Whenever a command appears in the text, it can be used as link to the corresponding online manual page.

Preconditions

All examples are based on the NMR structure of BPTI determined by K. Berndt et al., this file is stored as data/1pit.pdb in your MOLMOL distribution. The tutorial assumes that you start the program from the directory that contains this file. Note that menus, buttons etc. can be configured by the system adminstrator or user. This tutorial assumes that the program is in its default configuration.

Examples

Example 1: Neon Figure of Bundle with Sidechains in Different Colors

Example 2: Ribbon Display

Example 3: "Sausage" Display

Example 4: Surface with Electrostatic Potential

MOLMOL Tutorial - Example 1

Image

On this page, we will show how to create the following picture:

Steps

UserInterface 0 0 1 1 1 1
(Options->User Interface)
Switch the Valuator Box and the Log Window off. We will not make use of these two here.

ReadPdb 1pit.pdb
(File->Read Mol->PDB)
Read the structures from the given file in PDB format.

DialStyle on
(Button:style)
Open the style dialog.

StyleBond invisible
(Dialog:Style)
When you want to show only part of the bonds, it's often most convenient to make everything invisible first and then "build up" the visible parts piece by piece. Everything is selected by default, so this will make all bonds invisible.

DialSelect on
(Button:selection)
Open the selection dialog.

SelectBond 'bb'
(Dialog:Select)
Now we select all bonds in the backbone. bb is a shortcut for that, a so called "predefined property". Activate the HelpProp (Help->Prop) command for getting a list of all predefined properties. The definitons will also give you an impression of how the full MOLMOL expression syntax looks, in this tutorial we will mostly use shortcuts.

StyleBond line
(Dialog:Style)
Now we see only the backbone drawn with lines.

SelectAtom ':2-56 & bb'
(Dialog:Selection)
Fit to_first
(Edit->Fit)
The structures in the example file were already superimposed, but for demonstration purposes we do it again. We just use the backbone atoms of residues 2 to 56 for superposition, & is short for and.

You can now also try to rotate and zoom the structure. See HelpMouse (Help->Mouse) for a description on how to use the mouse.

DefPropRes 'inter' ':2,4,6,8,9,11,16,18,19,21-25,27,30,32-35,38,40,43,45,47,48,51,54'
(Prop->Define->Res)
We will display the well-defined (interiour) sidechains different from the other ones. We could select them with the residue numbers each time, but we can also define our own shortcut (property) that we can use each time we want to select these.

SelectBond 'res.inter & heavysc'
(Dialog:Select)
We now select the bonds to heavy atoms in the well-defined sidechains using the inter property that we just defined (since we defined it for residues, we have to write res.inter if we want to use if for bonds) and the predefined property heavysc (for heavy sidechain).

DialColor on
(Button:color)
Open the color dialog.

StyleBond line
(Dialog:Style)
ColorBond 1 0 0
(Dialog:Color)
Draw the selected bonds as red lines. The commands take colors as RGB (Red-Green-Blue) values, the color dialog allows you to choose the most common colors by name.

SelectBond '! res.inter & heavysc'
(Dialog:Select)
Select the rest of the sidechains. ! is short for not.

StyleBond line
(Dialog:Style)
ColorBond 0 1 0 (Dialog:Color)
Draw the selected bonds as green lines.

SelectBond 'visible'
(Dialog:Select)
So far we just displayed bonds as lines, mainly because it makes the display much faster. We now select all visible bonds...

StyleBond neon
(Dialog:Style)
... and display them as neon (cylinder with round ends).

RadiusBond 0.15
(Button:bond rad)
Make the cylinders somewhat thinner.

PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
(Options->Plot->Parameters)
Adapt the plot paramters to our needs. Read the online manual page carefully, understanding these parameters is very important for using the program successfully!

PlotTiff example1.tif
(File->Plot->TIFF)
Create a TIFF plot. External tools were used for the conversion to GIF used for this page.

WriteDump example1.mml
(File->Write Dump)
Save the current state for later use.

Quit no
(File->Quit)
Quit the program. Because we already saved a dump file, there is no need for saving the program state again.

Macro

The following is a summary of the executed commands, you can cut'n'paste it, edit it to your needs, and use it as macro:
UserInterface 0 0 1 1 1 1
ReadPdb 1pit.pdb
DialStyle on
StyleBond invisible
DialSelect on
SelectBond 'bb'
StyleBond line
SelectAtom ':2-56 & bb'
Fit to_first
DefPropRes 'inter' ':2,4,6,8,9,11,16,18,19,21-25,27,30,32-35,38,40,43,45,47,48,51,54'
SelectBond 'res.inter & heavysc'
DialColor on
StyleBond line
ColorBond 1 0 0
SelectBond '! res.inter & heavysc'
StyleBond line
ColorBond 0 1 0
SelectBond 'visible'
StyleBond neon
RadiusBond 0.15
PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
PlotTiff example1.tif
WriteDump example1.mol
Quit no

MOLMOL Tutorial - Example 2

Image

On this page, we will show how to create the following picture:

Steps

UserInterface 0 0 1 1 1 1
(Options->User Interface)
Switch the Valuator Box and the Log Window off. We will not make use of these two here.

ReadPdb 1pit.pdb
(File->Read Mol->PDB)
Read the structures from the given file in PDB format.

DialSelect on
(Button:selection)
Open the selection dialog.

SelectMol 'num > 1'
(Dialog:Select)
We only want to make a schematic drawing of the first of the 20 structures, so we select all but the first...

RemoveMol
(Edit->Structure->Remove Mol)
... and remove them.

SelectAtom ''
(Dialog:Select)
The standard orientation for BPTI is the one where the pricipal axes are aligned to the coordinate axes. So we select all atoms...

Fit to_axes
(Edit->Fit)
... and do the alignment.

XMacStand ribbon.mac
(File->Macro->Execute Standard)
Use the standard macro for creating a ribbon display. If you are interested in the detailed commands used to do all of the steps manually, have a look at this macro. We could have used Button:ribbon instead, but this would have done an automatic determination of the secondary structure first, while we preferred to use the definitions from the PDB file in this case.

DialColor on
(Button:color)
Open the color dialog.

BackColor 0 0 0
(Dialog:Color)
Change the background color to black.

SelectPrim 'num = 10'
(Mouse)
The second helix seems to be defined too long. So we select it by clicking on it with the mouse...

LengthPrim 46 55
(Prim->Length)
... and make it half a residue shorter at each end.

You could now use commands like SplitRibbon, StyleRibbon, SizeRibbon and ColorPrim to modify the display, but for the moment we are happy with the default.

PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
(Options->Plot->Parameters)
Adapt the plot paramters to our needs. Read the online manual page carefully, understanding these parameters is very important for using the program successfully!

PlotTiff example2.tif
(File->Plot->TIFF)
Create a TIFF plot. External tools were used for the conversion to GIF used for this page.

WriteDump example2.mml
(File->Write Dump)
Save the current state for later use.

Quit no
(File->Quit)
Quit the program. Because we already saved a dump file, there is no need for saving the program state again.

Macro

The following is a summary of the executed commands, you can cut'n'paste it, edit it to your needs, and use it as macro:
UserInterface 0 0 1 1 1 1
ReadPdb 1pit.pdb
DialSelect on
SelectMol 'num > 1'
RemoveMol
SelectAtom ''
Fit to_axes
XMacStand ribbon.mac
DialColor on
BackColor 0 0 0
SelectPrim 'num = 10'
LengthPrim 46 55
PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
PlotTiff example2.tif
WriteDump example2.mol
Quit no

MOLMOL Tutorial - Example 3

Image

On this page, we will show how to create the following picture:

Steps

UserInterface 0 0 1 1 1 1
(Options->User Interface)
Switch the Valuator Box and the Log Window off. We will not make use of these two here.

ReadPdb 1pit.pdb
(File->Read Mol->PDB)
Read the structures from the given file in PDB format.

The structures have to be superimposed for the next step. In our example they are already, otherwise we would do that here as explained in Example 1

XMacStand sausage.mac
(File->Macro->Execute Standard)
Use the standard macro for creating a sausage display. If you are interested in the detailed commands used to do all of the steps manually, have a look at this macro.

DialSelect on
(Button:selection)
Open the selection dialog.

SelectMol 'name != "mean"'
(Dialog:Select)
The macro created a mean structure. We can get rid of the original 20 structures now, so we select all but the mean structure...

RemoveMol
(Edit->Structure->Remove Mol)
... and remove them.

DialStyle on
(Button:style)
Open the style dialog.

SelectBond ''
(Dialog:Select)
StyleBond invisible
(Dialog:Style)
The bonds of the mean structure are still visible, select all bonds and make them invisible

SelectAtom ''
(Dialog:Select)
The standard orientation for BPTI is the one where the pricipal axes are aligned to the coordinate axes. So we select all atoms...

Fit to_axes
(Edit->Fit)
... and do the alignment.

We now have the basic sausage display. Now you will learn how to use "variable color", i. e. a separate color for each residue. We will use the secondary structure type for determining the color, it is also common to use physical properties like exchange rates.

CalcSecondary
(Calc->Secondary)
So we calculate the secondary structure first.

PaintRibbon atom
(Prim->Ribbon->Paint)
This causes the color of each sausage part to be taken from the atom that was used to define it. Because atoms also have a blue default color, there is no visible change yet.

DialColor on
(Button:color)
Open the color dialog.

SelectAtom '@CA'
(Dialog:Selection)
ColorAtom 0.7 0.7 0.7
(Dialog:Color)
The macro that we used took the CA atoms to define the sausage, so we have to set the color of the CA atoms. We first select all CA atoms and color them grey.

SelectAtom '@CA & res.helix'
(Dialog:Selection)
ColorAtom 1 0 0
(Dialog:Color)
Then we select all CA atoms within helices and color them red.

SelectAtom '@CA & res.sheet'
(Dialog:Selection)
ColorAtom 0 1 1
(Dialog:Color)
In the same way we color all CA atoms within a sheet cyan.

BackColor 0 0 0
(Dialog:Color)
Change the background color to black.

PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
(Options->Plot->Parameters)
Adapt the plot paramters to our needs. Read the online manual page carefully, understanding these parameters is very important for using the program successfully!

PlotTiff example3.tif
(File->Plot->TIFF)
Create a TIFF plot. External tools were used for the conversion to GIF used for this page.

WriteDump example3.mml
(File->Write Dump)
Save the current state for later use.

Quit no
(File->Quit)
Quit the program. Because we already saved a dump file, there is no need for saving the program state again.

Macro

The following is a summary of the executed commands, you can cut'n'paste it, edit it to your needs, and use it as macro:
UserInterface 0 0 1 1 1 1
ReadPdb 1pit.pdb
XMacStand sausage.mac
DialSelect on
SelectMol 'name != "mean"'
RemoveMol
DialStyle on
SelectBond ''
StyleBond invisible
SelectAtom ''
Fit to_axes
CalcSecondary
PaintRibbon atom
DialColor on
SelectAtom '@CA'
ColorAtom 0.7 0.7 0.7
SelectAtom '@CA & res.helix'
ColorAtom 1 0 0
SelectAtom '@CA & res.sheet'
ColorAtom 0 1 1
BackColor 0 0 0
PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
PlotTiff example3.tif
WriteDump example3.mol
Quit no

MOLMOL Tutorial - Example 4

Image

On this page, we will show how to create the following picture:

Steps

UserInterface 0 0 1 1 1 1
(Options->User Interface)
Switch the Valuator Box and the Log Window off. We will not make use of these two here.

ReadPdb 1pit.pdb
(File->Read Mol->PDB)
Read the structures from the given file in PDB format.

DialSelect on
(Button:selection)
Open the selection dialog.

SelectMol 'num > 1'
(Dialog:Select)
We only want to plot of the surface of the first of the 20 structures, so we select all but the first...

RemoveMol
(Edit->Structure->Remove Mol)
... and remove them.

SelectAtom ''
(Dialog:Select)
The standard orientation for BPTI is the one where the pricipal axes are aligned to the coordinate axes. So we select all atoms...

Fit to_axes
(Edit->Fit)
... and do the alignment.

XMacStand pdb_charge.mac
(File->Macro->Execute Standard)
For calculating the electrostatic potential, it is very important to have the proper charge for all residues. Since the charges are normally not given in a PDB file, we call this macro that does the typically necessary changes, like GLU to GLU-. You should manually check whether all charges are correct before calculating the potential. In this case we notice that we are missing the charges at the termini, because the sequence in the file just starts with an ARG and ends with an ALA.

SelectRes ':1'
(Dialog:Select)
So we select the first residue...

ChangeRes atoms 'NARG'
(Edit->Structure->Change Res)
And convert it to NARG, the form of ARG with an N-terminal group, maintaining the old coordinates.

CalcAtom 'HN*'
(Calc->Atom)
It is not really needed for this example, but for demonstration purpose we calculate the coordinates of the HN2 and HN3 that are missing because these atoms did not exist in the ARG residue that we originally read from the file.

SelectRes ':58'
(Dialog:Select)
The same way we select the last residue...

ChangeRes atoms 'CALA'
(Edit->Structure->Change Res)
... convert it to CALA, the form of ALA with a C-terminal group...

CalcAtom 'O*'
(Calc->Atom)
... and calculate the coordinates of OA and OB. These we actually need, because they hold charges.

SelectAtom 'heavy'
(Dialog:Select)
We only use the heavy atoms for calculating potential and surface. If protons are also used, they "dampen" the charges visible at the surface, which leads to less clear pictures.

CalcPot (vdw) (simplecharge) 2 80 1.4 2 2 10 zero 'bpti.pot'
(Calc->Potential)
Now we can calculate the electrostatic potential, storing the result in the file bpti.pot. Check the help page for details about the arguments. We accept the defaults, except for the charge, where we choose the simple model without partial charges, only charges located on one or two atoms of each charged residue. Note that the current drawing precision (see DrawPrec) determines the grid width for the calculation, we keep the default of 3 that leads to a grid spacing of 1 Angstrom.

AddSurface (vdw) contact 1.4 shaded
(Prim->Surface->Add)
Calculate the contact surface.

ReadPot bpti.pot
(File->Read Potential)
Read the previously calculated potential. The values are now mapped onto the surface, so this step has to be executed after calculating the surface.

PaintSurface pot 0.0 1.4 0.2 3 '-0.3 1 0 0 0.0 1 1 1 0.3 0 0 1'
(Prim->Surface->Paint)
Define how the surface is colored. We choose calculating the color from the previously read potential. The second to fifth arguments are not used in this case, the last argument gives the mapping from potential to color, see the help page for details.

PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
(Options->Plot->Parameters)
Adapt the plot paramters to our needs. Read the online manual page carefully, understanding these parameters is very important for using the program successfully!

PlotTiff example4.tif
(File->Plot->TIFF)
Create a TIFF plot. External tools were used for the conversion to GIF used for this page.

WriteDump example4.mml
(File->Write Dump)
Save the current state for later use.

Quit no
(File->Quit)
Quit the program. Because we already saved a dump file, there is no need for saving the program state again.

Macro

The following is a summary of the executed commands, you can cut'n'paste it, edit it to your needs, and use it as macro:
UserInterface 0 0 1 1 1 1
ReadPdb 1pit.pdb
DialSelect on
SelectMol 'num > 1'
RemoveMol
SelectAtom ''
Fit to_axes
XMacStand pdb_charge.mac
SelectRes ':1'
ChangeRes atoms 'NARG'
CalcAtom 'HN*'
SelectRes ':58'
ChangeRes atoms 'CALA'
CalcAtom 'O*'
SelectAtom 'heavy'
CalcPot vdw simplecharge 2 80 1.4 2 2 10 zero 'bpti.pot'
AddSurface vdw contact 1.4 shaded
ReadPot bpti.pot
PaintSurface pot 0.0 1.4 0.2 3 '-0.3 1 0 0 0.0 1 1 1 0.3 0 0 1'
PlotPar 21 29.7 18 0 500 0 1 1 0 3 1.0 75
PlotTiff example4.tif
WriteDump example4.mol
Quit no

Last modified: Sun Mar 12 16:58:10 CST 2000

Reto Koradi, kor@mol.biol.ethz.ch