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
8. Hints and Usage Tips
9. Other Programs
10. Scripting Functions
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

The reference for the the Electron Density Server is:

GJ Kleywegt, MR Harris, JY Zou, TC Taylor, A Wählby, TA Jones (2004), "The Uppsala Electron-Density Server", Acta Crystallographica Section D-Biological Crystallography 60, 2240-2249.

Please also cite the primary literature for the received structures.

1.2 What is Coot?

Coot is a molecular graphics application. Its primary focus is crystallographic macromolecular model-building and manipulation rather than representation i.e. more like Frodo than Rasmol. Having said that, Coot can work with small molecule (SHELXL) and electron microscopy data, be used for homology modelling, make passably pretty pictures and display NMR structures.

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 should 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 standard (part of the distribution) scheme files
• COOT_SCHEME_EXTRAS_DIR The directory containing bespoke scheme files. This variable is not set by default. If you set it, Coot will test that it points to a directory, and if it does, Coot will load all the .scm files in that directory.
• 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_REF_SEC_STRUCTS The directory containing a set of high-quality structures to be used as templates for fitting beta strands. If this is not set, then the directory COOT_REF_SEC_STRUCTS will be used to find the reference pdb files.
• 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 shell script.

1.6 Command Line Arguments

• --c cmd to run a command cmd on start up
• --script filename to run a script on start up (but see Section 3.10 Scripting)
• --no-state-script don't run the 0-coot.state.scm script on start up. Don't save a state script on exit either.
• --pdb filename for pdb/coordinates file
• --coords filename for SHELX .ins/.res and CIF files
• --data filename for mtz, phs or mmCIF data file
• --auto filename for auto-reading mtz files (mtz file has the default labels FWT, PHWT)
• --map filename for a map (currently CCP4-format only)
• --dictionary filename read in a cif monomer dictionary
• --help print command line options
• --stereo start up in hardware stereo mode
• --version print the version of coot and exit
• --code accession-code on starting Coot, get the pdb file and mtz file (if it exists) from the EDS
• --no-guano don't leave "Coot droppings" i.e. don't write state and history files on exit.
• --side-by-side start in side-by-side stereo mode
• --python an argument with no parameters - used to tell Coot that the -c arguments should be process as python (rather than as scheme).

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).

1.8 Crash

Whenever Coot manipulates the model, it saves a backup pdb file. 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). Note that you may have to source the contents of bin/coot so that the libraries are can be found when the executable dynamically links.

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.5 Getting out of "Translate" Mode for more help.

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

2.1 Next Residue

"Space"

Next Residue

"Shift" "Space"

Previous Residue

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

2.2 Keyboard Contouring

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

2.3 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.4 Keyboard Translation

Keypad 3

Push View (+Z translation)

Keypad .

Pull View (-Z translation)

2.5 Keyboard Zoom and Clip

N

Zoom out

M

Zoom in

D

Slim clip

F

Fatten clip

2.6 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.7 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 (13).

2.8 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 edge of the screen.

2.9 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 (17) 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 Screenshot
3.6 Raster3D output
3.7 Display Manager
3.8 The Modelling Toolbar
3.9 The file selector
3.10 Scripting
3.10.2 Scheme
3.11 Backups and Undo
3.14 Recentring View
3.15 Clipping manipulation
3.16 Background colour
3.17 Unit Cell
3.18 Rotation Centre Pointer
3.19 Crosshairs
3.20 3D Annotations
3.21 Frame Rate
3.22 Program Output

3.1 Version number

This will return the version of coot:

$ coot --version

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

(coot-version)

3.2 Anti-aliasing

(set-do-anti-aliasing 1)

The default is 0 (off).

This can also be activated using Edit Preferences -> Others -> Antialiasing -> Yes.

If you have an nVidia graphics card, external antialiasing can be actived using nvidia-settings:

Antialiasing Setting -> Override Application Settings and slide the slider to the right.

On restarting Coot, it should be in antialias mode (18).

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.7 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.15 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 Screenshot

A simple screenshot (image dump) can be made using Draw -> Screenshot -> Simple.... Note that in side by side stereo mode you only get the left-hand image.

3.6 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)

Similarly for bones:

(set-raster3d-bone-thickness 0.05)

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

(set-renderer-show-atoms 0)

3.7 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.8 The Modelling Toolbar

You might not want to have the right-hand-side vertical toolbar that contains icons for some modelling operations (22) displayed:

(hide-modelling-toolbar)

to bring it back again:

(show-modelling-toolbar)

3.9 The file selector

3.9.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.9.2 Filename Sorting

(set-sticky-sort-by-date)

3.9.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.10 Scripting

3.10.1 Python
3.10.2 Scheme
3.10.3 Coot State
3.10.4 Key Binding

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, others with python.

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, the scripting interface description linked from the Coot web page 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 upper entry widget and the command gets echoed (in red) and the return value and any output is displayed in the text widget lower (green). The typed command should be terminated with a carriage return (23). Files (24) 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.10.1 Python

3.10.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.10.2 Scheme

3.10.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 (25) 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.10.4 Key Binding

"Power users" of Coot might like to write their own functions and bind that function to a keyboard key. How do they do that?

By using the add-key-binding function:

(add-key-binding function-name key function)

where key is a quoted string (note that upper case and lower case keys are distinguished - activate get upper case key binding you need to chord the shift key (26)).

for example:

(add-key-binding "Refine Active Residue with Auto-accept" "x" refine-active-residue) Have a look at the key bindings section on the Coot wiki for several more examples.

3.11 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(30) 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.11.1 Redo

3.11.2 Restoring from Backup

See also Section 1.8 Crash.

3.12 View Matrix

(view-matrix)

Also, the internal representation of the view can be returned and set using:

(view-quaternion) to return a 4-element list

(set-view-quaternion i j k l) which sets the view quaternion.

So the usage of these functions would be something like:

@verbatim (let ((v (view-quaternion))) ;; manipulate v here, maybe (apply set-view-quaternion v))

3.13 Space Group and Symmetry

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

(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").

To show the symmetry operators of a particular molecule use: (get-symmetry imol) which will return a list of strings.

3.14 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 arbitrary position (x,y,z), use the scripting function (set-rotation-centre x y z).
• or
• Use the keyboard: [Ctrl G] then key in a residue number and (optionally) a chainid and press Return

If you don't want smooth recentring (sliding) Edit -> Preferences -> 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.15 Clipping manipulation

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

3.16 Background colour

3.17 Unit Cell

3.18 Rotation Centre Pointer

3.18.1 Pointer Distances

3.19 Crosshairs

3.20 3D Annotations

3.21 Frame Rate

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

3.22 Program Output

• Output that starts "ERROR..." is a programming problem (and ideally, you should never see it).
• Output that starts "WARNING..." means that something probably unintended 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 Coordinates 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 Ball and Stick Representation
4.19 Mean, Median Temperature Factors
4.20 Secondary Structure Matching (SSM)
4.21 Least-Squares Fitting
4.22 Ligand Overlaying
4.23 Writing PDB files

4.1 Reading coordinates

To disable the recentring of the view on reading a coordinates file via scripting, use: (set-recentre-on-read-pdb 0). However, when reading a coordinates file from a script it is just as good (if not better) to use (handle-read-draw-molecule-with-recentre filename 0) - the additional 0 means "don't recentre". And that affects just the reading of filename and not subsequent files.

4.1.1 A Note on Space Groups Names

4.1.2 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.3 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 rudimentary 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)

