The Coot User Manual

1. Introduction
2. Mousing and Keyboarding
3. General Features
4. Coordinate-Related Features
5. Modelling and Building
6. Map-Related Features
7. Validation
Index		Complete index.

1. Introduction

1.1 Citing Coot and Friends
1.2 What is Coot?
1.3 What Coot is Not
1.4 Hardware Requirements
1.5 Environment Variables
1.6 Command Line Arguments
1.7 Web Page
1.8 Crash

1.1 Citing Coot and Friends

If have found this software to be useful, you are requested (if appropriate) to cite:

"Coot: model-building tools for molecular graphics" Emsley P, Cowtan K Acta Crystallographica Section D-Biological Crystallography 60: 2126-2132 Part 12 Sp. Iss. 1 DEC 2004

The reference for the REFMAC5 Dictionary is:

REFMAC5 dictionary: "Organization of Prior Chemical Knowledge and Guidelines for its Use" Vagin AA, Steiner RA, Lebedev AA, Potterton L, McNicholas S Long F, Murshudov GN Acta Crystallographica Section D-Biological Crystallography 60: 2184-2195 Part 12 Sp. Iss. 1 DEC 2004"

If using "SSM Superposition", please cite:

"Secondary-structure matching (SSM), a new tool for fast protein structure alignment in three dimensions" Krissinel E, Henrick K Acta Crystallographica Section D-Biological Crystallography 60: 2256-2268 Part 12 Sp. Iss. 1 DEC 2004

1.2 What is Coot?

Coot is a stand-alone portion of CCP4's Molecular Graphics project. Its focus is crystallographic model-building and manipulation rather than representation i.e. more like Frodo than Rasmol .

Coot is Free Software. You can give it away. If you don't like the way it behaves, you can fix it yourself.

1.3 What Coot is Not

Coot is not:

• CCP4's official Molecular Graphics program (1)

• a program to do refinement (2)

• a protein crystallographic suite(3).

1.4 Hardware Requirements

The code is designed to be portable to any Unix-like operating system. Coot certainly runs on SGI IRIX64, RedHat Linux of various sorts, SuSe Linux(4) and MacOS X (10.2). The sgi Coot binaries shouold also work on IRIX.

If you want to port to some other operating system, you are welcome (5). Note that your task will be eased by using GNU GCC to compile the programs components.

1.4.1 Mouse

1.5 Environment Variables

• COOT_STANDARD_RESIDUES The filename of the pdb file containing the standard amino acid residues in "standard conformation" (7)
• COOT_SCHEME_DIR The directory containing auxiliary scheme files
• COOT_REF_STRUCTS The directory containing a set of high resolution pdb files used as reference structures to build backbone atoms from C\alpha positions
• COOT_REFMAC_LIB_DIR Refmac's CIF directory containing the monomers and link descriptions. In the future this may simply be the same directory in which refmac looks to find the library dictionary.
• COOT_RESOURCES_DIR The directory that contains the splash screen image and the GTk application resources.
• COOT_BACKUP_DIR The directory to which backup are written (if it exists as a directory). If it is not, then backups are written to the current directory (the directory in which coot was started).

• PYTHONPATH (for python modules)
• GUILE_LOAD_PATH (for guile modules)

