# Coot

Coot is a graphics program for building, refining and analysing macromolecular models obtained with crystallographic procedures.

There is a homepage with extensive documentation. The program may be downloaded for Linux, Mac and Windows computers from the primary server (as of July 10, 2009 there's a new site at http://www.biop.ox.ac.uk/coot/devel/build-info.html) or, if that is not available, from an external mirror. The license of Coot is GNU GPL.

# Installing Coot

## Installing Coot on OS X

OS X install packages for nightly builds that work on 10.8.X and 10.9.X are available here: Coot OS X package installers

Please refer to the Installing Coot on OS X page

## Installing Coot on Linux

Installing coot on linux is rather more straightforward than on OS X, because most linux systems are based on gnome and/or kde, and tend to have many of the required components already installed. Most of the other dependencies are also readily available.

### Installation from a distributed binary tarball package

This is the recommended way for those who do not want to delve into the mysteries of compiling and linking a great but complex piece of software. Read the (somewhat outdated, it seems) Coot FAQ to find "Additional Notes" for your operating system.

In short, just go to http://www.ysbl.york.ac.uk/~emsley/software/binaries/nightlies/pre-release/ (a mirror is at ftp://turn5.biologie.uni-konstanz.de/coot/software/binaries/nightlies/pre-release/ ) and pick a suitable binary, e.g. coot-0.5-pre-1-revision-1003-binary-Linux-i386-fedora-5.tar.gz for a Red Hat Enterprise Linux 5 or CentOS-5 system (Fedora 6 corresponds to RHEL5, thus Fedora 5 binaries are OK). If you prefer a "stable" binary, these are at http://www.ysbl.york.ac.uk/~emsley/software/binaries/stable/.

Then un-tar it under /usr/local/src (or in your $HOME), and establish a symlink (ln -s) between /usr/local/bin/coot and the bin/coot of the freshly unpacked distribution. If you then run coot, and the loader complains that a certain library is missing, just ask yum whatprovides <thatlibrary>  and install the library, again using yum (assuming yum is available in your distribution, otherwise use apt or whatever is there for this purpose). #### Example: installing a 64bit nightly CentOS5 binary build on 64bit SL6.1 First of all, SL (Scientific Linux) is a derivative of RHEL, as is CentOS. So all three OSs behave exactly the same. The binaries with "x86_64" binaries are for 64bit systems; the "i386" binaries are for 32bit systems. Since my notebook is 64bits ("uname -a" reports "x86_64" more than once), I download ftp://turn5.biologie.uni-konstanz.de/coot/software/binaries/nightlies/pre-release/coot-0.7-pre-1-revision-3999-binary-Linux-x86_64-centos-5-python-gtk2.tar.gz (the main server is slow, so I use the mirror). As root, I "cd /usr/local/src" and un-tar. Next, have to find out which libraries are missing. This can be achieved by (note the use of LD_LIBRARY_PATH in the second command - do not permanently modify LD_LIBRARY_PATH !): [root@localhost]# cd coot-Linux-x86_64-centos-5-gtk2-python [root@localhost]# LD_LIBRARY_PATH=lib ldd bin/coot-real | grep found libssl.so.6 => not found libcrypto.so.6 => not found libssl.so.6 => not found libcrypto.so.6 => not found  So only two libraries are missing! Either they can be installed using yum, or they are already available, but have a higher version. • First possibility: find out about installable RPM packages (preferred way): [root@localhost src]# yum provides libssl.so.6 libcrypto.so.6 Loaded plugins: refresh-packagekit openssl098e-0.9.8e-17.el6.i686 : A compatibility version of a general : cryptography and TLS library Repo : sl Matched from: Other : libssl.so.6 ... (the package is repeated, and libcrypto.so.6 is also mentioned)  Now don't just install the openssl098e-0.9.8e-17.el6.i686 and its dependencies - it is a 32bit library (the name ends with ".i686")! Installing it does not solve the problem - we need a 64bit library. Unfortunately "yum provides" does not tell us about the 64bit library (is that a yum bug?). By specifying just the package name (openssl098e.x86_64 would also work, and would avoid any 32bit package) yum install openssl098e  we install both libssl.so.6 and libcrypto.so.6 in their 64bit versions - done! • Second possibility: find out if the system already has a higher version of the two libraries: [root@localhost locate libssl.so /usr/lib64/.libssl.so.1.0.0.hmac /usr/lib64/.libssl.so.10.hmac /usr/lib64/libssl.so /usr/lib64/libssl.so.1.0.0 /usr/lib64/libssl.so.10  So the answer is: there is /usr/lib64/libssl.so which is at version 10, which is compatible with the version we need (6). For libcrypto.so the same is true. So just cd coot-Linux-x86_64-centos-5-gtk2-python/lib/ ln -s /usr/lib64/libssl.so libssl.so.6 ln -s /usr/lib64/libcrypto.so libcrypto.so.6  The way these symlinks are made they would even work if RHEL upgrades libssl or libcrypto to higher versions. Works for me. Final step (this does not need to be repeated for a new coot version): create /usr/local/bin/coot with #!/bin/csh -f setenv LANG C exec /usr/local/src/coot-Linux-x86_64-centos-5-gtk2-python/bin/coot$*


and make it executable with

chmod a+x /usr/local/bin/coot


### Installation on Debian/Ubuntu from debian archive files

As an alternative, you might wish to exploit the debain dpkg/apt/synaptic package management system on Ubuntu and other Debian linux distributions using (unofficial) pre-compiled debian packages for coot and its dependencies. (These will be discontinued when official packages become available.)

To do so, simply download the deb files and install with the command

sudo dpkg -i *.deb


dpkg will complain if a dependency is missing rather than install a broken program.

### Packages for Ubuntu

A pre-packaged version of Coot (0.7-pre-1) for Ubuntu is available from mok0's Personal Package Archive (PPA) on Launchpad. Currently, packages for Ubuntu 10.04 (Lucid) and 10.10 (Maverick) are available.

To install the coot package on your system, you first need to install the public key for mok0's PPA:

 sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1DC81A57


 sudo add-apt-repository ppa:mok0/ppa


That's it! Now, you should be able to:

 apt-get update && apt-get install coot


This version of Coot only supports the Python scripting language.

### Mandriva Installation

To install the coot on Mandriva 2010.0 use the ubuntu distribution: tar zxf coot-0.6.2-binary-Linux-i686-ubuntu-8.04.1-python-gtk2.tar.gz

in the .cshrc file: alias coot 'source /prog/CCP4/ccp4-6.1.13/include/ccp4.setup-csh ; /prog/coot-Linux-i686-ubuntu-8.04.1-gtk2-python/bin/coot'

### Converting to rpm packages

You can convert any debian package file into an rpm file using the program alien. I have done this and have made the resulting packages available.

### Installation from source code via autobuild scripts

Installation of coot and all of its dependencies are handled automatically through the autobuild scripts. There are two versions:

• GTK1 - the old user interface. This script builds coot and all its dependencies.
• GTK2 - the new user interface. This script builds coot and most of the dependencies, excluding GTK2.

To build Coot, all you should need to do is edit a few settings in the top of the build script, or alternatively specify those settings as environment variables. For example, the following sequence of instructions will build the latest pre-release of the GTK 2 version with python support:

wget http://www.ysbl.york.ac.uk/~emsley/build-logs/build-it-gtk2-simple

export AUTOBUILD_INSTALLED=${HOME}/autobuild/coot export AUTOBUILD_BUILD=${HOME}/autobuild/
export LOGS=$AUTOBUILD_BUILD/logs export NIGHTLY_DEST_DIR=$AUTOBUILD_BUILD
export STABLE_DEST_DIR=$AUTOBUILD_BUILD export build_coot_prerelease=1 bash build-it-gtk2-simple python > build.log  (This script works in bash. For tcsh, replace 'export' with 'setenv' and '=' with ' '. In some cases you may need to download additional development packages in order to build all the components. ### Installation from source code manually There are also instructions for Custom building Coot from source code. # Running Coot ## General Topics ### Controls ### Stereographic Display Coot has several options for stereographic display, ranging from cross-eyed and wall-eyed split-screen stereo, to hardware-stereo modes that work with CRT systems and most recently the new Zalman 3-D LCD monitor. #### Side-by-Side Either cross-eyed or wall-eyed split-screen stereo mode can be invoked using the "Stereo" menu item under "Draw", as is shown in the image below: #### Hardware Stereo Similarly, hardware stereo can be invoked (assuming you have the CRT, correct graphics card, emitter, etc) using the same menu item, by selecting "Hardware Stereo". 3d lcd #### Zalman Stereo The first viable LCD monitor for stereographics display is made by Zalman and costs about$300: Zalman ZM-M220W

The attributes for this monitor have been tested and described rather extensively by Warren DeLano on the PyMOL site. Please read it for important details and suggested purchasing sources.

The coot zalman page describes specifically how to get this to work with coot on Mac OS X, but the instructions should be generalizable to linux and Windoze.

Note that the stereo effect is very sensitive to the vertical position of your eyes relative to the screen: if you don't see stereo, try tilting the screen.

### Stereo: left/right (and front/back) interchanged?

Establish an additional toolbutton "swap stereo":

Main Toolbar -> right mouse click-> Manage buttons-> select Swap Stereo

Or for the script minded:

switch_stereo_sides()

This will toggle the stereo images left and right.

## As of 0.4, coot works with gtk+2

This permits use of themes for a more OSX-like experience, among other things.

Click on the thumbnail image below to see a full-size screenshot of Coot with a gtk+2 Aqua-like theme.

To get this effect, you need the Glossy_P gtk+2 theme:

Edit a file called ~/.gtkrc-2.0 and put into it the following line:

include "/usr/share/themes/Glossy\ P/gtk-2.0/gtkrc"


Alternatively, if you use gnome or xfce4, you can open the theme manager and just make it open the downloaded Glossy_P tarball, and it should add this as a theme.

# Assorted questions and answers (from the mailinglist)

It should be noted that the answers ("A") are from Paul Emsley himself (and were maybe slightly edited).

## Coot development

Q: How can I get involved with Coot development?

A: Join the Coot Janitors project. This is a project to get new people involved in improving Coot, by acting as a clearing house for simple tasks which need doing, and providing documentation for doing them.

## NCS edits

Q: I am sure this exists somewhere through scripting in COOT, but can I apply NCS edits to only a subset of NCS copies? In other words, can I tell coot which are NCS related chains, and which aren't. I am working on this nightmarish case of asymmetrical homodimers, where the sequences are very similar, but the structures are not, so I need to tell coot which chains are actually related to each other.

A: Nightmare. If you have a recent [1632 or later for the scheme version, 1646 for the python version] Coot, you can do this:

(manual-ncs-ghosts imol resno-start resno-end chain-id-list)

where

• imol is 0 (say)
• resno-start and resno-end is the residue range for the LSQ fitting to return the NCS matrix,
• chain-id-list is the list of chain-ids, starting with the master/reference chain-id and followed by the peer chain-ids that are NCS related, e.g. (list "A" "B" "D")

The python interface is similar.

There is also a GUI to activate this feature under Extensions -> NCS.

## SHELXL

Description of problematic situation: I am using SHELXL to refine my 1.2 Å data and I am refining the hydrogen atoms. Subsequent rebuilding in coot is difficult though since hydrogens often does not "follow" when you do side chain rebuilding. For the moment I have quit transfering hydrogens to coot and add the hydrogens every refinement cycle, though it would be good I think if I could see them in coot without bothering about wrong positions. So these are my specific questions:

Specific Q1: Using "edit chi angles" does not work properly.

A: This fails because for chi angles Coot uses the Refmac dictionary to know what is connected to what (if it can). The work-around is to rename the refmac dictionary so Coot can't find it - which will force Coot to find bond by distance criteria.

Specific Q2: Using "real space refine" does not work properly.

A: Yes this fails. Hydrogens are named differently to SHELX hydrogens. In principal this could be made to work if the dictionary was reworked to use SHELX hydrogen names. This would also fix the chi angles problem too of course.

Specific Q3: I am unable to open the output pdb file from ShelXL in Coot.

A: Well, it's hard to know what's the problem without details - the console should say something. But when handling the output of shelxl, I suggest you read the .res file rather than the pdb, then the subsequent .ins file contains lots of "header" information.

## Image quality on NVidia cards

Q: improvement of image quality on machines with NVidia cards?

A: After talking about antialiasing with Stuart McNicholas, I discovered a program called nvidia-settings. I found that if I do:

Antialiasing Settings -> Override Application Setting, and set the slider to 16x


then I start Coot, I see that it starts up in nice antialiasing mode (which is a lot better that the poor mode that Coot has built-in). I don't know if this works on other/newer systems, but it works for me on my oldish GeForce 6600. (Of course the FPS takes a hit.)

## Setting default to show symmetry-related molecules

Q: How to set the default to display symmetry related molecules?

A: Add (set-show-symmetry-master 1) to the appropriate file.

## Startup files

Q: I still have a ".coot" file in my home folder for a few coot preferences that I couldn't find in the new ".coot-preferences/coot-preferences.scm". There is a warning that I should not add commands to this file. So is a "~/.coot" still the proper place to add default commands for coot?

A: Coot does not create a ~/.coot file for you, but will read it if it exists. Likewise, ~/.coot.py in which you can write python commands.~/.coot-preferences is a directory in which all .scm files and .py files are executed. coot-preferences.scm and coot_preferences.py there are generated by using the Edit -> Preferences dialog (and thus it overwrites older versions - hence the warning).

If you want to create a script that will be read by everyone then put those files into a directory defined by environment variable $COOT_SCHEME_EXTRAS_DIR (for *.scm) or$COOT_PYTHON_EXTRAS_DIR (*.py). All *.scm in $COOT_SCHEME_EXTRAS_DIR and *.py files in$COOT_PYTHON_EXTRAS_DIR will be executed at start up.

So you have a variety of places. Personally I mostly use ~/.coot.

## Torsion general

Q: How do I use "torsion general"?

A: Thanks for pointing out the lack of documentation on this. I'll make a note to add some.

You need to click on the torsion-general icon, 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 [1].

Move this dialog out of the way and then left mouse click and drag in the main window will rotate the moving/"top" part of the residue round the clicked atoms 2 and 3. When you are happy, click "Accept".

Window focus may be an issue - depending on your setting, the window manager may eat one of your clicks as you change focus between the dialog and the main graphics window (this I find annoying and there are instructions in the FAQ on how to turn that off for various systems).

[1] which may not work in 0.6-pre (grumble/sigh/sorry). If it doesn't not work, the "Reverse" button should invert the moving and "base" part of the residue.

## Peak heights in maps

Q: I have some peaks in my map which take water or sodium/magnesium or chlorine atom with out giving out any positive or negative density upon further refinement. Is there any easy way of calculating the peak height / number of electrons at a given position, say a mouse click point in coot? Is there any formula to calculate the number of electrons based on sigma level and peak height, as given in difference map peaks in coot?

A: First, go to the Coot wiki and pick up the scheme key bindings.

If you want density information at a given cursor point: point at the blob, press the 'g' key (which recentres on the biggest density under the cursor).

using the Scheme scripting window:

(apply density-at-point (imol-refinement-map) (rotation-centre))


There is no user access to the peak integration code of coot as yet.

## Disulfide bond across crystallographic axis

Q: I have a pair of disulfide bonds which link two monomers in separate asymmetric units. There is a single monomer in the asymmetric unit, and two monomers come together to form disulfides between Cys 26-Cys45, and Cys45-Cys26. When I real-space-refine these residues, they do not form a nice disulfide, and Coot does not seem to recognize them as a disulfide.

A: For the record, you can't refine symmetry-related disulfides in Coot (as of Nov 3, 2009).

## Macros in COOT

Q: How to use macros in COOT? Do they need to be written in Python or another language that I had not heard of before? Where can I find a low level description of how to write macros with some examples (I know nothing about Python, except that it is fashionable)?

A: The other language is a form of Lisp, called Scheme. You can learn about programming python in many ways of course (not least the python tutorial, which is what I read first). The coot python extensions are described in the documentation. There is a standard trivial formatting change that has to be made to get the syntax right for python, see "Python Scripting" [[1]]. There is a growing collection of coot scripts in this Wiki article.

## building loops

Q: Is there any similar function in COOT as lego_auto_mainchain command in O program?

A: there are 2 loop fitting tools in Coot

1. C alpha -> Mainchain [2],[3]
2. DB Loop: (No good documentation) [4] Extensions -> Modelling -> DB Loop...

## LSQ superpositions

Q: Do an LSQ superposition using specified residues in multiple chains (superposing one oligomer on another).

A: Something like this then?

clear_lsq_matches()
# specs for reference then moving
add_lsq_match(20, 90, "A",  20, 90, "A", 1)
add_lsq_match(20, 90, "B",  20, 90, "B", 1)
add_lsq_match(15, 75, "D",  15, 75, "D", 1)
apply_lsq_matches(1, 2)


which presumes that the reference molecule is in 1 and the moving molecule 2.

Q: How to do a LSQ superposition of a homologous structure onto my working structure using ± N residues about the current position, where N is a variable (not essential, could be fixed) and the current position is the last residue that I clicked on.

A: That is more involved - and more useful because it can be dynamic. Something like the following perhaps (in Scheme, just for amusement (not tested)). You will need to set imol-ref, perhaps by reading in the reference pdb, as demonstrated below. The function is bound to Shift-Y.

(define dynamic-lsq-range-extent 2)  ;; ± 2 residues either side of centre residue

;; convert between the input reference chain id and the chain id of
;; the moving molecule that corresponds to that chain
;;
(define (mov-match-chain ref-chain-id)
ref-chain-id)

(define (dynamic-lsq-match)

;; get the current residue and use that to make residue ranges for
;; an LSQ fit
;;

(using-active-atom
(clear-lsq-matches)
(+ aa-res-no dynamic-lsq-range-extent)
aa-chain-id
(- aa-res-no dynamic-lsq-range-extent)
(+ aa-res-no dynamic-lsq-range-extent)
(mov-match-chain aa-chain-id)
1)
(apply-lsq-matches aa-imol imol-ref)))

(add-key-binding "Dynamic LSQ overlay" "Y" dynamic-lsq-match)


## reading MTZ file with experimental PHI and FOM using --auto

Q: There is the --auto <filename> commandline option for auto-reading mtz files (mtz file has the default labels FWT, PHWT). Can this be made to work with a SHELXE .phs output file after converting with convert2mtz ? - the resulting MTZ file has labels F PHI FOM.

A: use: coot --python -c 'make_and_draw_map("sad.mtz", "F", "PHI", "FOM", "/HKL_base/HKL_base/FOM",1, 0)'

## NCS Rotamer differences

Show me where NCS-related side-chains have different rotamers

(define (compare-ncs-rotamer imol chain-A chain-B)
(let ((n-residues (chain-n-residues chain-A imol))
(mismatched-rotamers '()))
(for-each
(lambda (serial-number)

(let ((res-name-A (resname-from-serial-number imol chain-A serial-number))
(res-no-A   (seqnum-from-serial-number  imol chain-A serial-number))
(ins-code-A (insertion-code-from-serial-number imol chain-A serial-number))
(res-name-B (resname-from-serial-number imol chain-A serial-number))
(res-no-B   (seqnum-from-serial-number  imol chain-A serial-number))
(ins-code-B (insertion-code-from-serial-number imol chain-A serial-number)))
(if (not (= res-no-A res-no-B))
(begin
(format #t "sequence number for ~s do not match~%" res-no-A))
(if (not (string=? res-name-A res-name-B))
(begin
(format #t "residue names for ~s do not match~%" res-no-A))
(let ((rot-name-A (get-rotamer-name imol chain-A res-no-A ins-code-A))
(rot-name-B (get-rotamer-name imol chain-B res-no-B ins-code-B)))
(if (not (string=? rot-name-A rot-name-B))
(begin
(set! mismatched-rotamers
(cons (list imol chain-A res-no-A ins-code-A
res-name-A
(if (string=? rot-name-A "") "-" rot-name-A)
(if (string=? rot-name-B "") "-" rot-name-B))
mismatched-rotamers))))
)))))
(range n-residues))
(dialog-box-of-buttons "Mismatched Rotamers"
(cons 300 300)
(map (lambda(rotamer)
(let ((label (string-append " "
(list-ref rotamer 1)
" "
(number->string (list-ref rotamer 2))
(list-ref rotamer 3)
" "
(list-ref rotamer 4) ;; res-name
":  "
(list-ref rotamer 5)
" vs. "
(list-ref rotamer 6)))
(thunk (lambda ()
(set-go-to-atom-molecule imol)
(set-go-to-atom-chain-residue-atom-name
(list-ref rotamer 1)
(list-ref rotamer 2) " CA "))))
(list label thunk)))
mismatched-rotamers)
"  Close  ")))


And one would use this something like:

;; example usage: