Coot Reference Manual

1. Acknowledgments

Paul Emsley is grateful to use the library code of the following people, without whom Coot could not have been realised:

• Kevin Cowtan
• Eugene Krissinel
• Stuart McNicholas
• Raghavendra Chandrashekara
• Paul Bourke & Cory Gene Bloyd

For dictionaries:

• Alexei Vagin for Refmac Monomer Library
• Roland Dunbrack & co-workers for rotamer library data

Also (for generally useful software used in Coot):

• Matteo Frigo & Steven G. Johnson
• Gary Houston & other Guile developers
• Python developers
• GTk+ and GNOME-Canvas developers
• GNU Scientific Library developers
• OpenGL developers
• Janne Löf

Also those with whom Paul has corresponded or provided features and bug fixes and built the software from source code:

• William G. Scott
• Bernhard Lohkamp
• Joel Bard
• Ezra Peisach
• Alex Schuettelkopf
• Charlie Bond
• Ethan Merritt

Not forgetting the testers(1)

• Eleanor J. Dodson
• Jan Dohnalek
• Karen McLuskey
• Bernhard Lohkamp
• Aleks Roszak
• Florence Vincent
• Roberto Steiner
• Alex Schuettelkopf
• Charlie Bond
• Constantina Fotinou
• Miguel Ortiz Lombardía
• William G. Scott
• Adrian Lapthorn
• Frank von Delft

Those with experience of Quanta, XFit and O will notice similarities between Coot and those programs, it's fair to say that they have had considerable influence in the look of Coot, so Paul respectively thanks for inspiration: Tom Oldfield, Alwyn Jones (2) and Duncan McRee (and their co-workers).

2. Design Overview

2.1 Why?

"Why does Coot exist?" you might ask. "Given that other molecular graphics (3) programs exist, why write another?"

Because I like having the source code to programs I use and think/would like/hope that others feel the same. Because the other programs don't quite work how I wanted them to (4). Because there was the possibility to seamlessly integrate molecular graphics into the CCP4 Suite/CCP4i and because there was an opportunity to use new powerful CCP4 library code for model-building.

As to why write Coot when CCP4MG was available: that is not how it happened. Coot (5) was released over a year before CCP4MG was available. I followed my own design, GUI, toolkit and aesthetic decisions - for good or bad (6).

2.2 Hacker's Guide

The are several core libraries that are fundamental to Coot:

• Clipper: Kevin Cowtan's General crystallographic object library
• mmdb: CCP4's Coordinate Library
• GTk+: GNU's GUI toolkit.

2.2.1 GUI

The GUI is almost entirely built using glade. Glade writes out its code in pure C. This causes a problem. `src/interface.h' and `src/support.h' both get regenerated in "C mode" every time glade is run. So, after every time we change the GUI with glade, we need to run `post-glade' to introduce the C/C++ linking type declaration wrapper into these files.