Normally, these environment variables will be set correctly in the coot setup script (which can be found in the setup directory in the binary distribution. See the web site (Section 1.7 Web Page) for setup details.

1.6 Command Line Arguments

• --script to run a script on start up (but see Section 3.8 Scripting)
• --no-state-script don't run the 0-coot.state.scm script on start up
• --pdb for pdb/coordinates file
• --coords for SHELX .ins/.res and CIF files
• --data for mtz, phs or mmCIF data file
• --auto for auto-reading mtz files (mtz file has the default labels FWT, PHWT)
• --map for a map (currently CCP4-format only)
• --dictionary read in a cif monomer dictionary
• --help print command line options
• --stereo start up in hardware stereo mode
• --version print the version of coot

So, for example, one might use:

• coot --pdb post-refinement.pdb --auto refmac-2.mtz --dictionary lig.cif

1.7 Web Page

• http://www.ysbl.york.ac.uk/~emsley/coot

There you can read more about the CCP4 molecular graphics project in general and other projects which are important for Coot (8).

The web page also contains an example "setup" file which assigns the environment variables to change the behaviour of Coot.

1.8 Crash

There are backup files in the directory coot-backup (9). You can recover the session (until the last edit) by reading in the pdb file that you started with last time and then use File -> Recover Session....

I would like to know about coot crashing (10) so that I can fix it as soon as possible. If you want your problem fixed, this involves some work on your part sadly.

First please make sure that you are using the most recent version of coot. I will often need to know as much as possible about what you did to cause the bug. If you can reproduce the bug and send me the files that are needed to cause it, I can almost certainly fix it (11) - especially if you use the debugger (gdb) and send a backtrace too(12).

2. Mousing and Keyboarding

Left-mouse Drag

Rotate view

Ctrl Left-Mouse Drag

Translates view

Shift Left-Mouse

Label Atom

Right-Mouse Drag

Zoom in and out

Ctrl Shift Right-Mouse Drag

Rotate View around Screen Z axis

Middle-mouse

Centre on atom

Scroll-wheel Forward

Increase map contour level

Scroll-wheel Backward

Decrease map contour level

See also Chapter 8.2 Getting out of "Translate" Mode for more help.

2.1 Next Residue
2.2 Keyboard Contouring
2.3 Keyboard Rotation
2.4 Mouse Z Translation and Clipping
2.5 Keyboard Translation
2.6 Keyboard Zoom and Clip
2.7 Scrollwheel
2.8 Selecting Atoms
2.9 Virtual Trackball
2.10 More on Zooming

2.1 Next Residue

"Space"

Next Residue

"Shift" "Space"

Previous Residue

See also "Recentring View" (Section 3.12 Recentring View).

2.2 Keyboard Contouring

Use + or - on the keyboard if you don't have a scroll-wheel.

2.3 Keyboard Rotation

Q

Rotate + X Axis

W

Rotate - X Axis

E

Rotate + Y Axis

R

Rotate - Y Axis

T

Rotate + Z Axis

Y

Rotate - Z Axis

I

Continuous Y Axis Rotation

U

Undo Last Navigation Move

2.4 Mouse Z Translation and Clipping

Here we can change the clipping and Translate in Screen Z

Ctrl Right-Mouse Drag Up/Down

changes the slab (clipping planes)

Ctrl Right-Mouse Drag Left/Right

translates the view in screen Z

2.5 Keyboard Translation

Keypad 3

Push View (+Z translation)

Keypad .

Pull View (-Z translation)

2.6 Keyboard Zoom and Clip

N

Zoom out

M

Zoom in

D

Slim clip

F

Fatten clip

2.7 Scrollwheel

You can turn off the map contour level changing by the scroll wheel using:

(set-scroll-by-wheel-mouse 0)

(the default is 1 [on]).

2.8 Selecting Atoms

Use the scripting function (quanta-buttons) to make the mouse functions more like other molecular graphics programs to which you may be more accustomed (14).

2.9 Virtual Trackball

If you do want screen-z rotation screen-z rotation, you can either use Shift Right-Mouse Drag or set the Virtual Trackball to Spherical Surface mode and move the mouse along the bottom edget of the screen.

2.10 More on Zooming

There is also a Zoom slider (Draw -> Zoom) for those without a right-mouse button.

3. General Features

The map-fitting and model-building tools can be accessed by using Calculate -> Model/Fit/Refine.... Many functions have tooltips (18) describing the particular features and are documented in Chapter 5. Modelling and Building.

F5:

posts the Model/Fit/Refine dialog

F6:

posts the Go To Atom Window

F7:

posts the Display Control Window

3.1 Version number
3.5 Raster3D output
3.6 Display Manager
3.8 Scripting
3.8.2 Scheme
3.8.3 Coot State
3.9 Backups and Undo
3.12 Recentring View
3.13 Clipping manipulation
3.14 Background colour
3.15 Unit Cell
3.16 Rotation Centre Pointer
3.17 Crosshairs
3.18 Frame Rate
3.19 Program Output

3.1 Version number

There is also a script function to return the version of coot:

(coot-version)

3.2 Antialiasing

(set-do-anti-aliasing 1)

The default is 0 (off).

3.3 Molecule Number

The Molecule Number of a molecule can be found by clicking on an atom of that molecule (if it has coordinates of course). The first number in brackets in the resulting text in the status bar and console is the Molecule Number. The Molecule Number can also be found in Display Control window (Section 3.6 Display Manager). It is also displayed on the left-hand side of the molecule name in the option menus of the "Save Coordinates" and "Go To Atom" windows.

3.4 Display Issues

The view is orthographic (i.e. the back is the same size as the front). The default clipping is about right for viewing coordinate data, but is often a little too "thick" for viewing electron density. It is easily changed (see Section 3.13 Clipping manipulation).

Depth-cueing is linear and fixed on.

The graphics window can be resized, but it has a minimum size of 400x400 pixels.

3.4.1 Stereo

The angle between the stereo pairs (the stereo separation) can be changed to suit your personal tastes using:

(set-hardware-stereo-angle-factor angle-factor)

where angle-factor would typically be between 1.0 and 2.0

3.4.2 Pick Cursor

(set-pick-cursor-index i)

where i is an integer less than 256. The cursors can be viewed using an external X program:

xfd -fn cursor

3.4.3 Origin Marker

A yellow box called the "origin marker" marks the origin. It can be removed using:

(set-show-origin-marker 0)

Its state can be queried like this:

(show-origin-marker-state)

which returns an number (0 if it is not displayed, 1 if it is).

3.5 Raster3D output

(raster3d file-name)

where file-name is such as "test.r3d" (19).

There is a keyboard key to generate this file, run "render" and display the image: Function key F8.

You can also use the function

(render-image)

which will create a file `coot.r3d', from which "render" produces `coot.png'. This png file is displayed using ImageMagick's display program (by default). Use something like:

(set! coot-png-display-program "gqview")

to change that to different display program ("gqview" in this case).

(set! coot-png-display-program "open")

would use Preview (by default) on Macintosh.

To change the widths of the bonds and density "lines" use (for example):

(set-raster3d-bond-thickness 0.1)

and

(set-raster3d-density-thickness 0.01)

To turn off the representations of the atoms (spheres):

(set-renderer-show-atoms 0)

3.6 Display Manager

The "Scroll" radio buttons sets which map is has its contour level changed by scrolling the mouse scroll wheel.

By default, the path names of the files are not displayed in the Display Manager. To turn them on:

(set-show-paths-in-display-manager 1)

If you pull across the horizontal scrollbar in a Molecule view, you will see the "Render as" menu. You can use this to change between normal "Bonds (Colour by Atom)","Bonds (Colour by Chain)" and "C\alpha" representation There is also available "No Waters" and "C\alpha + ligands" representations.

3.7 The file selector

3.7.1 File-name Filtering

• (add-coordinates-glob-extension extension)
• (add-data-glob-extension extension)
• (add-map-glob-extension extension)
• (add-dictionary-glob-extension extension)

If you want the fileselection to be filtered without having to use the "Filter" button, use the scripting function

(set-filter-fileselection-filenames 1)

3.7.2 Filename Sorting

(set-sticky-sort-by-date)

3.7.3 Save Coordinates Directory

Some people prefer that the fileselection for saving coordinates starts in the original directory (rather than the directory from which they last imported coordinates). This option is for them:

(set-save-coordinates-in-original-directory 1)

3.8 Scripting

3.8.1 Python
3.8.2 Scheme
3.8.3 Coot State

There is an compile-time option of adding a script interpreter. Currently the options are python and guile. It seems possible that in future you will be able to use both in the same executable. The binary distribution of Coot are linked with guile.

Hundreds of commands are made available for use in scripting by using SWIG, some of which are documented here. Other functions are are currently not well documented but can be found in the Coot Reference Manual or the source code (`c-interface.h').

Commands described throughout this manual (such as (vt-surface 1)) can be evaluated directly by Coot by using the "Scripting Window" (Calculate -> Scripting...). Note that you type the commands in the lower entry widget and the command gets echoed (in red) and the return vaule and any output is displayed in the text widget above. The typed command should be terminated with a carriage return (22). Files (23) can be evaluated (executed) using Calculate -> Run Script.... Note that in scheme (the usual scripting language of Coot), the parentheses are important.

To execute a script file from the command line use the --script filename arguments (except when also using the command line argument --no-graphics, in which case you should use -s filename).

After you have used the scripting window, you may have noticed that you can no longer kill Coot by using Ctrl-C in the console. To recover this ability:

(exit)

in the scripting window.

3.8.1 Python

3.8.1.1 Python Commands

(function arg1 arg2...)

If you are using Python instead: the format needs to be changed to:

function(arg1,arg2...)

Note that dashes in guile function names become underscores for python, so that (for example) (raster-screen-shot) becomes raster_screen_shot().

3.8.2 Scheme

3.8.3 Coot State

Use Calculate -> Run Script... to use this file to re-create the loaded maps and models that you had when you finished using Coot (24) last time. A state file can be saved at any time using (save-state) which saves to file 0-coot.state.scm or (save-state-filename "thing.scm") which saves to file thing.scm.

When Coot starts it can optionally run the commands in 0-coot.state.scm.

Use (set-run-state-file-status i) to change the behaviour: i is 0 to never run this state file at startup, i is 1 to get a dialog option (this is the default) and i is 2 to run the commands without question.

3.9 Backups and Undo

If you have made changes to more than one molecule, Coot will pop-up a dialog box in which you should set the "Undo Molecule" i.e. the molecule to which the Undo operations will apply. Further Undo operations will continue to apply to this molecule until there are none left. If another Undo is requested Coot checks to see if there are other molecules that can be undone, if there is exactly one, then that molecule becomes the "Undo Molecule", if there are more than one, then another Undo selection dialog will be displayed.

You can set the undo molecule using the scripting function:

(set-undo-molecule imol)

If for reasons of strange system(28) requirements you want to remove the path components of the backup file name you can do so using:

(set-unpathed-backup-file-names 1)

3.9.1 Redo

3.9.2 Restoring from Backup

See also Section 1.8 Crash.

3.10 View Matrix

(view-matrix)

3.11 Space Group

There is a scripting interface function that returns the space group for a given molecule (31):

(show-spacegroup imol)

You can force a space group onto a molecule using the following:

(set-space-group imol space-group)

where space-group is one of the standard CCP4 space group names (e.g. "P 21 21 21").

3.12 Recentring View

• Use Control + left-mouse to drag around the view
• or
• middle-mouse over an atom. In this case, you will often see "slide-recentring", the graphics smoothly changes between the current centre and the newly selected centre.
• or
• Use Draw -> Go To Atom... to select an atom using the keyboard. Note that you can subsequently use "Space" in the "graphics" window (OpenGL canvas) to recentre on the next C\alpha.
• or
• To centre on an arbitary position (x,y,z), use the scripting function (set-rotation-centre x y z).

If you don't want smooth recentring (sliding) Draw -> Smooth Recentring -> Off. You can also use this dialog to speed it up a bit (by decreasing the number of steps instead of turning it off).

3.13 Clipping manipulation

One can "push" and "pull" the view in the screen-Z direction using keypad 3 and keypad "." (see Section 2.5 Keyboard Translation).

3.14 Background colour

3.15 Unit Cell

3.16 Rotation Centre Pointer

3.16.1 Pointer Distances

3.17 Crosshairs

3.18 Frame Rate

The contouring elapsed time (35) gives an indication of CPU performance.

3.19 Program Output

• Output that starts "ERROR..." is a programming problem (and ideally, you should never see it).
• Output that starts "WARNING..." means that something propably unintented happened due to the unexpected nature of your input or file(s).
• Output that starts "DEBUG..." has (obviously enough) been added to aid debugging. Most of them should have been cleaned up before release, but as Coot is constantly being developed, a few may slip through. Just ignore them.

4. Coordinate-Related Features

4.1 Reading coordinates
4.2 Atom Info
4.3 Atom Labeling
4.4 Atom Colouring
4.5 Bond Parameters
4.6 Download coordinates
4.7 Get Coordintes and Map from EDS
4.8 Save Coordinates
4.9 Setting the Space Group
4.10 Anisotropic Atoms
4.11 Symmetry
4.12 Sequence View
4.13 Print Sequence
4.14 Environment Distances
4.15 Distances and Angles
4.16 Zero Occupancy Marker
4.17 Atomic Dots
4.18 Mean, Median Temperature Factors
4.19 Secondary Structure Matching (SSM)
4.20 Least-Squares Fitting

4.1 Reading coordinates

4.1.1 Read multiple coordinate files

(read-pdb-all)

which reads all the "*.pdb" files in the current directory

(multi-read-pdb glob-pattern dir)

which reads all the files matching glob-pattern in directory dir. Typical usage of this might be:

(multi-read-pdb "a*.pdb" ".")

Alternatively you can specify the files to be opened on the command line when you start coot (see Section 1.6 Command Line Arguments).

4.1.2 SHELX .ins/.res files

SHELX ".res" (and ".ins" of course) files can be read into Coot, either using the GUI File -> Open Coordinates... or by the scripting function:

(read-shelx-ins-file file-name)

where file-name is quoted, such as "thox.ins".

Although Coot should be able to read any SHELX ".res" file, it may currently have trouble displaying the bonds for centro-symmetric structures.

ShelxL atoms with negative PART numbers are given alternative configuration identifiers in lower case.

To write a SHELX ".ins" file:

(write-shelx-ins-file imol file-name)

where imol is the number of the molecule you wish to export.

This will be a rudamentary file if the coordinates were initially from a "PDB" file, but will contain substantial SHELX commands if the coordinates were initially generated from a SHELX ins file.

4.2 Atom Info

The temperature factors and occupancy of the atoms in a residue can be set by using Edit -> Residue Info....

4.3 Atom Labeling

(set-label-on-recentre-flag 0)

Some people prefer to have atom labels that are shorter, without the slashes and residue name:

(set-brief-atom-labels 1)

4.4 Atom Colouring

• (set-colour-map-rotation-on-read-pdb 30).

The default value is 31^\circ.

Also one is able to select only the Carbon atoms to change colour in this manner: (set-colour-map-rotation-on-read-pdb-c-only-flag 1).

The colour map rotation can be set individually for each molecule by using the GUI: Edit -> Bond Colours.....

4.5 Bond Parameters

4.5.1 Bond Thickness

(set-bond-thickness thickness imol)

where imol is the molecule number. The default thickness is 3.0. The bond thickness also applies to the symmetry atoms of the molecule. There is no means to change the bond thickness of a residue selection within a molecule.

4.5.2 Display Hydrogens

(set-draw-hydrogens mol-no 0) (38)

where mol-no is the molecule number.

There is a GUI to control this too, under "Edit -> Bond Parameters".

4.5.3 NCS Ghosts Coordinates

4.5.4 NCS Maps

4.5.5 Using Strict NCS

(add-strict-ncs-matrix imol ncs-chain-id ncs-target-chain-id m11 m12 m13 m21 m22 m23 m31 m32 m33 t1 t2 t3)

where ncs-chain-id might be "B", "C" "D" (etc.) and ncs-target-chain-id is "A", i.e. the B, C, D molecules are NCS copies of the A chain.

for icosohedral symmetry the translation components t1, t2, t3 will be 0.

You need to turn on symmetry for molecule imol and set the displayed symmetry object type to "Display Near Chains".

4.6 Download coordinates

It is also possible to download mmCIF data and generate a map. This currently requires a properly formatted database structure factors mmCIF file (43).

4.7 Get Coordintes and Map from EDS

With the assistance of Gerard Kleywegt I have added the ability to download coordinates and view the map from structures in the Electron Density Server (EDS) at Uppsala University. This is a much more robust and faster way to see maps from deposited structures. This function can be found under the File menu item. Very nice.