To change the atom label colour, use:

(set-font-colour 0.9 0.9 0.9)

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 pixels. The bond thickness also applies to the symmetry atoms of the molecule. The default bond thickness for new molecules can be set using:

(set-default-bond-thickness thick)

where thick is an integer.

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) (40)

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

Sometimes SSM does not provide a good (or even useful) matrix. In that case, we can specify the residue range ourselves and let the LSQ algorithm provide the matrix. A gui dialog for this operation can be found under Extensions -> NCS -> NCS Ghosts by Residue Range....

The scripting function is used like this:

(manual-ncs-ghosts imol resno-start resno-end ncs-chain-ids)

Typical usage: (manual-ncs-ghosts 0 1 10 (list "A" "B" "C"))

note that in ncs-chain-ids, the NCS master/reference chain-id goes first.

4.5.4 NCS Maps

Note also that the internal representation of the map is not transformed. If you try to export a NCS overlay map you will get an untransformed map. A transformed map only makes sense around a given point (and when using transformed maps in Coot, this reference point is changed on the fly, thus allowing map transformations on the fly). [This applies to NCS overlap maps, NCS averaged maps are transformed].

This will also create an NCS averaged map (42).

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 icosahedral 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 (45).

4.7 Get Coordinates and Map from EDS

Using this function we have 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.

This feature was added with the assistance of Gerard Kleywegt. If you use the EDS, please cite GJ Kleywegt, MR Harris, JY Zou, TC Taylor, A Wählby & TA Jones (2004), "The Uppsala Electron-Density Server", Acta Cryst. D60, 2240-2249.

4.8 Save Coordinates

If your filename ends in .cif, .mmcif or .mmCIF then an mmCIF file will be written (not a "PDB" file).

4.9 Setting the Space Group

If for some reason, the pdb file that you read does not have a space group, or has the wrong space group, then you can set it using the following function:

(set-space-group imol symbol)

e.g.:

(set-space-group 0 "P 41 21 2")

4.10 Anisotropic Atoms

You cannot currently display thermal ellipsoids (47) for isotropic atoms.

4.11 Symmetry

By default symmetry atoms are not displayed.

If you want coot to display symmetry coordinates without having to use the gui, add to your `~/.coot' the following:

(set-show-symmetry-master 1)

The symmetry can be represented as C\alphas. This along with representation of the molecule as C\alphas (Section 3.7 Display Manager) allow the production of a packing diagram.

4.11.1 Missing symmetry

Sometimes (rarely) coot misses symmetry-related molecules that should be displayed. In that case you need to expand the shift search (the default is 1):

(set-symmetry-shift-search-size 2)

This is a hack, until the symmetry search algorithm is improved.

4.12 Sequence View

4.13 Print Sequence

(print-sequence imol)

4.14 Environment Distances

4.15 Distances and Angles

4.16 Zero Occupancy Marker

(set-draw-zero-occ-markers 0)

Use an argument of 1 to turn them on.

4.17 Atomic Dots

You can draw dots round arbitrary atom selections

(dots imol atom-selection dot-density radius) The function returns a handle.

e.g. put a sphere of dots around all atoms of the 0th molecule (it might be a set of heavy atom coordinates) at the default dot density and radius:

(dots 0 "/1" 1 1)

You can't change the colour of the dots.

There is no internal mechanism to change the radius according to atom type. With some cleverness you might be able to call this function several times and change the radius according to the atom selection.

There is a function to clear up the dots for a particular molecule imol and dots set identifier dots-handle

(clear-dots imol dots-handle)

There is a function to return how many dots sets there are for a particular molecule imol:

(n-dots-set imol)

4.18 Ball and Stick Representation

Fragments of the molecule can be rendered as a "ball and stick" molecule:

(make-ball-and-stick imol atom-selection bond-thickness sphere-size draw-spheres-flag)

e.g. (make-ball-and-stick 0 "/1/A/10-20" 0.3 0.4 1)

The ball-and-stick representation can be cleared using:

(clear-ball-and-stick imol)

4.19 Mean, Median Temperature Factors

(average-temperature-factor imol)

(median-temperature-factor imol)

-1 is returned if there was a problem (51).

4.20 Secondary Structure Matching (SSM)

The excellent SSM alogrithm(52) of Eugene Krissinel is available in Coot. The GUI interface is straight-forward and can be found under Calculate -> SSM Superpose. You can specify the specific chains that you wish to match using the "Use Specific Chain" check-button.

There is a scripting level function which gives even finer control:

(superpose-with-atom-selection imol1 imol2 mmdb-atom-selection-string-1 mmdb-atom-selection-string-2 move-copy-flag )

the move-copy-flag should be 1 if you want to apply the transformation to a copy of imol2 (rather than imol2 itself). Otherwise, move-copy-flag should be 0.

mmdb atom selection strings (Coordinate-IDs) are explained in detail in the mmdb manual.

Briefly, the string should be formed in this manner:

/mdl/chn/seq(res).ic/atm[elm]:aloc

e.g. "/1/A/12-130/CA"

<p><a href="http://www.ebi.ac.uk/~keb/cldoc/object/cl_obj_surf.html#CoordinateID">The mmdb manual CoordinateID description</a>.</p>

4.21 Least-Squares Fitting

There is a simple GUI for this Calculate -> LSQ Superpose...

The scripting interface to LSQ fitting is as follows:

(simple-lsq-match ref-start-resno ref-end-resno ref-chain-id imol-ref mov-start-resno mov-end-resno mov-chain-id imol-mov match-type)

where:

• ref-start-resno is the starting residue number of the reference molecule
• ref-end-resno is the last residue number of the reference molecule
• mov-start-resno is the starting residue number of the moving molecule
• mov-end-resno is the last residue number of the moving molecule
• match-type is one of 'CA, 'main, or 'all.

e.g.: (simple-lsq-match 940 950 "A" 0 940 950 "A" 1 'main)

More sophisticated (match molecule number 1 chain "B" on to molecule number 0 chain "A"):

(define match1 (list 840 850 "A" 440 450 "B" 'all))

(define match2 (list 940 950 "A" 540 550 "B" 'main))

(clear-lsq-matches)

(set-match-element match1)

(set-match-element match2)

(lsq-match 0 1) ; match molecule number 1 onto molecule number 0.

4.22 Ligand Overlaying

The scripting function

(overlap-ligands imol-ligand imol-ref chain-id-ref resno-ref)

returns a rotation+translation operator which can be applied to other molecules (and maps). Here, imol-ligand is the molecule number of the ligand (which is presumed to be a a molecule on its own - Coot simply takes the first residue that it finds). imol-ref chain-id-ref resno-ref collectively describe the target position for the moving imol-ligand molecule.

The convenience function

(overlay-my-ligands imol-mov chain-id-mov resno-mov imol-ref chain-id-ref resno-ref)

wraps overlap-ligands. The is no GUI for this function yet.

4.23 Writing PDB files

As well as the GUI option File -> Save Coordinates... there is a scripting options available:

(write-pdb-file imol pdb-file-name)

which writes the imolth coordinates molecule to filename.

To write a specific residue range:

(write-residue-range-to-pdb-file imol chain-id start-resno endresno pdb-file-name)

5. Modelling and Building

5.1 Regularization and Real Space Refinement
5.2 Changing the Map for Building/Refinement
5.3 Rotate/Translate Zone
5.4 Rigid Body Refinement
5.5 Simplex Refinement
5.6 Baton Building
5.7 Reversing Direction of Fragment
5.8 C\alpha -> Mainchain
5.9 Backbone Torsion Angles
5.10 Rotamers
5.11 Editing \chi Angles
5.12 Torsion General
5.13 Pep-flip
5.14 Add Alternate Conformation
5.15 Mutation
5.16 Importing Lignds/Monomers
5.17 Ligand from SMILES strings
5.18 Find Ligands
5.19 Flip Ligand
5.20 Find Waters
5.24 Place Helix
5.25 Building Ideal DNA and RNA
5.26 Merge Molecules
5.27 Temperature Factor for New Atoms
5.28 Applying NCS Edits
5.29 Running Refmac
5.30 Running SHELXL
5.31 Clear Pending Picks
5.32 Delete
5.33 Sequence Assignment
5.34 Building Links and Loops
5.35 Fill Partial Residues
5.36 Setting Occupancies
5.37 Fix Nomenclature Errors
5.38 Rotamer Fix Whole Protein
5.39 Refine All Waters
5.40 Moving Molecules/Ligands
5.41 Modifying the Labels on the Model/Fit/Refine dialog

The functions described in this chapter manipulate, extend or build molecules and can be found under Calculate -> Model/Fit/Refine.... When activated, the dialog "stays on top" of the main graphics window (53). Some people think that this is not always desirable, so this behaviour can be undone using:

(set-model-fit-refine-dialog-stays-on-top 0)

5.1 Regularization and Real Space Refinement

5.1.1 Dictionary
5.1.2 Refining Carbohydrates
5.1.3 Planar Peptide Restraints
5.1.4 The UNK residue type
5.1.5 Moving Zero Occupancy Atoms

Coot will read the geometry restraints for refmac and use them in fragment (zone) idealization - this is called "Regularization". The geometrical restraints are, by default, bonds, angles, planes and non-bonded contacts. You can additionally use torsion restraints by Calculate -> Model/Fit/Refine... -> Refine/Regularize Control -> Use Torsion Restraints. Truth to tell, this has not been successful in my hands (sadly).

"RS (Real Space) Refinement" (after Diamond, 1971 (54)) in Coot is the use of the map in addition to geometry terms to improve the positions of the atoms. Select "Regularize" from the "Model/Fit/Refine" dialog and click on 2 atoms to define the zone (you can of course click on the same atom twice if you only want to regularize one residue). Coot then regularizes the residue range. At the end Coot, displays the intermediate atoms in white and also displays a dialog, in which you can accept or reject this regularization. In the console are displayed the \chi^2 values of the various geometrical restraints for the zone before and after the regularization. Usually the \chi^2 values are considerably decreased - structure idealization such as this should drive the \chi^2 values toward zero.

The use of "Refinement" is similar - with the addition of using a map. The map used to refine the structure is set by using the "Refine/Regularize Control" dialog. If you have read/created only one map into Coot, then that map will be used (there is no need to set it explicitly).

Use, for example, (set-matrix 20.0)

to change the weight of the map gradients to geometric gradients. The higher the number the more weight that is given to the map terms (55). The default is 60.0. This will be needed for maps generated from data not on (or close to) the absolute scale or maps that have been scaled (for example so that the sigma level has been scaled to 1.0).

For both "Regularize Zone" and "Refine Zone" one is able to use a single click to refine a residue range. Pressing A on the keyboard while selecting an atom in a residue will automatically create a residue range with that residue in the middle. By default the zone is extended one residue either size of the central residue. This can be changed to 2 either side using (set-refine-auto-range-step 2).

Intermediate (white) atoms can be moved around with the mouse (click and drag with left-mouse, by default). Refinement will proceed from the new atom positions when the mouse button is released. It is possible to create incorrect atom nomenclature and/or chiral volumes in this manner - so some care must be taken. Press the A key as you left-mouse click to move atoms more "locally" (rather than a linear shear) and Ctrl key as you left-mouse click to move just one atom.

In more up to date versions, Coot will display colour patches (something like a traffic light system) representing the chi squared values of each of types of geometric feature refined. Typically "5 greens" is the thing to aim for, the colour changes occurring at chi squared values 2, 5 and 8 (8 being the most red).

To prevent the unintentional refinement of a large number of residues, there is a "heuristic fencepost" of 20 residues. A selection of than 20 residues will not be regularized or refined. The limit can be changed using the scripting function: e.g. (set-refine-max-residues 30).

5.1.1 Dictionary

The geometry description for residues, monomers and links used by Coot are in the standard mmCIF format. Because this format alows multiple comp_ids (residue types) to be described within a cif loop, it is hard to tell when a dictionary entry needs to be overwritten when reading a new file. Therefore Coot makes this extra constraint: that the "chem_comp" loop should appear first in the comp list data item - if this is the case, then Coot can overwrite an old restraint table for a particular comp_id/residue-type when a new one is read.

By default, the geometry dictionary entries for only the standard residues are read in at the start (56). It may be that your particular ligand is not amongst these. To interactively add a dictionary entry use File -> Import CIF Dictionary. Alternatively, you can use the function:

(read-cif-dictionary filename)

and add this to your .coot file (this may be the preferred method if you want to read the file on more than one occasion).

Note: the dictionary also provides the description of the ligand's torsions.

5.1.2 Refining Carbohydrates

Refining carbohydrates monomers should be as straightforward as refining a protein residue. Coot will look in the dictionary for the 3-letter code for the particular residue type, if it does not find it, Coot will try to search for dictionary files using "-b-D" or "-a-L" extensions.

When refining a group of carbohydrates, the situation needs a bit more explanation. For each residue pair with tandem residue numbers specified in the refinement range selection, Coot checks if these residue types are are furanose or pyranose in the dictionary, and if the are both one or the other, then it tries to see if there are any of the 11 link types (BETA1-4, BETA2-3, ALPHA1-2 and so on) specified in the dictionary. It does this by a distance check of the potentially bonding atoms. If the distance is less than 3.0Å (2.0Å in 0.4.x and before, I think), then a glycosidic bond is made and used in the refinement.

Bonds between protein and carbohydrate and branched carbohydrates are not yet understood.

LINK and LNKR cards are not used.

5.1.3 Planar Peptide Restraints

There is a new mechanism (as of 0.1.1) to introduce 5 atom (CA-1, C-1, O-1, N-2, CA-2) planar peptide restraints. These restraints should help in low resolution fitting (the main-chains becomes less distorted), reduce accidental cis-peptides and may help "clean up" Ramachandran plots.

(add-planar-peptide-restraints)

And similarly they can be removed:

(remove-planar-peptide-restraints)

The old way used to be to edit the Refmac `monomers/list/mon_lib_list.cif' by hand.

5.1.4 The UNK residue type

The UNK residue type is a special residue type to Coot. It has been added for use with Buccaneer. Don't give you ligand (or anything else) the 3-letter-code UNK or confusion will result (57).

5.1.5 Moving Zero Occupancy Atoms

By default, atoms with zero occupancy are moved when refining and regularizing. This can sometimes be inconvenient. To turn of the movement of atoms with zero occupancy when refining and regularizing:

(set-refinement-move-atoms-with-zero-occupancy 0)

5.2 Changing the Map for Building/Refinement

You can change the map that is used for the fitting and refinement tools using the Select Map.... button on the Model/Fit/Refine dialog.

5.3 Rotate/Translate Zone

"Rotate/Translate Zone" from the "Model/Fit/Refine" menu allows manual movement of a zone. After pressing the "Rotate/Translate Zone" button, select two atoms in the graphics canvas to define a residue range (58), the second atom that you click will be the local rotation centre for the zone. The atoms selected in the moving fragment have the same alternate conformation code as the first atom you click. To actuate a transformation, click and drag horizontally across the relevant button in the newly-created "Rotation \& Translation" dialog. The axis system of the rotations and translations are the screen coordinates. Alternatively (59), you can click using left-mouse on an atom in the fragment and drag the fragment around. Use Control Left-mouse to move just one atom, rather than the whole fragment. If you click Control Left-mouse whilst not over an atom then you can rotate the fragment using mouse drag. Click "OK" (or press Return) when the transformation is complete.

To change the rotation point to the centre of the intermediate atoms (rather than the second clicked atom), use the setting:

(set-rotate-translate-zone-rotates-about-zone-centre 1)

5.4 Rigid Body Refinement

Sometimes no results are displayed after Rigid Body Fit Zone. This is because the final model positions had too many final atom positions in negative density. If you want to over-rule the default fraction of atoms in the zone that have an acceptable fit (0.75), to be (say) 0.25:

(set-rigid-body-fit-acceptable-fit-fraction 0.25)

5.5 Simplex Refinement

Rigid body refinement via Nelder-Mead Simplex minimization is available in Coot. Simplex refinement has a larger radius of convergence and thus is useful in a position where simple rigid body refinement finds the wrong minimum. However the Simplex algorithm is much slower. Simplex refinement for a residue range start-resno to end-resno (inclusive) in chain chain-id can be accessed as follows:

(fit-residue-range-to-map-by-simplex start-resno end-resno alt-loc chain-id imol imol-for-map)

There is currently no GUI interface to Simplex refinement.

5.6 Baton Building

Baton build is most useful if a skeleton is already calculated and displayed (see Section 6.13 Skeletonization). When three or more atoms have been built in a chain, Coot will use a prior probability distribution for the next position based on the position of the previous three. The analysis is similar to that of Oldfield & Hubbard (1994) (61), however it is based on a more recent and considerably larger database.

Little crosses are drawn representing directions in which is is possible that the chain goes, and a baton is drawn from the current point to one of these new positions. If you don't like this particular direction (62), use Try Another. The list of directions is scored according to the above criterion and sorted so that the most likely is at the top of the list and displayed first as the baton direction.

When starting baton building, be sure to be about 3.8Å from the position of the first-placed C\alpha, this is because the next C\alpha is placed at the end of the baton, the baton root being at the centre of the screen. So, when trying to baton-build a chain starting at residue 1, centre the screen at about the position of residue 2.

It seems like a good idea to increase the map sampling to 2 or even 2.5 (before reading in your mtz file) [a grid sampling of about 0.5Å seems reasonable] when trying to baton-build a low resolution map. You can set the map sampling using Edit -> Map Parameters -> Map Sampling.

Occasionally, every point is not where you want to position the next atom. In that case you can either shorten or lengthen the baton, or position it yourself using the mouse. Use "b" on the keyboard to swap to baton mode for the mouse (63).

Baton-built atoms are placed into a molecule called "Baton Atom" and it is often sensible to save the coordinates of this molecule before quitting coot.

If you try to trace a high resolution map (1.5Å or better) you will need to increase the skeleton search depth from the default (10), for example:

(set-max-skeleton-search-depth 20)

Alternatively, you could generate a new map using data to a more moderate resolution (2Å), the map may be easier to interpret at that resolution anyhow (64).

The guide positions are updated every time the "Accept" button is clicked. The molecule name for these atoms is "Baton Build Guide Points" and is is not usually necessary to keep them.

5.6.1 Undo

5.6.2 Missing Skeleton

5.6.3 Building Backwards

• Use the command:

  (set-baton-build-params start-resno chain-id "backwards")

  where start-resno would typically be 0 (65) and chain-id would be "" (default).

• Recentre the graphics window on the first atom of the just-build fragment
• Select "Ca Baton Mode" and select a baton direction that goes in the "opposite" direction to what is typically residue 2. This is slightly awkward because the initial baton atoms build in the "opposite" direction are not dependent on the first few atoms of the previously build fragment.

5.7 Reversing Direction of Fragment

After you've build a fragment, sometimes you might want to change the direction of that fragment (this function changes an already existing fragment, as opposed to Backwards Building which sets up Baton Building to place new points in reverse order).

The fragment is defined as a contiguous set of residues numbers. So that you should be sure that other partial fragments which have the same chain id and that are not connected to this fragment have residue numbers that are not contiguous with the fragment you are trying to reverse.

5.8 C\alpha -> Mainchain

This function is also available from the scripting interface:

(db-mainchain imol chain-id resno-start resno-end direction) where direction is either "backwards" or "forwards".

Recall that the chain-id needs to be quoted, i.e. use "A" not A. Note that chain-id is "" when the C\alphas have been built with Baton Mode in Coot.

5.9 Backbone Torsion Angles

5.10 Rotamers

Using the default build, the rotamers are generated (71) from the backbone independent sidechain library of the Richardsons group (72).

The m, t and p stand for "minus (-60)", "trans (180)" and "plus (+60)". There is one letter per \chi angle.

Use keyboard . and , to cycle round the rotamers.

5.10.1 Auto Fit Rotamer

The algorithm doesn't know if the other atoms in the structure are in sensible positions. If they are, then it is sensible not to put this residue too close to them, if they are not then there should be no restriction from the other atoms as to the position of this residue - the default is "are sensible", which means that the algorithm is prevented from finding solutions that are too close to the atoms of other residues. (set-rotamer-check-clashes 0) will stop this.

There is a scripting interface to auto-fitting rotamers:

(auto-fit-best-rotamer resno alt-loc ins-code chain-id imol-coords imol-map clash-flag lowest-rotamer-probability)

where:

resno is the residue number