Not all of the GUI is build with glade - there are dynamic elements, for example the "Map and Molecule (Display) Control" window the frame of which are generated in glade, but the hboxs are filled using hand-made code (see `gtk-manual.c').

2.2.2 GUI/State Variables

The `graphics_info_t' class contains a host of static state variables, mostly manipulated by GUI element (e.g button) callbacks (7). For historical reasons they are initially set in `globjects.cc'. Because the callbacks are written in C by glade (8), these variables need a functional interface to set the variables, and that interface is used by both the GUI button (9) callbacks and is exported to the scripting level. These function declarations are in `c-interface.h'. All manipulations of `graphics_info_t''s state variables go via `c-interface.h'.

Notice that MMDB functions are not allowed in this interface (10).

2.2.3 Scripting

So, SWIG uses `c-interface.h' to generate the python/scheme scripting interface. The scripting language is chosen at configure-time using either --with-guile or --with-python.

2.3 Validation

As I write this, a few of us are cobbling together a XML-based system for validation. We think that validation data should be presented as XML data that can be passed between packages and programs. Either the program itself will output the data, or we will write a wrapper to turn the output into the appropriate XML format.

These XML data will be then available for use in the molecular graphics and will provide information for a "Next Unusual Feature" button. The library to provide the XML cabability for this is expat, the same library used in Perl's XML::Parser, Python's XML parser Pyexpat and Mozilla's XML parser.

2.3.1 Example: Temperature Factor Analysis

Recall that the kurtosis of a distribution, k is given by:

We calculate the kurtosis for the isotropic temperature factors for each residue in the molecule and residues with the most leptokurtic distributions are written out to a file. The format of the file is XML.

This is an example of how we expect validation data to be presented to molecular graphics programs.

3. Exported Functions

So, here for reference purposes is the full list of user-accessable functions exported to the scripting interface. I have tried to remove from this list functions that pass or return a GtkWidget *, since they are not useful in the scripting interface at the moment.

I hope to enable direct access to the menu-bar and menu items will be available to the scripting layer at some stage in the future. This will open the door to user-defined menus and (I hope) encourage 3rd-party coot scripts.

3.0.1 (try-load-scheme-extras-dir)

3.1 File System Functions

3.1.1 (make-directory-maybe dir)

where:

• dir is a string

3.1.2 (set-show-paths-in-display-manager i)

where:

• i is an exact integer number

3.1.3 (show-paths-in-display-manager-state)

3.1.4 (add-coordinates-glob-extension ext)

where:

• ext is a string

3.1.5 (add-data-glob-extension ext)

where:

• ext is a string

3.1.6 (add-dictionary-glob-extension ext)

where:

• ext is a string

3.1.7 (add-map-glob-extension ext)

where:

• ext is a string

3.1.8 (remove-coordinates-glob-extension ext)

where:

• ext is a string

3.1.9 (remove-data-glob-extension ext)

where:

• ext is a string

3.1.10 (remove-dictionary-glob-extension ext)

where:

• ext is a string

3.1.11 (remove-map-glob-extension ext)

where:

• ext is a string

3.1.12 (set-sticky-sort-by-date)

3.1.13 (unset-sticky-sort-by-date)

3.1.14 (set-filter-fileselection-filenames istate)

where:

• istate is an exact integer number

3.1.15 (filter-fileselection-filenames-state)

3.1.16 (set-file-chooser-selector istate)

where:

• istate is an exact integer number

3.1.17 (file-chooser-selector-state)

3.1.18 (set-file-chooser-overwrite istate)

where:

• istate is an exact integer number

3.1.19 (file-chooser-overwrite-state)

3.2 Widget Utilities

3.2.1 (info-dialog txt)

where:

• txt is a string

3.3 Widget Utilities

3.3.1 (manage-column-selector filename)

where:

• filename is a string

3.4 Molecule Info Functions

3.4.1 (chain-n-residues chain-id imol)

where:

• chain-id is a string
• imol is an exact integer number

3.4.2 (molecule-centre-internal imol iaxis)

where:

• imol is an exact integer number
• iaxis is an exact integer number

3.4.3 (n-chains imol)

where:

• imol is an exact integer number

3.4.4 (is-solvent-chain-p imol chain-id)

where:

• imol is an exact integer number
• chain-id is a string

3.4.5 (sort-chains imol)

where:

• imol is an exact integer number

3.4.6 (copy-molecule imol)

where:

• imol is an exact integer number

3.4.7 (exchange-chain-ids-for-seg-ids imol)

where:

• imol is an exact integer number

3.5 Library and Utility Functions

3.5.1 (set-molecule-name imol new-name)

where:

• imol is an exact integer number
• new-name is a string

3.5.2 (coot-real-exit retval)

where:

• retval is an exact integer number

3.5.3 (coot-clear-backup-or-real-exit retval)

where:

• retval is an exact integer number

3.5.4 (run-clear-backups retval)

where:

• retval is an exact integer number

3.5.5 (run-clear-backups-py retval)

where:

• retval is an exact integer number

3.5.6 (wrapped-create-coot-references-dialog)

3.5.7 (first-coords-imol)

3.6 Graphics Utility Functions

3.6.1 (set-do-anti-aliasing state)

where:

• state is an exact integer number

3.6.2 (do-anti-aliasing-state)

3.6.3 (set-do-GL-lighting state)

where:

• state is an exact integer number

3.6.4 (do-GL-lighting-state)

3.6.5 (use-graphics-interface-state)

3.6.6 (start-graphics-interface)

3.6.7 (reset-view)

3.6.8 (graphics-n-molecules)

3.6.9 (own-molecule-number imol)

where:

• imol is an exact integer number

3.6.10 (next-map-for-molecule imol)

where:

• imol is an exact integer number

3.6.11 (toggle-idle-spin-function)

3.6.12 (set-idle-function-rotate-angle f)

where:

• f is an inexact number

3.6.13 (idle-function-rotate-angle)

3.6.14 (handle-read-draw-molecule filename)

where:

• filename is a string

3.6.15 (read-pdb filename)

where:

• filename is a string

3.6.16 (replace-fragment imol-target imol-fragment atom-selection)

where:

• imol-target is an exact integer number
• imol-fragment is an exact integer number
• atom-selection is a string

3.6.17 (screendump-image filename)

where:

• filename is a string

3.7 Interface Preferences

3.7.1 (set-scroll-by-wheel-mouse istate)

where:

• istate is an exact integer number

3.7.2 (scroll-by-wheel-mouse-state)

3.7.3 (set-default-initial-contour-level-for-map n-sigma)

where:

• n-sigma is an inexact number

3.7.4 (set-default-initial-contour-level-for-difference-map n-sigma)

where:

• n-sigma is an inexact number

3.7.5 (print-view-matrix)

3.7.6 (get-view-matrix-element row col)

where:

• row is an exact integer number
• col is an exact integer number

3.7.7 (get-view-quaternion-internal element)

where:

• element is an exact integer number

3.7.8 (set-view-quaternion i j k l)

where:

• i is an inexact number
• j is an inexact number
• k is an inexact number
• l is an inexact number

3.7.9 (apply-ncs-to-view-orientation imol current-chain next-ncs-chain)

where:

• imol is an exact integer number
• current-chain is a string
• next-ncs-chain is a string

3.7.10 (set-fps-flag t)

where:

• t is an exact integer number

3.7.11 (get-fps-flag)

3.7.12 (set-show-origin-marker istate)

where:

• istate is an exact integer number

3.7.13 (show-origin-marker-state)

3.7.14 (suck-model-fit-dialog)

3.7.15 (suck-model-fit-dialog-bl)

3.7.16 (add-status-bar-text s)

where:

• s is a string

3.7.17 (set-model-fit-refine-dialog-stays-on-top istate)

where:

• istate is an exact integer number

3.7.18 (model-fit-refine-dialog-stays-on-top-state)

3.7.19 (set-accept-reject-dialog-docked state)

where:

• state is an exact integer number

3.7.20 (accept-reject-dialog-docked-state)

3.7.21 (set-model-toolbar-style state)

where:

• state is an exact integer number

3.7.22 (model-toolbar-style-state)

3.8 Mouse Buttons

3.8.1 (quanta-buttons)

3.8.2 (quanta-like-zoom)

3.8.3 (set-control-key-for-rotate state)

where:

• state is an exact integer number

3.8.4 (control-key-for-rotate-state)

3.8.5 (blob-under-pointer-to-screen-centre)

3.9 Cursor Function

3.9.1 (normal-cursor)

3.9.2 (fleur-cursor)

3.9.3 (pick-cursor-maybe)

3.9.4 (rotate-cursor)

3.9.5 (set-pick-cursor-index icursor-index)

where:

• icursor-index is an exact integer number

3.10 Model/Fit/Refine Functions

3.10.1 (post-model-fit-refine-dialog)

3.10.2 (unset-model-fit-refine-dialog)

3.10.3 (unset-refine-params-dialog)

3.10.4 (show-select-map-dialog)

3.10.5 (set-model-fit-refine-rotate-translate-zone-label txt)

where:

• txt is a string

3.10.6 (set-model-fit-refine-place-atom-at-pointer-label txt)

where:

• txt is a string

3.10.7 (unset-other-modelling-tools-dialog)

3.10.8 (post-other-modelling-tools-dialog)

3.11 Backup Functions

3.11.1 (make-backup imol)

where:

• imol is an exact integer number

3.11.2 (turn-off-backup imol)

where:

• imol is an exact integer number

3.11.3 (turn-on-backup imol)

where:

• imol is an exact integer number

3.11.4 (backup-state imol)

where:

• imol is an exact integer number

3.11.5 (apply-undo)

3.11.6 (apply-redo)

3.11.7 (set-have-unsaved-changes imol)

where:

• imol is an exact integer number

3.11.8 (have-unsaved-changes-p imol)

where:

• imol is an exact integer number

3.11.9 (set-undo-molecule imol)

where:

• imol is an exact integer number

3.11.10 (show-set-undo-molecule-chooser)

3.11.11 (show-set-undo-molecule-chooser-py)

3.11.12 (set-unpathed-backup-file-names state)

where:

• state is an exact integer number

3.11.13 (unpathed-backup-file-names-state)

3.12 Recover Session Function

3.12.1 (recover-session)

3.13 Map Functions

3.13.1 (calc-phases-generic mtz-file-name)

where:

• mtz-file-name is a string

3.13.2 (set-scroll-wheel-map imap)

where:

• imap is an exact integer number

3.13.3 (scroll-wheel-map)

3.13.4 (save-previous-map-colour imol)

where:

• imol is an exact integer number

3.13.5 (restore-previous-map-colour imol)

where:

• imol is an exact integer number

3.13.6 (set-active-map-drag-flag t)

where:

• t is an exact integer number

3.13.7 (get-active-map-drag-flag)

3.13.8 (set-last-map-colour f1 f2 f3)

where:

• f1 is an unknown type
• f2 is an unknown type
• f3 is an unknown type

3.13.9 (set-map-colour imol red green blue)

where:

• imol is an exact integer number
• red is an inexact number
• green is an inexact number
• blue is an inexact number

3.13.10 ( map-no gdouble[4])

where:

• map-no is an exact integer number
• gdouble[4] is an unknown type

3.13.11 (handle-symmetry-colour-change mol gdouble[4])

where:

• mol is an exact integer number
• gdouble[4] is an unknown type

3.13.12 (set-contour-level-absolute imol-map level)

where:

• imol-map is an exact integer number
• level is an inexact number

3.13.13 (set-contour-level-in-sigma imol-map level)

where:

• imol-map is an exact integer number
• level is an inexact number

3.13.14 (set-last-map-sigma-step f)

where:

• f is an inexact number

3.13.15 (set-contour-by-sigma-step-by-mol f state imol)

where:

• f is an inexact number
• state is an exact integer number
• imol is an exact integer number

3.13.16 (data-resolution imol)

where:

• imol is an exact integer number

3.13.17 (solid-surface imap on-off-flag)

where:

• imap is an exact integer number
• on-off-flag is an exact integer number

3.13.18 (export-map imol filename)

where:

• imol is an exact integer number
• filename is a string

3.13.19 (rotate-map-round-screen-axis-x r-degrees)

where:

• r-degrees is an inexact number

3.13.20 (rotate-map-round-screen-axis-y r-degrees)

where:

• r-degrees is an inexact number

3.13.21 (rotate-map-round-screen-axis-z r-degrees)

where:

• r-degrees is an inexact number

3.13.22 (difference-map imol1 imol2 map-scale)

where:

• imol1 is an exact integer number
• imol2 is an exact integer number
• map-scale is an inexact number

3.14 Density Increment

3.14.1 (set-iso-level-increment val)

where:

• val is an inexact number

3.14.2 (get-iso-level-increment)

3.14.3 (set-iso-level-increment-from-text text imol)

where:

• text is a string
• imol is an exact integer number

3.14.4 (set-diff-map-iso-level-increment val)

where:

• val is an inexact number

3.14.5 (get-diff-map-iso-level-increment)

3.14.6 (set-diff-map-iso-level-increment-from-text text imol)

where:

• text is a string
• imol is an exact integer number

3.14.7 (set-map-sampling-rate-text text)

where:

• text is a string

3.14.8 (set-map-sampling-rate r)

where:

• r is an inexact number

3.14.9 (get-map-sampling-rate)

3.14.10 (set-scrollable-map imol)

where:

• imol is an exact integer number

3.14.11 (change-contour-level is-increment)

where:

• is-increment is an exact integer number

3.14.12 (set-last-map-contour-level level)

where:

• level is an inexact number

3.14.13 (set-last-map-contour-level-by-sigma n-sigma)

where:

• n-sigma is an inexact number

3.14.14 (set-stop-scroll-diff-map i)

where:

• i is an exact integer number

3.14.15 (set-stop-scroll-iso-map i)

where:

• i is an exact integer number

3.14.16 (set-stop-scroll-iso-map-level f)

where:

• f is an inexact number

3.14.17 (set-stop-scroll-diff-map-level f)

where:

• f is an inexact number

3.14.18 (set-residue-density-fit-scale-factor f)

where:

• f is an inexact number

3.15 Density Functions

3.15.1 (set-map-line-width w)

where:

• w is an exact integer number

3.15.2 (map-line-width-state)

3.15.3 (mtz-file-has-phases-p mtz-file-name)

where:

• mtz-file-name is a string

3.15.4 (is-mtz-file-p filename)

where:

• filename is a string

3.15.5 (auto-read-make-and-draw-maps filename)

where:

• filename is a string

3.15.6 (set-auto-read-do-difference-map-too i)

where:

• i is an exact integer number

3.15.7 (auto-read-do-difference-map-too-state)

3.15.8 (set-density-size-from-widget text)

where:

• text is a string

3.15.9 (set-map-radius f)

where:

• f is an inexact number

3.15.10 (set-density-size f)

where:

• f is an inexact number

3.15.11 (set-map-radius-slider-max f)

where:

• f is an inexact number

3.15.12 (set-display-intro-string str)

where:

• str is a string

3.15.13 (get-map-radius)

3.15.14 (set-esoteric-depth-cue istate)

where:

• istate is an exact integer number

3.15.15 (esoteric-depth-cue-state)

3.15.16 (set-swap-difference-map-colours i)

where:

• i is an exact integer number

3.15.17 (swap-difference-map-colours-state)

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

where:

• imol is an exact integer number

3.15.19 (map-is-difference-map imol)

where:

• imol is an exact integer number

3.15.20 (another-level)

3.15.21 (another-level-from-map-molecule-number imap)

where:

• imap is an exact integer number

3.15.22 (residue-density-fit-scale-factor)

3.15.23 (density-at-point imol x y z)

where:

• imol is an exact integer number
• x is an inexact number
• y is an inexact number
• z is an inexact number

3.16 Parameters from map

3.16.1 (mtz-use-weight-for-map imol-map)

where:

• imol-map is an exact integer number

3.17 PDB Functions

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

where:

• imol is an exact integer number
• file-name is a string

3.18 Refmac Functions

3.18.1 (set-refmac-molecule imol)

where:

• imol is an exact integer number

3.18.2 (set-refmac-counter imol refmac-count)

where:

• imol is an exact integer number
• refmac-count is an exact integer number

3.18.3 (get-refmac-refinement-method void)

where:

• void is an unknown type

3.18.4 (set-refmac-refinement-method method)

where:

• method is an exact integer number

3.18.5 (get-refmac-phase-input void)

where:

• void is an unknown type

3.18.6 (set-refmac-phase-input phase-flag)

where:

• phase-flag is an exact integer number

3.18.7 (set-refmac-use-tls state)

where:

• state is an exact integer number

3.18.8 (refmac-use-tls-state void)

where:

• void is an unknown type

3.18.9 (set-refmac-use-twin state)

where:

• state is an exact integer number

3.18.10 (refmac-use-twin-state void)

where:

• void is an unknown type

3.18.11 (set-refmac-use-sad state)

where:

• state is an exact integer number

3.18.12 (refmac-use-sad-state void)

where:

• void is an unknown type

3.18.13 (get-refmac-ncycles void)

where:

• void is an unknown type

3.18.14 (set-refmac-ncycles no-cycles)

where:

• no-cycles is an exact integer number

3.18.15 (add-refmac-ncycle-no cycle)

where:

• cycle is an exact integer number

3.18.16 (set-refmac-use-ncs state)

where:

• state is an exact integer number

3.18.17 (refmac-use-ncs-state void)

where:

• void is an unknown type

3.18.18 (refmac-imol-coords void)

where:

• void is an unknown type

3.18.19 (add-refmac-sad-atom atom-name fp fpp lambda)

where:

• atom-name is a string
• fp is an inexact number
• fpp is an inexact number
• lambda is an inexact number

3.18.20 (clear-refmac-sad-atoms)

3.18.21 (swap-map-colours imol1 imol2)

where:

• imol1 is an exact integer number
• imol2 is an exact integer number

3.18.22 (set-keep-map-colour-after-refmac istate)

where:

• istate is an exact integer number

3.18.23 (keep-map-colour-after-refmac-state)

3.18.24 (refmac-runs-with-nolabels void)

where:

• void is an unknown type

3.19 Symmetry Functions

3.19.1 (set-symmetry-size-from-widget text)

where:

• text is a string

3.19.2 (set-symmetry-size f)

where:

• f is an inexact number

3.19.3 (get-show-symmetry)

3.19.4 (set-show-symmetry-master state)

where:

• state is an exact integer number

3.19.5 (set-show-symmetry-molecule mol-no state)

where:

• mol-no is an exact integer number
• state is an exact integer number

3.19.6 (symmetry-as-calphas mol-no state)

where:

• mol-no is an exact integer number
• state is an exact integer number

3.19.7 (get-symmetry-as-calphas-state imol)

where:

• imol is an exact integer number

3.19.8 (set-symmetry-molecule-rotate-colour-map imol state)

where:

• imol is an exact integer number
• state is an exact integer number

3.19.9 (symmetry-molecule-rotate-colour-map-state imol)

where:

• imol is an exact integer number

3.19.10 (set-symmetry-colour-by-symop imol state)

where:

• imol is an exact integer number
• state is an exact integer number

3.19.11 (set-symmetry-whole-chain imol state)

where:

• imol is an exact integer number
• state is an exact integer number

3.19.12 (set-symmetry-atom-labels-expanded state)

where:

• state is an exact integer number

3.19.13 (has-unit-cell-state imol)

where:

• imol is an exact integer number

3.19.14 (setup-save-symmetry-coords)

3.19.15 (set-space-group imol spg)

where:

• imol is an exact integer number
• spg is a string

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

where:

• shift is an exact integer number

3.20 File Selection Functions

3.20.1 (clear-refmac-ccp4i-project)

3.21 History Functions

3.21.1 (print-all-history-in-scheme)

3.21.2 (print-all-history-in-python)

3.21.3 (set-console-display-commands-state istate)

where:

• istate is an exact integer number