alt-loc is the alternate/alternative location symbol (e.g. "A" or "B", but most often "")

ins-code is the insertion code (usually "")

imol-coords is the molecule number of the coordinates molecule

imol-map is the molecule number of the map to which you wish to fit the side chains

clash-flag should the positions of other residues be included in the scoring of the rotamers (i.e. clashing with other other atoms gets marked as bad/unlikely)

lowest-rotamer-probability: some rotamers of some side chains are so unlikely that they shouldn't be considered - typically 0.01 (1%).

5.10.2 De-clashing residues

(de-clash imol chain-id start-resno end-resno)

start-resno is the residue number of the first residue you wish to de-clash

end-resno is the residue number of the last residue you wish to de-clash

imol is the molecule number of the coordinates molecule

This interface will not change residues with insertion codes or alternate conformation. The lowest-rotamer-probability is set to 0.01.

5.11 Editing \chi Angles

For non-standard residues, the clicked atom defines the base of the atom tree, which defines the "head" of the molecule (it's the "tail" (twigs/leaves) that wags). To emphasise, then: it matters on which atom you click!

By default torsions for hydrogen atoms are turned off. To turn them on:

(set-find-hydrogen-torsions 1)

5.12 Torsion General

You need to click on the torsion-general button, then click 4 atoms that describe the torsion - the first atom will be the base (non moving) part of the atom tree, on clicking the 4th atom a dialog will pop up with a "Reverse" button. Move this dialog out of the way and then left mouse click and drag in the main window will rotate the "top" part of the residue round the clicked atoms 2 and 3. When you are happy, click "Accept".

5.12.1 Ligand Torsion angles

5.13 Pep-flip

5.14 Add Alternate Conformation

The allows the addition alternate (dual, triple etc.) conformations to the picked residue. By default, this provides a choice of rotamer (Section 5.10 Rotamers). If there are not the correct main chain atoms a rotamer choice cannot be provided, and Coot falls back to providing intermediate atoms.

The default occupancy for new atoms is 0.5. This can be changed by using use slider on the rotamer selection window or by using the scripting function:

(set-add-alt-conf-new-atoms-occupancy 0.4)

The default Split Type is to split the whole residue. If you want the default to be to split a residue after (and including) the CA, then add to your `.coot' file:

(set-add-alt-conf-split-type-number 0)

5.15 Mutation

5.15.1 Mutating DNA/RNA

5.15.2 Multiple mutations

Multiple mutations are also supported via the scripting interface. Unlike the single residue mutation function, a residue type match will prevent a modification of the residue (79). Two functions are provided: To mutate a whole chain, use (mutate-chain imol chain-id sequence) where:

chain-id is the chain identifier of the chain that you wish to mutate (e.g. "A") and

imol is molecule number.

sequence is a list of single-letter residue codes, such as "GYRESDF" (this should be a straight string with no additional spaces or carriage returns).

Note that the number of residues in the sequence chain and those in the chain of the protein must match exactly (i.e. the whole of the chain is mutated (except residues that have a matching residue type).)

To mutate a residue range, use

• (mutate-residue-range chain-id start-res-no stop-res-no sequence)

where

start-res-no is the starting residue for mutation

stop-res-no is the last residue for mutation, i.e. using values of 2 and 3 for start-res-no and stop-res-no respectively will mutate 2 residues.

Again, the length of the sequence must correspond to the residue range length. Note also that this is a protein sequence - not nucleic acid.

5.15.3 Mutating to a Non-Standard Residue

Sometimes one might like to model post-translational or other such modifications. How is that done, if the new residue type is not one of the standard residue types? There is a scripting function:

(mutate-by-overlap imol chain-id resno new-three-letter-code)

This imports a model residue for the new residue type and overlays it on to the given residue by using graph-matching to determine the equivalent atoms.

There is no GUI interface to this function yet.

5.15.4 Mutate and Autofit

5.15.5 Renumbering

(renumber-residue-range imol chain-id start-res-no last-resno offset)

5.16 Importing Lignds/Monomers

You can import monomers (often ligands) using File -> Get Monomer...(80) by providing the 3-letter code of your monomer/ligand. The resulting molecule will be moved so that it placed at the current screen centre.

Typically, when you are happy about the placement of the ligand, you'd then use Merge Molecules to add the ligand/monomer to the main set of coordinates.

This procedure creates a pdb file `monomer-XXX.pdb' and a dictionary file `libcheck_XXX.cif' in the directory in which Coot was started.

A future invocation of Get Monomer uses these file so that the monomer appears quickly (81).

5.17 Ligand from SMILES strings

Similarly, you can generate ligands using File -> SMILES... and providing a SMILES string and a code for the residue name (this is your name for the residue type and a dictionary will be generated for the monomer of this type)(82).

5.18 Find Ligands

If you do not have any molecules with less that 400 atoms loaded in Coot, you will get the message:

"Error: you must have at least one ligand to search for!"

New ligands are placed where the map density is and protein (mask) atoms are not). The masked map is searched for clusters using a default cut-off of 1.0\sigma. In weak density this cut-off may be too high and in such a case the cut-off value can be changed using something such as:

(set-ligand-cluster-sigma-level 0.8)

However, if the map to be searched for ligands is a difference map, a cluster level of 2.0 or 3.0 would probably be more appropriate (less likely to generate spurious sites).

Each ligand is fitted with rigid body refinement to each potential ligand site in the map and the best one for each site selected and written out as a pdb file. The clusters are sorted by size, the biggest one first (with an index of 0). The output placed ligands files have a prefix "best-overall" and are tagged by the cluster index and residue type of the best fit ligand in that site.

By default, the top 10 sites are tested for ligands - to increase this use:

(set-ligand-n-top-ligands 20)

5.18.1 Flexible Ligands

Before you search for flexible ligands you must have read the mmCIF dictionary for that particular ligand residue type (File -> Import CIF dictionary).

Use:

(set-ligand-flexible-ligand-n-samples n-samples)

where n-samples is the number of samples of flexibility made for each ligand. Generally speaking, The more the number of rotatable bonds, the bigger this number should be.

By default the options to change these values are not in the GUI. To enable these GUI options, use the scripting function:

(ligand-expert)

5.18.2 Adding Ligands to Model

5.19 Flip Ligand

Sometimes a ligand is placed more or less in the correct position, but the orientation is wrong - or at least you might want to explore other possible orientation. To do that easily a function has been provided:

(flip-ligand imol chain-id residue-number)

This will flip the orientation of the residue around the Eigen vector corresponding to the largest Eigen value, exploring 4 possible orientations.

This function has been further wrapped to provide flipping for the active residue:

(flip-active-ligand)

This function can easily be bound to a key.

5.20 Find Waters

You have control over several parameters used in the water finding:

(set-write-peaksearched-waters)

which writes ligand-waters-peaksearch-results.pdb, which contains the water peaks (from the clusters) without any filtering and ligand-waters.pdb which are a disk copy filtered waters that have been either added to the molecule or from which a new molecule has been created.

(set-ligand-water-to-protein-distance-limits min-d max-d) sets the minimum and maximum allowable distances between new waters and the masking molecule (usually the protein).

(set-ligand-water-spherical-variance-limit varlim) sets the upper limit for the density variance around water atoms. The default is 0.12.

The map that is marked by the protein and is searched to find the waters is written out in CCP4 format as "masked-for-waters.map".

5.20.1 Refinement Failure

Sometimes as a result of water fitting, you may see something like:

@verbatim WARNING:: refinement failure start pos: xyz = ( 17.1, 34.76, 60.42) final pos: xyz = ( 17.19, 34.61, 60.59) When Coot finds a blob, it does a crude positioning of an atom at the centre of the grid points. It then proceeds to move to the peak of the blob by a series of translations. There are a certain number of cycles, and if it doesn't reach convergence by the end of those cycles then you get the error message.

Often when you go to the position indicated, you can see why Coot had a problem in the refinement.

5.20.2 Blobs

5.21 Add Terminal Residue

If you use the Extensions (Dock Sidechains... -> Associate Sequence with Model) to apply a PIR sequence file to a model then Add Terminal Residue will use the sequence alignment to determine the residue type of the added residue.

(set-terminal-residue-do-rigid-body-refine 0) will disable rigid body fitting of the terminal residue fragment for each trial residue position (the default is 1 (on)) - this may help if the search does not provide good results.

(set-add-terminal-residue-n-phi-psi-trials 50) will change the number of trials (default is 100).

5.22 Add OXT Atom to Residue

At the C-terminus of a chain of amino-acid residues, there is a "modification" so that the C-O becomes a carbonyl, i.e. an extra (terminal) oxygen (OXT) needs to be added. This atom is added so that it is in the plane of the C\alpha, C and O atoms of the residue.

Scripting usage:

(add-OXT-to-residue imol residue-number insertion-code chain-id) (86),

where insertion-code is typically "".

Note, in order to place OXT, the N, CA, C and O atoms must be present in the residue - if (for example) the existing carbonyl oxygen atom is called "OE1" then this function will not work.

5.23 Add Atom at Pointer

The atoms are added to a new molecule called "Pointer Atoms". They should be saved and merged with your coordinates outside of Coot.

5.24 Place Helix

The idea is to place a helix more or less "here" (the screen centre) by fitting to the electron density map. The algorithm is straightforward. First we move to the local centre of density, then examine the density for characteristic directions and fit ideal helices (of length 20 residues) to these directions. The helix is then extended if possible (by checking the fit to the map of residues added in ideal helix conformation) and chopped back if not. If the fit is successful, the helix is created in a new molecule called "Helix". If the fit is not successful, there is instead a message added to the status bar. You can build the majority of a helical protein in a few minutes using this method (you will of course have to assemble the helices and assign residue numbers and sequence later).

This is available as a scripting function (place-helix-here) and in the GUI (in the "Other Modelling Tools" dialog).

5.25 Building Ideal DNA and RNA

The interface to building ideal polynucleotides can be found by pressing the "Ideal RNA/DNA..." button on the "Other Modelling Tools" dialog.

For a given sequence, a choice of DNA or RNA, A or B form, single or double stranded is presented.

The interface may not gracefully handle uracils in DNA, thymines in RNA or B form RNA (88).

5.26 Merge Molecules

5.27 Temperature Factor for New Atoms

The default temperature factor for new atoms is 30.0. This can be changed by the following

(set-default-temperature-factor-for-new-atoms 50.0)

5.28 Applying NCS Edits

Let's imagine that you have 3-fold NCS. You have molecule "A" as your master molecule and you make edits to that molecule. Now you want to apply the edits that you made to "A" (the NCS master chain ID) to the "B" and "C" molecules (i.e. you want the "B" and "C" molecules to be rotated/translated versions of the "A" molecule). How is that done?

There are now guis to NCS command to help you out (under Extensions). However, for completeness here are the scripting versions:

(copy-from-ncs-master-to-others imol master-chain-id)

If you have only a range of residues, rather than a whole chain to replace:

(copy-residue-range-from-ncs-master-to-others imol master-chain-id start-resno end-resno)

e.g.

(copy-residue-range-from-ncs-master-to-others 0 "A" 1 5)

5.29 Running Refmac

Use the "Run Refmac...." button to select the dataset and the coordinates on which you would like to run Refmac. Note that here Coot only allows the use of datasets which has Refmac parameters set as the MTZ file was read. By default, Coot displays the new coordinates and the new map generated from refmac's output MTZ file. Optionally, you can also display the difference map.

You can add extra parameters (data lines) to refmac's input by storing them in a file called refmac-extra-params in the directory in which you started coot.

You can also provide extra/replacement parameters for refmac by setting the variable refmac-extra-params to a list of strings, for example:

(set! refmac-extra-params (list "REFINE MATRIX 0.1" "MAKE HYDROGENS NO"))

Coot "blocks" (90) until Refmac has terminated (91).

The default refmac executable is refmac5 it is presumed to be in the path. If you don't want this, it can be overridden using a re-definition either at the scripting interface or in one's ~/.coot file e.g.:

• (define refmac-exec "/e/refmac-new/bin/refmac5.6.3")

After running refmac several times, you may find that you prefer if the new map that refmac creates (after refmac refinement) is the same colour as the previous one (from before this refmac refinement). If so, use:

(set-keep-map-colour-after-refmac 1)

which will swap the colours of then new and old refmac map so that the post-refmac map has the same colour as the pre-refmac map and the pre-refmac map is coloured with a different colour.

5.30 Running SHELXL

Coot can read shelx .res files and write .ins files, and thus one can refine using SHELXL in a convenient manner using the function

(shelxl-refine imol . hkl-file-name)

(the hkl-file-name is an optional argument)

e.g.

(shelxl-refine 0)

or

(shelxl-refine 0 "insulin.hkl")

In the former case, coot will presume that there is a SHELX hkl file corresponding to the res file that you read in; if there is not coot will print a warning and not try to run shelxl. In the latter case, you can specify the location of the hkl file.

After shelxl has finished, coot will automatically read in the resulting res coordinates, the fcf file, convert the data to mmCIF format and read that, which generates a \sigma_A map and a difference map.

Coot creates a time stamped ins file and a time-stamped sym-link to the hkl file in the coot-shelxl directory.

Please note that the output ins file will not be particularly useful (and thus shelxl will fail) if the input file was not in SHELX ins format.

There is a GUI for this operation under the "Extensions" menu item.

5.31 Clear Pending Picks

5.32 Delete

Single atoms or residues can be deleted from the molecule using "Delete..." from the "Model/Fit/Refine"dialog. Pressing this button results in a new dialog, with the options of "Residue" (the default), "Atom" and "Hydrogen Atoms". Now click on an atom in the graphics - the deleted object will be the whole residue of the atom if "Residue" was selected and just that atom if "Atom" was selected. Note that if a residue has an alternative conformation, then "Delete Residue" will delete only the conformation that matches that alternative conformation specifier of the clicked atom.

Only waters are deletable if the "Water" check button is active and waters are not deletable if the "Residue/Monomer" check button is active. This is to reduce mis-clicking.

To rotate the view when in "Delete Mode", use Ctrl left-mouse.

If you want to delete multiple items you can use check the "Keep Delete Active" check-button on this dialog This will will keep the dialog open, ready for deletion of next item.

5.33 Sequence Assignment

(assign-fasta-sequence imol chain-id fasta-seq)

This function has been provided as a precursor to functions that will (as automatically as possible) mutate your current coordinates to one that has the desired sequence. It will be used in automatic side-chain assignment (at some stage in the future).

5.34 Building Links and Loops

Coot can make an attempt to build missing linking regions or loops (93). This is an area of Coot that needs to be improved, currently O does it much better. We will have several different loop tools here (94). For now there is Calculate -> Fit Gap or the scripting function:

(fit-gap imol chain-id start-resno stop-resno)

and

(fit-gap imol chain-id start-resno stop-resno sequence)

the second form will also mutate and try to rotamer fit the provided sequence.

Example usage: let's say for molecule number 0 in chain "A" we have residues up to 56 and then a gap after which we have residues 62 and beyond:

(fit-gap 0 "A" 57 61 "TYPWS")

5.35 Fill Partial Residues

After molecular replacement, the residues of your protein could well have the correct sequence but be chopped back to CG or CB atoms. There is a function to fill such partially-filled residues:

(fill-partial-residues imol)

This identifies residues with missing atoms, then fills them and does a rotamer fit and real-space refinement.

5.36 Setting Occupancies

• (zero-occupancy-residue-range imol chain-id resno-start resno-last)

example usage:

(zero-occupancy-residue-range 0 "A" 23 28)

This is often useful to zero out a questionable loop before submitting for refinement. After refinement (with refmac) there should be relatively unbiased density in the resulting 2Fo-Fc-style and difference maps.

Similarly there is a function to reverse this operation:

• (fill-occupancy-residue-range imol chain-id resno-start resno-last)

5.37 Fix Nomenclature Errors

Currently this is available only in scripting form:

(fix-nomenclature-errors imol)

This will fix atoms nomenclature problems in molecule number imol according to the same criteria as WATCHECK (95) e.g. Chi-2 for Phe, Tyr, Asp, and Glu should be between -90 and 90 degrees.

5.38 Rotamer Fix Whole Protein

(fit-protein imol)

which does a auto-fit rotamer and Real Space Refinement for each residue. The graphics follow the refinement.

5.39 Refine All Waters

All the waters in a model can be refined (that is, moved to the local density peak) using

(fit-waters imol)

This is a non-interactive function (the waters are moved without user intervention).

5.40 Moving Molecules/Ligands

Often you want to move a ligand (or some such) from wherever it was read in to the position of interest in your molecule (i.e. the current view centre). There is a GUI to do this: Calculate -> Move Molecule Here.

There are scripting functions available for this sort of thing:

(molecule-centre imol)

will tell you the molecule centre of the imolth molecule.

(translate-molecule-by imol x-shift y-shift z-shift)

will translate all the atoms in molecule imol by the given amount (in Ångstr@"{o}ms).

(move-molecule-to-screen-centre imol)

will move the imolth molecule to the current centre of the screen (sometimes useful for imported ligands). Note that this moves the atoms of the molecule - not just the view of the molecule.

5.41 Modifying the Labels on the Model/Fit/Refine dialog

If you don't like the labels "Rotate/Translate Zone" or "Place Atom at Pointer" and rather they said something else, you can change the button names using:

(set-model-fit-refine-rotate-translate-zone-label "Move Zone")

and

(set-model-fit-refine-place-atom-at-pointer "Add Atom")

6. Map-Related Features

6.1 Maps in General
6.2 Create a Map
6.3 Map Contouring
6.4 Map Extent
6.6 Map Line Width
6.7 "Dynamic" Map colouring
6.8 Difference Map Colouring
6.10 Map Sampling
6.9 Make a Difference Map
6.11 Dragged Map
6.12 Dynamic Map Sampling and Display Size
6.13 Skeletonization
6.14 Masks
6.15 Trimming
6.16 Map Transformation
6.17 Export Map

6.1 Maps in General

6.1.1 Map Reading Bug

6.2 Create a Map

From a CCP4 map use File -> Read Map. After being generated/read, the map is immediately contoured and centred on the current rotation centre.

6.2.1 Auto-read MTZ file

(set-auto-read-column-labels "2FOFCWT" "PHIWT" 0) (set-auto-read-column-labels "FOFCWT" "DELPHIWT" 1)

By default the difference map is created in auto-reading the MTZ file. If you don't want a difference map, you can use the function:

(set-auto-read-do-difference-map-too 0)

6.2.2 Reading CIF data

• (read-cif-data-with-phases-fo-alpha-calc cif-file-name) Calculate an atom map using F_obs and \alpha_calc
• (read-cif-data-with-phases-2fo-fc cif-file-name) Calculate an atom map using F_obs, F_calc and \alpha_calc
• (read-cif-data-with-phases-fo-fc cif-file-name) Calculate an difference map using F_obs, F_calc and \alpha_calc.

6.2.3 Reading PHS data

There are 2 ways to read data by scripting:

(read-phs-and-make-map-using-cell-symm phs-file-name space-group-name a b c alpha beta gamma)

(read-pdb-and-make-map-with-reso-limits imol-previous phs-file-name reso-limit-low reso-limit-high)

The first specifies the cell explicitly, and alpha, beta and gamma are specified in degrees.

The second form allows the specification of resolution limits and takes the cell and symmetry from a previous molecule (typically a pdb file).

6.3 Map Contouring

Use keyboard + or - to change the contour level if you don't have a scroll-wheel (97).

If you are creating your map from an MTZ file, you can choose to click on the "is difference map" button on the Column Label selection widget (after a data set filename has been selected) then this map will be displayed in 2 colours corresponding to + and - the map contour level.

If you read in a map and it is a difference map then there is a checkbutton to tell Coot that.

If you want to tell Coot that a map is a difference map after it has been read, use:

(set-map-is-difference-map imol)

where imol is the molecule number.

By default the change of the contour level is determined from the sigma of the map. You can change this in the map properties dialog or by using the scripting function:

(set-contour-by-sigma-step-by-mol step on/off? imol)

where

step is the difference in sigma from one level to the next (typically 0.2)

on/off? is either 0 (sigma stepping off) or 1 (sigma stepping on)

By default the map radius (98) is 10Å. The default increment to the electron density depends on whether or not this is a difference map (0.05 e^-/\AA^3 for a "2Fo-Fc" style map and 0.005 e^-/\AA^3 for a difference map). You can change these using Edit -> Map Parameters or by using the "Properties" button of a particular map in the Display Control (Display Manager) window.

6.4 Map Extent

The extent of the map can be set using the GUI (Edit -> Map Parameters -> Map Radius) or by using the scripting function, e.g.:

(set-map-radius 13.2)

6.5 Map contour "scrolling" limits

(set-stop-scroll-iso-map 0) for a 2Fo-Fc style map

(set-stop-scroll-diff-map 0) for a difference map

To set the limits to negative (e.g. -0.6) levels:

(set-stop-scroll-iso-map-level -0.6)

and similarly:

(set-stop-scroll-diff-map-level -0.6)

where the level is specified in e^-/\AA^3.

6.6 Map Line Width

(set-map-line-width 2)

The default line width is 1.

6.7 "Dynamic" Map colouring

As subsequent maps are read, they are coloured by rotation round a colour wheel. The default colour map step is 31 degrees. You can change this using:

(set-colour-map-rotation-for-map step)

6.8 Difference Map Colouring

(set-swap-difference-map-colours 1)

This option will allow the "blue is positive, red is negative" colour scheme on "Edit -> Map Colour".

6.9 Make a Difference Map

Using the "Make a Difference Map" function in the Extensions menu, one can make a difference from two arbitrary maps. The maps need not be on the same griding, or in the same group even. The resulting map will be on the same griding and space group as the "Reference" map.

6.10 Map Sampling

This value can be set by the scripting command

(set-map-sampling-rate 2.5)

6.11 Dragged Map

To change this by scripting:

(set-active-map-drag-flag 0)

6.12 Dynamic Map Sampling and Display Size

If you want to have these functions active for all maps, add the following to your initialization file 3.10.2 Scheme:

(set-dynamic-map-sampling-on) (set-dynamic-map-size-display-on)

6.13 Skeletonization

The level of the skeleton can be changed by using Edit -> Skeleton Parameters... -> Skeletonization Level... and corresponds to the electron density level in the map. By default this value is 1.2 map standard deviations. The amount of map can be changed using Edit -> Skeleton Parameters... -> Skeleton Box Radius...(104). The units are in Ångstr@"{o}ms, with 40 as the default value.

The skeleton is often recalculated as the screen centre changes - but not always since it can be an irritatingly slow calculation. If you want to force a regeneration of the displayed skeleton, simply centre on an atom (using the middle mouse button) or press the S key.

6.14 Masks

(mask-map-by-molecule imol-map imol-model invert-mask?)

If invert-mask? is 0, this will create a new map that has density only where there are no (close) coordinates. If invert-mask? is 1 then the map density values will be set to zero everywhere except close to the atoms of molecule number imol-model.

The radius of the mask around each atom is 2.0Å by default. You can change this using:

(set-map-mask-atom-radius radius)

There is a GUI interface to Map Masking under the Extensions menu.

6.14.1 Example

1. Make a pdb file the contains just the ligand and read it in to Coot - let's say it is molecule 1 and the ligand is residue 3 of chain "L".
2. Get a map that covers the ligand (e.g. from refmac). Let's say this map is molecule number 2.
3. Mask the map:

   (mask-map-by-molecule 2 1 1)

   This creates a new map. Turn the other maps off, leaving only the masked map.

To get a nice rendered image, press F8 (see Section 3.6 Raster3D output).

6.15 Trimming

(trim-molecule-by-map imol-coords imol-map density-level delete/zero-occ?)

where delete/zero-occ? is 0 to remove the atoms and 1 to set their occupancy to zero.

There is a GUI interface for this feature under the "Extensions" menu item.

6.16 Map Transformation

If you want to transform a map, you can do it thusly:

(transform-map imol rotation-matrix trans point radius)

where:

rotation-matrix is a 9-membered list of numbers for an orthogonal rotation matrix.

trans is a 3-membered list of numbers (distances in Ångst@"{o}ms).

point is a 3-membered list of numbers (centre point in Ångst@"{o}ms).

radius is a single number (also in Ångst@"{o}ms).

This applies the rotation rotation-matrix and a translation trans to a map fragment, so that when the transformation is applied the centre of the new map is at point.

Example usage:

(transform-map 2 '(1 0 0 0 1 0 0 0 1) '(0 0 1) (rotation-centre) 10)

which transforms map number 2 by a translation of 1Å along the Z axis, centred at the screen centre for 10Å around that centre.

Here's a more real-world example:

Let's say we want to tranform the density over the "B" molecule to a position over the "A" molecule. First we do a LSQ transformation to get the rotation and translation that moves the "B" coordinates over the "A" coordinates:

In the terminal output we get:

@verbatim | 0.9707, 0.2351, 0.05033| | -0.04676, 0.39, -0.9196| | -0.2358, 0.8903, 0.3896| ( -33.34, 21.14, 18.82)

The centre of the "A" molecule is at (58.456, 5.65, 11.108). So we do:

(transform-map 3 (list 0.9707 0.2351 0.05033 -0.04676 0.39 -0.9196 -0.2358 0.8903 0.3896) (list -33.34 21.14 18.82) (list 58.456 5.65 11.108) 8)

Which creates a map over the middle of the "A" molecule. Note that using a too high radius can cause overlap problems, so try with a small radius (e.g. 5.0) if the resulting map looks problematic.

Alternatively, instead of typing the whole matrix, you can use a coordinates least-squares fit to generate the matrix for you. (transform-map-using-lsq-matrix) does just that.

Heres how to use it:

(transform-map-using-lsq-matrix imol-ref ref-chain ref-resno-start ref-resno-end imol-mov mov-chain mov-resno-start mov-resno-end imol-map about-pt radius)

Hopefully the arguments are self explanatory (ref refers to the reference molecule, of course and about-pt is a 3-number list such as is returned by (rotation-centre)).

We can now export that map, if we want.

6.17 Export Map

You can write out a map from Coot (e.g. one from NCS averaging, or masking or general transformation) using the export map function:

(export-map imol filename)

e.g.

(export-map 4 "ncs-averaged.map")

7. Validation

The validation functions are still being added to from time to time. In future there will be more functions, particularly those that will interface to other programs.

7.1 Ramachandran Plots
7.2 Chiral Volumes
7.3 Blobs: a.k.a. Unmodelled density
7.4 Check Waters by Difference Map
7.6 Molprobity Tools Interface
7.7 GLN and ASN B-factor Outliers
7.8 Validation Graphs

7.1 Ramachandran Plots

Ramachandran plots are "dynamic". When you edit the molecule (i.e. move the coordinates of some of atoms) the Ramachandran plot gets updated to reflect those changes. Also the underlying \phi/\psi probability density changes according to the selected residue type (i.e. the residue under the mouse in the plot). There are 3 different residue types: GLY, PRO, and not-GLY-or-PRO (106).

When you mouse over a representation of a residue (a little square or triangle (107)) the residue label pops up. The residue is "active" i.e. it can be clicked. The "graphics" view changes so that the C\alpha of the selected residue is centred. In the Ramachandran plot window, the current residue is highlighted by a green square.

The underlying distributions are taken from the Richardson's Top500 structures http://kinemage.biochem.duke.edu/databases/top500.php.

The probability levels for acceptable (yellow) and preferred (red) are 0.2% and 2% respectively.

You can change the contour levels:

(set-ramachandran-plot-contour-levels 0.025 0.003)

You can change the "blocksize" (the default is 10 degrees) of the contours using

(set-ramachandran-plot-background-block-size 5)