%-*-LaTeX-*-
% $Header: manual.tex,v 1.3 95/01/30 14:31:48 morten Locked $

% This is the manual for O in LaTeX format.
% Unresolved questions are marked with -?- in the text.
% mk.

\documentstyle[twoside,fancyheadings,alltt,makeidx,html]{report}
\pagestyle{fancyplain}

% Define some macros:

\newenvironment{example}%
          {\begin{quote}\begin{alltt}}{\end{alltt}\end{quote}}



\newcommand{\syntax}[1]% Syntax of a command
        {\begin{verse} {\bf #1}\end{verse}}


% fancyheadings stuff 
% for fancyheadings (else the rule's in the wrong margin)
\def\ps@@fancy{
  \def\@oddhead{\@fancyhead\hss\@olhead\@ochead\@orhead\relax}
  \def\@oddfoot{\@fancyfoot\hss\@olfoot\@ocfoot\@orfoot\relax}
  \def\@evenhead{\@fancyhead\hss\@elhead\@echead\@erhead\relax}
  \def\@evenfoot{\@fancyfoot\hss\@elfoot\@ecfoot\@erfoot\relax}
}

\footrulewidth 0.4pt 
\plainfootrulewidth 0.4pt 

%\lhead{\fancyplain{\sf \mbox{\bf O} version 5.9 users manual}{}}
%\rhead{\fancyplain{\sf\thepage}{}}
\rhead{}
\lhead{}
\chead{\fancyplain{}{\sf \mbox{\bf O} version 5.10 users manual}}


%\lfoot[\fancyplain{}{\sf\thepage}]%
%  {\fancyplain{}{\sf\rightmark}}
\lfoot[{\sf\thepage}]%
  {{\sf\rightmark}}

%\rfoot[\fancyplain{}{\sf\leftmark}]%
%  {\fancyplain{}{\sf\thepage}}
\rfoot[{\sf\leftmark}]%
  {{\sf\thepage}}
\cfoot{}

\renewcommand{\chaptermark}[1]{\markboth{#1}{#1}}
\renewcommand{\sectionmark}[1]{\markright{\thesection\quad #1}}
\renewcommand{\subsectionmark}[1]{\markright{\thesubsection\quad #1}}
\addtolength{\headheight}{2pt} \addtolength{\footheight}{2pt}

\hyphenation{phe-nyl-ala-nine}

\input{psfig}
\makeindex


% --- End of preamble ---

\begin{document}
\parskip=7pt
\parindent=0pt
\pagenumbering{roman} \setcounter{secnumdepth}{-1}

% --- Title page ---
\begin {titlepage}
\begin{center}

\vspace*{3cm}
{\Huge \mbox{\bf O}  -- the manual} \\
\vskip 2.5cm
\vskip 1cm
{\Large Manual for {\bf O} version 5.10} \\
\vskip 1cm
{ \Large T.A Jones {\small \P} \& Morten Kjeldgaard {\small \S}} \\
\vskip 1cm
{\small \P\  Department of Molecular Biology, BMC, 
Uppsala University, Sweden; \\
\S\  Department of Chemistry, Aarhus University, Denmark
}
\end{center}

\end{titlepage}

% empty page 

\begin{titlepage}

\vspace*{\fill}
This version typeset in \LaTeX, \today. The front cover shows a bit of
helix A with density from elongation factor EF-Tu-GDPNP from {\em
Thermus aquaticus} (Kjeldgaard, M. {\em et al.} (1993) Structure, {\bf 1},
35--50). The plot was generated with \mbox{\bf O} and converted to {\sc PostScript}
with {\bf oplot}.
\begin{verbatim}
$Header: manual.tex,v 1.3 95/01/30 14:31:48 morten Locked $
\end{verbatim}
\end{titlepage}

% table of contents: 

\tableofcontents

\chapter{Preface}

% "... when you are a Bear of Very Little Brain, and you Think of Things, you
% find sometimes that a Thing which seemed very Thingish inside you is quite
% different when it gets out into the open and has other people looking at it."
%
%                                               -- Winnie the Pooh

This version of the \mbox{\bf O} users manual does not pretend to be complete or
without errors. Because \mbox{\bf O} is still developing quite rapidly, the program
may not in every detail correspond to what the manual says it should
do. Therefore, constructive criticism, suggestions and ideas for this
manual are most welcome, as well as reports of bugs and other behavioral
disorders of the program. If you do report a bug, be sure to note the exact
circumstances in which it occurred.  Contributions in the form of \mbox{\bf O}
macros are most welcome, and will be distributed to other \mbox{\bf O} users with
proper credit to your contribution. Please write, phone, fax or e-mail:

\begin{center}
Prof. T.A. Jones\\
Department of Molecular Biology,\\
BMC, Box 590,\\
S-75124 Uppsala, Sweden.\\
Tel. - 46-18-174566\\
FAX -46-18-536971\\
e-mail: {\tt alwyn@xray.bmc.uu.se}
\end{center}

New versions of \mbox{\bf O} auxiliary files and the latest binary versions of the
program can be fetched using anonymous ftp. Log on with user ftp, password
your e-mail address to {\tt rose.bmc.uu.se} (130.238.37.19). Goto directory
{\tt pub/} and subdirectories. This version of \mbox{\bf O} is supported on the
Evans \& Sutherland ESV and Freedom workstations, the Silicon Graphics 4D
family of workstations and the Hewlett-Packard HP9000/7xx series workstations.


%%% introduction %%%

\clearpage
\pagenumbering{arabic} \setcounter{secnumdepth}{3}

\chapter {Introduction}


\section {General description} 

\mbox{\bf O} is a general purpose macromolecular modelling environment. The program is
aimed at scientists with a need to model, build and display
macromolecules. Unlike other molecular modelling programs, such as FRODO
\cite{jones78}, \mbox{\bf O} is a graphical display program built on top of a
versatile database system. All molecular data is kept in this database, in
a predefined datastructure. However, any data can be stored in the
database. Data produced by associated, stand-alone programs can very easily
be stored in the database, and used by the program, for example for
colouring of atoms.

The powerful macro facility of \mbox{\bf O} enables the user to customize the use
of the program to satisfy his or her specific needs. The current version of
\mbox{\bf O} is mainly aimed at the field of protein crystallography, bringing into
use several new tools, which ease the building of models into electron
density, allowing this to be done faster and more correctly. Notably, some
new autobuild options greatly enhance the speed of building and rebuilding
molecular models.

The program is the work of Alwyn Jones and Morten Kjeldgaard. 

\section {Hardware requirements} 

The software is designed to be easily portable between different computers
and graphics systems. The current version of the program is running on
Silicon Graphics IRIS 4D and the Evans \& Sutherland ESV
workstations. Although the 4D version of the program can be used with just
a mouse to control it, it is strongly recommended that dials be used with
both versions of the program.

Both versions of the program support Crystal Eyes Stereo glasses.


%%% basic_design %%%

\section{Basic design}
 
The program has been designed in a strictly modular way. The purpose of
this is to make the program easier to maintain on different computers,
easier to debug, and last, but not least, to facilitate the introduction of
new options and ideas by different people at the same time. Developers are
required to keep to a set of programming rules, to ensure lack of
interference between different branches of the program. Parallel
development work is therefore painless.

Various major functions (such as the map handling) are described in a {\em
major menu} list. Such a major menu can expand to a maximum of ten {\em
minor menu} keywords, allowing the user to select the particular operation
to be performed. Thus, the major menus do not perform any actions of their
own, but merely constitute a logical grouping of minor menus
(commands). This design is intended to make it easier for both developers
and users. Flag codes are issued to developers, ten at a time, without
caring if they are all used.

The macro facility of \mbox{\bf O} enhances the functionality of the program. \mbox{\bf O}
also contains a powerful graphics interpreter, enabling the user to display
any graphics data, wire frame or solids.


%%% o_database %%%
\section {The O database}  

The heart of \mbox{\bf O} is the database. Most data used or created by the program
is kept here. The \mbox{\bf O} database is the equivalent of a simple file
system. The files are called {\em datablocks}, or {\em parameter blocks}. Each
datablock has an associated header, containing data such as name, size,
read-write status, data-type, and so on. This header data is maintained by
the program. Only four types of data are allowed: real, integer, characters
and text. Most of the datablocks in the database are data items created by
the program itself, but the user has the possibility of entering and
extracting information as well.

In dealing with macromolecules, \mbox{\bf O} adopts a naming convention so that
structural information is stored in particular datablock entries. To access
the orthogonal coordinates for example, the program would look for a
datablock composed of the user-defined molecule name appended with the
string {\tt\_atom\_xyz}.  \index{\_atom\_xyz} Such an example of a datablock
is called an {\em atomic property}. Likewise, there are {\em residue
properties}; an example of this is the {\tt \_residue\_type}.
\index{\_residue\_type}
This is an array of character variables that describes the amino acid or
nucleotide sequence of the macromolecule. A standard molecular data set
consists of 9 datablocks in the current version of \mbox{\bf O}. Other atom or
residue properties can be generated by the user, using a text editor, or by
using separate stand-alone programs.

Another group of items kept in the database includes default values that do
not need to be changed very often. For example, the object definition code
defining how to display a single, unconnected atom is in the database. This
is usually a 3-D cross, but could be changed to a tetrahedron, icosahedron,
sphere, etc. This is a characteristic result of the {\em object oriented}
design of the \mbox{\bf O} program. \index{single atom}

Some files are distributed, which contain database information that is
required when starting \mbox{\bf O} for the first time. The file {\tt startup.o}
defines a number of things, e.g. the standard RSR dictionary, constants
needed for molecular object definition and the recognized colours. The {\tt
menu.o} file defines the actual menu names used to key the commands (see
Appendix \ref{app-sorted-req} for a list of the required datablocks).

%%% menus %%%

\section {Menus}

The menus have been designed in a non-hierarchical manner. This means that
any of the commands can be activated and passed to the
interpreter. Commands can be displayed on the display screen where they are
activated by picking, but they can also be typed in the terminal or
graphics windows. There is no equivalent of the FRODO CHAT mode nor of
nested pull-down or pop-up menus.

Each new release of the program is usually accompanied by new versions of
files {\tt startup.o} and {\tt menu.o}, that have the program version
number appended to their names. For example, for release 5.10 of the
program, the startup files are called {\tt startup\_5.10.o} and {\tt
menu\_5.10.o}. An \mbox{\bf O} macro file is also provided to read in these and
make any other changes that are needed to the user's existing databases.
This macro is called {\tt update\_[version].omac}. \index{update
macro} Users can also personalize the program's keywords by editing the
{\tt menu.o} file; however this is not recommended if macros are going to
be exchanged with other users. \index{menu.o}

It is recommended that a simple screen layout is adopted, consisting of
frequently used commands, personalized macros, frequently used input values
and the options controlling object visibility. Much more complicated menus
can, however, be designed.
%% (see the menus described in Appendix \ref{app-dist-macros}). 
In principle, it would be possible to mimic much of the appearance of
FRODO. However, in our experience, users will quickly prefer to use their
own macros, tailored to do repetitive, complex tasks (see {\tt
@two\_molecules} in Appendix \ref{app-dist-macros}, for example).

\section {The command line interpreter}

The user interacts with \mbox{\bf O} through a terminal and a graphics window. Some
commands will be typed on the terminal, others will be activated on the
screen by picking, clicking, pushing, pressing, flipping or popping the
appropriate pointing device. Since the program is modeless, this can be
done completely at the user's discretion. Generally, all commands are in
free format and consist of a keyword possibly followed by one or more
parameters. A command may be in upper or lower case letters, and may be
abbreviated as long as it remains unambiguous.  The underscore (\_)
character, which is a part of most minor menu names, is special. If the
input command contains one, then the parser \index{parser} skips to a \_ in
the minor menu name. For example: if you wish to activate {\bf
Lsq\_explicit}, then typing any of the following is OK:

\begin{verbatim}
lsq_explicit
lsq_e
ls_e
l_e
\end{verbatim}

However, {\tt lsq} is not be sufficient because the
command {\bf Lsq\_improve} also begins with the same characters. In macros,
it is advisable to use the full command name for readability; in
interactive work, the user will quickly learn the shortest possible form of
the most commonly typed commands.

Special care must be taken with inputs requiring text strings where buried
spaces are allowed. Such input can be delineated with double quotes ({\tt "}).

If the command requires parameters, and not all were entered on the same
line as the command keyword, the program will prompt for the parameters by
displaying the current values between square brackets:

\begin{verbatim}
Define cell parameters [ 98.2 100.8 162.0 90.0 90.0 90.0 ]: 
\end{verbatim}

Hitting [CR] will keep the current parameters. If the first one is wrong,
it is sufficient to type the first number; the rest will keep their current
values. If the third one is wrong, a comma can be entered for each
parameter that should remain unchanged, i.e: entering

\begin{verbatim} 
,,160.8
\end{verbatim}

would change the length of the c-axis in this case. 

Any number of commands and command inputs can be typed on the line in one
go.  They must be separated by at least one space. The effect of a [CR]
on a prompt can be produced with the semi-colon character ( ; ), so that

\begin{verbatim} 
ca ;
\end{verbatim}

is the same as typing {\tt ca} followed by a [CR] at the prompt. 

The following line

\begin{verbatim}
write .lsq_rt_a_to_b ; (3f10.3)
\end{verbatim}

writes out on the terminal the contents of a parameter block produced using
the {\bf Lsq\_improve} command. This would give the same result as typing
four lines:

\begin{verbatim}
write<cr>
.lsq_rt_a_to_b<cr>
<cr>
(3f10.3)<cr>
\end{verbatim}

although the latter would produce prompts after each [CR]. This is
recommended when dealing with an unfamiliar command.

The parser \index{parser} recognizes 4 special characters, @, !, \# and
\$. The @ character before a keyword specifies a macro file of
commands. All characters following a ! on a line are treated as
comments. The special character, \#, is mainly used in macros. The
character string between a pair of \#'s will be written to the terminal and
be replaced by whatever is typed at the terminal. This allows macros to
prompt for terminal input (see the {\tt @save\_as} macro in Appedix
\ref{app-dist-macros}). The special characters recognized by the parser can
be protected from expansion if they are escaped by a backslash character
\verb|(\)|.   

A word starting with a \$ is recognised as a possible
\htmlref{symbol}{cmd-symbols} and will be expanded by the parser if it is
found in the symbol table. Symbols are especially useful when creating
macros. The symbol name to be expanded may be enclosed in braces (\$\{{\em
symbol}\}), which are optional but serve to protect the variable to be
expanded from characters immediately following it which could be
interpreted as part of the name. Brace expansion of symbols were introduced
in \mbox{\bf O} version 5.10.3.

All input can be typed in upper or lower case, or intermixed any way the
user prefers. The same is true for symbols; in contrast to the UNIX
operating system, symbols are not case sensitive inside \mbox{\bf O}.

The view into the 3-D window is usually controlled by a set of physical
dials.  These dials are also used as inputs for many \mbox{\bf O} commands. A mouse
is used to pick atoms and items on a screen menu.

In the SGI 4D version of the program, there is the possibility to use a
separate window of virtual dials that can be activated by the mouse. When
the pointer is in the graphics window, the mouse can also be used to
control some of the viewing operations.

%%% objects %%%

\section {Objects}
 
In \mbox{\bf O}, everything drawn on the screen belongs to an {\em object}. This
can be a molecular object, a skeleton object, an electron density object
and so on. For each object generated, a minor menu in one of the five major
menus called {\bf Object\_1}, {\bf \_2}, {\bf \_3}, {\bf \_4}, and {\bf \_5} 
is renamed. If an object
called \verb|mol_a| is created, then the new minor menu name would be
\verb|^mol_a|. Objects can be switched on or off by picking these names on
the screen, or by typing them on the keyboard. Thus, typing

\begin{verbatim}
^mol_a
\end{verbatim}

at the terminal toggles the display state of the object called \verb|mol_a|.

Some objects are created explicitly by the user, while other objects are
created by commands. For example, the command {\bf Move\_zone} will create
an object called {\tt fragmv\_rt}. Therefore, while this command is active,
you will be able to switch the moving object on or off. The names of the
minor menus are not always updated each time a new object is created, but
activating the command {\bf On\_off} \index{On\_off} will place the names of
all currently active objects in the five major menus and display them on
the screen.

Some objects, such as atomic objects, are {\em pickable}. This allows atoms
to be identified. Other objects are {\em not} pickable. These include
electron density maps and objects created using \mbox{\bf O} {\em graphic object
descriptors} (see Chapter \ref{ch-ODL}) and displayed with the 
{\bf Draw\_object} command. \index{Draw\_object} 

%%% help %%%

\section{Getting help...}

Of course, the best way to get help using \mbox{\bf O} is to ask someone in your
lab. However, you should also be aware of two other good sources of help:
the o-info mailing list and the list of FAQ's (Frequently Asked
Questions). To join the o-info mailing list, just send a message to

\begin{verbatim}
o-info-request@kaktus.kemi.aau.dk 
\end{verbatim}

containing the word ``subscribe'' in the subject line. The mailing list
software decodes your e-mail address and adds it to the list of
subscribers.  To ensure your privacy, this list is {\em not} made
publically available.  The body of the message is not scanned for keywords,
so there is no need to put anything in there. The software receiving
messages to o-info-request also recognizes a few other keywords, that
enables you to unsubscribe or retrieve files. Requests are {\em not}
reflected to the other subscribers of the list.

{\em Postings} to the o-info mailing list are distributed to all subscribers of
the list, and should be sent to:
\begin{verbatim}
o-info@kaktus.kemi.aau.dk
\end{verbatim}
Give your posting a subject line that briefly describes the nature of your
problem.

Before posting, it is perhaps a good idea to consult the FAQ. Often, you
will find the answer to your problems in there. The FAQ, maintained by
Dr. Gerard Kleywegt, is available from anonymous ftp to {\tt rose.bmc.uu.se}.

Finally, you should be aware of the \mbox{\bf O} home page on the World Wide
Web. The URL is ({\tt http://kaktus.kemi.aau.dk}). Here, you can find a lot
of useful material, for example the FAQ list (including a keyword search),
chapter 3 of this manual (also including a keyword search), an archive of
postings to o-info, and so on. The WWW page, as well as the o-info mailing
list, are administered by Morten Kjeldgaard ({\tt mok@kemi.aau.dk}).


\section{What to do about Bugs}

Although we have worked with the program for many years, we have not
eliminated all bugs in the program.  If you think you have found a bug in
\mbox{\bf O}, you should address yourself directly to one of the authors, preferably
via e-mail, not to o-info. Please include a description of the exact
circumstances that triggered the bug, and also what machine and which
version of the program.  To be able to fix the bug, we will have to be able
to reproduce it. If you cannot reproduce the bug yourself, forget about
it, then we will not be able to do it either. If you can reproduce it, but
we can't, we may ask you to supply additional data.

A word of caution is appropriate: the open data structure of the \mbox{\bf O}
program gives you some very powerful capabilities, but if you don't know
what you're doing, you can easily disrupt the internal datastructure in the
program, making it fail immediately, or under certain circumstances. This
gives you a lot of flexibility and power, but also responsibility. The
program can not control the intactness of it's own datastructure, because
it does not have any knowledge of what values should be present in the
database. If you think you have a bug of this nature, you may try to
create a fresh new database, only entering an absolute minimum of data from
the old corrupt one.


\mbox{\bf O} relies on access to a lot of software facilities of the host computer,
for example the graphics libraries. Sometimes bugs and incompatibilities
are introduced by the vendor when updating from one version of the software
to the next. While we cannot be responsible for this type of bugs, we will
try to provide fixes and workarounds in the following version of \mbox{\bf O}.

%%% operation %%%

\chapter{Operation}

\section {Workstation versions}

The details of the installation are described in Appendix \ref{app-dist}.
The system manager decides where to store the distributed files. You start
the program by typing

\begin{verbatim}
% ono
\end{verbatim}

If the directory where the program load module is placed is not in your
{\tt \$PATH} environment variable, you have to specify the complete path
name.

On a UNIX system, it is possible use the {\em symbolic links} to shorten the
path names of the different \mbox{\bf O}  directories. If the database is stored in,
say,

\begin{verbatim}
/usr/local/o/data
\end{verbatim}

you can create a symbolic link to this directory in your own working
directory by typing

\begin{verbatim}
% ln -s /usr/local/o/data odat
\end{verbatim}

This will create a soft link (pointer) entry in your directory, to the public
directory. Then, you can refer to all the files in this directory like this:

\begin{verbatim}
odat/startup.o
\end{verbatim}

Alternatively, the user can make use of an environment variable:

\begin{verbatim}
% setenv ODAT /usr/local/o/data
\end{verbatim}

When opening a file, \mbox{\bf O} first tries the given file name, then concatenates
the contents of the datablock {\tt.odat} with the given file name, then the
environment variable with the file name. We suggest the environment variable be
set in the users {\tt .cshrc} file together with an alias for the program name.

If you have your own directory for macros and other files that you would
like \mbox{\bf O} to find, you can add those directories to the system wide default
in a colon separated list (version 5.9.2 and later):

\begin{verbatim}
% setenv ODAT $ODAT:/usr/people/morten/o/macros
\end{verbatim}

Likewise, you can add paths on separate lines in the {\tt .odat} datablock.
You cannot specify paths using the \verb|~| character, since \mbox{\bf O} does not expand
these.

\section {Getting started... } 

When the program has been started, it prompts for \mbox{\bf O} files (binary or
formatted). Any number of each can be read in. If you are starting for the
first time you MUST define {\tt startup.o}, {\tt menu.o}. You should also
define the name of the file defining the connectivity to be used when
creating molecular objects, {\tt all.dat}. \index{all.dat} The program
always asks if you wish to use the display or not.  Some commands do not
need the display so answer according to what you want to do. If you say
that you don't want to use the display, and then activate a command to
access the graphics system anyway, no graphics window will appear. When
starting for the first time, the program will prompt for any files that it
needs but are not defined. If unsure, strike the return key to accept the
default. It will also issue a warning if the user's database was created
with a different version of
\mbox{\bf O}.


\section {SGI 4D extensions} 

This version of the program will work with Crystal Eyes stereo and with
side-by-side stereo. Silicon Graphics makes a wide range of different
models. On Personal Iris machines the colouring model is colour look-up
table, on VGX, GTX, Indigo, Indigo/Elan the program uses RGB mode. The
mouse handling differs from other workstation versions of the program. By
suitable button and keyboard combinations, the mouse can now be used as a
trackball to rotate, translate, zoom, clip the picture etc. when the pointer
is within the graphics window. The solid options in {\bf Sketch} are 
equivalent to the ESV version of the program. Suitable SGI machines (VGX
and Indigo Elan models) can also display semi-transparent maps by choosing
the relevant map option. Atom identification and screen menu selection is
by interrupt picking.

The following special keys are now active when the pointer is within the graphics 
window:

[F1] -- on/off toggle for Crystal Eyes stereo.
[F2] -- on/off toggle for background black window. Because of the way
Crystal Eyes stereo works, one gets an awful mess of overlapping
windows. By using the black window and a suitably scaled and positioned
terminal window, it is possible to prevent overlap.
[F3] -- reset stereo parameters.
[F5] -- on/off toggle for line quality/type box. SGI machines come in all
shapes and forms. This box allows you to change line types. SInce the line
type affects how many lines can be drawn, you may want to draw poorer
quality lines but get a better rotational feel.
[F6] -- on/off toggle for a dial box. This can be used instead of or
incombination with real physical dials. The pointer must be positioned
within the dial box and the left button depressed; moving the mouse to
right or left with the button depressed then increases or decreases the
dial value.
[F7] -- on/off toggle for mouse trackball. Controls the action of the mouse.
[F8] -- on/off toggle for prompt text and menu windows
[F10] -- on/off toggle autospin
[F12] -- help key.

[Left Arrow / Right Arrow] -- changes stereo separation \index{arrow key}
[Up Arrow / Down Arrow] -- changes stereo depth.

[Right mouse button] -- rotation control \index{mouse buttons}
[Right mouse button + shift] -- x/y translation control
[Right mouse button + shift + middle mouse button] -- z-translation
[Shift + middle mouse button] -- scale
[Left mouse button +  middle mouse button] -- slab

\section {Dials} 

\mbox{\bf O} uses a system where up to 20 virtual dials can be used at any one
time. The first eight of these, inputs 1-8, are reserved for use with
controlling the view on the screen and so never get changed. The other 12,
are allocated and de-allocated as commands are activated. Because the dial
boxes on both E\&S and SGI use 8 physical dials, we map the 20 logical
inputs to 4 so-called {\em dialboxes}. \index{dialbox} In the distributed
startup file, this mapping ensures that the first 4 logical inputs
(controlling rotations and zooming) are always available. The mapping
groups together:

\begin{verbatim}
box 1 : 1 2 3 4  5 6 7 8 
box 2 : 1 2 3 4 9 10 11 12
box 3 : 1 2 3 4 13 14 15 16
box 4 : 1 2 3 4 17 18 19 20
\end{verbatim}

The mapping is actually controlled by entries in the database ({\tt .box1}
to {\tt.box4}) that control the assignments. These can be changed by the
user. The commands {\bf Dial\_previous}/{\bf Dial\_next} cycle through these 4
\index{Dial\_next} \index{Dial\_previous}
boxes. The user is not limited to 4 sets of boxes, but \mbox{\bf O} internally uses
only 4. The user can make entries in the database ({\tt .box5} upwards) for
special assignments. For example, it may be preferable to have all 6
degrees of freedom on the dial box when manipulating a {\bf Move\_zone}.
\index{Move\_zone}

This mechanism also has the advantage of deciding which sets of dials to
associate with the screen rotations (a source of problems for some people
who have got used to a particular way of working on other programs).

%%% commands %%%

\chapter {Description of Commands}

\section {Menus} \index{menus}
 
\mbox{\bf O} makes use of a number of socalled major menus that expand into minor
menus. A maximum of 10 minor menus or {\em commands} can be associated with
each major menu. A minor menu may always be activated by typing its name
(or bits thereof) in the terminal or graphics window.

The {\bf Menu\_control} command controls the display of keywords on 
the screen.
%The display of keywords on the screen is controlled using the command {\bf
%Menu\_control}. 
\index{Menu\_control} 
The screen menu is described in a text datablock called
{\tt .menu}. \index{.menu} The contents of this
datablock can be changed by the option {\bf Menu\_control}, or by creating
a text file using the {\bf Write\_formatted} command, editing the file, and
then reading it into the database with the {\bf Read\_formatted} command.
Don't forget to change the number of lines in the datablock header.
\index{Write\_formatted} \index{Read\_formatted}

The keywords appear on the screen with colours that vary according to
which major menu the keyword belongs. These colours are defined in the
\mbox{\bf O} database, initially from the file {\tt menu.o}. In the current
version of \mbox{\bf O}, menus are added to the screen display by adding the entire
major menu in which it appears or one item at a time, using {\bf
Menu\_control}. If one adds e.g. the {\bf Assorted\_1} major menu, it is
possible to remove for example the {\bf Wait\_ID} command from the screen
by writing to the file system the text datablock {\tt .menu}, editing it
(don't forget to change the number of lines in the datablock header), and
then reading it back into \mbox{\bf O}. For example,

\begin{verbatim}
O > write .menu q ;
O > $ vi q
\end{verbatim}

edit it to your satisfaction and then read it back into your database

\begin{verbatim}
O > read q
\end{verbatim}

The {\bf Menu\_control} command  can be used directly to add or remove single
\index{Menu\_control}
commands to the menu, e.g.

\begin{verbatim}
O > menu wait_id off
\end{verbatim}

accomplishes the task mentioned above.

The arrangement of commands in major menus is not really important to the
user of the program, except in that the grouping is made according to
functionality.  The real advantage of this design is in the ease of adding
new groups of commands to the program that do not interfere a lot with what
is already there.

In the following sections, the commands will be described according to
which major menu they belong. Each section will contain a general
description of the major menu, followed by descriptions of the individual
commands. It will include examples and macros, where applicable. If the
major menu has an associated datablock in the \mbox{\bf O} database, it too will be
described in detail.

%%% draw_mol %%%

\section {The Draw\_Mol commands}

This is a group of commands to construct molecular objects from data in the
\mbox{\bf O} database. Before issuing a series of zones, cover-spheres etc, the
molecule to be used should be defined with the command {\bf
Molecule\_name}. Once defined, the molecule name is maintained until
\index{Molecule\_name}
changed explicitly. The name of the object to be created and viewed can be
defined with {\bf Object\_name}, otherwise the object will have the same
\index{Object\_name}
name as the molecule.

\mbox{\bf O} uses explicit connectivity tables for each residue. When first started, the
program prompts for a file containing this information. The default file
connectivity draws bonds between heavy (i.e. non-hydrogen) atoms. A residue
not in the connectivity list is drawn by a distance criterion to define
bonds. Note that any number of generating commands ({\bf Ca}, {\bf Zone},
{\bf Cover}, {\bf Sphere}) can be issued (possibly with different
connectivity files) so that complicated objects can be constructed. If more
generating commands are issued after an {\bf End\_object} without defining
\index{End\_object}
a new object, then the current object gets overwritten. The colours used
are the values in the parameter block {\tt [mol]\_atom\_colour} at the
issue of the {\bf End\_object} command. Lines will only be drawn between
atoms that have on values in their {\tt [mol]\_atom\_visible}
datablock. These values can be set by the {\bf Select} commands.

Note that any number of objects can be made from one molecule, but that each
object is made from only one molecule.

When an atom is picked, the default action is to label it with a small
piece of text containing the residue and atom name. More information, such
as the residue type, and the orthogonal coordinates of the atom, can be
given in the message area at the top of the screen. The content of both the
label and the message can be customized by the user. See in the example
section \ref{sub-draw-macros} how to do this.

%---
\subsection {Object\_name}  \index{Object\_name}
\syntax {Object\_name [name]}
Define the name of a new molecular object. In the current version of \mbox{\bf O}, the
name can be up to 6 characters long.

%---
\subsection {Molecule\_name}  \index{Molecule\_name}
\syntax {Molecule\_name [name]}
Redefine the name of the molecule. The name of the current object is
changed to the same name. Therefore, if the object name is to be different
from the molecule name, the {\bf Object\_name} command must be invoked
after {\bf Molecule\_name}. Once defined, the name of the current molecule
is saved, until it is explicitly changed. The names of several datablocks
are generated from the molecule name. For example, if the molecule name is
M15, a datablock called

\begin{verbatim}
	m15_atom_xyz
\end{verbatim}

holds the orthogonal coordinates of all atoms in molecule M15. In the current
version of \mbox{\bf O}, the name of the molecule must fit into 5 characters.

%---
\subsection {Ca\_zone} \index{Ca\_zone}
\syntax {Ca\_zone [res1 res2]}
Add a CA zone to the current open object. A blank input specifies all
residues in the molecule. Entering just one residue name, specifies only
that residue.

%---
\subsection {Zone} \index{Zone}
\syntax {zone [res1 res2]}
Add a zone of residues to an object. The connectivity between residues will be
that defined in the current connectivity file (see the {\bf Connect\_file} 
command below). A blank input specifies all residues in the molecule. Entering
just one residue name, specifies only that residue.

%---
\subsection {Cover\_sphere}  \index{Cover\_sphere}
\syntax {Cover\_sphere [res atom] [radius]}
Add the residues in contact with an atom or to whole residue. Define either
an explicit atom (i.e. a residue and an atom) to choose atoms around an
atom, or define just a residue to define atoms covering a residue. If one
atom from a residue is within the cover radius, all atoms in that residue
get chosen.

%---
\subsection {Sphere\_centre} \index{Sphere\_centre}
\syntax {Sphere\_centre [radius]}
Choose atoms in a sphere centred at the current active centre. The
coordinates of this point are stored in the \verb|.active_centre|
datablock.  \index{.active\_centre}
If an atom from a residue is within the given sphere radius, all atoms in
that residue get chosen. The {\tt .active\_centre} datablock is set by any
of the commands {\bf Centre\_ID}, {\bf Centre\_xyz}, {\bf Centre\_atom},
{\bf Centre\_zone}, or by the user directly overwriting the value stored in
the database.
\index{Centre\_ID} \index{Centre\_xyz} \index{Centre\_atom} 
\index{Centre\_zone}

%---
\subsection {End\_object}  \index{End\_object}
\syntax {End\_object}
End the current open object and display it. The atomic colouring codes in
the atom property datablock {\tt [mol]\_atom\_colour} are used for bond
drawing. If the user has not issued colouring commands (see the {\bf Paint}
major menu) default values are taken: carbons yellow, nitrogens blue,
oxygens red, sulphurs green, phosphorous pink etc.

%---
\subsection {Delete\_object} \label{del-obj}  \index{Delete\_object}
\syntax {Delete\_object [name](i)}
Delete any of the created objects. The user is presented with a list of all
current objects, and prompted for an object name to be deleted. Any number of
objects can be deleted and input is terminated by a blank line.

%---
\subsection {Connect\_file}  \index{Connect\_file}
\syntax {Connect\_file [file\_name] }
Define a new connectivity file. A number of connectivity files are
distributed. The file {\tt all.dat} draws bonds between non-hydrogen
atoms for all amino acid. The connectivity in file {\tt o.dat} draws
\index{connectivity file} \index{all.dat} \index{o.dat}
bonds between  CA  and all non-hydrogen sidechain bonds. File {\tt
xplor.dat} includes essential hydrogens. File {\tt trna.dat} contains
the connectivity for tRNA. The tRNA connectivity could be added to the
amino acid connectivity if desired. Any residues not described in the
connectivity file have bonds drawn according to a distance criterion.

The format of the connectivity file is simple. The LINK statement specifies
the maximum separation between atoms in adjacent residues for a bond to be
drawn.  For each residue, there is a number of records. The first one
contains the name (type) of residue. Subsequent records start with the
keywords ATOM or CONNECT.  The ATOM records specify the names of the atoms
making up the residue. Each CONNECT record specifies a linked list of bonds
between atoms. The connections to the previous and next residues are
specified by - and +. These special connections must occur on the same
CONNECT record. Below is an example of the entry for Valine:

\begin{verbatim}
VAL
ATOM N CA C O CB CG1 CG2
CONNECT - N CA C +
CONNECT CA CB CG1
CONNECT CB CG2
CONNECT C O
\end{verbatim}

The atom names associated with each residue are also used with the {\bf
Sam\_init\_db} command to generate database entries corresponding to a
\index{Sam\_init\_db}
particular sequence.

%---
\subsection {Examples} 
Suppose you want to display the CA-trace of a protein from residues B1 to
B100, plus a sphere of atoms around residue B50. If the molecule is called
M15, the following commands will create the desired object:

\begin{verbatim}
mol m15  obj mol1  ca b1 b100 
centre_atom b50 ; sphere 10.0  end
\end{verbatim}

If you quit the program, and come back later, the object will still exist. The
object can be deleted with the command:

\begin{verbatim}
del_obj mol1 ;
\end{verbatim}

%---
\subsection {Customizing the message and atom labels} 
\index{.message\_template} \index{.id\_template}
\index{ID label, customizing} \index{message text, customizing}
The messages given when an atom is picked can be customized. This is done
via two text datablocks, {\tt .message\_template} and {\tt
.id\_template}. The text datablock contains lines of text that will be
\index{.message\_template} \index{.id\_template}
concatenated to form the string to be displayed. In the absence of the
templates, only the residue name and atom name is shown. Thus, there is
no default {\tt .id\_template}. Certain predefined format strings will
be expanded, but atom and residue properties can be included as well.
The atom or residue property names must be at the beginning of a line
and be written in full. This is best illustrated by an example. The
default template for messages is:

\begin{verbatim}
.message_template t   9  40
%MOLNAM %RESNAM %Restyp %ATMNAM, xyz =
atom_xyz
; B =
atom_b
; Z =
atom_z
atom_bone
;
residue_2ry_struc
\end{verbatim}

This could generate a string like this in the message area at the top of the
screen:

\begin{verbatim}
HCAC 43 Ser CA, xyz = -22.06 4.02 37.76 ; B = 25.86 ; Z = 6 ;
\end{verbatim}

No secondary structure nor skeleton data was output because no such
datablocks existed in the user database. Without an Id template, the label
beside the atom would be simply

\begin{verbatim}
43 CA
\end{verbatim}
Format strings which are expanded in the template include:

\begin{description}
\item [\%MOLNAM] Name of current molecule
\item [\%RESNAM] Name of current residue
\item [\%RESTYP] Residue type of current residue
\item [\%ATMNAM] Name of picked atom
\item [\%R1] Residue-type in one-letter code
\end{description}
	
The case of the letters in the format string is important and controls the
case of the output text. For example, {\tt \%RESTYP} expands to {\tt TYR},
{\tt \%Restyp} expands to {\tt Tyr}, and {\tt \%ReStyp} expands to {\tt
TyR}. {\em Datablock items must be given on separate lines} , and if a
datablock does not exist, it is simply ignored. In the example above, the
{\tt \_atom\_bone} property is shown when \index{\_atom\_bone} a bone atom is
picked, and the element number is shown when a normal atom is picked.

%---
\subsection{Macros} \label{sub-draw-macros}

The {\bf @change\_id\_colour} macro supplied with the distribution allows the
user to change the Id text colour code. The default colour is red. The {\bf
@change\_id\_number} macro changes the number of Id's in an object.  The
default has been chosen to be 3, to avoid the screen cluttering up with Id
labels, but more may be desired, for example for picture taking.


%---
\subsection {Datablocks} \label{sec-draw-db}

\begin{itemize}
\item {\tt .molec\_obj\_integer} \index{.molec\_obj\_integer}
  \begin{description} 
  \item [7 The Id text size [7].]
  \item [8   Controls the Id text colour [16711680, i.e.red].]
  \item [9   The number of Id's displayed per object [3].]
  \end{description}

\item {\tt .active\_centre}  \index{.active\_centre}
   \begin{description} 
   \item [1-3 3 real numbers, used by a variety of commands,
	including {\bf Sphere\_centre}. \index{Sphere\_centre}]
   \end{description}
\end{itemize}

Each molecular object creates a number of entries in the data base. If the
object name is {\tt CA}, for example, then the following entries are created:

\begin{description}
\item [{\tt .obj\_3dt\_ca}] Holds the current text of Id'ed atoms. 
     \index{.obj\_3dt\_ca}
\item [{\tt .obj\_con\_ca}] \index{.obj\_con\_ca}
Holds the connectivity between the atoms being displayed. This is stored as
a list of integers, pointers to the order of the atoms in the molecule. If
atoms $i$, $j$, $k$ are connected, then this would be encoded as $2i+1$,
$2j$, $2k$ in this list.

\item [{\tt .obj\_idx\_ca}]  \index{.obj\_idx\_ca}
Holds a list of pointers directly to the atoms, $i$, $j$, $k$ in the example
above.

\item [{\tt .obj\_col\_ca}]  \index{.obj\_col\_ca}
Holds a list of colours to be drawn for the atoms, in the order in {\tt
.obj\_idx\_ca} in this example.

\end{description}

Note that the actual commands issued by the user are not stored in the
database.


%%% paint %%%

\section {The Paint commands} 

The {\bf Paint} commands affect the colour properties of molecules {\em or}
molecular {\em objects}. Each molecule has an associated atomic property
called {\tt [mol]\_atom\_colour}, and each molecular object has a property
called {\tt .obj\_col\_}[object name]. These are integer arrays of colour
values. The difference between these two lists of colours is subtle, but it
is important that the difference between them is understood. If you make a
molecular object, for example using the command {\bf Zone} or {\bf Ca} ,
the current colour property of the molecule is copied to the {\em object}
colour array. Therefore, you can make an object of a molecule coloured
according to element type, with carbons white, oxygens red etc. Now, you
can change the colours associated with each atom, to represent, for example
the magnitude of their temperature factors, and make another object. Now
there are two objects, representing the same molecule. However, the colours
of the {\em first} object you created (the one with atom colouring) did
{\em not} change when you changed the colour property of the molecule,
because they are saved in the \mbox{\bf O} database along the description of the
{\em object}. \index{colour, of objects}

Some of the commands in the {\bf Paint} menu change the colour property of
the {\em objects}. These are {\bf Paint\_object}, {\bf Paint\_obj\_zone}
and {\bf Paint\_obj\_atom}, and can be used to colour {\em objects} with
the current active colour, set by {\bf Paint\_colour}. The molecular
colours have to be set according to some atom or residue property. There is
a selection of commands for doing this in different ways, namely {\bf
Paint\_property}, {\bf Paint\_ramp}, {\bf Paint\_case} and {\bf
Paint\_zone}.

\index{Paint\_property} \index{Paint\_object} \index{Paint\_obj\_zone} 
\index{Paint\_colour} \index{Paint\_zone}

\mbox{\bf O} makes use of the RGB (Red-Green-Blue) colour scheme, where the relative
intensities of the three major colour components are set, using numbers
between 0.0 and 1.0. Thus, red is (1,0,0), blue is (0,0,1) and so on. In
the program, these three numbers are converted to three 8 bit numbers between 0
and 255, and packed into a 32 bit integer word. These numbers 
(referred to as {\em colour codes}) \index{colour code} are extremely
strange when written out in decimal format, and are not understandable by
normal human beings. Unless you're really into changing certain datablocks
in the database, you should never have to deal with these strange colour 
codes. The normal way to specify colours in \mbox{\bf O} is by typing the {\em
name} of a colour. In the default {\tt startup.o} and {\tt
colour\_default.o} files, there are 71 colours to choose from and are the
colours defined in X-windows. These are

% use verbatim instead of example here to avoid left margin
\begin {verbatim}
O > pai_col ?                                                               
 Paint>Available colors:
 Paint>  aquamarine            black                 blue
 Paint>  blue_violet           brown                 cadet_blue
 Paint>  coral                 cornflower_blue       cyan
 Paint>  dark_green            dark_olive_green      dark_orchid
 Paint>  dark_slate_blue       dark_slate_gray       dark_slate_grey
 Paint>  dark_turquoise        dim_gray              dim_grey
 Paint>  firebrick             forest_green          gold
 Paint>  goldenrod             gray                  green
 Paint>  green_yellow          grey                  indian_red
 Paint>  khaki                 light_blue            light_gray
 Paint>  light_grey            light_steel_blue      lime_green
 Paint>  magenta               maroon                medium_aquamarine
 Paint>  medium_blue           medium_forest_green   medium_goldenrod
 Paint>  medium_orchid         medium_sea_green      medium_slate_blue
 Paint>  medium_spring_green   medium_turquoise      medium_violet_red
 Paint>  midnight_blue         navy                  navy_blue
 Paint>  orange                orange_red            orchid
 Paint>  pale_green            pink                  plum
 Paint>  red                   salmon                sea_green
 Paint>  sienna                sky_blue              slate_blue
 Paint>  spring_green          steel_blue            tan
 Paint>  thistle               turquoise             violet
 Paint>  violet_red            wheat                 white
 Paint>  yellow                yellow_green
\end{verbatim}

If this is not enough for you, the program will in most places accept 3
numbers for the RGB value when the colour prompt comes up. You can also
define your own set of colour names. To get the list of colour names, type a
question mark (?) as argument to the {\bf Paint\_colour} command.  When
specifying a colour name, you are allowed to abbreviate to a unique set of
letters. \index{Paint\_colour}

(If you insist on fooling around with the strange colour numbers, for
modifying {\tt menu.o}, for example, there is a macro {\bf @colcod} to do
the conversion for you).
\index{colcod macro}

%---
\subsection {Paint\_property} \index{Paint\_property}
\syntax {paint\_property [property] [operator] [value]
	 [colour]}
Paint according to the residue or atomic property. For example, paint all
phenylalanine residues blue and all tryptophanes violet:

\begin{verbatim}
paint_prop residue_type = phe blue
paint_prop residue_type = trp violet
z ; end
\end{verbatim}

Or, colour the first 15 residues red, the remaining yellow:

\begin{verbatim}
paint_prop residue_name < A16 red
paint_prop residue_name >= A16 yellow
z ; end
\end{verbatim}

%---
\subsection {Paint\_ramp}  \index{Paint\_ramp}
\syntax {paint\_ramp [property] [min\_value max\_value]
	                [start\_colour] [end\_colour] } 
Colour ramp according to the individual value of the property. The default
property is the residue internal number, stored as a datablock with a
residue property {\tt [mol]\_residue\_irc}.  \index{\_residue\_irc}
If this property does not exist, it is created. The minimum and maximum
values are those in the specified property vector. This option can be used
make pretty CA drawings where the colour changes as one goes from
N-terminal to the C-terminal:

\begin{verbatim}
paint_ramp ; ; red blue ca ; end
\end{verbatim}

We could also ramp according to temperature factors, so that the smallest
values are blue and the highest values are red:

\begin{verbatim}
paint_ramp atom_b ; violet red zone ; end
\end{verbatim}

or we could colour the real space residue fit from salmon pink to cyan:

\begin{verbatim}
paint_ra res_rsfit ; salmon cyan   z  ; end
\end{verbatim}

%---
\subsection {Paint\_case}  \index{Paint\_case}
\syntax {paint\_case [property] 
        [\#values] [values] [colours]}
Colour residue or atomic properties according to discrete values, all in
one go. The default is {\tt [mol]\_atom\_z}. The following commands will
colour the current molecule according to atom name:

\begin{verbatim}
paint_case atom_name 5 c* n* o* s* p* white blue red yellow green
z ; end
\end{verbatim}

Notice that for the specification of character value properties such as
atom names or residue types, you can use the wildcard character * in the
specification.  Thus, for residue types, T* could be Tyr, Thr or Trp. This
is {\em not} the case in command, property or colour specification.

Another way to paint atoms according to the type of atom is to use the element 
number property:

\begin{verbatim}
pa_ca atom_z 3  6 7 8  white blue red  z ; end
\end{verbatim}

This will colour atoms with Z = 6 (carbon) white, atoms with Z = 7
(nitrogen) blue and atoms with Z = 8 (oxygen) red. The zone containing the
whole molecule will be drawn. In fact this way of colouring according to
atom type is faster, because there is less computation involved in the
comparison, than is the case for character properties like {\tt
\_atom\_name}. Now let us try to paint according to the charges on
residues. To do this, you need to load the residue table containing the
charges: \index{\_atom\_name}

\begin{verbatim}
db_table_res charge i table_charge
paint_case residue_charge 3  -1 0 1 red white blue z ; 	end
\end{verbatim}

The latter line could be abbreviated even further:

\begin{verbatim}
p_ca r_c 3  -1 0 1 re whi blue z ; end
\end{verbatim}

%---
\subsection {Paint\_zone}  \index{Paint\_zone}
\syntax {paint\_zone [mol] [start end] [colour]}
Paint a zone of a molecule a particular colour. The following command will
paint residues A1 to A23 of the current molecule green, and draw all the
CA's:

\begin{verbatim}
paint_z ; a1 a23 green ca ; end
\end{verbatim}

%---
\subsection {Paint\_select} \index{Paint\_select}
\syntax {Paint\_select}
Paint a selection. See the section on the {\bf Select} commands (\ref{sec-select-ex})
for examples.

%---
\subsection {Paint\_object}  \index{Paint\_object}
\syntax {Paint\_object [id an atom] or  [object]}
The user is required to identify an object, which is painted with the
current colour. The object can be specified by identifying an atom in the
object or by by typing on the same line , e.g.

\begin{verbatim}
pa_obje m14 90 sph
\end{verbatim}

%---
\subsection {Paint\_obj\_zone}  \index{Paint\_obj\_zone}
\syntax {Paint\_obj\_zone [id two atoms] or  [mol res1 res2 object]}
The user is required to identify a zone in an object, which gets painted with
the current colour. Useful for interactively making a picture where for example
alpha-helices are one colour, and beta-strands another. The object can 
be specified by identifying two atoms in the object or by by typing on the 
same line, e.g.

\begin{verbatim}
pa_obj_z m14 90 110 ca
\end{verbatim}

%---
\subsection {Paint\_obj\_atom} \index{Paint\_obj\_atom}
\syntax {Paint\_obj\_atom [id an atom] or [mol res atom object]}
 The user is asked to identify an atom, which gets painted with the current
colour.

%---
\subsection {Paint\_colour} \index{Paint\_colour}
Select the current colour. The colour is be given as a colour name. There
are 71 standard colours to choose from, and the list of colour names can be
listed by answering with a question mark (?) in response to the prompt. The
colour name is converted internally to a mysterious integer code. The
current colour {\em code} is stored in the datablock {\tt .active\_colour},
the {\em name} of the current colour is stored in the datablock {\tt
.active\_colour\_name}. If an unknown colour input is given, the current
colour remains unchanged. It is also possible to specify a colour directly
using the RGB triple.
\index{.active\_colour\_name} \index{RGB colour} \index{.active\_colour}

%---
\subsection {Personalized Colours} \index{colours, personalized}
The colours available to the user are stored in the \mbox{\bf O} database, and can
be changed. There are two datablocks, one containing the names, {\tt
.colour\_names}, and one containing the corresponding RGB triplets, {\tt
.colour\_rgb}. The latter is a real datablock, and the values are
\index{.colour\_rgb} \index{.colour\_names}
normalized to the range [0:1]. You can easily configure your own colours
from the standard X colour database. First make a text copy onto your
working directory:

\begin{verbatim}
% /usr/bin/X11/showrgb > myrgb.txt
\end{verbatim}

Edit this file to weed out the colours you dont need. There will be quite a
few; the XR11.4 database contains $>$ 200. If you want a feel for the look of
the different colours, use the UNIX shell script {\tt dispcol}: \index{{\tt dispcol}}

\begin{verbatim}
% dispcol < myrgb.txt > tmp
\end{verbatim}

The file {\tt tmp} contains a series of ODL drawing instructions that can be
displayed in \mbox{\bf O} using the {\bf Draw} command:

\begin{verbatim}
O > draw tmp
\end{verbatim}

There is another shell script, {\tt mkcol}, that will generate the relevant
datablocks. \index{{\tt mkcol}}

\begin{verbatim}
% mkcol < myrgb.txt > junk 
\end{verbatim}

Then, inside \mbox{\bf O}, read the file using {\bf Read\_formatted:} 

\begin{verbatim}
O > {\bf read junk} 
\end{verbatim}

and you are set to go.

%%% Note %%%
\section{The Notes menu}
The {\bf Notes} major menu contains a number of commands that enable the user
to maintain three-dimensional notes in the database. Such notes are useful is
for tracing a new structure when one often wants to record ideas of where one
may be in a structure, for introducing reminders during refinement, or for
taking pictures.Each note has an associated name, and can contain an arbitrary
number of text elements. Any number of objects can be generated from the notes.
The colour and size of the text elements can be adjusted (SGI machines don't
support different text character sizes). A text string can be added next to an
ID'ed atom, or at a specific coordinate in orthogonal {\AA}ngstrom
coordinates. When created, a text string will be added to the currently open
note name and note object. However, to avoid the screen from getting cluttered
with a large number of 3D text strings, that also degrade the performance of
the graphics system, the display of notes can be restricted to those within a
given radius from the active centre. Presently, note objects are not recreated
when the program is started.

\subsection{Note\_setup} \index{Note\_setup}
\syntax{Note\_setup [colour] [size] [font]}
Set the colour, size and (not yet used) font of the next text element.

\subsection{Note\_name} \index{Note\_name}
\syntax{Note\_name [name]}
Change the name of the "active note". If a note of this name does not exist, a
new one is created. If the note does exist, text is added to it.

\subsection{Note\_object} \index{Note\_object}
\syntax{Note\_object [object name]}
Define the object name of the displayed note.

\subsection{Note\_id\_add} \index{Note\_id\_add}
\syntax{Note\_id\_add [identify atom] [text string]}
Add note at a picked atom or bone atom. The text string is added to the current
note and note object.

\subsection{Note\_xyz\_add} \index{Note\_xyz\_add}
\syntax{note\_xyz\_add [x y z] [text string]}
Add note at the given orthogonal {\AA}ngstrom coordinate. The text
string is added to the current note and note object.

\subsection{Note\_sphere} \index{Note\_sphere}
\syntax{Note\_sphere [radius]}
Create an object from the current note, with a name defined by
{\bf Note\_object}, displaying all notes within the given radius. To display
all your notes, simply specify a very large radius. This command is used to
redisplay notes after you startup the program.

%%% sketch %%%

\section {The Sketch commands}
 
The {\bf Sketch } major menu is a menu to draw different stylized pictures
of macromolecules. The {\bf Sketch} menu works similarly to the {\bf
Draw\_mol} commands: first an object is opened, by giving it a name. The
{\bf Sketch\_object} command is used to do this. Then a series of drawing
instructions can be given to add to the currently open sketch object, using
the {\bf Sketch\_add} command. Unlike the {\bf Zone} command, used to draw
molecular objects (which are pickable, sketch objects are not), {\bf
Sketch\_add} allows you to define the zones by picking start and end
residues on the screen.  (Of course, you can only do this if you have a
molecular object displayed).

The current sketch type is set by the {\bf Sketch\_type}  command. The options
\index{Sketch\_type} available in the current version of \mbox{\bf O}  are:

\begin {description}
\item [tapeworm] A worm made up of little rectangles in the peptide planes, in
the style of Arthur Lesk \cite{lesk82}. Works for protein only, as the atoms
forming the peptide plane are needed by the algorithm. \index{tapeworm}

\item [ribbon]  The classic ribbon representation, as described by 
Carson \cite{carson87}.  A set of cubic b-spline curves is drawn using the central
atoms of the molecule atoms as control points. Works for protein molecules
only. \index{ribbon}

\item [cylinder] This sketch type draws a cylinder, coaxial to an alpha helix.
Works for protein molecules only. \index{cylinder} The first and last turns
in the helix are used to calculate the axis direction of the cylinder.

\item [spiral]  The classic alpha-helix style made popular by Jane Richardson
\cite{richardson81}. 
This sketch type is not suited for beta-strand regions, but looks good for RNA
structures, when using P or C1* as central atoms. \index{spiral}

\item [arrow]  The classic beta-strand style made popular by Jane Richardson. Only
suited for protein beta-strand. The arrows do not look good when drawn in alpha-helical
regions. \index{arrow}

\item [rattler]  Also known as the {\em tube}. Draw a smooth looking rattle
snake through the central atoms. Very suitable for loop regions of a
protein when creating a cartoon. \index{rattler}

\end{description}


The command {\bf Sketch\_add} uses the current definition of what type of
sketch you want, and for each type, the characteristic parameters. These
parameters are set by {\bf Sketch\_setup}. Normally, once and for all, you
would settle for a set of parameters that appeal to you, and only rarely
change them.  The colours of the sketches are taken from the current colour
of the central atom of the molecule. For proteins, this is normally the Ca
atom, but the user can define the central atom in the {\tt
[mol]\_molecule\_ca} datablock. For tRNA, it often looks good to use
the C1* atom as the central atom, instead of P. The program can also apply
two particular sketch operations to whole objects.  These can be used to
make objects of balls ({\bf Sketch\_cpk}) or of sticks ({\bf
Sketch\_stick}). Several different types of sketches can be mixed in the
same object. If you begin the definition of a new sketch without defining
another object name, the old sketch will be overwritten.
A

%---
\subsection {Sketch\_setup}  \index{Sketch\_setup}
\syntax {Sketch\_setup [option] [parameters]}
Set up parameters for the different sketch options. After issuing the {\bf
Sketch\_setup} command, you have to specify the sketch type for which to
\index{Sketch\_setup}
set up parameters; this also sets the current sketch type (same as {\bf
Sketch\_type}).  The number of parameters vary according to type. Default
\index{Sketch\_type} 
values are given in brackets.

\begin{itemize}
\item Tapeworm
   \begin{itemize}
   \item Solid or line mode [solid]
   \item Width of tapeworm in \AA\ [1.5].
   \end {itemize}

\item Ribbon. Only available in line mode.
   \begin{itemize}
   \item Width of ribbon in \AA\ [1.5]
   \item Number of lines in ribbon [7]. This parameter determines 
   how many parallel curves are drawn along the polypeptide chain.
   \item Number of segments per peptide [5]. This is the number of 
   points that are generated on the curve between successive CA's. 
   Five segments gives a nice reasonable compromise between a 
   smooth looking curve, and not too many vectors on the display.
   \item Smoothness [2]. A value of 1 for the smoothness generates 
   a Cardinal spline instead of a b-spline.
   \end {itemize}

\item Cylinder. The zone chosen to define a cylinder must be \verb|>=|4.
   \begin {itemize}
   \item Rendering mode [solid]. For cylinders, the rendering 
   mode can be line, solid or smooth. Both solid and smooth 
   modes generate solid cylinders, but in the former mode 
   the cylinders are built up using polygons.
   \item Radius [2.5]. This is the approximate radius of an alpha-helix.
   \item Number of edges [24]. The number of facets on the 
   polygonal approximation to the cylinder.
   \end{itemize}

\item Arrow.
   \begin{itemize}
   \item Rendering mode [solid]. For arrows, this can be line or solid.
   \item Width of arrow in \AA\ [2.5].
   \item Thickness of arrow in \AA\ [0.5].
   \item Width of arrow head in \AA [3.75]. 
   This is the width at the base of the
   arrowhead. The default is actually 1.5 X  the width of the arrow.
   \item Number of segments {\sl n}(s) [2]. This parameter determines how each 
   segment of the arrow is subdivided.
   \item Number of lines on face \& side [7 3]. These parameters are used 
   only in line mode. They can be used to give the arrows a solid look.
   \item Smoothness {\sl s} [2]. The s parameter determines the degree of 
   interpolation of the central atom curve. This is done in order to 
   give a smooth appearance of the arrow. 
   \end{itemize}	

The number of extra points inserted between two atoms is equal to \verb|2^(s-1)|
where {\sl s} is the smoothness parameter. Each of the \verb|2^(s-1)| segments are
then subdivided into the number sub-segments defined by the number of
segments parameter {\sl n(s)}. The number of polygons drawn depend very heavily
on the two parameters {\sl s} and {\sl n(s)}. For picture taking, you might want a
very smooth looking sketch, but when speed is important, a more coarse
representation will probably do. The total number of polygons used to
render an arrow of length N residues is: Equation 1


\item Spiral
   \begin{itemize}
   \item Rendering mode [solid]. For spirals, this can be line or solid.
   \item Width of spiral in \AA [2.5].
   \item Thickness of spiral in \AA\ [0.5].
   \item Width of spiral termini in \AA\ [0.5]. This parameter determines 
   how wide the spiral is at the termini, where it normally joins up 
   with other sketch elements.
   \item Number of segments {\sl n}(s) [2]. As for the arrow.
   \item Number of lines on face \& side [7 3]. As for the arrow.
   \item Smoothness {\sl s} [2]. As for the arrow.
   \end{itemize}
	
The number of polygons used to draw a spiral of length N residues is: Equation 2


\item Rattler
   \begin{itemize}
   \item Rendering mode [solid]. For rattlers, this can be line or solid.
   \item Radius of rattler [0.5].
   \item Number of edges {\sl n}(e) [7]. This parameter sets the number of facets.
   \item Smoothness {\sl s} [2]. As for the arrow. 
   \end{itemize}

Experimenting with the parameters may result in many interesting looking
representations.

In solid rendering mode, the {\em rattler} is made up of tiny polygons. There
can be quite a large number of polygons forming a rattler, and the performance
of the computer my degrade considerably. If the length of the rattler is N, the
number of polygons used in the rendering will be: Equation 3


\item  Stick
   \begin{itemize}
   \item Rendering mode [smooth]. For sticks, this can be line, 
   solid or smooth.
   \item Radius of stick [0.1].
   \item Number of edges [5].
   \end{itemize} 
   	
\item Sphere
   \begin{itemize}
   \item Rendering mode [smooth]. For spheres, this can be line, 
   solid or smooth. 
   \item Tesselation number [2]. 
   \end{itemize}

In solid or line mode, \mbox{\bf O} will generate spheres made of polygons. This
is useful when making plots, since the current version of the plotting
program {\bf oplot} \index{oplot} can't handle spheres yet. The
tesselation number {\sl n} determines how close an approximation to a sphere
is made. The number of polygons is \verb|(2 x 4^(n+1))| and is thus a very
rapidly growing function.

\item Cartoon
   \begin{itemize}
   \item Alpha helix: sketch type [spiral], colour [red], template name [ALPHA].
   \item Beta strand: sketch type [arrow], colour [blue], template name [BETA].
   \item Loop: sketch type [rattler], colour [yellow], template name [].
   \end{itemize}
	
Other sketch types that could be chosen instead of the defaults are for
example: cylinder for alpha helix, and tapeworm for loop regions. If the
special colour `molecule' is chosen, the sketch will be coloured according
to the molecule's colour for each residue.
\end{itemize}

%---
\subsection {Sketch\_object} \index{Sketch\_object}
\syntax {Sketch\_object [object]}
Begin the definition of a new sketch object. This command is equivalent to the
{\bf Object}  command for molecular objects.

%---
\subsection {Sketch\_type}  \index{Sketch\_type}
\syntax {Sketch\_type [option]}
Set the current sketch type (arrow, rattler, etc.).

%---
\subsection {Sketch\_add} \index{Sketch\_add}
\syntax {Sketch\_add [id two atoms] or  [mol] res1 [res2]}
Add a zone, with the current setup parameters, to the currently open sketch
descriptor. Input can be given by picking on the display, or by entering
the zone from the terminal. The sketch element appears immediately on the
screen.

%---
\subsection {Sketch\_undo} \index{Sketch\_undo}
\syntax {Sketch\_undo} 
Undo the action of the last {\bf Sketch\_add}  command. Repeating the command
\index{Sketch\_add}
results in the removal of the sketch elements, with the most recent ones being
removed first, i.e. you cannot undo a {\bf Sketch\_undo} command.

%---
\subsection {Sketch\_auto}  \index{Sketch\_auto}
\syntax {Sketch\_auto [mol] [zone]} 
This command allows you to generate a cartoon of the type invented in
Uppsala, but popularized by Jane Richardson and made more accurately
using computer graphics by Arthur Lesk and Karl Hardman. {\bf
Sketch\_auto}  uses the output of a previous {\bf Yasspa}  run, and
generates and executes a macro called @cartoon. This macro is stored as
a text data block in the \mbox{\bf O} database, and it uses the current setting
as defined in {\bf Sketch\_setup}. Therefore, if you do not like the
\index{Sketch\_setup}
appearance of the cartoon, you can change the parameters and run the
macro again:

\begin{verbatim}
@cartoon
\end{verbatim}

Colours and type of the cartoon are defined in the cartoon section
of {\bf Sketch\_setup}. \index{Sketch\_setup}

%---
\subsection {Sketch\_stick} \index{Sketch\_stick}
\syntax {Sketch\_stick [id an atom] or [object]}
Unlike most of the other sketch commands, this is object oriented. Can be
used to draw cylinders around the bonds of an object. If the real
datablock {\tt .stick\_radius} exists, its value is used for the radius of the
\index{.stick\_radius}
cylinder. In this way, {\bf Sketch\_stick} can also be used to stickify
a C-alpha trace with thick cylinders. Both this command and {\bf
Sketch\_cpk}  keep the atomic colouring used in the defined object. Sticks
\index{Sketch\_cpk} \index{stick representation}
can be drawn in line, solid or the computer's generic mode. Stick
drawings, if they are complicated, don't rotate in real time on most
workstations.

%---
\subsection {Sketch\_cpk} \index{Sketch\_cpk}
\syntax {Sketch\_object [id an atom] or [object]}
Converts an atomic object of bonds into a CPK object. This is essentially
identical to {\bf CPK\_object} but without the options. It uses the same
\index{CPK\_object}
datablock {\tt .cpk\_radii} to obtain atomic radii for the spheres. It can,
\index{.cpk\_radii.o} \index{radii.o}
therefore, be used to construct real CPK objects or in the creation of
ball-and-stick objects by reading in suitable atomic radii. Two example
files are provided in {\tt cpk\_radii.o} and {\tt radii.o}, for large and
small balls. Both this command and {\bf Sketch\_stick} keep the atomic
\index{Sketch\_stick} \index{CPK models}
colouring used in the defined object. CPK models can be drawn in line,
solid or the computer's generic mode. Creating a spacefilling model of the
entire molecule is likely to make most workstations go totally dead if you
try to turn the dials. The best way to take a photo is to find the
orientation first with a normal vector drawing, turn off everything, and
then create the spacefilling model.

%---
\subsection {Example} 
Draw tapeworms from residues A1 to A10 and A100 and A120, and connect
these by a ribbon:

\begin{verbatim}
sketch_obj x 
sk_set tape line 1.5
sk_add a1 a10
sk_add a100 a120
sk_typ ribbon
sk_add a10 a100
\end{verbatim}

Make a ball-and-stick object of an object {\tt x} :

\begin{verbatim}
obj x sphe 10 end
ske_stick x
read radii.o
ske_cpk x
\end{verbatim}

%---
\subsection {A note on solid surfaces} 
On machines utilizing the PHIGS graphics library (ESV, ESF \& HP), 
the rendering of solid surfaces is controlled via a
datablock called {\tt .active\_surface}. The entries in the datablock are as
\index{.active\_surface} follows:

\begin{description}
\item [1  Ambient coefficient [1.0].]
\item [2  Diffuse coefficient [1.0].]
\item [3  Specular coefficient [1.0].]
\item [4-6 Specular colour component in rgb [1.0 1.0 1.0].]
\item [7 Specular exponent [0.5].]
\item [8 Transparency [0.0].]
\item [9  Shading method [2]. Sets the PHIGS+ shading method. The possible values are:] 
	\begin {description}
	\item [1 No shading. This means that nothing appears on the screen.] 
	\item [2 Colour interpolation shading.]
	\item [3 Dot product interpolation shading.]
	\item [4 Normal interpolation shading.]
	\end{description}
\item [10  Shading style [1] Sets the PHIGS+ shading style. The only
sensible value to use is]
	\begin{description}
	\item [1 solid]
	\end{description}
\item [11  Reflectance equation [4] Sets the PHIGS+ interior reflectance
equation parameters. The possible values are:]
	\begin{description}
	\item [1 No reflectance calculation performed.]
	\item [2 Use ambient term]
	\item [3 Use ambient and diffuse terms.]
	\item [4 Use ambient, diffuse and specular terms.]
	\end{description}
\end{description}

There is not yet any user interface for changing the active surface. If
for some reason, therefore, you don't see any solids appearing on the
screen when you thought something would, it is possible that the values
in the database have been corrupted. You should then try deleting the
datablock {\tt .active\_surface}. \mbox{\bf O} will then reset things to a sensible
\index{.active\_surface}
state.

%%% select %%%

\section {The Select commands}

This menu includes a set of commands to select atoms on the basis of
properties. After the selection of a set of atoms, different actions can
be performed on the selection; most commonly they are displayed or
coloured. The {\bf Select}  commands act on an atomic property 
{\tt [mol]\_atom\_select}. If this property does not exist for a given
molecule, it is created.
\index{\_atom\_select}

Several commands make use of the selected atoms, for example: {\bf
Sam\_atom\_out}, {\bf Paint\_select}, {\bf Lego\_loop} \& {\bf
Patt\_cross}. When used for display purposes, the selection can be used
to create an additional filter in determining which atoms are to be
displayed.  This filter is made with the atomic property
{\tt [mol]\_atom\_visible}. Bonds will only be drawn when the value of
this property for each atom is on. This atomic property is best
manipulated with the {\bf Select} menu, first defining which atoms are
to be selected, and then copied to the correct datablock with {\bf
Select\_visible}.

\index{Patt\_cross} \index{Paint\_select} \index{Lego\_loop}
\index{Sam\_atom\_out}
\index{Select\_visible}

Several \mbox{\bf O} commands make use of the visibility filter datablock
feature behind the user's back. For example, in {\bf Move\_fragment},
the atoms in the moving fragment are marked to be visible. The
visibility datablock is then inverted and the drawing routine called
again to create the rest of the object.
\index{Move\_fragment}

%---
\subsection {Select\_on} \index{Select\_on}
\syntax {Select\_on [mol] [res1] [res2]}
The residues given are selected. The selection values of atoms outside
the zone are not affected. If no input is given, all residues in the
current molecule are selected.

%---
\subsection {Select\_off}  \index{Select\_off}
\syntax {Select\_off [mol] [res1] [res2]}
The residues given are removed from the selection. Atoms outside the zone
are not affected. If no input is given, all residues in the current
molecule are un-selected. This command is often used to clear the
selection property, like this:

\begin{verbatim}
Sel_off ;;
\end{verbatim}

%---
\subsection {Select\_property}  \index{Select\_property}
\syntax {Select\_property [property] [op] [value] [on/off]}
Select atoms or residues according to property. The property can be of type
real, integer or character. The operator must be one of the following: 
\verb|<|, \verb|>|, \verb|<=|, \verb|>=|, \verb|=|, \verb|^=| 
(means not equal). In future versions of
\mbox{\bf O}, it will be possible to make logical operations on selections.

%---
\subsection {Select\_visible}  \index{Select\_visible}
\syntax {Select\_visible}
The select datablock of the current molecule is copied to the visibility
datablock of that molecule. The latter datablock acts as a filter in the
drawing of new objects. Bonds will appear between atoms that are set on.

%---
\subsection {Select\_invert}  \index{Select\_invert}
\syntax {Select\_invert}
The select datablock is inverted, that is, 1's become 0's and vice versa.

%---
\subsection {Examples} \label{sec-select-ex}
{\bf Select\_property}  can be used to create more complicated molecular objects
for display. The following commands will create a CA-trace showing all
the tyrosine sidechains.  The final {\bf Zone} command specifies the whole
molecule since no input is given but only the `visible' atoms are
drawn. It is wise to reset both the selection and visible datablocks
after making the object:
\index{Zone} \index{Select\_property} \index{visibility}

\begin{verbatim}
obj ca_tyr
conn o.dat
sel_off ;;
sel_prop atom_name = ca on
sel_prop residue_type = tyr on
sel_vis
z ; end
sel_on ;; sel_vis
\end{verbatim}

Note that the connectivity file is {\tt o.dat} and not {\tt all.dat}. 
\index{o.dat} \index{all.dat}
Using the latter would cause small crosses to be drawn at non-tyrosine residues.


In the next example, we display the poly-Gly backbone:

\begin{verbatim}
obj poly_g
conn all.dat
sel_off ;;
sel_prop atom_name = n on
sel_prop atom_name = ca on
sel_prop atom_name = c on
sel_prop atom_name = o on
sel_vis
z ; end
\end{verbatim}

 
Now, display all residues with bad rms pep-flip values:

\begin{verbatim}
obj flip
sel_prop residue_pepflip > 2.5 on
sel_vis
z ; end
\end{verbatim}

In this last example, the residue property called {\tt
\_residue\_pepflip} must have been calculated in advance by the {\bf
Pep\_flip} option.
\index{\_residue\_pepflip} \index{Pep\_flip}

Paint acidic residues red, basic residues blue, all other residues white:

\begin{verbatim}
sel_on ;; 
paint_sel white
sel_off ;;
sel_prop residue_type = asp on
sel_prop residue_type = glu on
paint_sel red
sel_off ;;
sel_prop residue_type = lys on
sel_prop residue_type = arg on
sel_prop residue_type = his on
paint_sel blue
obj chrg z ; end
\end{verbatim}


%%% manip %%%

\section {The Manip menu}  

These menus allows the user to manipulate a molecule, that is, to move
around atoms or groups of atoms. The coordinates in the database are
updated as the atom(s) move and can therefore be tagged with distances and
neighbour calculations. However, the updated coordinates are {\em not}
written to disk until one of the following commands {\bf Save\_DB,} {\bf
Stop}, {\bf BackUp\_db}, or {\bf Sam\_atom\_out} is issued. In general, the
{\bf Manip} commands are terminated by selecting {\bf Yes} or {\bf No} to
accept or reject the new coordinates.
\index{Manip} \index{BackUp\_db}

Each minor menu has a so called {\em dial set} associated with it. All dial
\index{dial set}
sets have the {\em same} four dials associated with the view rotations
around $x$, $y$ and $z$, and the zoom. The remaining dials may have different
functions in the different dial sets, depending on the requirements of the
particular menu activating the dial set. These will be called the auxiliary
dials. For example, the {\bf Move\_atom} menu has a dial set in which the
\index{Move\_atom}
three auxiliary dials control the translations along $x$, $y$ \& $z$,
respectively. Some commands, for example {\bf Move\_zone} need to activate
\index{Move\_zone}
two dial sets, one for the rotations and one for the translations. To
switch between different dial sets, the two commands {\bf Dial\_previous}
\index{Dial\_previous}
and {\bf Dial\_next} are used. In fact, we recommend that these two
\index{Dial\_next}
commands are on the screen at all times. Dial set 1 is the default viewing
dial set, activated when \mbox{\bf O} is invoked.

%---
\subsection {Move\_atom}  \index{Move\_atom}
\syntax {move\_atom [id an atom] or [mol res atom]}
The identified atom moves under the influence of the dials. You should
use {\bf Yes} or {\bf No} to terminate the command. The {\bf Clear\_flag}
\index{Clear\_flag}
command accepts the coordinates, producing the same result as {\bf
Yes}. The coordinates are updated as the atom moves. The shape of the
moving atom can be changed at will, an \mbox{\bf O} descriptor in a text datablock
called {\tt .moving\_atom} is used to draw the atom.
\index{.moving\_atom}
A related command is {\bf Patt\_move}, which moves the atom 
along the crystal axes instead of the screen axis system. \index{Patt\_move}

%---
\subsection {Move\_zone} \index{Move\_zone}
\syntax {Move\_zone [id two atoms] or [mol res1 res2 object]}
Moves a specified zone of residues. The user is required to pick an atom in
the starting and the ending residue. In particular, double clicking on an
atom in a residue makes that residue active and the identified atom is
taken as the pivot point. Otherwise the centre of mass is used as the pivot
point. The identified zone moves under the influence of the dials. You
should use {\bf Yes} or {\bf No} to terminate the command. The {\bf
Clear\_flag} command accepts the coordinates, producing the same result as
\index{Clear\_flag}
{\bf Yes}. The coordinates of all atoms in the zone are updated as the
atoms move but only the displayed atoms are updated on the screen.

%---
\subsection {Move\_fragment}  \index{Move\_fragment}
\syntax {Move\_fragment [id an atom] or [mol res1 res2 object]}
Moves an atomic fragment. The fragment containing the identified atom
moves, with this atom as the pivot point. The breakdown of each residue
into fragments is defined in a dictionary, and can be customized by the
user. Currently, the dictionary is the same as that used by the {\bf RSR}
menus. In the distribution files, the peptide plane fragment is defined as
CA C O N+ (i.e. the nitrogen of the next residue). Do not
therefore, identify a peptide nitrogen to define the fragment. You should
use {\bf Yes} or {\bf No} to terminate the command. The {\bf Clear\_flag}
\index{Clear\_flag}
command accepts the coordinates, producing the same result as {\bf
Yes}. The coordinates are updated as the fragment moves.

%---
\subsection {Flip\_peptide}  \index{Flip\_peptide}
\syntax {Flip\_peptide [id an atom] or [mol res atom]}
This is an easy but dirty way to flip peptides, since the peptide group
simply is rotated 180 degrees around the CA -- CA direction. After the flip,
the geometry of the peptide group of the current and adjacent residues are
slightly distorted. The operation should therefore be followed by a
regularization or a database fragment fit. This is an immediate action
command, there is no need to accept/reject the new coordinates. If you
regret the flip, simply activate the command once more.

You must identify any atom in the residue whose carbonyl oxygen gets
flipped. A number of people have identified the nitrogen atom N of the
next residue, thinking that will define the peptide. They are surprised
to see the `next' oxygen flip!

%---
\subsection {Move\_object} \index{Move\_object}
\syntax {Move\_object [object]}
Moves any object that is presently being displayed. {\em This cannot be
used to change the coordinates of any molecule} (it does not update any
coordinates). You can make a graphical entity using the Object
Description Language (ODL, see Chapter \ref{ch-ODL}), for example, and
then place it anywhere you like. The applied transformation can be saved
in the database, and the object remains transformed on acceptance. You
must use {\bf Yes } or {\bf No} to terminate the command.The {\bf
Clear\_flag} command accepts the operation, producing the same result as
{\bf Yes}. \index{Clear\_flag}

%---
\subsection {Tor\_residue}  \index{Tor\_residue}
\syntax {Tor\_residue [id an atom] or [mol res atom]}
This allows one to make dihedral rotations around bonds between pairs of
atoms. All of the torsional angles associated with the identified residue
can be changed via the dials. The number of dials activated depends on how
many angles are defined for the particular residue.  Therefore, {\bf
Dial\_previous} or {\bf Dial\_next} may have to be used.  Use {\bf Yes/No}
to accept or reject the result.
\index{Dial\_previous} \index{Dial\_next}

The program needs to know what angles are associated with the residue and
how they are defined. This torsional information is kept in the data
base as an entry  {\tt .torsion\_information}. The distributed version of this
information can be loaded from  {\tt \$ODAT/torsion.o} and is also in
{\tt \$ODAT/startup.o}. It is very easy to add new residues to this entry. For
example, a serine residue is encoded as
\index{.torsion\_information} \index{torsion.o}

\begin{verbatim}
RESIDUE SER
TORSION PHI -57. C- N CA C C O N+ CB OG
TORSION PSI -47. N CA C N+ N+ O CB OG
TORSION CHI1 -60. N CA CB OG OG
\end{verbatim}

In this residue there are 3 torsion angles (PHI, PSI and CHI1) with
preferred values 57., 47., 60 respectively. The first four atom names
describe how each angle is defined, the remaining names specify which
atoms are affected by the angle. The CHI1 angle is, therefore, defined
by looking along the CA-CB bond and measuring the angle subtended by the
lines N-CA and CB-OG. Only the OG atom moves when this angle is
changed.

Note that atoms from last and next residues have `-' and `+' signs in
their names. In the distributed database, we have chosen to move the N
of the next residue as PHI and PSI change. If the list of atoms is too
long, you can go into the next line by typing a back-slash character. %%??? \\.
Begin the next line with at least 6 spaces for tidiness's sake.
 
If you do not follow the standard atomic naming convention, or if you
have extra atoms (e.g. hydrogens) in your residues, you must make a new
version of {\tt .torsion\_information}.
\index{.torsion\_information}

The program reports atoms that are defined in the torsion database but
not present in the residue. If an atom is in the residue but not defined
as a moving atom, it will never move.

We would love to receive entries for new types of residues, and will
place them on the ftp server for the benefit of other \mbox{\bf O} users.

%---
\subsection{Tor\_general} \index{Tor\_general}
\syntax{Tor\_general [Id 2 connected atoms]}
This command allows one to change torsion angles by identifying two atoms
defining the angle to be changed. The identified atoms must be connected and
there cannot be a ring between them. One angle requires four connected atoms,
two angles needs five, etc. A maximum of eight angles can change.


%---
\subsection {Examples} 
In the default setup (the standard {\tt startup.o} file), the moving atom
is defined as a small cross:

\begin{verbatim}
.moving_atom             t         8 80
begin moving_atom
M 0.2 0 0
L -0.2 0 0
M 0 0.2 0
L 0 -0.2 0
M 0 0 0.2
L 0 0 -0.2
end_object
\end{verbatim}

The utility program {\tt O\_moving\_atom} \index{O\_moving\_atom} can
create \mbox{\bf O} ODL descriptors for the moving atom in the shape of a
dodecahedron or an icosahedron, which are easier to see if you have a
lot of objects on the screen. The resulting file must be read into the
database using the command {\bf Read\_formatted}. \index{Read\_formatted}

%---
\subsection {Datablocks used by the Manip menus} 

\begin{itemize}
\item {\tt .manip\_integer} \index{.manip\_integer}
   \begin{description}
   \item [1 Color of the moving atom (mnpcol)]
   \end{description}
\item {\tt .torsion\_information} containing the torsion database.
   \index{.torsion\_information}
\item {\tt .rsr\_dict\_XXX} Fragment dictionary,with one database entry
   \index{.rsr\_dict\_XXX}
for each amino acid.
\end{itemize}

%%% trig %%%

\section {The Trig commands} 

This menu allows for the display of trigonometric data on molecules. At
present it gives distances, close contacts and angles between atoms. It
generates display instructions in object distances. Text and dashed
lines are drawn in the Id colour defined in the datablock
{\tt .molec\_obj\_integer} item 8 (see section \ref{sec-draw-db}).
\index{.molec\_obj\_integer}

%---
\subsection {Dist\_define} \index{Dist\_define}
\syntax {Dist\_define [id 2 atoms]}
Identify 2 atoms. A line is drawn between them with the distance. Up to
20 distances can be drawn. The atoms can be identified in a macro by
using the {\bf Term\_id} command. \index{Term\_id}

%---
\subsection {Trig\_reset} \index{Trig\_reset}
\syntax {Trig\_reset}
Reset and delete the object containing trigonometric information.

%---
\subsection {Trig\_refresh} \index{Trig\_refresh}
\syntax {Trig\_refresh}
Continuously refresh the trig object. If a marked atom is moving, the
trigonometric information is updated. The command can be switched off
with {\bf Clear\_flag} or {\bf Trig\_reset} commands.
\index{Clear\_flag}

%---
\subsection {Neighbour\_atom}  \index{Neighbour\_atom}
\syntax {Neighbour\_atom [id an atom] or [mol res atom]}
Show neighboring atoms to identified atom. The calculation is repeated so
that the contacts of moving atoms get flagged. The distance cut-off is
kept in the database in {\tt .trig\_real}. Contacts within the same
residue are not calculated. \index{.trig\_real}

%---
\subsection {Neighbour\_residue}  \index{Neighbour\_residue}
\syntax {Neighbour\_residue [id an atom] or [mol res atom]}
Show neighboring atoms to all atoms in the residue of the identified
atom. The calculation is repeated so that the contacts of moving atoms
get flagged. The distance cut-off is kept in the database in {\tt 
.trig\_real}. Contacts within the same residue are not calculated.
\index{.trig\_real}

%---
\subsection {Hbonds\_mc} \index{Hbonds\_mc} \index{hydrogen bonds}
\syntax {Hbonds\_mc [id two atoms] or [mol res1 res2]}
The hydrogen bonds between main chain atoms within the desired zone are
drawn as dotted lines. The bond is made according to a simple energy
term defined by Kabsch \& Sander \cite{kabsch83}. The
cutoff values are 3.5\AA\ in length and 0.5 Kcal/mol in energy. The minimum
separation is 3 residues.  For making solid H-bonds, see section \ref{sec-trig-db}.

%---
\subsection {Hbonds\_all}  \index{Hbonds\_all} \index{hydrogen bonds}
\syntax{Hbonds\_all [id two atoms] or [mol res1 res2]}
The hydrogen bonds between all atoms within the desired zone are drawn as
dotted lines. The bond is made according to a trigonometric calculation.
The donor-acceptor atoms must be closer than 3.25\AA\ and an angular
cut-off of 90 degress. This option requires that the user database contains
a definition of what atoms can act as H-bond acceptors or donors. If not
included in the {\tt \$ODAT/startup.o} file, it can be included by reading in
{\tt \$ODAT/residue\_dict.o}. For making solid H-bonds, see section \ref{sec-trig-db}.
\index{residue\_dict.o}

%---
\subsection {Phi\_Psi}  \index{Phi\_Psi}
\syntax {Phi\_psi [id an atom] or [mol res atom]}
The phi and psi values for the residue containing each identified atom
are displayed in the message window. The command is only applicable to
protein molecules. The command stays active so that information about
other residues can be obtained by identifying an atom in the residue. It
can be reset with {\bf Clear\_flags}.
\index{Clear\_flags}

%---
\subsection {Angle\_define}  \index{Angle\_define}
\syntax {Angle\_define [id three atoms]}
The angle between 3 identified atoms is calculated and displayed. The
atoms can be identified from a macro with the {\bf Term\_id} 
command.
\index{Term\_id}

%---
\subsection {Example} 
Activate {\bf Dist\_define} and pick two atoms. A line is drawn between
\index{Dist\_define}
them, with the distance between the two atoms indicated halfway along
the line segment. Now activate {\bf Move\_atom}  and choose one of the
\index{Move\_atom}
atoms. Choose {\bf Trig\_refresh}, and you will see the distance vector
\index{Trig\_refresh}
get updated as the atom is moved with the dials.

%---
\subsection {Datablock used} \label{sec-trig-db}
The distance used as the cutoff for the neighbour calculation is kept in
{\tt .trig\_real}  as a floating point number.
\index{.trig\_real}
H-bonds will be drawn as a series of small solid spheres provided a
datablock {\tt .solid\_hbonds} is present. The following would draw 7 spheres,
each of 0.2\AA\ radius:
\index{.solid\_hbonds}

\begin{verbatim}
.solid_hbonds t 1 12
.2 7
\end{verbatim}

%%% lsq %%%

\section {The LSQ commands} \index{overlaying structures}

This major menu is designed for looking at similar 3-D structures. It can
determine the transformation operator between 2 structures either by
explicitly defining pairs of atoms for a least squares calculation, or
given a transformation, it can produce an improvement both in the matrix
and in the set of matched atom pairs. Afterwards the transformation can
be applied to an object or to the coordinates of a molecule in the
database.

%---
\subsection{Lsq\_explicit}  \index{Lsq\_explicit}
\syntax {Lsq\_explicit  [mol A] [mol B]
              [[res1 res2 (atom)](A) [res1 (atom)](B)]i [(atom)] [result]}
Least squares comparison of 2 structures via explicit atoms. The user
must specify two molecules, for example, A and B. The transformation is
then applied to B to bring it onto A. No wild cards are allowed when
defining the atoms. If no atom name is specified for molecule A, then Ca
is implied. If no atom name is specified for molecule B, then the atom
name specified for molecule A is chosen. The number of atoms chosen must
be identical in the two groups. The result of the comparison can be
stored in the database. The user supplied name is appended to various
names defined by the program, creating 4 datablocks for each comparison.

%---
\subsection{Lsq\_improve}  \index{Lsq\_improve}
\syntax {Lsq\_improve [old\_result]
              [mol res1 res2](A)
              [mol res1 res2](B)
              [atom] [result]}
This command can improve on a given transformation. The command employs
an algorithm involving a search for structure fragments that can be
aligned within a given cutoff limit, and tries to improve the
transformation and the matched atoms. The user must specify which
transformation currently stored in the database is to be used as the
start value that is to be improved. The user then specifies which part of
molecule A is being matched with B. The improved transformation operator
can be stored in the database (with the same name as the start matrix or
as a new entry). The algorithm cycles until either the same set of atoms
are selected or until 10 cycles are made. The algorithm used (developed
by TAJ) has not been published yet. Roughly speaking, it works by
locating the longest matching fragments between the two molecules where
each pair of atoms in a fragment fits better than a set value.

%---
\subsection{Lsq\_object}  \index{Lsq\_object}
\syntax {Lsq\_object [object] [transformation\_name]}
Apply a transformation to an existing molecular {\em object}. No changes
are made to the coordinates of the atoms making up the object. Notice
that if you try to move an atom occurring in a transformed object, the
moving atom cross comes up at the actual coordinates of the atom. Typing
just [CR] instead of the transformation, removes an operator that is
being applied to the object. If a transformation is defined, a vector
{\tt .lsq\_rt\_[transformation\_name]} must exist in the database.
\index{.lsq\_rt\_}

%---
\subsection{Lsq\_molecule} \index{Lsq\_molecule}
\syntax {Lsq\_molecule [transformation\_name] [mol]}
Apply a transformation to a {\em molecule} or to part of a molecule. {\em
This option will change the coordinates of the atoms in the database}.
If you are frequently working with 2 or more molecules it might often be
better to apply a transformation to the whole molecule, but remember to
have a reverse transformation in the database to restore the coordinates
to the correct place. Entering a [CR] at either prompt, terminates
the option. If a transformation is defined, a vector
{\tt .lsq\_rt\_[transformation\_name]} must exist in the database.
\index{.lsq\_rt\_}

%---
\subsection{Lsq\_paired\_atoms} \index{Lsq\_paired\_atoms}
\syntax {Lsq\_paired\_atoms [transformation] [on/off]}
Display or remove vectors between a set of atoms that were used in a
LSQ'ed operation. The {\bf Lsq\_explicit } / {\bf Lsq\_improve}  commands
\index{Lsq\_improve}
create a data structure of the paired atoms used in the alignment. The
command draws a vector from the one set in molecule A and the
transformed set in molecule B.

%---
\subsection{Examples } 

See the examples in Chapter \ref{ch-tutorial}.

%---
\subsection{Macros}

{\bf @change\_lsq\_cutoff}: Enter the cutoff distance used in the {\bf
Lsq\_improve}  algorithm. This {\em must} be an integer, and 10 times the real
value. The default is 38, i.e. 3.8\AA.
 \index{Lsq\_improve} \index{cutoff, in lsq}

%---
\subsection{Datablocks for the LSQ menu} 

\begin{itemize}
\item {\tt .lsq\_integer}  \index{.lsq\_integer}
   \begin{description}
   \item [1 Defines a distance cutoff limit for {\bf Lsq\_improve},
    			default of 38 corresponds to 3.8\AA.]
   \item [2 Defines smallest fragment size for {\bf Lsq\_improve},
		 		default 3.]
   \item [3 Defines the colour code of the vector between paired
	 			atoms, default red.]
   \end{description}
\end{itemize}
	 

Each transformation saved by the program creates 4 data blocks. If the
user saved a transformation under the name {\tt rbp\_to\_p2},
then the following would be created:

{\tt .lsq\_rt\_rbp\_to\_p2} : the transformation matrix, stored columnwise,
as the following 12 real numbers:

\begin{verbatim}
x  =  R(1)x + R(4)y + R(7)z + R(10)
y  =  R(2)x + R(5)y + R(8)z + R(11)
z  =  R(3}x + R(6)y + R(9)z + R(12) 
\end{verbatim}

This data block can be used to specify operators that are applied to 3-D
objects such as maps (command {\bf Rot\_tran\_obj}), objects (command
{\bf Lsq\_obj}) or molecular coordinates (command {\bf Lsq\_mol}).
\index{Rot\_tran\_obj} \index{Lsq\_mol} \index{Lsq\_obj}

\begin{itemize}
   \item {\tt .lsq\_mm\_rbp\_to\_p2}: Holds the names of the two molecules
          being compared.
   \item {\tt .lsq\_mn\_rbp\_to\_p2}: Holds the paired set of atoms from
          each molecule.
   \item {\tt .lsq\_vp\_rbp\_to\_p2}: A description of the vectors between
          paired atoms in the \mbox{\bf O} graphics object descriptor language.
          This is a large entry and should be deleted if not needed.
\end{itemize} 

%%% map %%%

\section {The Map commands} \index{electron density map}
 
This major menu allows you to control the parameters affecting the display
of density maps. Data extracted from the maps are defined as objects. Each
object requires the user to define a number of parameters.  Thus it is
possible to have different maps, colour, contour level etc.  displayed at
the same time. Any number of objects can be made from a particular map file
but a particular object comes from just one file, one level, one volume,
one colour.

The program caches the map to speed up access. This is associated with
the file name so the user must issue a {\bf Map\_cache} command before
\index{Map\_cache}
introducing a different map with the same file name during the same
session.

Map objects are deleted with the {\bf Delete\_object} command 
(see section \ref{del-obj}).
\index{Delete\_object}

%---
\subsection {Map\_File} \index{Map\_File}
\syntax {map\_file [file\_name]} Name the map file. This is a special
bricked electron density file made up of (8 x 8 x 8) byte cubes
of density. It is made from standard maps, (CCP4, X-PLOR, PROTEIN, etc.),
with a program called mappage (see section \ref{sec-mappage}). This file
structure is the same one used in most versions of FRODO (but not in
Phillip Evans' version).  \index{CCP4} \index{PROTEIN} \index{X-PLOR}
\index{mappage} Another bricked map format is supported in \mbox{\bf O} versions
5.9.2 or newer. It can be moved from any computer to any other, and the
header contains more information, most importantly, the sigma level of the
map. The new map is calculated by the {\tt brix} program (see section
\ref{sec-brix}). \mbox{\bf O} will automatically figure out how the density file is
formatted. \index{brix}

%---
\subsection {Map\_object}  \index{Map\_object}
\syntax {Map\_object [object]}
Name for the map object. This object cannot be picked (identified) and
only the first 6 characters are used.

%---
\subsection {Map\_param}  \index{Map\_param}
\syntax {Map\_param [box\_x box\_y box\_z]
          [level]
          [colour]
          [front\_intensity back\_intensity]
          [line\_type] }
Define the map parameters. These are the box sides in \AA's, the level, the
colour, the front and back intensity and the line type. The following
line types are supported:

\begin{enumerate}
\item solid line
\item dashed line
\item dotted line
\item dot dash line
\item semi-transparent solid surface.
\end{enumerate}

%---
\subsection {Map\_Atom\_Centre}  \index{Map\_Atom\_Centre}
\syntax {Map\_atom\_centre [[mol] residue [atom]]}
Define the map centre for extracting contours by molecule, residue, and
atom. The molecule and atom names are defaulted to current molecule and
CA.

%---
\subsection {Map\_Active\_Centre} \index{Active\_Centre}
\syntax {Map\_active\_centre}
Define map centre by selecting the value stored in the datablock
{\tt .active\_centre}. \index{.active\_centre}

%---
\subsection {Map\_Xyz\_Centre}  \index{Xyz\_Centre}
\syntax {Map\_xyz\_centre [x y z]}
Define map centre by coordinates. The coordinate system used is
orthogonal with the a axis parallel to $x$ as in the PDB standard. This
differs from the system used by Rossmann \& Blow in their Rotation
Function paper for monoclinic space groups. It is identical to the
coordinate system used in FRODO \cite{jones78}. \index{coordinate system}

%---
\subsection {Map\_info}  \index{Map\_info}
\syntax {Map\_info}
Gives information about the currently used map file. The mean and 
standard deviations of the map are stored in the map file calculated by
the brix program. \index{brix}

%---
\subsection {Map\_draw} \index{Map\_draw}
\syntax {Map\_draw}
Draw a map object using currently defined parameters, file, and centre.

%---
\subsection {Map\_Cache} \index{Map\_Cache}
\syntax {Map\_cache}
Resets all cache data structures. To speed up map access, each record
that is read from a map file is cached into memory so that it can more
quickly be accessed in a subsequent read operation. If a user works with
a map {\tt q25\_f21.map} say, and then finds it was a F(o)-F(c) map
by mistake, he might be tempted to use the same file name after
correcting the mistake. In such a case it would be necessary to clear
the map cache before using the new map.

%---
\subsection {Map\_cover} \index{Map\_cover}
\syntax {Map\_cover [object\_name] or [Id atom] [radius]}
This command allows you to display density around an object. When
chosen, the command changes the current values for the map box and
centre. It forms a mask around each atom in the object using the input
radius. This mask is applied the next time {\bf Map\_draw} is chosen, and
then cleared. Therefore, the second time you choose {\bf Map\_draw}, you
will get the whole map box contoured. \index{Map\_draw}

%---
\subsection {Examples}
In the following example, we draw a map around residue b50. The map will
go into an object called {\tt map\_a}:

\begin{verbatim}
map_file m10_a.dsn6
map_par 12. 12. 12. 0.18 sky_blue 0.5 0.1 1
map_obj map_a 2.0
map_atom b50
map_draw 
\end{verbatim}

{\bf Map\_cover} is useful when making photographs or plots, and you want
to get rid of irrelevant density, but it is also useful just to draw the
density around an object. In this case you should chose a large radius,
so you dont accidentally mask out density that you {\em want} to see. In
this macro, we define a sphere of atoms, and cover them with a map:

\begin{verbatim}
centre_id wait_id
object sph  sphere 8. end
map_cover sph 5.
map_obj map_a map_draw
\end{verbatim}

%---
\subsection {Datablocks for the Map menus}
The datablocks for the map menus listed below can all be changed using
{\bf Map}  commands, so they are only listed here for completeness

\begin {itemize}
   \item {\tt .map\_integer} \index{.map\_integer}
      \begin {description}
         \item [1 map colour code (mpcolr)]
	  \end{description}
   \item {\tt .map\_real} \index{.map\_real}
	  \begin {description}
	     \item [1 contouring level (mplevl)]
	     \item [2 - 4 size of contour box along cell edges (mpbox)]
	     \item [5 - 7 centre of density (mpxyz)]
	     \item [8 - 9 intensity of the map, fore \& aft (mpini).]
	     \item [10 map cover radius]
	  \end{description}
   \item {\tt .map\_c6} \index{.map\_c6}
	\begin {description}	
	    \item [1 map line type (mpltyp) - not currently used.]
	    \item [2 map type (mptyp)]
	    \item [3 - 5 map centre: molecule, residue, atom (mpacon)]
	    \item [6 map object name (mptyp).]
       \end{description}
\end{itemize}

%%% qm %%%

\section{The Quick Map commands}

The Quick Map commands present an alternative to the {\bf Map}
commands. Quick maps are read directly from the map file and are handled in
core. The map formats currently recognized are CCP4, X-PLOR, TNT, PHASES
and EZD. 
\index{CCP4 map} \index{X-PLOR} \index{TNT} \index{PHASES} \index{EZD}
The crystallographic symmetry operators are used to expand the map
on the fly, so it is only necessary to calculate the electron density in an
asymmetric unit.  The program associates a short name with each map, by
default {\tt Q1}, {\tt Q2}, etc. All operations on the map must be
referenced with this short name. There is currently a limit of 5 maps.

The Quick Maps are quicker than the old style maps because the contoured
density is stored in the computer. If you go back to an area that you have
already contoured, the program will not repeat the calculations, only
redisplay the contours that were already calculated. However, contours are
not stored indefinately; if \mbox{\bf O} runs out of graphics memory, it employs a
caching algorithm, deleting the oldest bits of density first.

The advantage of the Quick Map system is most apparent if you are working
with fitting, only displaying small boxes of density at any time. If you need to
display large cubes of density, you should use the {\bf Map} or {\bf EZD}
options. 

%--
\subsection {Qm\_setup} \index{Qm\_setup} 
\syntax {Qm\_setup [qmap name] [radius] [\# levels] 
	[[level] [colour]](i)}
For the given map, setup the number of contour levels, and the colour of
each contour. A maximum of three levels can be handled. The map must be in
core before this command can be used.

%--
\subsection {Qm\_file} \index{Qm\_file} 
\syntax {Qm\_file [file name] [qmap name] [spacegroup] }
Define and read the map from the given file name. \mbox{\bf O} will try to
determine what type of map file is being read automatically. The map formats
recognized are CCP4, PHASES, X-PLOR, TNT and EZD. If the program cannot
determine the map format, it will prompt you. CCP4 maps calculated on a
computer with a different byte endian can be read, but are not recognized 
automatically. Map files written by TNT do not store the cell parameters, or the
sectioning mode of the map. The program will prompt you for the missing
information.

Finally, the program will ask you to define the name of the spacegroup. It
will attempt to open a file in the {\tt \$ODAT/symm} directory
corresponding to that spacegroup. If it fails, you will be asked to define
the name of a file contaning the spacegroup symmetry operators. If that
fails, it will use spacegroup P1.

Binary map files are read very much faster than formatted ones, CCP4 maps
are the fastest.

%--
\subsection {Qm\_draw}\index{Qm\_draw} 
\syntax {Qm\_draw [qmap name] }
Draw contours as specified by {\bf Qm\_setup}, centered at the current
active centre. All levels are drawn. The current Quick map is
default, so you may place the command on the menu:

\begin{verbatim}
menu "qm_draw ;"
\end{verbatim}

%--
\subsection {Qm\_zap} \index{Qm\_zap} 
\syntax {Qm\_zap [qmap name]} 
Remove the given map from the computers memory, free this memory, and
remove all contours generated from this map.

%%% bones %%%

\section {The Bones commands} \index{skeleton} \index{bones}
This group of commands allows the user to display and manipulate the
skeletonized electron density (Bones atoms). The \mbox{\bf O}  skeleton is like
a regular molecule but with some extra data blocks. Each skeleton
therefore has an associated molecule name. One special datablock is a
set of status codes or levels that can be changed by the user with the
{\bf Bone\_redefine}  command. Another datablock defines the connectivity
\index{Bone\_redefine}
of the skeleton.  The skeleton can be edited by making and breaking
bonds between skeleton atoms. 

The skeleton is produced from an electron density map by running the
program {\tt bones}. Atoms recieve a level code of 2 or 3 if they are
thought to be side chain or main atoms, respectively. The user is free
to use any system of code definition that may be applicable to the
problem. Normally, a simple system would assign level 1 to be the correct
main chain trace.

The colour associated with each level is defined in the datablock
{\tt .bones\_colour} and can be any of the possible X-windows colours.
\index{.bones\_colour}
The skeleton can also be used to form an envelope by associating radii to
skeleton atoms of particular types. Skeletons can also be used with the
{\bf Trace} commands in \mbox{\bf O}.

On UNIX workstations, the skeleton is calculated by the {\tt bones}
program (see section \ref{sec-bones}) \index{bones} which reads an
electron density map, and outputs an \mbox{\bf O} datastructure, that can be
read with {\bf Read\_formatted}. The program assigns levels 3, 2 and 1
to the skeleton, depending whether it thinks the density belongs to main
chain, side chain or junk, respectively.

For users using the earlier implementation of skeletons on a VAX, an \mbox{\bf O}
skeleton can be made from a FRODO skeleton by running a utility program
{\tt oexe:o\_bones} on the VAX. FRODO levels USM are levels 1, 2, 3
respectively. The VAX program {\tt abones} distributes with FRODO
calculates levels S and M. In \mbox{\bf O}, therefore, these will correspond to
levels 2 and 3.

%---
\subsection {Bone\_setup} \index{Bone\_setup}
\syntax {Bone\_setup [mol] [object] [radius] [level]}
Setup necessary parameters. These define the skeleton molecule, the
object name being created, the radius within which to display atoms, and
what levels to use.

%---
\subsection {Bone\_draw} \index{Bone\_draw}
\syntax {Bone\_draw}
Extract and draw the skeleton atoms on the screen using current parameters.

%---
\subsection {Bone\_redefine} \index{Bone\_redefine}
\syntax {Bone\_redefine [id 2 atoms] [new level]}
Redefine the bone level of a set of connected Bones atoms. Must not be in
a circular connection. The objects are redrawn with the new colours.
NOTE: you can put any text up on the screen menu, so if you are doing
skeleton editing, you might want to put the characters 1, 2, and 3 as separate
menu items.

%---
\subsection {Bone\_Ca\_Id}  \index{Bone\_Ca\_Id}
\syntax {Bone\_Ca\_id [mol] [start\_residue] [direction]
	[id(i)]}
When activated you must specify where you wish to start in the sequence
and if you wish to go forward or backward through the sequence. You can
then pick a Bone atom and its coordinates get associated with the CA
atom of the current residue shown in the prompt window. The identified
atom is usually a skeleton atom but can in fact be any kind of atom.
After the atom has been identified, an object called {\tt CA} will be
updated, if it exists. At the start of building a new structure, there
will be no sensible coordinates for any of the atoms in the molecule but
the user should still create an object called {\tt CA} to see what happens
when using this command. The {\tt CA} object can be created with the
following commands

\begin{verbatim}
obj ca ca ; end
\end{verbatim}

but no object will be seen on the screen until you start picking atoms.
The {\bf Baton\_build}  command is an alternative (and often preferred) way of
building a CA trace.

%---
\subsection {Bone\_repeat} \index{Bone\_repeat}
\syntax {Bone\_repeat}
Backtrack one position in the sequence for {\bf Bone\_Ca\_id}. Depending
on the choice of direction, you may be going forwards or backwards. This command
is typically used to correct for mistakes if a wrong choise was made for
a CA atom.

%---
\subsection {Bone\_skip} \index{Bone\_skip}
\syntax {Bone\_skip}
Move forward (or backward, depending on choice of direction) one residue
in the sequence for {\bf Bone\_Ca\_id}. Complementary to the {\bf Bone\_repeat}
command.

%---
\subsection {Bone\_break\_bond} \index{Bone\_break\_bond}
\syntax {Bone\_break\_bond [id 2 atoms]}
Break all bonds between 2 identified atoms. The 2 atoms must not form a
closed connection. The new connectivity must be saved by the user with
{\bf Save\_DB}  or {\bf Stop}. {\em Do not make a lot of changes without
hitting} {\bf Save\_DB}. Note that there is no specific 'undo' command
for this operation. The user might instead want to use the following 2
macros
\index{Save\_DB}

\begin{verbatim}
!bond_break macro
copy save_connectivity skel_connectivity
bon_break
\end{verbatim}

to break the bonds and

\begin{verbatim}
! bond_undo macro
copy skel_connectivity save_connectivity
\end{verbatim}

to undo the act if a mistake was made. In both macros, it is assumed that
the skeleton molecule is called {\tt skel}. After calling the undo macro,
merely make the affected objects again.

%---
\subsection {Bone\_make\_bond} \index{Bone\_make\_bond}
\syntax {Bone\_make\_bond [id 2 atoms]}
Add a new bond between 2 atoms. The new connectivity must be saved by the
user with {\bf Save\_DB}  or {\bf Stop}.
\index{Save\_DB}

%---
\subsection {Bone\_mask}  \index{Bone\_mask}
\syntax {Bone\_mask [molecule]  [codes] [radii]}
This command is used to make a datablock called {\tt [mol]\_mask} that
contains coordinate and radii information for use in making a molecular
mask. The option requests a set of skeleton codes and the associated
radii. Only the specified coded skeleton atoms are used in making the mask
datablock. Use the {\bf Bone\_redefine} command to set the desired
\index{Bone\_redefine}
codes. Computer programs are available to read the mask datablock and
generate masks suitable for the {\bf A} programs \cite{jones92} or the
newer {\bf RAVE} programs \cite{kleiywegt93}.
\index{RAVE}

%---
\subsection {Bone\_Ca\_zone} \index{Bone\_Ca\_zone}
\syntax {Bone\_Ca\_zone [Id 2 atoms] [molecule] [start residue]
[direction]}
This command is intended to help in the construction of CA traces. It
would normally be used after using the {\bf Bone\_prune} command to create
something that looks like a trace. All atoms between the identified atoms are
taken to be CA atoms of the molecule being constructed. The identified atoms
cannot be joined in a circular connection. It is only necessary to specify the
start residue of the molecule under construction. The direction can be forwards
or backwards in the chain. If an object {\tt CA} has been constructed, it
will be redrawn.

%---
\subsection {Examples} 
See the examples in Chapter \ref{ch-tutorial}

%---
\subsection {Macros} 
Two macros are distributed. One, {\bf @bones\_50A} selects current
main chain level Bone atoms (values 1 and 3) within 50\AA. The other,
{\bf @bones\_20A}, draws main chain and side chain levels within
20\AA. This is the latter:
\index{macro bones\_50a}

\begin{verbatim}
Bone_setup ano1 20a 20. 1 2 3 ;
centre_id wait_id
bone_draw
\end{verbatim}

The skeleton is called {\tt ano1}, the created object is called {\tt 20a}.  


%%% lego %%%  

\section {The Lego commands} \index{protein building blocks}
				\index{rotamer database}
				\index{main chain database}

Use a protein database to model a structure. This menu can access both the
main chain database \cite{jones86} and side chain rotamers
\cite{ponder87}. The data base files are loaded from the public area when
used in the session.  They go into the user's \mbox{\bf O} database but are not
written back when the database is saved because they have a status of R
(readonly).

The main chain database consists of 32 protein structures that have been
refined at high resolution. The side chain database consists of the
rotamers that occur with a frequency $>$10\% in the Ponder \& Richards
study \cite{ponder87}.

%---
\subsection {Lego\_setup} \index{Lego\_setup}
\syntax {Lego\_setup [Ca trace Y/N]
           [colour ramp]
           [main chain database]
           [database directory]
           [rotamer database]}
Define necessary parameters for the menu. This allows the user to select
an option to show or not show CA traces, the colour codes to be used to
display them, a file with the definition of the precalculated CA
diagonal distance matrix, the directory where this database is kept and
the file with the side chain rotamer database. Most of the values will
be correct by default, but it is necessary to define these parameters
the first time the {\bf Lego} commands are used with a given database file.


%---
\subsection {Lego\_Ca} \index{Lego\_Ca}
\syntax {Lego\_Ca [id two atoms] or [mol res1 res2]}
Look through the fragment database to find similar pieces of structure. A
dial becomes activated to pass through the top 20 best fits. The rms
fit, protein and sequences are shown on the prompt window. The user is
also able to specify any particular protein in the data base. Use {\bf
Yes}/{\bf No} to pick the best matching main chain fit to one's own
CA atoms. Only the main chain atoms are extracted from the database. The
coordinates of the first and last residues in the user's zone are not
affected.

%---
\subsection {Lego\_bones}  \index{Lego\_bones}
\syntax {Lego\_bones [id(i)]}
This command is meant for use with skeleton Bones atoms but is not
enforced by the program. Identify atoms to be taken as guide CA's. End
by specifying {\bf Yes}. Use {\bf Yes}/{\bf No} to pick best fit to
Id'ed (CA equivalent) atoms. We do not recommend using this option
anymore, rather we recommend using the {\bf Bones} commands to make a
CA trace which can then be built automatically.

%---
\subsection {Lego\_Auto\_MC} \index{Lego\_Auto\_MC}
\index{main chain, building}
\syntax {Lego\_auto\_mc [id two atoms] or [mol res1 res2]}
Automatically build the main chain for a zone of atoms, using the
database. This option goes along the chain searching for the best fitting
pentapeptide, keeping the main chain atoms of the middle 3 residues and
overlapping with the next pentapeptide. This means that the first and last
residues are not changed. The option requires coordinates for the CA atom
of each residue.

%---
\subsection {Lego\_Side\_Chain} \index{Lego\_Side\_Chain}
\syntax {Lego\_side\_chain [id an atom]  or [mol res atom]}
Pick a side chain rotamer for a specified residue from the library of
preferred side chain conformations. A residue is specified by
identifying any atom in the residue. A dial becomes activated to change
the rotamer. On the PS300, the screen A-D must be used. This command
requires the coordinates for `N', `CA', `C' atoms for each residue. Use
{\bf Yes}  to choose the rotamer you want, {\bf No}  to end without
changing the coordinates.

%---
\subsection {Lego\_Auto\_SC} \index{Lego\_Auto\_SC} 
\index{side chains, building}
\syntax {Lego\_auto\_sc [id two atoms] or [mol res1 res2]}
Move along the chain and automatically build side chain by choosing the
most frequent rotamer from the database. This requires the coordinates
for `N', `CA', `C' atoms for each residue. Useful for putting on
starting side chains that may then be checked individually or with RSR
commands. Because Ala and Gly residues have no rotamers, they will cause
a warning that can be ignored.

%---
\subsection {Lego\_Loop} \index{Lego\_Loop}
\syntax {Lego\_loop [id two atoms] or [mol res1 res2]}
Make a CA data base search for a zone but only use atoms that have been
selected with {\bf Select\_on} or {\bf Select\_off}. \index{Select\_on}
After accepting coordinates, the selection datablock is not changed so
sometime remember to use {\bf Select\_on}  again. Otherwise, when you
eventually write out the coordinates you might not get what you
expected.

Example: insert an extra residue into a molecule called {\tt a28} after
residue {\tt 100}. Use the databases to construct main and side chain
coordinates

\begin{verbatim}
mutate_insert a28 100 100a leu ;
sel_on a28 ;
sel_off a28 100 101
lego_loop a28 98 103
yes 
sel_on a28 ;
leg_side a28 100
yes
\end{verbatim}

The loop chosen is the best fit to the CA coordinates of residues {\tt
98}, {\tt 99}, {\tt 102},  and {\tt 103}. The new leucine residue has
the most common rotamer conformation. 

%%% rsr %%%

\section {The RSR commands} \index{real space refinement} \index{RSR}
The RSR (real space refinement) menu is a useful tool when fitting
molecular models into electron density. The algorithms used have been
described by Jones \& Liljas \cite{jones84}. All the refinement options in the
{\bf RSR} menu operate in a similar fashion. A volume is chosen around all
the selected atoms, including a wall of thickness 3.5 {\AA}ngstr{\o}ms,
say, on all sides. Only density within this box is considered. The program
will then build up a model density of all atoms inside the box.  This model
density is then scaled to the observed density. The model density is now
subtracted from the observed density, and the difference map is
stored. This is to prevent atomic groups from entering into density
belonging to neighboring atoms. When a group is being refined, the model
density for that group is added back into the observed density. The user is
able to influence the scaling and subtraction at will.

The optimization algorithm moves the fragment a certain step along a
direction that improves the goodness of fit. When the fit gets worse, it
attempts to locate a new direction along which to move. The user
controls the step size and how many different step sizes to try.

The {\bf RSR\_zone} command should only be used when you have an
excellent map.

%---
\subsection {RSR\_setup} \index{RSR\_setup}
This is a menu that  enables the user to change some parameters  and
options relating to the real space refinement. There are 2 possible
choices for the refinement method, the CONV method, which tries to
maximize the convolution product between observed and model density, and
the DIFF method, which tries to minimize the difference density.
Although the convolution product method biases the fit to place single
atoms on grid points, it is less sensitive to errors produced by scaling
the model to the observed density. It can therefore be used when the fit
to the observed density is poor. The effect of grid biasing is most
severe when fitting single atoms and is reduced by fitting residue
fragments.
\begin{description}

\item [Autoscaling] This is an option to turn on automatic scaling
of model to observed density. It is effective in most of the minor
menus in {\bf RSR}. It may sometimes be advantageous to switch off the
autoscale option and use the manual scaling in {\bf RSR\_scale}
instead.  

\item [Autosubtraction] The user is permitted to switch
off the subtraction of model density from observed. This is not
recommended, but may be used with the CONV refinement method when the
scaling of densities is inaccurate.

\item [Nscan] Set the
number of search scans in the refinement procedure.  Typical value
is 5.  

\item [Stepsize] Set the size of the Nscan steps in
{\AA}ngstr{\o}ms/degrees. 
Typical values are 1.0, 0.5, 0.25, 0.2, 0.05.  

\item [Form\_factors] Defines the values A(o) and $C$, used
to transform a B factor to an atomic radius A, using the relationship from
\cite{deisenhofer75}:
\begin{verbatim}
B = 4pi * ((C*A)^2 - A(o)^2) 
\end{verbatim}
Typical values are A(o) = 0.90; C = 1.04 for high resolution maps
(1.7--1.9\AA) and C = 0.82 for medium resolution (2.4\AA). 
See the discussion on page~\pageref{rsfit}.

\item [Irad] Specify how many grid points over which the grid sums are
formed. Should be of magnitude 3 {\AA}ngstr{\o}ms.
\end{description}

These parameters are also used by the {\bf RS\_fit} command.

%---
\subsection {RSR\_map} \index{RSR\_map}
\syntax {Rsr\_map [file name]}
This menu item defines the file name of the electron density map file. It is also
the map used by the {\bf RS\_fit} command.

%---
\subsection {RSR\_scale} \index{RSR\_scale}
\syntax {Rsr\_scale [id an atom] or [mol res atom]}
This menu item requires the user to choose a residue by picking on the
screen, or by specifying on the terminal, or in a macro. The scaling
takes place within a box around this residue.

%---
\subsection {RSR\_zone} \index{RSR\_zone}
\syntax {Rsr\_zone [id two atoms] or [mol res1 res2]}
The {\bf RSR\_zone} option is a flexible zone fitting option, allowing
rotation/translation real space refinement of residue fragments to
electron density. The user is asked to define a zone of residues by
picking two atoms on the screen, or by specifying on the terminal, or
(more likely) in a macro. A user definable fragment dictionary is
consulted to decide how the individual residues are divided into
fragments. The standard dictionary divides amino acids into a main chain
fragment, and one or more sidechain fragments.

The RSR dictionary is maintained in the \mbox{\bf O} database. There is an entry
for each residue, with the name {\tt RSR\_dict\_xxx}, where {\tt xxx} is the
\index{RSR\_dict\_} \index{rsr\_dict.o} \index{fragment dictionary}
three-letter code of the residue type. Each line in the entry corresponds
to a fragment group. The dictionary can most easily be changed by editing a
copy of the file {\tt \$ODAT/rsr\_dict.o}. Alternatively, one can write out
an entry on a local file, using

\begin{verbatim}
write rsr_dict_xxx junk.tmp ;
\end{verbatim}

where {\tt xxx} is the three-letter code of the desired amino acid. The entry
can then be edited, and read into the database using

\begin{verbatim}
read junk.tmp
\end{verbatim}

Since the name of the data block is part of the header, \mbox{\bf O} knows
where to put it.

%---
\subsection {RSR\_rigid}  \index{RSR\_rigid}
\syntax {Rsr\_rigid [id two atoms] or [mol res1 res2]}
This option allows the refinement of a zone of residues as a rigid body.
A zone is chosen by picking on the screen, or by specifying at the
terminal.

%---
\subsection {RSR\_rotamer}  \index{RSR\_rotamer}
\syntax {Rsr\_rotamer [id an atom] or [mol resatom]}
The side chain rotamer giving the best refined fit to the density is
suggested. Each rotamer is added in turn to the start main chain. The
whole residue then pivots about the CA atom to find the best fit. The
user is informed which rotamer gives the best fit.

%---
\subsection {RSR\_dgnl}  \index{RSR\_dgnl}
\syntax {Rsr\_dgnl [id an atom] or [mol res1 res2]}
This options functions like the {\bf Lego\_Ca}  option. A zone is chosen
by picking on the screen, or by specifying. The database is then
searched, and the poly-alanine chain giving the best rigid body fit to
the observed density is suggested.
\index{Lego\_Ca}

%---
%\subsection {RSR\_dihedral} \index{RSR\_dihedral}
%This option is not yet implemented.

%---
\subsection {RSR\_contours}  \index{RSR\_contours}
\syntax {Rsr\_contour [on/off]}
Toggle contouring of the density used in the refinement. This can be
useful when playing with the parameters in {\bf RSR\_setup}.

%---
%\subsection {RSR\_sidechains} 
%Not yet implemented. Zip through all possible sidechain, giving the 
%best fitting one.
%---

\subsection {The RSR dictionary} \index{RSR, dictionary}
The RSR dictionary consists of a series of text datablocks, with names
{\tt RSR\_dict\_xxx}, where {\tt xxx} is the three-letter code of the
residue type. Each line in the entry corresponds to a fragment group.
For example, the standard dictionary for isoleucine contains three
fragments:
\index{RSR\_dict\_}

\begin{verbatim}
RSR_dict_ile             T         3        70
CA   C   O   N+
CB   CG1 CG2
CD1
\end{verbatim}

The + after the nitrogen in the main chain fragment means that this
nitrogen comes from the {\em next} residue. Equivalently, a $-$ in front
of a C, say, would mean the C atom from the {\em previous} residue.
These fragment definitions can be changed at will. Be sure to change the
number of lines in the datablock header (= 3 in this example). The RSR
fragment dictionary is currently also being used for the fragment
definitions of the {\bf Move\_fragment}  command.
\index{Move\_fragment}


%%% refi %%%

\section {The Refi commands} \index{regularisation}

Model regularisation to force standard bond lengths, angles and fixed
dihedral angles. At the end of the regularisation, the user is prompted to
accept or refuse the new coordinates. In proteins, start and end main chain
atoms remain fixed. A new menu will be implemented soon.

%---
\subsection{Refi\_setup} \index{Refi\_setup}
\syntax {Refi\_setup [dictionary\_file]}
Define the dictionary of standard bond lengths and angles. This is the same
dictionary used by Hermans \& McQueen, and in FRODO. It can be found in
{\tt \$ODAT/dict.pdb} as default. When modifying a dictionary, it is
necessary to make a {\bf Refi\_setup} to force the reading of the latest
dictionary file.

%---
\subsection{Refi\_zone}  \index{Refi\_zone}
\syntax {Refi\_zone [id two atoms] or [mol res1 res2]}
Regularize a zone of residues. Residue types must be described in the
dictionary for each kind of residue in the zone. They can be picked at
the screen or typed at the console. Use {\bf Yes} or {\bf No} to accept
new or restore old coordinates.

%---
\subsection{Datablocks for the Refi Option}

\begin{itemize}
\item {\tt file\_refi\_dict} is a text datablock containing the 
dictionary file name. \index{file\_refi\_dict}
\item {\tt .refi\_dict} is a text datablock of the contents of the 
dictionary file. \index{.refi\_dict}
\item {\tt .refi\_real} is a datablock containing real variable. \index{.refi\_real}
\item {\tt .refi\_c6} is a datablock of character variables. \index{.refi\_c6}
\end{itemize}

None of these datablocks should be tampered with.


%%% sam %%%

\section {The Sam commands} \index{coordinate files}

This menu was named {\bf Sam} for old times sake\footnote{This weird name
is due to an irrational sentimentality of Alwyn: in FRODO, the SAM program was
used to read and write coordinate files}. It is associated with commands
that control the retrieval and storage of structural data in and out of
the \mbox{\bf O} database. The commands generate the datablocks from the entire
molecular data structure. They therefore differ from the {\bf
Read\_formatted} and {\bf Write\_formatted} commands, that are general
commands which can be used with any \mbox{\bf O} datablocks. The {\bf Sam}
commands are the link between the \mbox{\bf O} database and external program
systems such as the CCP4 package or PROTEIN. \index{CCP4} \index{PROTEIN}

When reading or writing coordinate files, the program attempts to identify
the kind of coordinates by checking the file type. Recognized file types
are :

\begin{description}

\item [.rd] files are Dr. Robert Diamond style files. These are usually in 
\AA's along the unit cell axes. This style is used by PROTEIN for FC
calculations, where the atom type field is used to describe formfactors.
\index{Diamond files}

\item [.wah] files are Dr. Wayne Arthur Hendrickson style files as used in
PROLSQ.  \index{PROLSQ}

\item [.pdb] files are the format used at the Protein Data Bank at
Brookhaven.  \index{PDB files}

\item [.xpl] are X-plor style PDB files where column 73 is used
as a chain ID.  \index{X-PLOR}

\item [.bud] Bill Fureys PHASES coordinate format. \index{PHASES}

\item [.xyz] are FRODO binary files, DSN2 format to some. Only works on
Vax/VMS.  

\item [.o] are binary \mbox{\bf O} database files.  

\end{description}

When reading PDB files, the program keeps the unit cell values and the
space group. When creating PDB files, the program also writes out the
extra records SCALEn, CRYST1 and ORIGx needed by some programs.  The
program generates a time of creation record {\tt [mol]\_date} when
it reads a coordinate file. See section \ref{sec-sam-db} on how the
file-type to file extension mapping is defined.

%---
\subsection{Sam\_atom\_in} \index{Sam\_atom\_in} \index{coordinate input}
\syntax {Sam\_atom\_in [mol] [file] [...]} 
Read atomic coordinates from an external file and give them an \mbox{\bf O}
associated 5 character name.  If the file name does not end with a
recognised file type, the user is prompted to describe the kind of
coordinates.

%---
\subsection {Sam\_atom\_out}  \index{Sam\_atom\_out} \index{coordinate output}
\syntax {Sam\_atom\_out [file] [mol] ... }
Write atomic coordinates in one of the standard formats. The user can write
out those atoms that have been `selected'.  For {\tt .rd} files, one usually
wants coordinates in \AA\ units along the cell axes. This requires that one
defines the cell constants as 1.0, 1.0, 1.0, alpha, beta, gamma.

%---
\subsection {Sam\_list\_sequ} \index{Sam\_list\_sequ}
\syntax {Sam\_list\_seq [mol]} 
List the sequence on the terminal.

%---
\subsection {Sam\_init\_db}   \index{Sam\_init\_db}
Create the initial datablocks required to describe a molecule. A datablock
entry describing the sequence (e.g. {\tt a\_residue\_type} for a molecule
named A) {\em must} exist in the database. If an entry describing the residue
name also exists (in this case {\tt a\_residue\_name}), it will be
used. Otherwise the first residue is called `1', the next `2' etc. The
sequence can be entered (in 3 letter code) as a formatted \mbox{\bf O}
datablock. All coordinates get the value (1500.0, 1500.0, 1500.0) so do not be
surprised if you get some strange looking bonds.

%---
\subsection {Water\_init} \index{Water\_init}
\syntax {Water\_init [mol] [number] [resname]}
Create an empty solvent molecule containing water residues. The command
prompts for the residue name of the first water residue. You can enter
i.e. X1, and the remaining water molecules will be named X2, X3 ...Xn,
where n is the number of water molecules specified. The command {\bf
Water\_add} can be used to fill the empty positions with real ones. Once
you initiate a new solvent molecule, you cannot continue adding water
positions to already existing solvent molecules, because the internal
residue counter is reset.  {\em Note: If you specify the name of an already
existing molecule, it will be overwritten.}

%---
\subsection {Water\_add} \index{Water\_add}
\syntax {Water\_add ...} 
When activated, this command places the coordinates of the {\tt
.active\_centre} into the next vacant water residue, which is displayed on
\index{.active\_centre}
the screen in an object {\tt SOLV}. The user is required to hit {\bf Yes} or {\bf
No}, to accept or reject the position. The {\tt .active\_center} can be set
by for example the {\bf Centre\_xyz} or {\bf Centre\_atom} commands.

%---
\subsection {Water\_pekpik} \index{Water\_pekpik} \index{water molecules}
\syntax {Water\_pekpik [pekmol] [zone] [solmol] 
	[first resname]}
This commands combines {\bf Water\_init } \& {\bf Water\_add}. The command
will go through the output of a PEKPIK run, and prompt you to place a water
molecule at each peak in the difference Fourier. All you have to do is
accept or reject the proposed water positions, by picking on {\bf Yes} or
{\bf No}. The command expects that you have already read in the output
list from a PEKPIK or PEAKMAX run into an ordinary \mbox{\bf O} molecule. Peak
searching programs will usually output the peaks in a standard (RD or PDB)
format, and can thus be read into the \mbox{\bf O} database using {\bf Sam\_atom\_in}.

%---
\subsection {Merge\_atoms}  \index{Merge\_atoms}
\syntax {Merge\_atoms [from\_molecule, zone\_start zone\_end]  
            [to\_molecule start] 
            [transformation matrix]}
This command allows one to merge a zone of atomic coordinates in one
molecule, into another molecule,with an optional transformation
applied. The transformation is a database vector of 12 numbers. They can be
the same molecules, and the {\em from} zone can overlap with the {\em to}
zone. The command can be used to : 

\begin{itemize}
\item Correct out of register errors, e.g. 

\begin{verbatim}
merge_atoms a27 a100 a110 a27 a101 ;
\end{verbatim}

Each residue would need updating with {\bf Lego\_side\_chain } or {\bf
Lego\_auto\_sc}.

\item If one has a number of molecules in the asymmetric unit, to paste the
coordinates of one into the other e.g. 
\begin{verbatim}
merge_atoms a27 a100 a110 b27 
\end{verbatim}

{\tt .lsq\_rt\_a\_to\_b} where we assume a transformation {\tt
.lsq\_rt\_a\_to\_b} relating molecules A27 and B27.

\item Generate a complete molecule from CA coordinates. If the complete molecule
is called M1 (made with {\bf Sam\_init\_db} ), and the CA's are stored as
M1CA, then 

\begin{verbatim}
merge_atoms m1ca 1 130 m1 1 ; 
\end{verbatim}

Then use {\bf Lego\_auto\_mc} and {\bf Lego\_auto\_sc}.

\end{itemize}

%---
\subsection {Sam\_rename}  \index{Sam\_rename}
\syntax {Sam\_rename [molecule] [res1 res2] 
	[first\_residue\_name]}
Change the residue name of a given zone of residues. Residue names are
generated from the first residue name supplied. Entering A1, for example,
generates names like A1, A2 etc.  Suppose you have 2 molecules in the
asymmetric unit and they have residue names in the ranges 1-200 and
201-400. The following commands may be used to call them molecules A and B
with names in the range 1-200.

\begin{verbatim}
sam_rename m23 1 200 a1
sam_rename m23 201 400 b1
\end{verbatim}

%---
\subsection{Datablocks} \label{sec-sam-db}
\mbox{\bf O} is not terribly smart when working out the {\em type} of a coordinate file. It 
simply attempts to figure it out by looking at the
file extension (the last characters of the file name, after the period).
The file-type to extension mapping is defined in the {\tt .sam\_c6} datablock.
To see what the default mapping is, write it out: 

\begin{verbatim}
  O >  write .sam_c6 ; (15a)
.SAM_C6                   C         32 (15a)
pdb   brk   brook rd    dia   wah   wh    xyz   bud   x     o     obin
PDB   PDB   PDB   RD    RD    WAH   WAH   XYZ   BUD   XPL   O     O
HOH
  O >
\end{verbatim}

The first 15 elements are the file extensions, the next 15 are the corresponding 
file types. Thus, a PDB type file, will be recognized if its file extension is
{\tt .pdb}, {\tt .brk}, or {\tt .brook}. An XPL file (X-PLOR PDB) is assumed 
if the file extension is {\tt .x}. The last element in the datablock ({\tt HOH})
is the name of the solvent residues created by {\bf Water\_init}.

%%% assorted %%%

\section {The Assorted\_1 commands} 
This is a major menu containing an assortment of commands. These commands
are very commonly used, and it is therefore recommended that most of these
commands be kept on the screen.

%---
\subsection{Centre\_ID}  \index{Centre\_ID}
\syntax{Centre\_ID [id an atom]}
The next identified atom becomes the screen centre. Atoms can be identified
by picking at the screen or by using the {\bf Terminal\_id} command.

%---
\subsection{Terminal\_ID} \index{Terminal\_ID}
\syntax{Terminal\_id [mol res atom] [object]}
Identify an atom by typing on the terminal. This command is normally used
in macros.The program prompts for the atom and then the object name.

%---
\subsection{Wait\_ID}  \index{Wait\_ID}
\syntax{Wait\_ID}
Ignore any command until an ID is made. This command is used {\em
exclusively} in macros. The ID {\em must} be made by picking an atom.

%---
\subsection{Stop} \index{Stop} \index{Save\_DB}
\syntax{Stop}
This commands stops the current work session. The database is saved to the
file specified in the datablock {\tt file\_O\_save}, as if the command {\bf
Save\_DB} was activated.

%---
\subsection{Yes} \index{Yes}
\syntax{Yes}
Set the ``Yes'' flag on, the ``No'' flag off. This command is a utility
command, and is being used by several other commands. When input from this
command, or its friend, {\bf No} is required, a prompt is shown in the
message area of the display. For example:

\begin{verbatim}
Hit Yes to accept, No to cancel.
\end{verbatim}

{\em Great care must be taken if multiple commands are active that wait for
a {\bf Yes} or {\bf No}.  They will be affected in the order that appears
in the active command line of the display. The leftmost command will
receive the Yes or No.}

%---
\subsection{No} \index{No}
\syntax{No}
Set the ``No'' flag on, the ``Yes'' flag off. See the description of
{\bf Yes}.

%---
\subsection{Clear\_flags}  \index{Clear\_flags}
\syntax{Clear\_flags}
Clear all flags. This command cancels all active commands. If atomic
coordinates are being changed, e.g. by {\bf Lego\_side\_chain}, the command
issues a {\bf No}.

 %---
\subsection{Save\_DB}  \index{Save\_DB}
Save the \mbox{\bf O} database in a previously assigned file. The first time the
command is activated, the user is prompted to decide the file where the
database is to be written. The name of this file is stored in the
database in the text datablock {\tt file\_O\_save} and can be changed
using the distributed macros {\bf @change\_save\_file} or {\bf
macro save\_as}. \index{macro change\_save\_file} \index{macro save\_as}
\index{file\_o\_save} As distributed, this macro activates an editor
`vi'. {\em The {\bf Save\_DB} command should be activated every time you
have made any important modifications in the database!}

%---
\subsection{Clear\_Id}  \index{Clear\_Id}
\syntax{Clear\_Id}
Remove ID text from all molecular objects.

%---
\subsection {Macros}
Macros {\bf @change\_save\_file} or {\bf @save\_as} to change the
name of the file in which the user's data base is stored is supplied with
the \mbox{\bf O} distribution. {\em You cannot change the save file simply by
copying a file to another. The {\tt file\_O\_save} datablock will {\em not} have
changed, and that file will still be used to save data.} 

%---
\subsection {Datablocks } 
\begin {itemize}
\item {\tt File\_O\_save}: a text data block storing the file name of the 
user's data base. \index{file\_o\_save}
\end{itemize}

%%% ass_2 %%%

\section {The Assorted\_2 commands}

An assortment of utilities for menu control, logging and HELP facilities.

%---
\subsection {Menu\_control}  \index{Menu\_control}
\syntax {Menu [major\_menu\_name or text] [on/off] [colour]}
Control what menus are displayed and therefore visible to the user on the
display. If the text is a major menu, all commands for that menu are put
onto the screen. To add the {\bf Lego} commands to the screen, for example,
just do

\begin{verbatim}
O > menu lego ;;
\end{verbatim}

To add a macro called map, do

\begin{verbatim}
O > menu @map ; 
\end{verbatim}

The new commands are added to the bottom of the menu.
A list of available major menus can be obtained by typing 

\begin{verbatim}
O > menu ?
\end{verbatim}

The screen menu is maintained in a datablock called {\tt .menu} and can
be \index{.menu} changed in other ways. For example, its contents can be
converted in a formatted file with {\bf Write\_formatted}, edited with
your favourite \index{Write\_formatted} editor (remembering to correctly
update the number of lines), and then added back into the database with
{\bf Read\_formatted} command. \index{Read\_formatted}

There are two datablocks associated with the control and positioning of the
menu:

\begin {itemize}
\item {\tt .menu\_integer} \index{.menu\_integer}
   \begin {description}
   \item [1 The number of major menus.]
   \item [2 Number of commands on screen.	Default is 50.]
   \item [3 Colour when a menu is active. Default colour is blue.]
   \end{description}
\item {\tt .menu\_real} \index{.menu\_real}
   \begin {description}
   \item [1 Position on horizontal axis. Default 0.79.]
   \item [2 Character size. Default 0.8.]
   \end{description}
\end{itemize}

%---
\subsection {Symbols} \index{Symbols} \label{cmd-symbols}
\syntax {Symbol name [text string]} 
Adds a symbol definition to the program. The name of the symbol must {\em
not} include a \$ character. To use the symbol, the user adds a \$ to the
start of the symbol name. For example,

\begin{verbatim}
O> symbol greetings Hullo world
O> print  $greetings
O>  Hullo world
\end{verbatim}

The terminal line is parsed and any set of characters representing a
current symbol is replaced by the symbol expansion. Symbols are
particularly useful with macros to define which molecule or map to work
with, for example. To remove a symbol, run the command with prompting and
hit a [CR] instead of a new text string.

%% True from 5.10.2
If symbols are part of a text string, the name of the symbol must be
enclosed in braces, like in the following example, which is the content of
a macro to set up parameter blocks to deal with nucleic acids:
\index{nucleic acids}

\begin{verbatim}
db_set_data ${mol}_molecule_ca ; P
db_set_data ${mol}_molecule_ca_mxdst ; 8.3
\end{verbatim}

Certain symbols are predefined by \mbox{\bf O}, for example \$\{user\}, \$\{host\}
and \$\{domain\}. \index{Symbols, predefined} If the \$ODAT environmental
variable is defined when the program starts, the first path of it is copied
into the symbol \$\{odat\}.  When using the \htmlref {{\bf \$}}{cmd-dollar}
command, symbols are scanned by \mbox{\bf O} before the line is received by the
operating system, so that

\begin{verbatim}
 O > $ ls ${odat}
\end{verbatim}

would give you the directory listing of the public \mbox{\bf O} directory.

A few very useful symbols are created and updated as you are picking
residues and atoms: \verb|${.id_m}| contains the name of the last picked
molecule, \verb|${.id_r}| and \verb|${.id_a}| the names of the last picked
residue and atom, respectively. The \verb|${.id_z}| symbol contains the
names of the last two residues that were picked, if these were from the
same molecule. \index{.id\_m} \index{.id\_r} \index{.id\_z} \index{.id\_a}

If a symbol is not found in the symbol table, ``brace'' form symbols are
eaten by the parser and deleted from input (like in the UNIX shell).
\index{parser} Contrary, the ``dollar'' form of the symbol is not eaten,
since it could be the name of a residue, for example.  The brace form of
symbols is the most unambiguous and preferred notation for symbol
references.

Symbols are saved in the {\tt .SYMBOLS} datablock, but you can {\em not}
change symbols by manipulating this datablock.

%---
\subsection {O\_setup} \index{O\_setup}
\syntax {O\_setup [on/off] [on/off] [on/off]}
\begin{enumerate} 
\item Control of echoing commands on the terminal that come from indirect files.
Can be useful for debugging macros.
\item Control logging of command line input to a file {\tt o\_log.fmt}. 
This is useful to create templates for macros.
\item Control logging of terminal listing to a file {\tt o\_log.lst}. 
This option can be used to keep track of the output from complicated
operations, such as the lsq commands. The listings of \mbox{\bf O} output in this
manual were created using this option.
\end{enumerate}

%---
\subsection {Help}  \index{Help}
Provide on-line help for running \mbox{\bf O}. The first time, causes an intercept
to define the help file ({\tt \$ODAT/o\_help.o} is the default distributed
file). The user can then enter the keyword requiring help.

%---
\subsection {Spawn}  \index{Spawn} \label{cmd-spawn}
\syntax{Spawn}
Spawn another process in the operating system. In Unix, the shell is closed
by logout, exit, or [CTRL]-D if this option is enabled in your shell
environment. Dials, ID's and menu items picked on the screen will remain
locked while the spawned process is running.

%---
\subsection {\$} \index{\$} \label{cmd-dollar}
\syntax{\$ [UNIX shell command [\&]]} 
Issue a one line shell command to the operating system. 

%---
\subsection {Stereo} \index{Stereo} 
\syntax{Stereo}
Toggle Stereo on and off for the ESV. On the ESV, we use the crystal eyes
stereo system. This splits the video memory for a left and right eye image
with a loss of resolution in the vertical direction. See Appendix
\ref{app-dist} for details on how to install stereo. On the SGI, we use F
keys for SGI dependent functions including the stereo. F1 toggles Crystal
Eyes stereo, F9 side-by-side. This Crystal Eyes stereo implementation can
result in overlapping opened terminal windows. These can be avoided by
using a smaller window, positioned at the lower left hand corner of the
screen or by using F2 to make a black background.

%---
\subsection {Rot\_Tran\_Obj} \index{Rot\_Tran\_Obj}
\syntax {Rot\_tran\_obj [transformation] [object]}
Rotate/translate a 3D graphical object, normally not a molecule object but
for use with maps, {\tt rsc\_db}, or {\tt ca\_db}. The object {\em must}
exist. It could be created by the user (e.g. with the {\bf Map\_draw} or
{\bf Draw\_object} commands) or by program options with defined names ({\bf
Lego\_ca} creates an objects {\tt ca\_db} and {\tt ala\_db}, while {\bf
Lego\_side} creates an object {\tt rsc\_db}). In the object list that may
be drawn on the screen, the transformed objects have {\tt \_rt} appended to its
name. The transformation is a datablock in the database containing the
rotation and translation operators. It must be the complete name
for example {\tt .lsq\_rt\_a\_to\_b}.

%---
\subsection {Macros}

{\bf @Symbol\_setup} : This macro could be used to set up miscellaneous 
symbols for the supplied macros. Edit this macro to suit your filenames etc. 

\begin{verbatim}
symbol map_a ano1.map
symbol map_b ano1.map
symbol mol_a a
symbol mol_b b
\end{verbatim}

et cetera. 


%%% ass_3 %%%

\section {The Assorted\_3 commands} 

An assortment of commands. 
%---
\subsection {Centre\_atom}  \index{Centre\_atom}
\syntax {centre\_atom [mol residue atom]}
Define the {\tt .active\_centre} by typing an atom name. The user can type
\index{.active\_centre}
molecule residue and atom explicitly or defaults as specific atom in a
particular molecule.  The coordinate is taken as orthogonal {\AA}ngstr{\o}m's.

%---
\subsection {Centre\_XYZ}  \index{Centre\_XYZ}
\syntax {Centre\_xyz [x y z]}
Define the {\tt .active\_centre} by a entering a coordinate value at the
terminal.
\index{.active\_centre}

%---
\subsection{Backup\_DB} \index{Backup\_DB}
\syntax{backup\_db}
Backup the user Database to another disk file. The name of the backup file
is stored in the text datablock {\tt File\_O\_Backup}.
\index{file\_o\_backup}

%---
\subsection {Message} \index{Message}
\syntax {message [string]}
Send a message to be displayed
on the screen. Use in your macros to say what you are doing.

%---
\subsection{Draw\_object} \index{Draw\_object}
\syntax{draw\_object [datablock name] or [filename]}
Add a new object to those being displayed. The user specifies a file or a
text block in the database that contains drawing instructions in the
\mbox{\bf O} graphics descriptor format (see Chapter \ref{ch-ODL}, General Drawing
Instructions).

%---
\subsection {Dial\_next}  \index{Dial\_next}
\syntax{Dial\_next}
When several dial sets are active at the same time, this command can be
used to cycle between them in a forward direction. For example, the {\bf
Move\_fragment} command activates two dial sets, one for the rotations
around the x, y, z axes, and one for the translations. {\bf Dial\_next}
will select the next dial set on the stack. This command changes this
assignment by one block of four, cycling through 4 dial boxes. For each box
number, there must be an entry in the database {\tt .box}[number]
Default examples are included in {\tt dialbox.o}, {\tt dialbox\_a.o} and in
the {\tt startup.o} files.
\index{dialbox.o} \index{startup.o}

%---
\subsection {Dial\_previous} \index{Dial\_previous}
\syntax{Dial\_previous}
This command functions equivalently to {\bf Dial\_next}, but cycles in the
opposite direction through 4 dial box settings.

%---
\subsection {Dial\_box} \index{Dial\_box}
\syntax {dial\_box [number]}
This command allows one to explicitly define which dialbox is to be mapped
to the dials. A search of the data base for {\tt .box}[number] is made
and a mapping made between the logical input device numbers and the 8
dials.  For example, if one wishes to control all of the rotations and
translations for a moving fragment and have the zoom and slab active on the
same box, one may use a box number 5 and have in the data base an entry

\begin{verbatim}
.box5 i 8 (3i3)
  9 10 11  4 13 14 15  8
\end{verbatim}

To activate this dialbox, one would issue the command

\begin{verbatim}
dial_box 5
\end{verbatim}

%---
\subsection {Rotate\_picture} \index{Rotate\_picture}
\syntax {rotate\_picture [axis] [angle]}
Apply a rotation about one of the screen axes. Specify the axis and the
angle. Can be used for taking stereopictures, if the rotation angle is
6 degrees, e.g.

\begin{verbatim}
rot\_pic y 6.
\end{verbatim}

%---
\subsection{Cpk\_object} \index{CPK\_object}
\syntax{ Cpk\_object [object] [mode] [cleanup] }
Make a CPK object out of a molecular object. Specify molecular object
name, and the kind of balls (fast or slow), and whether to clean-up an
intermediate datablock.  On the ESV the fast option generates a rough
approximation to a sphere, while the slow option is an excellent sphere.
This option uses datablock {\tt .cpk\_radii} to associate ball radii
with atom types. Two example files are provided in {\tt cpk\_radii.o}
and {\tt radii.o}, for large and small balls. The option generates a set
of drawing instructions in {\tt .object\_cpk\_[object]} that can be
written out and edited on a standard text editor if necessary. This
datablock gets deleted if the default cleanup option is taken.

%---
\subsection{Screen\_colour } \index{Screen\_colour} 
\syntax{ screen\_colour [colour] }
ESV and HP only. Set the colour of the screen background. This is useful when
taking pictures of solids.  

%---
\subsection{Spin} \index{Spin}
\syntax{Spin}
Set the view spinning automatically for a while. Mainly for testing and benchmarking
purposes. Spins through 100 views.

%---
\subsection{Print} \index{Print}
\syntax{Print [message]}
Print a message on the terminal. Used in macros.

%---
\subsection{Bell}  \index{Bell} 
\syntax{Bell}
Ring a bell on the terminal. Used in macros to wake up the user.
%---

\subsection{If\_yes\_no} \index{yes\_no}
\syntax{if\_yes\_no [macro1] [macro2]}
This command allows one to do a very simple conditional statement. The first
macro will be activated if ``Yes'' is set, the second one if ``No'' is
set.

%---
\subsection{Centre\_zone}  \index{Centre\_zone}
\syntax{ centre\_zone [id two atoms] or [mol res1 res2]}
The picture centre is redefined as the centre of gravity of the defined
zone

%---
%%%\subsection{Template}  -?- -?- -?-
%%%\syntax{Template [directory] [file] [id]} 


%---
\subsection{Centre\_next}  \index{Centre\_next}
\syntax{centre\_next [property] [operator] [value]} 
Move to the next atom or residue along the sequence that fullfill the
criteria of the logical expression. A sister command, {\bf Centre\_prev},
moves in the backward direction. Examples:

\begin{verbatim} 
centre_next atom_name = ca
\end{verbatim} 

sets the current active centre at next CA position. 

\begin{verbatim}
centre_next residue_type = lys
\end{verbatim}

centres on next lysine residue.

\begin{verbatim}
centre_next residue_rsfit < 0.8
\end{verbatim}

Centres on next residue with a rsfit correlation coefficient worse than 0.8

%---
\subsection{Centre\_prev}  \index{Centre\_prev}
\syntax{centre\_prev [property] [operator] [value]}
Same as {\bf Centre\_next}, but moves backwards in the sequence.


%---
\subsection{Quit} \index{Quit}
\syntax{quit}
This command stops the program {\em without} saving the database. 


%%% oheap %%%

\section {The O\_heap\_1 commands} \index{\mbox{\bf O} database}

Commands to monitor and modify the \mbox{\bf O} database. In the current
implementation there is no facility to read binary \mbox{\bf O} files in this
menu. An \mbox{\bf O} database datablock has a number of associated properties: its
name (up to 25 characters), its type (different kinds of data can be stored
with types `I': integer, `R': real, `C': 6 character variable and `T':
text) its size in storage units, a write-back-to-disk flag (all user
created data gets a flag to allow writing back to disk on a save command,
but the databases for example are not stored in the users disk database).

%---
\subsection{Directory} \index{Directory}
\syntax{directory [datablock]}
Directory listing of data blocks. Wild card * is allowed, for example:

\begin{verbatim} 
dir *atom*
\end{verbatim}

lists all datablocks containing the string atom in their name.

%---
\subsection{Db\_create}  \index{Db\_create}
\syntax{db\_create [name] [size] [type]}
Create a new data block. The user must specify the name, the size of the
block and its allowed type (I,R or C). This command could be used to create
new residue or atomic data blocks. It is up to the user to ensure that the
datablock is of the correct size. 

%---
\subsection{Db\_delete} \index{Db\_delete}
\syntax{db\_delete [param]} 
Delete an existing data block. Wild card * is allowed. The user is prompted
before each delete is made. {\bf Db\_kill} is a related command that deletes
without confirmation.

%---
\subsection{Read\_formatted} \index{Read\_formatted} \index{\mbox{\bf O} files, input}
\label{cmd-read} 
\syntax{read\_formatted [file]} 
Read an \mbox{\bf O} database source file from computer disk. This command is used
to update or insert new data blocks. Also, see section \ref{sec-read-external}.
This command can {\em not} be used to read a binary database file;
attempting so will result in an error.

%---
\subsection{Write\_formatted} \index{Write\_formatted} \label{cmd-write}
	\index{\mbox{\bf O} files, output}
\syntax{Write\_formatted [param] [file] [format]}
Write out a datablock file as an \mbox{\bf O} database source file. The command
prompts for a data block name, a file name, and a format specification, in
standard FORTRAN syntax. For example:

\begin{verbatim}
write .lsq_rt_a_to_b junk.tmp (3f10.4)
\end{verbatim}

When specifying the format manually, be aware that there must {\em not} be any
spaces within the parenthesis.

If nothing is specified for the format, \mbox{\bf O} will attempt to figure out how
best to format the numbers in the datablock, both for maintaining accuracy
and compactness. This algorithm is very efficient, so it is rarely
necessary to specify the format manually. Also, with the default mechanism,
you do not risk dumb mistakes like specifying an integer format for a
floating point datablock.  Occasionally, however, \mbox{\bf O} will not be able to
choose an adequate format. One example is when writing out the {\tt
.lsq\_rt\_*} datablocks; these contain a rotation matrix, where all the
elements lie between -1.0 and 1.0, but the translation component can have a
magnitude in the hundreds, and the default format will therefore not always
be adequate to represent the rotation matrix with enough precision.  In
these cases, it is possible to override the assignment made by the program
using the datablock {\tt .default\_formats}, \index{.default\_formats} that
specifies (datablock, format) pairs. For example:

\begin{verbatim}
.DEFAULT_FORMATS T 3 20
.lsq_rt_*  (5e)
.gs_real   (5e)
.sym_rt_*  (5e)
\end{verbatim}

overrides the default format assignment for three groups of datablocks.

Wild cards are permitted in the specification of data block names. In this
way one can write out the entire database in ASCII format, for porting to
another computer, or just for saving. When using wild cards in the
specification of datablocks, you can not specify the format manually. 

%---
\subsection{Db\_table\_residue} \index{Db\_table\_residue}
\syntax{Db\_table\_residue [name] [type] [file]}
Make a new residue property from a table of residue properties in the users molecule.

For example,

\begin{verbatim}   
  O > mol alpha
  O > db_table_res phob r phobicity.dat
\end{verbatim}  

will create a new real datablock called {\tt alpha\_residue\_phob}, using
the data in the file {\tt phobicity.dat}.

Look at appendix \ref{app-tables} for examples of residue property
tables, provided in {\tt \$ODAT} to describe residue size, charge,
hydrophobicity as a function of the residue type.
Contributions of property tables will be appreciated!

%---
\subsection{Db\_set\_data} \index{set\_data}
\syntax{Db\_set\_data [datablock] [range] [value]}
Set consecutive locations in data block to a value. This command is often used
to change values of constants in the database, if no user interface is provided
in the program. For example, to change the sensitivity of dials, we can poke 
a different multiplier value into {\tt .dial\_real}:

\begin{verbatim}
  O > db_set_data 
 Heap> Full name of data block: {\bf .dial\_real}
 Heap> It is of type R and has 1 entries
 Heap> Start and end entries [1 1 ]: {\bf 1 1}
 Heap> Changing entries 1 to 1 of data block .dial\_real
 Heap> Enter value (must be type R): {\bf 0.2}
  O >
\end{verbatim}
  
%---
\subsection{Db\_set\_zone}  \index{set\_zone}
\syntax{Db\_set\_zone [property] [zone] [value]}
In the current molecule, set a data block for all atoms in a zone to a value.

\begin{verbatim}
  O > mol alpha
  O > db_set_zone
 Heap> Full name of data block:ALPHA_{\bf atom\_b}
 Heap> It is of type R and has 35 entries
 Heap> Start and end residues in zone ([all residues]):
 Heap> Value (must match param block) : {\bf 30.}
  O >
\end{verbatim}  

%---
\subsection{Db\_set\_atom} \index{set\_atom}
\syntax{Db\_set\_atom [atom property] [zone] [atom] [value]}
In the current molecule, set a data block of a specific atom (e.g. CA) 
in a zone to a value. In the example from above, we can set the B-factors of the
CA atoms to a different value from the rest:

\begin{verbatim}
 O > db_set_atom
 Heap> Full name of data block: ALPHA{\bf \_atom\_b}
 Heap> It is of type R and has    35 entries
 Heap> Start and end residues in zone ([all residues]):
 Heap> Atom name [CA] :
 Heap> Value (must match param block) : {\bf 23.}
 Heap> There were     5 marked atoms
  O >
\end{verbatim}
  
%---
\subsection{A smart-ass example}
Question: suppose you have a completely unknown protein, that you don't
know anything about. How do you colour all non-amino-acid atoms {\em
salmon-pink\/}?? In \mbox{\bf O}, this is easy! First you create a residue property
table, giving all amino acids a character property, for example AA. Then
you read the residue table into the database using the {\bf
Db\_table\_residue} command. Finally, you go

\begin{verbatim}
obj salmon
paint_property residue_amino_acid != AA salmon
paint_property residue_amino_acid = AA green 
zone ;
end
\end{verbatim}

Easy, huh? 



\section {The O\_heap\_2 commands} \index{\mbox{\bf O} database}
More \mbox{\bf O} database related commands, that allow the user to manipulate the
content of individual datablocks.

%---
\subsection{Rot\_trans\_Db} \index{Rot\_trans\_Db}
\syntax{rot\_trans\_db [x'] [R] [x]}
Apply a rotation/translation operator $R$ to the coordinates of a point $x$
storing the results in  {\bf x'}:

\begin{verbatim} 
x'  = R * x 
\end{verbatim}  

where $x$, {\bf x'} and $R$ are names of datablocks. This is most frequently used to
modify the {\tt .active\_centre} to look at non-crystallographically related
molecules: \index{.active\_centre}

\begin{verbatim}
  O > copy save_centre .active_centre
  O > rot_trans_db .active_centre .lsq_rt_a_to_b .active_centre
\end{verbatim}

We first made a safe copy of {.active\_centre}, so we can restore it later.

%---
\subsection{Arith\_Db} \index{Arith\_Db}
\syntax{arith\_db [A] [B] [op] [C]}
A=B op C. Apply + - / * operators between datablocks B and C, storing
results in A.

%---
\subsection{Copy\_Db} \index{Copy\_Db}
\syntax{copy\_db [A] [B]}
A = B. Copy B on to A.  Can be used to make a backup of coordinates, for
example, prior to a drastic rebuilding session. The command {\bf Backup\_DB}
can also be used for this purpose, but this will save the entire database
to a file, {\bf Copy\_Db} only copies a single data block within the
database.

%---
\subsection{Db\_kill}  \index{Db\_kill}
\syntax{db\_kill [param]} 
Delete an existing data block. Wild card * is allowed. The user is {\bf
not} prompted before each delete is made. {\bf Db\_delete} is a related
command that deletes with a prompt confirmation.

%---
\subsection{DB\_stat}  \index{DB\_stat}
\syntax{db\_stat [param]} 
Supplies statistical information on an existing real or integer data block:
minimum and maximum values, mean and standard deviation. Wild card * is
{\em not} allowed.

%%%
\section {The special major menus Object\_1 to 5} \index{objects}

This menu control what objects are toggled on or off.This includes objects
made directly by the user from molecules and/or maps, but also objects
created on the fly by certain commands. For example, the {\bf Lego} major
menu creates a number of objects that can be toggled on and off. The
molecule object generating command {\bf End\_object} forces an update of the
object list, other object generating commands ({\bf Map} \ldots, {\bf
Lego\_ca} \ldots) do not.

%---
\subsection{On\_off} \index{On\_off}
The first command {\bf On\_off}, updates the list of what objects are
being displayed. Since 10 menus can be associated with a major command
only 9 can be toggled on/off with {\bf Object\_1}. Activating {\bf
Object\_2} gives another 10 objects and so on to a total of 50. Each
object being displayed is written on the menu with the hat character
preceding the name, as \verb|^CA|, for
example. Picking this item will turn on and off object {\tt CA}. When
the object is turned off, the colour of the menu item will change to red, and any
alphanumeric characters in its name will be converted to lower case. 

%%% symmetry %%%

\section {The Symmetry commands} \index{crystallographic symmetry}

The {\bf Symmetry} major menu implements the application of
crystallographic symmetry to a molecule. This requires that entries exist
in the database for the unit cell and the symmetry operators of the space
group of the molecule. These can be added via {\bf Read\_formatted} or by
the {\bf Symm\_setup} commands. The {\bf Symm\_sphere} command generates
complete molecules for the symmetry related molecules. Their names are
generated from user supplied names. After a call to {\bf Symm\_sphere} the
molecules exist in the database as molecules in their own right, until
overwritten by a later call or deleted by the user. The user may like to
paint carbons a different colour to make the symmetry atoms easier to
recognise.  If the asymmetric unit contains more then one chain, and these
exist as separate molecules in the database, then a number of symmetry
commands may be necessary to show all neighboring molecules.

%---
\subsection{Symm\_setup} \index{Symm\_setup} \index{unit cell, defining}
	\index{spacegroup, defining}
\syntax{Symm\_setup [mol] [cell] [symmops]}
Setup for symmetry. The user is prompted for the molecule name, the unit
cell constants, and then a formatted text datablock describing the
crystallographic symmetry operators. This datablock must be named {\tt
.space\_group\_operators} and must contain an explicit description of
{\em all} symmetry operators (including centered ones). The unit
transformation operator must be the first one defined. As everywhere
else in \mbox{\bf O}, each operator consists of 12 floating point numbers,
encoding a rotation matrix and a translation matrix. The rotation matrix
$R_{ij}$ is a (3 x 3) matrix store columnwise,
while the translation matrix {\bf T(i)}
is a column vector, given in crystallographic fractional coordinates.
They {\em must} be stored in columns as R(11), R(21), R(31), R(12),
R(22), R(32), R(13), R(23), R(33), T(1), T(2), T(3).  The
operators for space group P(21) would be

\begin{verbatim} 
1 0 0   0 1 0   0 0 1   0 0 0
\end{verbatim}
followed by
\begin{verbatim}
-1 0 0  0 1 0   0 0 -1  0 0.5 0
\end{verbatim}

Example files for the common space groups are found in the {\tt
\$ODAT/symm/} directory. This option creates 2 datablocks, {\tt
[mol]\_cell} and {\tt [mol]\_symmop}.

%---
\subsection{Symm\_sphere} \index{Symm\_sphere}
\syntax{Symm\_sphere [mol] [symmetry mol name] [radius]}
Draw all symmetry related atoms within a sphere of given radius, centred on
the {\tt .active\_centre}. Each symmetry operation that is found, generates a
\index{.active\_centre}
complete molecule in the database and a separate object of the part within
the sphere. The names of the new `symmetry molecules' are derived from the
supplied symmetry molecule name.

%---
\subsection{Symm\_object} \index{Symm\_object}
\syntax{Symm\_object [molecular object] [symmetry object]
 [radius]}
Draw a set of objects that are symmetry related to the desired molecular
object, and within the specified distance of the current centre. These
objects are drawn in one new object and are merely instances of the desired
object. As such they have the same colour as that object. The option
creates 2 datablocks, {\tt @symmetry\_molecules} and {\tt .draw\_symobj}.
\index{macro symmetry\_molecules} \index{.draw\_symobj}

%---
\subsection{Symm\_cell }  \index{Symm\_cell} \index{unit cell, drawing}
\syntax{Symm\_cell}
Draw a box representing the unit cell of the current molecule. This command
assumes the unit cell is in the data base by a previous {\bf Symm\_setup}
command. The command creates a datablock {\tt .cell\_odl} containing the ODL
instructions to create the drawing. \index{.cell\_odl}

%---
\subsection{Examples} 

The necessary symmetry information is added to the database of
molecule A27 by the following example

\begin{verbatim} 
symm\_setup a27 96.8 112.3 55.0 90. 90. 90. p212121
\end{verbatim} 


If the datablock describing your space group does not exist in 
{\tt \$ODAT/symm}, then use the {\tt p212121.o} file as an example. Remember to
include any centring operators as explicit operations.

The following example generates symmetry atoms for molecule A27.

\begin{verbatim} 
symm_sph a27 sym 10.
\end{verbatim} 

Any residue with its centre of gravity 10\AA\ from the current screen
centre (as defined by {\tt .active\_centre}) will appear on the
\index{.active\_centre} screen. These may be from a number of different
symmetry related molecules. Each object is named after the symmetry
molecule's name. The first symmetry molecule would be called SYM1, the
next SYM2, etc.


%---
\subsection{Datablocks} 

The {\bf Symm\_sphere} and {\bf Symm\_object} command modifies a text datablock
containing a macro {\tt @symmetry\_molecules}. \index{macro symmetry\_molecules}


%%% plot %%%

\section {The Plot commands} \index{Plot commands} \index{hardcopy}

The {\bf Plot} menu implements a rudimentary plotting option in \mbox{\bf O}. The
{\bf Plot} command generates an \mbox{\bf O} descriptor language description of the
objects to be plotted together with keywords describing scale and
orientation information. These may require fine tuning before making the
final plots. This file can be converted into a {\sc PostScript} file
using the program {\bf oplot}. \index{oplot} The semi-transparent maps can 
not currently
be plotted, but sketches and CPK's can. With a suitable printer, 
coloured drawings can be plotted. Refer to section \ref{sec-oplot} for further
information.

%---
\subsection{Plot\_setup}  \index{Plot\_setup}
\syntax{plot\_setup [file root] [plot number]
[plot the menu Y/N] [plot in stereo Y/N]}
Setup for the plotting menu. Define the root name of the plot file, and the
plot number. The root name is a template used to generate a unique name for
each file to be plotted. The plot number will be incremented for each file
created, and the plot number inserted into the file name template. The
position of the plot number in the template is indicated by character
\%. For example, defining {\tt crbp\_\%\%\%.plt} as the template and a plot
number of 1 would result in the first file being {\tt crbp\_001.plt}, the
next one {\tt crbp\_002.plt} etc. Defining {\tt crbp.plt} as a template
would result in the file being overwritten after each plot. The user is
also prompted to plot the menu and whether to make the final plot in mono
or stereo. \index{plotting, in stereo}

%---
\subsection{Plot} \index{Plot}
\syntax{Plot}
Creates a plot file for {\bf oplot}. This is the Quick'n Dirty way of plotting.
Only molecular objects, and the last
defined electron density file can be plotted, and only in black \& white.

%---
\subsection{Plot\_on}  \index{Plot\_on}
\syntax{Plot\_on}
Switch on plotting. Causes \mbox{\bf O} to open a new plot file, and stores the
current viewing parameters in the file. All graphics instructions that
afterwards get activated, will create something in the plot file. The dials
are not active while {\bf Plot\_on} is selected.

%---
\subsection{Plot\_off}  \index{Plot\_off}
Switch off plotting, and close the plot file.

%%% patterson %%%

\section{Patterson} \index{Patterson}

These commands allow one to solve Patterson functions interactively or to
check out the results from an automatic system.The proposed heavy atom
sites must exist as a molecule in \mbox{\bf O}, together with unit cell and symmetry
(see {\bf Symm\_setup}). The atom selection property {\tt
[mol]\_atom\_select} is used to switch on or off the use of a
particular atom to the cross vector calculation. It can be defined with the
{\bf Select} menu. \index{\_atom\_select}

A molecule PATT must exist and have enough entries to satisfy the
number of cross vectors that are generated. It can be made with {\bf
Patt\_setup} or {\bf Water\_init. } Before using these commands, it is
helpful to have an object displaying the unit cell, and map objects of
Harker sections and 3-D volume elements in the Patterson function.

%---
\subsection{Patt\_setup}  \index{Patt\_setup}
\syntax{patt\_setup}
This generates a molecule in \mbox{\bf O} called PATT that contains 1000 cross
vectors. The command is actually a call to {\bf Water\_init} so the cross vector
atom have solvent names. If you want more (or less) vectors you can
create the PATT molecule manually, for example:

\begin{verbatim} 
water\_init patt 100 1
\end{verbatim}

would create space for 100 cross-vectors.

%---
\subsection{Patt\_cross} \index{Patt\_cross}
\syntax{patt\_cross [heavy atom molecule name] 
             [xmin xmax ymin ymax zmin zmax]} 
This creates an object of all of the desired heavy atoms within the
selected volume. The volume must be defined in fractional unit cell
units. The cross vectors are put as atoms in molecule PATT (which must
exist) and an object created. The command remains active. If a heavy atom
position is being changed with {\bf Patt\_move} the cross vector
coordinates and object are updated. If a cross vector is identified, the
residue type field gives the from/to heavy atom.

%---
\subsection{Patt\_move}  \index{Patt\_move}
\syntax{patt\_move  [id an atom] or [mol res atom]}
Basically, this command is the same as {\bf Move\_atom}, but
the moving atom moves along the orthogonal axes of structure space and not
of display space. This means if you change the $x$-dial it moves along the
molecule $x$-axis not the screen $x$-axis. \index{moving atom}


%%% mutate %%%

\section {Mutate}  \index{Mutate}

This menu allows one to mutate the sequence of a molecule. The molecule
must exist in the data base. The commands may/will make use of the side
chain and main chain databases and must be correctly specified via the {\bf
Lego\_setup} command.
\index{Lego\_setup}

%---
\subsection{Mutate\_setup} \index{Mutate\_setup}
Does not do anything yet.

%---
\subsection{Mutate\_replace} \index{Mutate\_replace}
\syntax{mutate\_replace [molecule] [residue name,  
	new residue type](i)}
Any number of residues can be mutated until a blank line is entered. All
atom properties of the specified molecule are changed in size to
accommodate the new sequence. Certain properties are assigned special
values, others are given default values.

\begin{description}
\item [\_atom\_z]  is changed to reflect the element number Z of the new atom
\item [\_atom\_b]  new atoms have a temperature factor of 20.0\AA**2
\item [\_atom\_name] new atom names are taken from the contents of the file
specified in the last {\bf Connect\_file } command.
\item [\_atom\_wt] new atoms have weights of 1.0
\item [\_atom\_colour]  all atoms in a mutated residue are coloured magenta
\end{description}

\index{\_atom\_z} \index{\_atom\_b} \index{\_atom\_name}
\index{\_atom\_wt} \index{\_atom\_colour}

The default values for all other properties are 0, 0.0 and ` ' for integer,
real and character properties, respectively.

The new residue type must exist as an entry in the contents of the file
specified in the last {\bf Connect\_file } command.  Because molecular
objects are described in the database as link lists, their pointers are to
the {\em old} positions in the molecule. All objects of the changed molecule must
be re-made by the user. Mutated residues will appear coloured magenta.
Side chain confirmations are from the most frequent side chain rotamer. The
database must therefore be correctly defined with {\bf Lego\_setup}.
\index{Lego\_setup}

%---
\subsection{Mutate\_delete}  \index{Mutate\_delete}
\syntax{mutate\_delete [molecule] [residue name](i)}
Any number of residues are deleted. Input is terminated by a blank input.
This command would usually leave non-standard stereochemistry. This can be
corrected with {\bf Refi\_zone}, {\bf Lego\_loop} or {\bf Manip} commands.

%---
\subsection{Mutate\_insert}  \index{Mutate\_insert}
\syntax{mutate\_insert [molecule] [residue name] 
[new residue name,  new residue type](i)}
Adds new residues after a specified place in the molecule. Terminated by a
blank line. The new residue names should be unique to the molecule.  This
command merely makes space in the database for new residues. The user must
place them. This could be done in a number of ways, but recommend
{\bf Lego\_loop} to start with.
\index{Lego\_loop}

The following will insert an alanine residue after residue 102 in
molecule A26.

\begin{verbatim} 
mut_insert a26 102 102a ala ;
sel_off a26 102 103
lego_loop 
\end{verbatim}

and identify 100 to 105, say. If the new residue had a longer side chain,
for example Phe, it would also need to be constructed with {\bf Lego\_side} 
and identify an atom. \index{Lego\_side}

%---
\subsection{Example: menu\_mutate.o} \index{menu\_mutate.o}

This distributed file shows you how to make a menu that makes it easier to
mutate a structure. This is an \mbox{\bf O} file that must be read into the users
database. For each amino acid, there is a macro which when activated will
mutate the the residue containing the next Id'ed atom and make an object
{\tt sph} centred on this atom. To mutate a residue into a tryptophan, you
would hit the {\tt @trp} macro on the menu. This macro contains

\begin{verbatim}
cen_id wait_id
mut_repl $.id_m $.id_r trp ;
mol $.id_m obj sph sph 10 end
\end{verbatim} 


%%% slider %%%

\section{Slider} \index{Slider} \index{sequence, fitting}

This menu is an aid to map interpretation. It allows one to make an
estimate of what amino acid is to be associated with some electron
density. The user enters a guess of the sequence based on the shape and
position of the density that is then compared to the actual sequence via a
look up table that must have been read into the users database. The guess
may be accepted and may be entered into the database as a named entity. A
number of guesses can later be combined together.

The guesses entered are one letter codes that usually appear to be the 20
amino acids. However, any one letter can be entered but it must exist in
the `slider matrix' that converts the entered symbol into a score relative
to each of the 20 amino acids. The user is free to modify the file supplied
in {\tt \$ODAT/slider.o} --- it is NOT based simply on matching the size of
the sequence to the guess.

%---
\subsection{Slider\_setup} \index{Slider\_setup}
\syntax{Slider\_setup [mol] [max \# guesses]}
This command defines which molecule is to be worked on and how long a
scoring list is to be used.

\begin{verbatim} 
  O > {\bf slider}
  O >  SLIDER       is not a unique keyword.
  O >  SLider_Setup is a possibility.
  O >  Slider_guess is a possibility.
  O >  Slider_show  is a possibility.
  O >  Slider_displ is a possibility.
  O >  Slider_combi is a possibility.
  O >  Slider_lego  is a possibility.
  O >  SLIDER       is not a visible command.
  O > {\bf sl\_setup} 
 Slid> Slider molecule [A     ] :
 Slid> Maximum number on dial for Slider_guess [20] :
\end{verbatim}

%---
\subsection{Slider\_guess} \index{Slider\_guess}
\syntax{Slider\_guess [...]}
Allows one to enter a guess into the database. After getting a score, the
user is asked if it should be associated with some coordinates. This allows
one to first build a poly-alanine, for example, then later try to work out
where one is in the sequence. Since one could have build the initial
structure backwards, the program gives you the chance of associating the
guess with a backwards model.

The `slider matrix' must have been loaded. \index{Slider matrix}

\begin{verbatim}
  O > {\bf sl\_gues}
 Slid>  There are    132 residues in molecule.
 Slid>  There is no slider matrix in the database.
  O > {\bf read ../data/slider.o} 
 Slid>  There are    132 residues in molecule.
 Slid> Estimated sequence: {\bf gvwa} 
 Slid>  Average=      0.43,rms=      0.14
 Slid>                       GVWA
 Slid>  Fit   1 0.875 A6     GTWK
 Slid>  Fit   2 0.725 A33    GNLA
 Slid>  Fit   3 0.700 A84    VTLA
 Slid>  Fit   4 0.675 A26    GLAT
 Slid>  Fit   5 0.675 A55    SPFK
 Slid>  Fit   6 0.675 A122   VVCT
 Slid>  Fit   7 0.650 A99    GNET
 Slid>  Fit   8 0.650 A82    STVT
 Slid>  Fit   9 0.650 A111   GKMV
 Slid>  Fit  10 0.625 A28    ATRK
 Slid>  Fit  11 0.625 A89    GSLN
 Slid>  Fit  12 0.600 A62    ISFK
 Slid>  Fit  13 0.600 A40    VIIS
 Slid>  Fit  14 0.600 A72    ETTA
 Slid>  Fit  15 0.600 A24    GVGL
 Slid>  Fit  16 0.600 A50    TIRT
 Slid>  Fit  17 0.600 A22    ALGV
 Slid>  Fit  18 0.575 A102   TTIK
 Slid>  Fit  19 0.550 A79    KTKS
 Slid>  Fit  20 0.550 A73    TTAD
 Slid> Do you want to associate with a residue ([Y],n)?
 Slid> Molecule and residue name : {\bf a a6}
 Slid> Forwards or backwards ([F],b)?
\end{verbatim}

The best fitting sequence is now shown on the display, and a dial controls
which of the fits is displayed. To accept it into the database, type

\begin{verbatim}
  O > {\bf yes} 
 Slid> What name to associate with guess?{\bf g1} 
\end{verbatim}

The guess text can be 1-6 characters in length and creates 4 items in the
database. Which can be retrieved by other commands

\begin{verbatim}
  O > {\bf dir *g1*} 
 Heap>  .SLIDER_XYZ_G1            R W        12
 Heap>  .SLIDER_SEQ_G1            T W         4
 Heap>  .SLIDER_POS_G1            I W       132
 Heap>  .SLIDER_FIT_G1            R W       132
\end{verbatim}

%---
\subsection{Slider\_show} \index{Slider\_show}

Allows one to see on the display which guesses have been made.

%---
\subsection{Slider\_display} \index{Slider\_display}

Allows one to reactivate a guess that has been stored in the database. A
dial controls which of the scores is shown.

\begin{verbatim}
  O > {\bf sl\_displ} 
 Slid> Enter which one : {\bf g1} 
  O > {\bf no}
\end{verbatim}

%---
\subsection{Slider\_combine} \index{Slider\_combine}

Normally one enters a number of guesses into the system and then tries to
combine them in some way. The order in which guesses are specified to be
combined is vital since this implies that the first guess comes before the
second one in the sequence, and so on. When combining them, one specifies a
maximum size gap between guesses. These values are important since they act
as constraints in forming the scores.  In the following examples, a few
more guesses are added to the system. The first one is actually starting at
residue A38 and has quite a worse fit when compared to the top score.

\begin{verbatim} 
  O > {\bf sl\_gues} 
 Slid>  There are    132 residues in molecule.
 Slid> Estimated sequence: {\bf vavvlv} 
 Slid>  Average=      0.54,rms=      0.16
 Slid>                       VAVVLV
 Slid>  Fit   1 0.883 A82    STVTLA
 Slid>  Fit   2 0.833 A80    TKSTVT
 Slid>  Fit   3 0.783 A23    LGVGLA
 Slid>  Fit   4 0.767 A38    PRVIIS
 Slid>  Fit   5 0.733 A122   VVCTRI
 Slid>  Fit   6 0.733 A89    GSLNQV
 Slid>  Fit   7 0.717 A81    KSTVTL
 Slid>  Fit   8 0.717 A83    TVTLAR
 Slid>  Fit   9 0.717 A120   KDVVCT
 Slid>  Fit  10 0.717 A25    VGLATR
 Slid>  Fit  11 0.717 A88    RGSLNQ
 Slid>  Fit  12 0.717 A48    IITIRT
 Slid>  Fit  13 0.700 A100   NETTIK
 Slid>  Fit  14 0.700 A123   VCTRIY
 Slid>  Fit  15 0.700 A45    KGDIIT
 Slid>  Fit  16 0.683 A98    NGNETT
 Slid>  Fit  17 0.683 A11    VSSENF
 Slid>  Fit  18 0.683 A37    KPRVII
 Slid>  Fit  19 0.683 A73    TTADNR
 Slid>  Fit  20 0.667 A27    LATRKL
 Slid> Do you want to associate with a residue ([Y],n)?
 Slid> Molecule and residue name :{\bf  a a38} 
 Slid> Forwards or backwards ([F],b)?
  O > yes
 Slid> What name to associate with guess?{\bf g2} 
\end{verbatim}

Now the next strand is added, the correct answer is fit 12,  residue A48

\begin{verbatim}
   O >{\bf  sl\_gues}
 Slid>  There are    132 residues in molecule.
 Slid> Estimated sequence: {\bf vltfal} 
 Slid>  Average=      0.52,rms=      0.15
 Slid>                       VLTFAL
 Slid>  Fit   1 0.817 A90    SLNQVQ
 Slid>  Fit   2 0.767 A83    TVTLAR
 Slid>  Fit   3 0.750 A61    EISFKL
 Slid>  Fit   4 0.750 A22    ALGVGL
 Slid>  Fit   5 0.733 A63    SFKLGQ
 Slid>  Fit   6 0.717 A85    TLARGS
 Slid>  Fit   7 0.717 A92    NQVQKW
 Slid>  Fit   8 0.700 A114   VVECKM
 Slid>  Fit   9 0.700 A103   TIKRKL
 Slid>  Fit  10 0.700 A29    TRKLGN
 Slid>  Fit  11 0.683 A5     LGTWKL
 Slid>  Fit  12 0.683 A48    IITIRT
 Slid>  Fit  13 0.683 A123   VCTRIY
 Slid>  Fit  14 0.667 A7     TWKLVS
 Slid>  Fit  15 0.667 A81    KSTVTL
 Slid>  Fit  16 0.650 A11    VSSENF
 Slid>  Fit  17 0.650 A59    NTEISF
 Slid>  Fit  18 0.650 A99    GNETTI
 Slid>  Fit  19 0.650 A54    ESPFKN
 Slid>  Fit  20 0.633 A24    GVGLAT
 Slid> Do you want to associate with a residue ([Y],n)?
 Slid> Molecule and residue name : {\bf a a48} 
 Slid> Forwards or backwards ([F],b)?
  O > {\bf yes}
\end{verbatim}
 
Now they can all be combined, or in pairs

\begin{verbatim}
   O > {\bf sl\_com}
 Slid>  Slider guess : G1
 Slid>  Slider guess : G2
 Slid>  Slider guess : G3
 Slid> Enter which ones : g2 g3
 Slid>  There will be a search for     2
 Slid> Enter gap sizes : 4
 Slid>  Fit  1 =  0.850   82   90
 Slid>  Fit  2 =  0.825   80   90
 Slid>  Fit  3 =  0.800   82   92
 Slid>  Fit  4 =  0.767   81   90
 Slid>  Fit  5 =  0.767   83   90
 Slid>  Fit  6 =  0.742   23   29
 Slid>  Fit  7 =  0.725   84   90
 Slid>  Fit  8 =  0.725   73   83
 Slid>  Fit  9 =  0.725   38   48
 Slid>  Fit 10 =  0.717   82   88
 Slid>  Fit 11 =  0.717   83   92
 Slid>  Fit 12 =  0.708   82   89
 Slid>  Fit 13 =  0.708   55   61
 Slid>  Fit 14 =  0.708   82   91
 Slid>  Fit 15 =  0.700   55   63
 Slid>  Fit 16 =  0.700   80   86
 Slid>  Fit 17 =  0.692   53   61
 Slid>  Fit 18 =  0.692   89   99
 Slid>  Fit 19 =  0.692   80   88
 Slid>  Fit 20 =  0.683   80   89
  O > {\bf no}
\end{verbatim}

Because of the relatively poor guessing, the correct answer is a little way
down the list at position 9.

Lets add some more, the next strand. The error message ``{\tt Residue FA not in
matrix}'' comes because the A molecule includes a fatty acid that is not in
the slider matrix.

The guess is a good one, the top score is correct.

\begin{verbatim} 
  O > {\bf sl\_gues}
 Slid>  There are    132 residues in molecule.
 Slid> Estimated sequence: {\bf siqlqf}
 Slid>  Residue FA     not in matrix.
 Slid>  Residue FA     not in matrix.
 Slid>  Residue FA     not in matrix.
 Slid>  Residue FA     not in matrix.
 Slid>  Residue FA     not in matrix.
 Slid>  Residue FA     not in matrix.
 Slid>  Average=      0.53,rms=      0.15
 Slid>                       SIQLQF
 Slid>  Fit   1 0.833 A59    NTEISF
 Slid>  Fit   2 0.817 A90    SLNQVQ
 Slid>  Fit   3 0.783 A114   VVECKM
 Slid>  Fit   4 0.750 A67    GQEFEE
 Slid>  Fit   5 0.750 A12    SSENFD
 Slid>  Fit   6 0.733 A89    GSLNQV
 Slid>  Fit   7 0.717 A91    LNQVQK
 Slid>  Fit   8 0.717 A14    ENFDEY
 Slid>  Fit   9 0.717 A50    TIRTES
 Slid>  Fit  10 0.700 A65    KLGQEF
 Slid>  Fit  11 0.700 A92    NQVQKW
 Slid>  Fit  12 0.700 A63    SFKLGQ
 Slid>  Fit  13 0.700 A124   CTRIYE
 Slid>  Fit  14 0.700 A13    SENFDE
 Slid>  Fit  15 0.683 A10    LVSSEN
 Slid>  Fit  16 0.683 A61    EISFKL
 Slid>  Fit  17 0.683 A47    DIITIR
 Slid>  Fit  18 0.667 A123   VCTRIY
 Slid>  Fit  19 0.667 A82    STVTLA
 Slid>  Fit  20 0.667 A15    NFDEYM
 Slid> Do you want to associate with a residue ([Y],n)?
 Slid> Molecule and residue name : {\bf a a59}
 Slid> Forwards or backwards ([F],b)?
  O > yes
 Slid> What name to associate with guess? {\bf g4}
\end{verbatim}

Now include this one and  the first guess which is also well defined. 

\begin{verbatim} 
  O > {\bf sl\_com} 
 Slid>  Slider guess : G1
 Slid>  Slider guess : G2
 Slid>  Slider guess : G3
 Slid>  Slider guess : G4
 Slid> Enter which ones : {\bf g1 g2 g3 g4} 
 Slid>  There will be a search for     4
 Slid> Enter gap sizes : {\bf 40 5 5} 
 Slid>  Fit  1 =  0.782    6   38   48   59
 Slid>  Fit  2 =  0.764   55   82   90   99
 Slid>  Fit  3 =  0.759    6   37   48   59
 Slid>  Fit  4 =  0.755   55   82   90  101
 Slid>  Fit  5 =  0.755   33   38   48   59
 Slid>  Fit  6 =  0.750   40   82   90   99
 Slid>  Fit  7 =  0.750   72   82   90   99
 Slid>  Fit  8 =  0.750   55   80   90   99
 Slid>  Fit  9 =  0.750   33   73   83   90
 Slid>  Fit 10 =  0.750   50   82   90   99
 Slid>  Fit 11 =  0.750   62   82   90   99
 Slid>  Fit 12 =  0.745    6   50   61   67
 Slid>  Fit 13 =  0.745   26   38   48   59
 Slid>  Fit 14 =  0.741   40   82   90  101
 Slid>  Fit 15 =  0.741   62   82   90  101
 Slid>  Fit 16 =  0.741    6   38   49   59
 Slid>  Fit 17 =  0.741   50   82   90  101
 Slid>  Fit 18 =  0.741   72   82   90  101
 Slid>  Fit 19 =  0.741    6   23   29   40
 Slid>  Fit 20 =  0.741   55   80   90  101
  O > no
\end{verbatim} 

The correct answer is at the top. Notice that there are clusters of correct
answers in the top scores. The gap values are important since they are
restraints in evaluating the scores.  In the above example, we check all
possibilities that are separated by less then 40 residues between guess G1
and G2; by 5 between G2 and G3, and by 5 between G3 and G4. In the next
example, the gaps are all less then 200 residues, i.e. the gap restraints
are not of any use (there are only 131 residues in the protein).

\begin{verbatim} 
  O > {\bf sl\_set} 
 Slid> Slider molecule [A     ] :
 Slid> Maximum number on dial for Slider_guess [20] :{\bf 30} 
  O > {\bf sl\_comb}
 Slid>  Slider guess : G1
 Slid>  Slider guess : G2
 Slid>  Slider guess : G3
 Slid>  Slider guess : G4
 Slid> Enter which ones : {\bf g1 g2 g3 g4} 
 Slid>  There will be a search for     4
 Slid> Enter gap sizes : {\bf 200 200 200} 
 Slid>  Fit  1 =  0.836    6   82   90  114
 Slid>  Fit  2 =  0.823    6   80   90  114
 Slid>  Fit  3 =  0.814    6   82   90  124
 Slid>  Fit  4 =  0.809    6   23   90  114
 Slid>  Fit  5 =  0.809   33   82   90  114
 Slid>  Fit  6 =  0.809    6   82   92  114
 Slid>  Fit  7 =  0.805    6   38   90  114
 Slid>  Fit  8 =  0.805    6   82   90  123
 Slid>  Fit  9 =  0.805    6   82  103  114
 Slid>  Fit 10 =  0.805    6   23   83   90
 Slid>  Fit 11 =  0.800    6   82   90   99
 Slid>  Fit 12 =  0.800    6   23   61   90
 Slid>  Fit 13 =  0.800   55   82   90  114
 Slid>  Fit 14 =  0.800    6   82   90  122
 Slid>  Fit 15 =  0.800    6   82   90  108
 Slid>  Fit 16 =  0.800    6   38   83   90
 Slid>  Fit 17 =  0.800    6   82   90  112
 Slid>  Fit 18 =  0.800    6   82   90  103
 Slid>  Fit 19 =  0.800   26   82   90  114
 Slid>  Fit 20 =  0.800    6   80   90  124
 Slid>  Fit 21 =  0.795    6   23   83  114
 Slid>  Fit 22 =  0.795   33   80   90  114
 Slid>  Fit 23 =  0.795    6   80   92  114
 Slid>  Fit 24 =  0.795    6   23   63   90
 Slid>  Fit 25 =  0.795    6   38   61   90
 Slid>  Fit 26 =  0.791    6   23   61  114
 Slid>  Fit 27 =  0.791    6   82   90  125
 Slid>  Fit 28 =  0.791    6   38   83  114
 Slid>  Fit 29 =  0.791    6   23   29   59
 Slid>  Fit 30 =  0.791   28   82   90  114
  O > {\bf no}
\end{verbatim}

Now the correct answer does not show in the top 30!
%---
\subsection{Slider\_lego} \index{Slider\_lego}

People are often unsure about the size of a particular amino acid. 
\index{amino acid, size}
This makes it rather difficult to make guess when one sees density. Even
for experts, it helps to concentrate the mind to see which ones could
actually fit. It is necessary to have built at least a poly-alanine before
this command works. Then the first time one ID's an atom, 2 knobs get
activated so that one controls which amino acid type gets displayed and one
controls the rotamer for that residue type. If the Poly-alanine does not
point into the density, then the side chain will not fit into the
density. Making further ID's, transfers the activity to the new residue.

At present, some of the commands are a bit dumb when it comes to accepting
the results. Future releases will have enhanced functionality in
{\bf Slider\_combine} and {\bf Slider\_lego}.

%---
\subsection{Datablocks Used}

{\tt .slider\_integer}, {\tt .slider\_real}, {\tt .slider\_matrix} should
\index{.slider\_integer} \index{.slider\_real} \index{.slider\_matrix}
not be of interest to anyone.  The slider matrix is read in as a formatted
T type data block. The first line contains the one letter symbolic names,
then each following line scores how the amino acids are matched to the
symbolic residue name.


%%% utility %%%

\section {Utilities} 

This menu is a collection of utility programs that generate database
blocks that may be of some interest to the user. Values generated in these
datablocks can be used for colouring or for selection purposes.

%---
\subsection{Pep\_flip} \index{Pep\_flip}
\syntax{pep\_flip [id two atoms] or [mol res1 res2]}
This command allows the user to locate peptide conformations that are
unusual. The technique has been described by Jones {\em et
al.} \cite{jones91} and will not be repeated here. If the database of
structures has not been loaded, then it will be loaded before carrying out
the calculation. It must, therefore, be properly defined in {\bf
Lego\_setup}. The command makes a residue property called {\tt
[mol]\_residue\_pepflip}. \index{\_residue\_pepflip}

Example:

\begin{verbatim} 
 O > {\bf pep\_flip a a1 a20}
 Util>  Calculating zone A1  to A20    in molecule A     , object C
 Util>  The DB is now being loaded.
 Util>  Loading data for protein:HCAC
 Util>  Loading data for protein:PA
 Util>  Loading data for protein:51C_3
 Util>  Loading data for protein:ACT_2
 Util>  Loading data for protein:APP_2
 Util>  Loading data for protein:AZA_1
 Util>  Loading data for protein:B5C_2
 Util>  Loading data for protein:BP2_1
 Util>  Loading data for protein:C2C_3
 Util>  Loading data for protein:CPA_5
 Util>  Loading data for protein:CPV_1
 Util>  Loading data for protein:CRN_1
 Util>  Loading data for protein:CYT_4
 Util>  Loading data for protein:DFR_3
 Util>  Loading data for protein:ECD_1
 Util>  Loading data for protein:FB4_1
 Util>  Loading data for protein:FDX_1
 Util>  Loading data for protein:FXN_3
 Util>  Loading data for protein:HIP_1
 Util>  Loading data for protein:INS_1
 Util>  Loading data for protein:LH1_1
 Util>  Loading data for protein:MBO_1
 Util>  Loading data for protein:NXB_1
 Util>  Loading data for protein:OVO_1
 Util>  Loading data for protein:PCY_1
 Util>  Loading data for protein:PPT_1
 Util>  Loading data for protein:PTI_4
 Util>  Loading data for protein:PTN_2
 Util>  Loading data for protein:REI_1
 Util>  Loading data for protein:RHD_1
 Util>  Loading data for protein:SGA_2
 Util>  Loading data for protein:SN3_1
 Util>  Loading data for protein:SNS_2
 Util>  Loading data for protein:TLN_3
 Util>  Residue A3     has a pep_flip r.m.s. value of    1.43
 Util>  Residue A4     has a pep_flip r.m.s. value of    0.41
 Util>  Residue A5     has a pep_flip r.m.s. value of    2.54
 Util>  Residue A6     has a pep_flip r.m.s. value of    1.56
 Util>  Residue A7     has a pep_flip r.m.s. value of    0.54
 Util>  Residue A8     has a pep_flip r.m.s. value of    0.69
 Util>  Residue A9     has a pep_flip r.m.s. value of    0.40
 Util>  Residue A10    has a pep_flip r.m.s. value of    0.70
 Util>  Residue A11    has a pep_flip r.m.s. value of    0.83
 Util>  Residue A12    has a pep_flip r.m.s. value of    0.50
 Util>  Residue A13    has a pep_flip r.m.s. value of    0.96
 Util>  Residue A14    has a pep_flip r.m.s. value of    0.97
 Util>  Residue A15    has a pep_flip r.m.s. value of    1.96
 Util>  Residue A16    has a pep_flip r.m.s. value of    1.53
 Util>  Residue A17    has a pep_flip r.m.s. value of    0.67
 Util>  Residue A18    has a pep_flip r.m.s. value of    0.33
 Util>  Residue A19    has a pep_flip r.m.s. value of    0.81
 Util>  Residue A20    has a pep_flip r.m.s. value of    0.23
  O > {\bf dir a\_*pep*}
 Heap>  A_RESIDUE_PEPFLIP         R W       132
 O >
\end{verbatim} 

%---
\subsection{RS\_fit} \index{RS\_fit} \index{real space correlation}
\syntax{rs\_fit [id two atoms] or [mol res1 res2]}
This command allows one to evaluate how well the molecule fits the density
on a per residue basis as desribed by Jones {\em et al.} \cite{jones91}. This
implementation differs by outputting the correlation coefficient between the
model fragment and the map. This function takes values between -1 and
1. The program generates a residue property {\tt
[mol]\_residue\_rsfit} that can be used for colouring and selection
\index{\_residue\_rsfit}
purposes.  The user is free to decide which atoms in each residue
contribute to determining the residue fit by loading a suitable table into
the database. This table contains an entry for each amino acid type
describing what atoms are to be used in the calculation. The following
example is part of {\tt \$ODAT/rsfit\_mc.o} and would be used if one wanted
only main chain atoms in the calculation: \index{rsfit\_mc.o}

\begin{verbatim} 
rsfit_PHE             T         1        70
N   CA  C   O   CB
rsfit_PRO             T         1        70
N   CA  C   O   CB
rsfit_SER             T         1        70
N   CA  C   O   CB
\end{verbatim}

In the {\tt \$ODAT} directory, files also exist for only side chain atoms
 ({\tt rsfit\_sc.o}) and
all atoms ({\tt rsfit\_all.o}).  The first time through, the program
prompts for the map, otherwise the map is defined in {\bf RSR\_map}. The
\index{RSR\_map} \index{rsfit\_all.o}
calculation is carried out 5 residues at a time. The following example is
edited a bit to reduce output.

\begin{verbatim}
 O > {\bf rs\_fit a a1 a20}
 Util> A     A1    A20   C
 Util>  Calculating zone A1     to A20    in molecule A    , object C
 Util>   42 atoms in zone
 Util>  File_RSR_map is not defined.
 Util> Enter file name [ rsr.map]: {\bf ano1.map}
 Util> Map centre:    46.05  55.49  20.79
 Util> Grid origin:    29   37    8
 Util> Grid extent:    17   17   18
 Util>  Plus value for this map is:    0
 Util>     6 atoms for residue A1    correlation= 0.501
 Util>     8 atoms for residue A2    correlation= 0.466
 Util>     9 atoms for residue A3    correlation= 0.454
 Util>    11 atoms for residue A4    correlation= 0.690
 Util>     8 atoms for residue A5    correlation= 0.726
 Util>     4 atoms for residue A6    correlation= 0.742
 Util>     7 atoms for residue A7    correlation= 0.590
 Util>    14 atoms for residue A8    correlation= 0.780
 Util>     9 atoms for residue A9    correlation= 0.594
 Util>     8 atoms for residue A10   correlation= 0.722
 Util>     7 atoms for residue A11   correlation= 0.643
 Util>     6 atoms for residue A12   correlation= 0.507
 Util>     6 atoms for residue A13   correlation= 0.504
 Util>     9 atoms for residue A14   correlation= 0.534
 Util>     8 atoms for residue A15   correlation= 0.594
 Util>    11 atoms for residue A16   correlation= 0.440
 Util>     8 atoms for residue A17   correlation= 0.638
 Util>     9 atoms for residue A18   correlation= 0.503
 Util>    12 atoms for residue A19   correlation= 0.512
 Util>     8 atoms for residue A20   correlation= 0.607
 Util>  *** garbage collecting ***
  O > {\bf dir a\_*rsfit*}
 Heap>  A_RESIDUE_RSFIT           R W       132
\end{verbatim}

\label{rsfit}
In the calculation of the real space fit of structures to electron density
maps (command {\bf Rs\_fit}) \mbox{\bf O}'s default values for the parameters
{\bf A(o)} and $C$ may not result in correlation coefficients with optimal
discrimination between good and bad electron density fit. Since these
parameters covary, there are multiple ways to obtain the desired result. In
practice, $A_{o}$ can be set to 0.9, and $C$ varied between 0.6 and 1.2 in
steps of 0.05. Selection of the value of $C$ which gives the highest
correlation coeffcient for a residue with good electron density fit should
also give the largest difference between the correlation coefficients of
residues with good and bad density fit. The default value of $C$ = 1.04 has
worked well for maps in the 1.7--1.9\AA\ range, while a value of 0.82 was
better for a map at 2.4\AA\ resolution.  In a future version of the
program, it will be possible to refine these values. \index{real space fit}

%---
\subsection{YASSPA} 
\syntax{yasspa [molecule] [template] [cutoff distance]}
An option to define the secondary structure of a protein, given a set of CA
coordinates.  The template molecule {\em must} reside in the users
database. It is normally supplied in the {\tt \$ODAT} directory as an \mbox{\bf O}
type file. Current templates are {\tt alpha.o} and {\tt beta.o}
\index{alpha.o} \index{beta.o}
corresponding to alpha-helices and beta-strands. These coordinates
are the central members of a cluster analysis (Jones, unpublished) using a
0.5\AA\ cutoff (the default value to YASSPA). To define alpha-helices
use this 0.5\AA\ cutoff. For beta-strands use 0.8\AA\ (this is because
beta-strands show more deviation from the central cluster). If it does not
exist, The option creates a residue property {\tt
[mol]\_residue\_2ry\_struc}. The
\index{\_residue\_2ry\_struc}
following example colours a molecule depending on secondary structure:

\begin{verbatim} 
mol a
yasspa a alpha 0.5
yasspa a beta 0.8
pain_prop res_2ry = ' '   yellow
pain_prop res_2ry = alpha red
pain_prop res_2ry = beta  green
ca ; end
\end{verbatim} 

%---
\subsection {RSC\_fit} \index{RSC\_fit}
\syntax{rsc\_fit [id 2 atoms] or [mol res1 res2]}
This option compares the users side chain coordinates with the rotamer
library. It finds which rotamer is most like the users conformation and
evaluates the r.m.s. deviation of the side chain atoms after superimposing
the main chain atoms. These values are stored in a datablock {\tt
[mol]\_residue\_rsc}. The location of the side chain rotamer database
\index{\_residue\_rsc}
must have been defined with the {\bf Lego\_setup} command.
\index{Lego\_setup}

The following side chains are treated specially: Phe's \& Tyr's CHI2s are
changed by 180 degrees. CD1\&2 and CE1\&2, Asp's CHI2 and Glu's CHI3 are
changed by 180 degrees to force equivalence of carboxylate oxygens.

%---
\subsection{EZD\_map}  \index{EZD\_map} \index{EZD map format}
\syntax{ezd\_map [keyword data](i)}
This is a formatted electron density file. The keywords define the origin,
extent, grid, cell constants, scaling, and the density.  The order is not
important, but the values must be on the same line, except for the density
data. The density is read/written by a block matrix operation

\begin{verbatim} 
(((ed(i,j,k),i=1,nx),j=1,ny),k=1,nz) 
\end{verbatim}

with 7 density values on a line. The density is divided by the scale
constant. Since the denity file includes the \mbox{\bf O} keyword, this command is
always actived as if the file were a macro:

\begin{verbatim} 
%{\bf  cat chop.ezd} 
EZD_map
! Created by ODALISQUE V-920917/2.5
! At Mon Sep 21 13:21:16 1992
CELL 40.090 47.390 69.340 90.000 90.000 90.000
ORIGIN 42 -21 -11
EXTENT 33 27 17
GRID 80 80 80
SCALE 1000.000
MAP
35. -122. -293. -340. -245. -138. -135.
-210. -248. -175. -26. 108. 162. 124.
16. -123. -244. -289. -215. -43. 131.
200. 126. -36. -202. -311. -322. -210.
....
....
-426. -73. 486. 779. 483. -208. -687.
-504. 160. 666. 600. 218. 127. 557.
1074. 1081. 487. -223. -556. -472. -273.
-169. -112. -18. 30. -107. -380.
END
\end{verbatim}

In O, this map would be read in

\begin{verbatim} 
O > {\bf @chop.ezd} 
\end{verbatim} 

%---
\subsection{EZD\_draw}  \index{EZD\_draw}
\syntax{ezd\_draw [level] [colour]}
The command contours the last read in EZD file at the desired level,
creating an object with lines of the desired colour. All of the EZD map is
contoured. Entering a [CR] for the level results in contouring at the s
level of the map. The following example would contour at the sigma level,
creating a blue object:

\begin{verbatim} 
O > {\bf ezd\_dr ; sky\_blue} 
\end{verbatim} 


%%% mask %%%

\section {Mask Commands} \index{mask editing} \index{envelope}

This menu contains commands for editing an existing mask.  Molecules
frequently crystallize in space groups where there are more than one
molecule in the asymmetric unit. This can be used to advantage by averaging
the electron density. One requirement for this is the creation of a volume
containing the non-crystallographic asymmetric unit, called the mask. The
user is encouraged to read the paper \cite{jones92} to get an overview of
averaging but also to read the original literature.

Once a mask file has been generated, it can be edited in \mbox{\bf O} with some of
the {\bf Mask} menu commands. The commands available give complete control
over the final shape of the mask.

%---
\subsection{Mask\_setup} \index{Mask\_setup}
\syntax{mask\_setup [value set, value displayed]
		    [set radius, display radius] 
                    [contour radius]
                    [contour colour]}
Setting a pixel point on, associates the value 1 with that point. This
command allows the user to decide if the mask is to be shaved, or
expanded. When the mask is being edited, it appears as a grid of
dots. These dots can either represent mask on or off, depending on what the
user defines in {\bf Mask\_setup}. Radii are used to control the volume in
which editing takes place, the volume to be displayed as dots, and the
radius within which the mask can be contoured with {\bf Mask\_contour}. The
contoured mask can of course have a user definable colour.

%---
\subsection{Mask\_read}  \index{Mask\_read}
\syntax{mask\_read [file name]}
This commands reads in a mask from the external file system. Only one
mask is stored in \mbox{\bf O} at a time, so an earlier mask is over-written.
From version 5.9.2, \mbox{\bf O} can read a number of different mask formats:
old \mbox{\bf O} mask format, {\tt MAMA} compressed format, and compressed or
explicit OMASK format. Masks can be generated by a number of external
programs, {\tt MAMA}, {\tt Bones\_mask} or {\tt Pdb\_mask}.

%---
\subsection{Mask\_write}  \index{Mask\_write}
\syntax{mask\_write [file name]}
This command writes out the current mask to the file system, in OMASK compressed
format.

%---
\subsection{Mask\_off} \index{Mask\_off}
\syntax{mask\_off [id an atom]}
This command allows a user to travel through the mask to inspect it. The
mask appears as a set of green points, either at pixels where the mask is
on or off, depending on the last {\bf Mask\_setup}. The identified atom
moves under the control of the dials.

%---
\subsection{Mask\_on}  \index{Mask\_on}
\syntax{mask\_off [id an atom]}
This command allows a user to edit a mask. As the atom moves, pixel points
within a specified radius get set to a particular value. Both these values
are set by {\bf Mask\_setup}.

%---
\subsection{Mask\_contour} \index{Mask\_contour}
\syntax{mask\_contour}
This command allows a user to display a wire contour view of the current
mask. The centre is the current active centre.

%---
\subsection{Mask\_object} \index{Mask\_object}
\syntax{mask\_object [Object name]}
This command allows one to define the name of the object that is created by the
{\bf Mask\_contour} command.

%---
\subsection{Examples} 

The use of the existing commands is illustrated by the following example
(user input is high-lighted):

\begin{verbatim} 
 O > {\bf mask\_read}
Mask> File name of mask to be read: {\bf m12a.mask} 
Mask> Parameters as read from the mask file:
Mask> Grid .................       100       110        64
Mask> Origin ...............        31        45         8
Mask> Extent ...............        48        53        61
Mask> Cell axes ............     91.80     99.50     56.50
Mask> Cell angles ..........     90.00     90.00     90.00
Mask> Mask read OK.
Mask>   33221 points set in mask
Mask>  155184 points total
 O > {\bf mask\_setup} 
Mask> Mask value to set \& display [ 1 1]: 1 0
Mask> Radius in which pixels are set \& displayed [ 1.0 8.0]:{\bf  2. 9.} 
Mask> Radius in which to contour [ 10.0]:
Mask> Contour colour? [red]:
 O  > {\bf mask\_on}
 O  > {\bf mask\_off}
 O  > {\bf mask\_contour}
 O  > {\bf mask\_write}
Mask> File name of mask to be written: {\bf m12a\_edit.mask}
 O > 
\end{verbatim} 

The {\bf Mask\_read} and {\bf Mask\_write} commands read and write out mask
files. Only one mask file can be stored at a time (at present).
The {\bf Mask\_setup} command set parameters used with the {\bf Mask\_on} and
{\bf Mask\_off} commands that control what will be displayed and how the mask is
to be edited. In the above example, both {\bf Mask\_on} and {\bf Mask\_off}
will display non-mask grid points within 10\AA\ of a moving atom as dots. When
editing is set `on' by the {\bf Mask\_on} command, points 1.0\AA\ from the
moving atom will be set as lying within the mask. This will have the affect
of erasing the dots drawn on the display. The setup values used here are,
therefore, suitable for detecting holes in the mask and for removing them.

The commands {\bf Mask\_on} and {\bf Mask\_off} start the display of the
mask. Both commands require the user to identify an atom that can be moved
around in space. Dots will appear that represent grid points either within
or outside the mask depending on the values set with {\bf Mask\_setup}. If
{\bf Mask\_off} is active, then as the atom is moved around, the mask object
is updated but the mask is not changed. When {\bf Mask\_on} is active, the
mask gets changed and grid points within the specified radius are reset,
according to the {\bf Mask\_setup} values. Activating {\bf Mask\_on},
deactivates {\bf Mask\_off} and {\em vice versa}. When either command is
active, {\bf Mask\_setup} can be activated to change the current values.

%---
\subsection{Datablocks}

Most parameters in the {\tt .mask\_*} datablocks are set by the {\bf
Mask\_setup} command. Perhaps the first entry in {\tt .mask\_c6} could be of
interest to some.

\begin{itemize}
\item {\tt .mask\_c6} \index{.mask\_c6}
  \begin{description} 
  \item [1  The mask object name (6 bytes). If more mask objects are 
  wanted on the display, change the mask object name, and draw the new mask.]
  \item [2--5  Colour of the mask (24 bytes).]
  \item [6--15 Input file name (60 bytes).]
  \item [16--25 Output file name (60 bytes)]
  \end{description}
\end{itemize}

%%% molrep %%%

\section{MolRep -- Molecular Replacement} \index{MolRep} 
	\index{Molecular Replacement}

This major menu is meant as an aid when solving a structure using
Molecular Replacement. At present, two commands are available in the menu,
but additional features are planned, and will appear in a future
release. As usual, there is a setup command where different parameters can
be defined. The idea of this menu is not to solve a Molecular Replacement
problem, but to be able to quickly check solutions suggested by other
programs.

The idea of Molecular Replacement is that you have an known structure that
you are trying to replace in the data of the unknown structure. Structure
factors are calculated from the coordinates of the known structure,
generally in a cubic unit cell. If your known structure has not been placed
in an orthogonal system (or higher) you have to be extremely careful, as
the different programs use different conventions for transforming from
fractional to orthogonal \AA. X-PLOR, uses the same orthogonalization
convention as \mbox{\bf O} and PDB, but Merlot uses a different one.

%---
\subsection{MR\_setup} \index{MR\_setup}
\syntax{mr\_setup [program name] [unit cell]}
Set up parameters. Angle convention, 
%(only X-PLOR has been debugged), 
and the unit cell of the {\em unknown} structure.

% use verbatim to move a bit left for space
\begin{verbatim}  
 O > mr_set
MR> Angle convention? [X-PLOR]:
MR> Define unit cell of unknown [42.70 41.70 73.00 90.00 104.60 90.00]:
\end{verbatim} 

%---
\subsection{MR\_rt}  \index{MR\_rt}
\syntax{mr\_rt [search mol] [initial rotation] 
	[initial translation]}
When this command is activated, the user is asked to identify an atom in
the molecule that is going to be rotated/translated. When that is done, the
user can input initial values for the eulerean angles. These are given in
degrees. The initial translation can be given in fractional \AA.

The dials then become active, and the eulerian angles and fractional
translation can be dialed in. The current values are shown on the
screen. The {\bf Yes} command will apply the transformation operator to the
coordinates, and the {\bf No} command will keep the original
coordinates. If you accept the new coordinates, and reactivate {\bf MR\_rt},
the eulerian angles will be relative to the newly accepted coordinates, so
be careful.

\begin{verbatim} 
  O > {\bf mr\_rt}
  O >  MR> Angle convention: {\bf X-PLOR}
 MR> Search molecule: {\bf HCAC}
 MR> Object: {\bf HCAC}
 MR> Define initial eulerian angles [ 315.60 39.60 0.00]: {\bf 0 0 0}
 MR> Define initial translation (fractional) [ 0.00 0.00 0.00]:
 MR> Dials are now active...
  O >
  O > {\bf no}
 MR> Original coordinates restored.
  O >
\end{verbatim} 



%%% trace %%%

\section{Trace Commands} \index{Trace commands}

These commands are extensions of the {\bf Bones} menu are designed to aid
in electron density map interpretation. Most of the commands act as
filters, taking one skeleton and generating another, usually with different
connectivity or some moved atoms. One command, {\bf Baton\_build}, is a tool for
rapidly building guide CA coordinates.
\index{skeleton filters}

%---
\subsection{Baton\_build}  \index{Baton\_build}
\syntax{Baton\_build [mol] [start residue] [direction]
	[manipulate Baton]}
This command is used to build a CA trace. It uses a measuring stick in the
form of a di-peptide which can be moved around and can be pivoted about one
end. The baton is actually a di-peptide from which the user must make an
object of a single bond between the CA atoms before using this
command. When the command is activated, the di-peptide object appears at
the current screen centre and consists of a single split coloured bond. The
dial set can be used to translate the di-peptide object, and to pivot the
object around the green atom. When {\bf Yes} is activated, the coordinates
of the {\em red\/} residue are taken and written into the molecule that is being
contructed. The baton jumps to this new position and the process can be
repeated until the command is cleared with {\bf No}. If an object called
{\tt CA} exists, it will be updated after each {\bf Yes} command.

%This command overcomes one of the problems associated with using the {\bf
%Bone\_pick\_Ca} command where long or short inter-CA separations can be
%produced. 
One of the problems associated with the {\bf Bone\_Ca\_Id} command, where
long or short inter-CA separations can be produced, is overcome by using
{\bf Baton\_build}. \index{Bone\_Ca\_Id}
After approxmately 5 pivots of the baton, it may be necessary to use
the translation dials again to get the di-peptide and the density back in
register. The command can be used to build the whole structure, but is
particularly useful for building difficult loopy bits that the other {\bf
Trace} commands have had problems with. Since the di-peptide is in fact a
poly-alanine, the {\bf Slider\_lego} command can be used to check out side
\index{Slider\_lego}
chain sizes.

The position and orientation of the di-peptide can be changed by the {\bf
Baton\_mode} command when {\bf Baton\_build} is active. When the {\bf No}
or {\bf Clear\_flag} commands are activated, this option activates {\bf
Lego\_auto\_mc} and {\bf Lego\_auto\_sc} to construct both main and side
chains from the CA trace that has been generated.

Examples: Before using the command, information for the di-peptide must be
in the users database. A database file {\tt di.o} is supplied and can be
added by

\begin{verbatim} 
O> read di.o
\end{verbatim} 

The user must then create the di-peptide object by

\begin{verbatim} 
O> mol di ca ; end
\end{verbatim} 

The {\bf Baton\_build}  command can then be used.

The position and orientation of the di-peptide can be changed by the
{\bf Baton\_mode} command when {\bf Baton\_build} is active. When the {\bf No}
or {\bf Clear\_flag} commands are activated, this option activates
{\bf Lego\_auto\_mc} and {\bf Lego\_auto\_sc} to construct both main and side
chains from the CA trace that has been generated. 

%---
\subsection{Baton\_mode} \index{Baton\_mode}
\syntax{baton\_mode [option]}

This command controls the orientation and position of the di-peptide when
{\bf Baton\_build} is active. If the mode setting is {\tt alpha}, the
coordinates of the last 4 CA atoms are taken and a least squares comparison
made with a regular alpha-helix. The di-peptide is then placed in the
position of the 4th and 5th residues of the helix. If the mode is {\tt
beta}, the comparison is made with residues from a regular
beta-strand. If the mode is {\tt 2ry}, a comparison is made with both
alpha and beta structures, and the one closest to the last 4
residues is used to position the di-peptide. In all three modes, if 4
residues have not been built, the mode defaults to a `standard' orientation
for the peptide. This can also be achieved by defining mode {\tt ?} or any
other non-recognized character string. 

The option may also be the name of a skeleton molecule. The program uses
the current connectivity of this molecule to place one end of the
di-peptide on a line joining 2 bones atoms, if these atoms exist. If more
than one pair of atoms exists, the program creates a list of
suggestions. Multiple calls to this command cause the peptide to be placed
at different positions within this list. The order of items in the list is
determined by the bones status of the pair of skeleton atoms; pairs of
class 1 atoms first, followed by pairs of non-class 2, followed by mixed
2/other etc., and by the direction of building. This option, therefore,
makes it easy to follow a skeleton or to build standard secondary structure
elements, or anything in-between.

%---
\subsection{Trace\_setup}  \index{Trace\_setup}
\syntax{trace\_setup [unmodified skeleton] [modified skeleton]}
This command defines the two skeletons used in the filter operations. One
skeleton is the input to the filter, the other is an output or a
modification of an existing skeleton.

%---
\subsection{Trace\_prune} \index{Trace\_prune}
\syntax{trace\_prune}
This command takes an existing skeleton and modifes its connectivity so
that only bones atoms with branch points (i.e. with at least 3 bonds) can be
seen. This means that if the connection between two branch point bones
consisted of a number of short bonds, they are replaced by just one bond
between the two atoms. The pruning action greatly simplifies the skeleton
and often allows the user to recognise structural features. If the density
lacks branching features, the pruned skeleton will have very long
connections, and some long connections in the original skeleton may be
missing.

The command is intended as a step towards building a skeleton which ends up
closely resembling a CA trace.

%---
\subsection{Trace\_fill\_Ca} \index{Trace\_fill\_Ca} 
\syntax{trace\_fill\_ca}
This command needs both an input and output skeleton. For those atoms in a
pruned skeleton that are too far apart for a pair of connected CA atoms,
extra atoms will be filled in between them at the correct separation. The
filled in atoms will follow the connections of the input skeleton, and the
new atoms will be exisitng atoms from that skeleton.

%---
\subsection{Bone\_prune}
\index{Bone\_prune}
\syntax{bone\_prune [Id 2 atoms]}
This command attempts to create a tentative CA trace. It modifies the
connectivity of all atoms linking the 2 identified atoms, to more closely
resemble a CA trace. The two end-point atoms are kept, as are all atoms
containing a branch. Connections from/to other atoms are removed if the
distance to the last tentative CA atom is less than 3.8 \AA. When an atom
is found to be more than 3.8\AA\ from the last tentative CA, it is shifted
to make a more exact separation. Any remaining short separations between
tentative CA atoms are flagged in an object called {\tt WARN}.

%---
\subsection{Bone\_excise} \index{Bone\_excise}
\syntax{bone\_excise [Id 2 atoms]} 
All bonds connecting the 2 identified atoms are broken, and replaced by a
single direct bond. The atoms must be in the same skeleton molecule.

%---
\subsection{Bone\_branch} \index{Bone\_branch}
\syntax{bone\_branch [Id an atom]}
An atom will be added to the object of the identified atom, connected to
this atom but displaced (0.5, 0.5, 0.5)\AA. It will be given the
status code 2 (which usually specifies a side chain) and will initially
appear as a white bond (this will change to the users specified colour when
the next object is created). This command is useful to indicate the desired
position for a CA atom when a branch point is lacking. It can also
be used to extend a skeleton from a loose end (via repeated {\bf
Bone\_branch} and {\bf Move\_atom} commands).

%---
\subsection{Bone\_undo} \index{Bone\_undo}
\syntax{bone\_undo}
This command restores the connectivity prior to the last {\bf Bone\_break}
or {\bf Bone\_prune} operation. Only one level of undo is maintained. 
{\em Any objects that may exist will have to be remade by the user}.

%%% chapter4 %%%

\chapter{An O Tutorial.} \label{ch-tutorial} 

\section {Example 1: Getting started with a set of coordinates}

One can access the database information on an ESV or SGI in a number of
different ways:.

\begin{enumerate}
\item Define the directory explicitly e.g. {\tt 
/usr/people/alwyn/o/data/menu.o}, 

\item Use a soft link by issuing the following before starting the program
\begin{verbatim} 
% link -s /usr/people/alwyn/o/data odat 
\end{verbatim} 
Then in the program one would use {\tt menu.o},

\item Use an environment parameter. Set it by
\begin{verbatim} 
% setenv ODAT /usr/people/alwyn/o/data/ 
\end{verbatim} 
Then in the program one would merely specify {\tt menu.o}.  Provided {\tt
menu.o} did not exist in the current directory, it would then come from the
correct place.  

\item Set up the directory name in the user database in the
datablock {\tt .odat}. Read in the following datablock 
\begin{verbatim} 
.odat T 1 40
/usr/people/alwyn/o/data/
\end{verbatim} 
Then in the program  one would merely specify {\tt menu.o}
\end{enumerate}

In the following, user input is written in boldface. 

\begin{verbatim} 
% ono
 O > Use of this program implies acceptance of conditions
 O > described in Appendix 1 of the O manual
 O > O version 5.9.1 , Fri Jul 30 14:36:38 MET DST
 O > Define an O file (terminate with blank): {\bf startup.o} 
 O > File is formatted
 O > Define an O file (terminate with blank): {\bf menu.o} 
 O > File is formatted
 O > Define an O file (terminate with blank): 
 O > File_display_connectivity is not defined.
 O > Enter file name [ o.dat] :
Maximum inter-residue link distance = 6.00
There were   22 residues
            113 atoms
 O > Do you want to use the display? [Y]/N 
\end{verbatim} 

Read in coords for 2 chains, call them A and B

\begin{verbatim} 
 O > {\bf sam\_at\_in} 
Sam>Name of input file: {\bf m17\_a.wah} 
Sam>O associated molecule name : {\bf a} 
Sam>Type of coordinates assumed from file name. 
Sam>Is that O.K. ? ([Y]/N)
Sam>Is it Wayne s format ([Y]/N) ?
Sam>Are there any S-S bridges (Y/[N]) ? 
 O > {\bf sam\_at\_in}   
Sam>Name of input file: {\bf m17\_b.wah} 
Sam>O associated molecule name : {\bf b} 
Sam>Type of coordinates assumed from file name.
Sam>Is that O.K. ? ([Y]/N)
Sam>Is it Wayne s format ([Y]/N) ?
Sam>Are there any S-S bridges (Y/[N]) ?
 O > {\bf dir a*} 
Heap>A_ATOM_XYZ	R W 3162 
Heap>A_ATOM_B	I W 1054 
Heap>A_ATOM_Z	I W 1054 
Heap>A_ATOM_NAME	C W 1054 
Heap>A_ATOM_WT	R W 1054 
Heap>A_RESIDUE_NAME	C W  132 
Heap>A_RESIDUE_TYPE	C W  132 
Heap>A_RESIDUE_POINTERS	I W  264 
Heap>A_RESIDUE_CG	R W  528 
 O > {\bf save} 
As1> File_O_save is not defined. 
As1> Enter file name [ binary.o] :
\end{verbatim} 

Make an object from molecule a

\begin{verbatim} 
 O >{\bf  mol} 
 O > Current molecule has not been loaded.
Mol> Molecule code name []: {\bf a} 
 O > {\bf ca} 
Mol> Ca zone [all molecule]:
 O > {\bf end}   
\end{verbatim} 

That could all have been done in one line:

\begin{verbatim} 
 O > {\bf mol a ca ; end} 
\end{verbatim} 

Centre it on the fatty acid

\begin{verbatim} 
 O > {\bf cen\_atom} 
As3> Define molecule [A     ], residue, and atom [CA] : {\bf a132 c5} 
\end{verbatim} 

Believe me , it did centre. Now make an object with the fatty acid too

\begin{verbatim} 
 O > {\bf ca ; zon a132 ; end} 
\end{verbatim} 

Note the use of `;' in the above line. Make another object with those
residues close to the fatty acid:

\begin{verbatim} 
 O > {\bf obj sph\_a cover a132 ; 2.5 end} 
\end{verbatim}

After activating {\bf On\_off}, we can click the objects on and off... Now,
make mol b...

\begin{verbatim}
 O > {\bf mol b ca ; z b132 end}   
Mol> Second residue not in molecule 
\end{verbatim}

Notice the error in the last line. It was trying to find a second residue in
the zone called {\tt end}. Add the desired zone with

\begin{verbatim}
 O >{\bf  z b132 ; end}  
\end{verbatim}

 Now compare molecules A and B

\begin{verbatim}
 O > {\bf lsq\_ex} 
Lsq >Lsq definition defaults are taken. 
Lsq >Least squares match by explicit definition of atoms.
Lsq >Given 2 molecules A,B the transformation rotates B onto A
Lsq >What is the name of A (the not rotated molecule) ? {\bf a} 
Lsq >What is the name of B (the rotated molecule) ? {\bf b} 
Lsq >Now define what atoms in A are to be matched to B.
Lsq >Defining 3 names in A implies a zone and an atom name.
Lsq >Defining 2 names in A implies a zone and CA atoms.
Lsq >Defining 1 name in A implies the CA of that residue.
Lsq >The B molecule requires just the start residue.
Lsq >A blank line terminates input.
Lsq >Define atoms from A (the not rotated molecule) : {\bf a1 a131} 
Lsq >Define atoms from  B (the rotated molecule) : {\bf b1} 
Lsq >Define atoms from A (the not rotated molecule) :
Lsq >The   131 atoms have an r.m.s. fit of     0.614 
Lsq >xyz(1) =     0.3866*x+    0.0907*y+    0.9178*z+  -16.9487 
Lsq >xyz(2) =     0.1155*x+    0.9826*y+   -0.1458*z+   25.7526 
Lsq >xyz(3) =    -0.9150*x+    0.1624*y+    0.3694*z+   66.9966 
Lsq >The transformation can be stored in O. 
Lsq >A blank is taken to mean do not store anything 
Lsq >The transformation will be stored in .LSQ_RT_ {\bf b\_to\_a} 
 O > {\bf lsq\_obj} 
Lsq >Apply a transformation to an existing object. 
Lsq >There is an alignment called B_TO_A 
Lsq >Which alignment [<CR>=restore a transformed object] ? {\bf b\_to\_a} 
Lsq >There is an object called A 
Lsq >There is an object called SPH_A 
Lsq >There is an object called B 
Lsq >Which object ? {\bf b} 
\end{verbatim}

Now they are on top of each other, we can identify them

\begin{verbatim}
 O > {\bf lsq\_obj ; b} 
\end{verbatim}
 
That removed them. Do a deliberate mistake in {\bf LSQ}:

\begin{verbatim}
 O > {\bf lsq\_e} 
Lsq >Lsq definition defaults are taken. 
Lsq >Least squares match by explicit definition of atoms.
Lsq >Given 2 molecules A,B the transformation rotates B onto A
Lsq >What is the name of A (the not rotated molecule) ? {\bf a} 
Lsq >What is the name of B (the rotated molecule) ? {\bf b} 
Lsq >Now define what atoms in A are to be matched to B.
Lsq >Defining 3 names in A implies a zone and an atom name.
Lsq >Defining 2 names in A implies a zone and CA atoms.
Lsq >Defining 1 name in A implies the CA of that residue.
Lsq >The B molecule requires just the start residue.
Lsq >A blank line terminates input.
Lsq >Define atoms from A (the not rotated molecule) : {\bf a1 a125} 
Lsq >Define atoms from  B (the rotated molecule) : {\bf b5} 
Lsq >Define atoms from A (the not rotated molecule) :
Lsq >The   125 atoms have an r.m.s. fit of    11.038 
Lsq >xyz(1) =     0.2809*x+    0.0037*y+    0.9597*z+   -8.7543 
Lsq >xyz(2) =     0.2134*x+    0.9747*y+   -0.0662*z+   16.6426 
Lsq >xyz(3) =    -0.9357*x+    0.2234*y+    0.2730*z+   69.5881 
Lsq >The transformation can be stored in O. 
Lsq >A blank is taken to mean do not store anything 
Lsq >The transformation will be stored in .LSQ_RT_{\bf b\_to\_a} 
 O >{\bf  lsq\_i} 
Lsq >Least squares match by Semi Automatic Alignment. 
Lsq >There is an alignment called B_TO_A 
Lsq >Given 2 molecules A,B the transformation rotates B onto A 
Lsq >What is the name of molecule A [A     ]?
Lsq >Zone to look for alignment [all molecule A] :
Lsq >What is the name of molecule B [B     ]?
Lsq >Zone to look for alignment [all molecule B] :
Lsq >What atom [CA] ?
Lsq >Number of atoms in A/B to look for alignment   131  131
Lsq >Search for connected fragments.
Lsq >A fragment of   131    1    1 residues located. 
Lsq >Loop =    1 ,r.m.s. fit =     0.614 with   131 atoms 
Lsq >x(1) =     0.3866*x+    0.0907*y+    0.9178*z+  -16.9487 
Lsq >x(2) =     0.1155*x+    0.9826*y+   -0.1458*z+   25.7526 
Lsq >x(3) =    -0.9150*x+    0.1624*y+    0.3694*z+   66.9966 
Lsq >Search for connected fragments. 
Lsq >A fragment of   131    1    1 residues located. 
Lsq >Loop =    2 ,r.m.s. fit =     0.614 with   131 atoms 
Lsq >x(1) =     0.3866*x+    0.0907*y+    0.9178*z+  -16.9487 
Lsq >x(2) =     0.1155*x+    0.9826*y+   -0.1458*z+   25.7526 
Lsq >x(3) =    -0.9150*x+    0.1624*y+    0.3694*z+   66.9966 
Lsq >The transformation can be stored in O. 
Lsq >A blank is taken to mean do not store anything 
Lsq >The transformation will be stored in .LSQ_RT_ {\bf b\_to\_a} 
Lsq >Here are the fragments used in the alignment 
Lsq >    A1 SNKFLGTWKLVSSENFDEYMKALGVGLATRKLGNLAKPRVIISKKGDIIT 
Lsq >    B1 SNKFLGTWKLVSSENFDEYMKALGVGLATRKLGNLAKPRVIISKKGDIIT 
Lsq >   A51 IRTESPFKNTEISFKLGQEFEETTADNRKTKSTVTLARGSLNQVQKWNGN 
Lsq >   B51 IRTESPFKNTEISFKLGQEFEETTADNRKTKSTVTLARGSLNQVQKWNGN 
Lsq >  A101 ETTIKRKLVDGKMVVECKMKDVVCTRIYEKV   A131 
Lsq >  B101 ETTIKRKLVDGKMVVECKMKDVVCTRIYEKV   B131 
\end{verbatim}

See it worked

\begin{verbatim}
 O > {\bf lsq\_pair} 
Lsq >There is an matched pair called B_TO_A 
Lsq >Object state ([ON],OFF) : {\bf on} 
\end{verbatim}

That shows some little arrows between matched atoms

\begin{verbatim}
 O > stop 
%
\end{verbatim}

This ends the session. Next time \mbox{\bf O} is started up, you don't need to specify
the {\tt startup.o} and {\tt menu.o} files.

\section {Example 2: Colouring the molecule}

Some simple painting examples. It assumes that an object has been created
at least once from the molecule. This is because the program forces the
creation of a set of default colouring parameters (if they do not exist)
once the first object is being drawn. Otherwise it is necessary to make an
atom property of the correct name and length.

\begin{verbatim} 
 O > {\bf dir *xyz}   
 Heap> A_ATOM_XYZ           R W    3162
 O > {\bf dir a*} 
 Heap> A_ATOM_COLOUR        I W    1054
 Heap> A_ATOM_XYZ           R W    3162
 Heap> A_ATOM_B	            R W    1054
 Heap> A_ATOM_WT            R W    1054
 Heap> A_ATOM_Z             I W    1054
 Heap> A_ATOM_NAME          C W    1054
 Heap> A_RESIDUE_NAME       C W     132
 Heap> A_RESIDUE_TYPE       C W     132
 Heap> A_RESIDUE_POINTERS   I W     264
 Heap> A_RESIDUE_CG         R W     528
\end{verbatim}

The above shows there are 132 residues and 1054 atoms in molecule A. Note
that an atomic property {\tt a\_atom\_colour} already exists.

\begin{verbatim}
 O > {\bf paint\_colour lime\_green} 
 O > {\bf paint\_prop}   
Pnt> Property [atom_name]:{\bf atom\_z}
Pnt> Operator (< > <= >= ^= [=]):{\bf  =}
Pnt> Value:{\bf 6} 
Pnt> Colour [lime_green]:{\bf yellow} 
\end{verbatim}

The next line does the same thing

\begin{verbatim}
 O > {\bf pai\_prop atom\_z = 6 yellow} 
\end{verbatim}

Paint all carbons that are CA's white

\begin{verbatim}
 O > {\bf paint\_prop atom\_name = ca white} 
 O > {\bf z ; end} 
\end{verbatim}
 
Believe me, the CA's are white and the rest are yellow. Now make the Phe
residue light blue

\begin{verbatim}
 O > {\bf pai\_pr residue\_type = phe sky\_blue } 
 O > {\bf z ; end} 
 O > {\bf paint} 
 O >  PAINT is not a unique keyword.
 O >  Paint_proper is a possibility.
 O >  Paint_ramp   is a possibility.
 O >  Paint_case   is a possibility.
 O >  Paint_zone   is a possibility.
 O >  Paint_select is a possibility.
 O >  Paint_object is a possibility.
 O >  Paint_obj_zo is a possibility.
 O >  Paint_obj_at is a possibility.
 O >  Paint_colour is a possibility.
 O >  PAINT        is not a visible command.
\end{verbatim}

Notice we now have an atom property called {\tt atom\_z}. Let's now use it
to set everything to standard colours

\begin{verbatim} 
 O > {\bf pai\_case} 
Pnt>  Colour-case a property in molecule A
Pnt> Property [atom_z] :{\bf atom\_z} 
Pnt> How many cases [8]?{\bf 4} 
Pnt> Enter property values [1 2 3 4] :{\bf 6 7 8 16} 
Pnt> Enter 4 colour names :{\bf 
} Pnt> Colour [sky_blue]: {\bf yellow} 
Pnt> Colour [yellow]: {\bf blue} 
Pnt> Colour [blue]: {\bf red} 
Pnt> Colour [rede]: {\bf green} 
 O >{\bf  z ; end} 
\end{verbatim}

Paint by internal residue count


\begin{verbatim}
 O > {\bf pain\_ramp} 
 Pnt>  Colour-ramp a property in molecule A
Pnt> Property [residue_irc]:{\bf residue\_irc} 
Pnt> Minimum and maximum value of property [1 132] :{\bf 1 131} 
Pnt> First colour [red]:{\bf blue} 
Pnt> First colour [blue]:{\bf red} 
 O > obj ca ca ; end
\end{verbatim}

Now there is an object called {\tt CA} that is a rainbow of colours, blue at
the N-terminal and red at the C-terminal. If you wanted it to go blue to
red without passing through yellow and green etc, then you have to specify
the first colour as blue with a bit of red

\begin{verbatim} 
Pnt> First colour [red]:{\bf 1 0 255} 
Pnt> First colour [red]:{\bf red} 
\end{verbatim}

This is because of how we do the ramping, using the {\bf HSV } colouring
model. Blue comes out at 360 degrees, while (1,0,255) comes out close to 0
degrees.

\begin{verbatim}
 O > {\bf stop} 
\end{verbatim}


 
\section {Example 3: Using skeletons}

This example illustrates the use of skeletons and generating the necessary
datablocks for a new molecule from its sequence.

\begin{verbatim} 
  O > {\bf bone} 
  O >  BONE         is not a unique keyword.
  O >  Bone_setup   is a possibility.
  O >  Bone_select  is a possibility.
  O >  Bone_redefin is a possibility.
  O >  Bone_pick_Ca is a possibility.
  O >  Bone_repeat  is a possibility.
  O >  Bone_skip    is a possibility.
  O >  Bone_break_b is a possibility.
  O >  Bone_make_bo is a possibility.
  O >  BONE         is not a visible command.
  O > {\bf bone\_setup} 
 Bone> Skeleton name []:{\bf ano1}  
 Bone> Object name []:{\bf 100A} 
 Bone>Sphere radius [    0.0 ]:{\bf 100.} 
 Bone>What bone levels? [ 1 ]:{\bf 1 3}
  O > {\bf bone\_select}
  O > {\bf dir ano1*} 
 Heap> ANO1_ATOM_XYZ            R W     19959
 Heap> ANO1_ATOM_BONE           I W      6653
 Heap> ANO1_CONNECTIVITY        I W      7393
 Heap> ANO1_ATOM_COLOUR         I W      6653
 Heap> ANO1_RESIDUE_NAME        C W         1
 Heap> ANO1_RESIDUE_TYPE        C W         1
 Heap> ANO1_RESIDUE_POINTERS    I W         2
 Heap> ANO1_ATOM_SELECT         I W      6653
\end{verbatim} 

Activate a macro, its contents will be listed

\begin{verbatim}
  O> {\bf @skl\_100a.dat} 
bone_setup ano1 bone1 100.    1  3 ; 
centre_id wait_id
bone_select
  O >
  O > {\bf bone\_break} 
 Bone> Object 100A   re-drawn.
 Bone> Object BONE1  re-drawn.
  O >{\bf  del 100a ;} 
  O > {\bf @../macros/bones\_20a.macro}  
\end{verbatim} 

Select all bones atoms of type 1, 2 \& 3 within 20A of an Id'ed atom. This
creates an atomic object called {\tt 20a}, chosing skeleton atoms from bones
molecule `ano1'.

\begin{verbatim} 
bone_setup ano1 20a 20.    1 2 3 ; 
centre_id wait_id
bone_select
\end{verbatim}

Now create empty datablocks for a molecule of P2 myelin.
Read in the sequence from an external file:

\begin{verbatim}
  O > {\bf read p2\_sequence.o} 
\end{verbatim}

That was a single datablock describing the P2 sequence
with a molecule named NEW.

\begin{verbatim}
  O >{\bf  sam\_init } 
 Sam> This WILL initialise certain datablocks.
 Sam> Molecule name ([] to exit) : {\bf new} 
 Sam> Database compressed.
 Sam> Making residue names.
 Sam> There are   131 residues,   647 atoms.
 \end{verbatim}

Make an object called {\tt CA}, it will get updated as you
use {\bf Bone\_Ca\_Id}. The residues have names 1, 2, 3, etc.,
because we did not supply a datablock of names:

\begin{verbatim}
  O > {\bf mol new obj ca ; end}
  O >{\bf  bone\_ca\_id}
  ...
  ...
  O > {\bf stop}
\end{verbatim}

\section {Example 4: Customizing the screen menu}

First list all menus, then add menu 1 and 14 to the screen:

\begin{verbatim} 
 O > {\bf menu} 
 As2> ? gives list of menu names
 As2> Major menu? (<cr> = refresh){\bf ?} 
 As2> Available menus:
 As2>   Assorted_1    Draw_Mol      O_heap_1      Sketch
 As2>   Lsq_align     Assorted_2    Map           Slider
 As2>   Refi          Lego          Manip         Bones
 As2>   Macro_2       Assorted_3    Sam           RSR
 As2>   O_heap_2      Paint_mol
 As2>   Trig          Assorted_4    Select        Symmetry
 As2>   Plot          Sequence      Utility       Patterson
 As2>   Mutate        Mask          Odalisque     Autobuild
 As2>   Mol_replace   Object_1      Object_2      Object_3
 As2>   Object_4      Object_5
 O >
 O > {\bf menu ass\_3 ;;} 
 O > {\bf write .menu junk.o ;} 
 O > {\bf $ cat junk.o} 
.MENU                    T        19        12
Centre_ID   
Terminal_ID 
Wait_ID     
Stop        
Yes         
No          
Clear_flags 
Save_DB     
Id_reset    
Centre_atom 
Centre_Xyz  
Backup_DB   
Message     
Macro       
Draw_object 
Dial_last   
Dial_next   
Rotate_pictu
CPK_object  
 O > {\bf $ vi junk.o} 
\end{verbatim} 

Here we edit the file, deleting some of the menu items. Notice that the
number of lines in the datablock header must be changed, too. After
editing, the file looks like this:


\begin{verbatim} 
 O > {\bf $ cat junk.o} 
.MENU                    T        9        12
Centre_ID   
Stop        
Yes         
No          
Clear_flags 
Save_DB     
Id_reset    
Dial_last   
Dial_next   
\end{verbatim}

Read the {\tt .menu} datablock back into the database, and redraw the menu:

\begin{verbatim} 
 O > {\bf read junk.o} 
 O > {\bf menu ;} 
 O > 
\end{verbatim} 

%%% how_to %%%

\chapter {How to \ldots}   \label{ch-howto}

\section {How to Colour atoms} 

We define the default colours used in \mbox{\bf O} with the names used by the
X-window system. A full listing can be produced by issuing the following
command
\begin{verbatim} 
paint_colo ?
\end{verbatim} 

The default red/green/blue name and mixtures are taken from Xlib
Programming Manual, written by A.Nye, published by O'Reilly \&Associates,
page 185.

Colouring of atoms in \mbox{\bf O} is controlled by the {\bf Paint} commands.  If
the user does not specify any colouring, the program decides itself that
you want to see atom colouring (i.e. based on the atomic number of the
atom) using a particular set of colours.

Some commands affect an object that has already been created. This implies
that some colour has already been used in the object creation
creation. These object oriented commands ({\bf Paint\_object}, {\bf
Paint\_obj\_zon}, {\bf Paint\_obj\_atom}) re-colour the object with the colour
currently specified in the data-base as a colour code in the datablock
{\tt .active\_colour}. This can be reset with the {\bf Paint\_colour} command.

The other {\bf Paint} commands modify a datablock that is an atomic
property associated with a particular molecule. This property is called
{\tt a27\_atom\_colour} for a molecule called a27. If it does not exist,
it will be created by the program with default colours. This datablock
contains integer colouring codes, the RGB triplets are packed into a byte
each. When a new molecular object is created (i.e. at the moment the {\bf
End\_object } command is issued), the atoms are coloured with whatever is
defined in the data block.

Skeleton atoms are in practise treated a bit differently. Their status
codes are mapped to the colours defined in the datablock {\tt
.bones\_colour} (they can also be {\bf Paint}'ed but don't confuse
yourself).


\section {How to Change the values in a datablock} 

The contents of datablocks can be changed interactively with several
commands, for example {\bf Db\_set\_data}, {\bf Db\_set\_zone} and {\bf
Db\_set\_atom}.  However, we recommend a different approach unless you
really know what you are doing. A safer method is to write the datablock
out into the computer file-system (use {\bf Write\_formatted}), edit it with
your favourite editor, and read it back in again (use {\bf
Read\_formatted}). Note that formatted data blocks are read back under
formatted control!

\section {How to Read in external data from own programs} \label{sec-read-external}

Create formatted datasets that can be read by {\bf Read\_formatted}. 
The first line contains:

[data block name] [data\_block\_type] [number\_items] 
[format]

The data block name must be less or equal to 25 characters and not contain
spaces. The data block type can be T, C, R, or I. If the type is T then the
number of items is the number of lines of text and the format is the number
of characters on a line,otherwise it really is the number of items and the
FORTRAN style format.  For example {\tt p1 i 5 (5i2)} or {\tt p2 t 5 72}
are both O.K. specifying integer and text data, respectively.
Subsequent lines contain the information, as specified in the format
statement or the line count.

\section {How to move a map file from a VAX to a workstation} 

Maps for use with \mbox{\bf O} can also be made with {\bf amappage} (an old program,
much abused by many over the years, and distributed with FRODO) running on
a VAX,and then transferred to the workstation with ftp. Here is an
example, where the user is logged on the workstation (an ESV say)

\begin{verbatim} 
% {\bf ftp xray}
\ldots
 ftp> {\bf cd [.work]}
 ftp> {\bf binary}
 ftp> {\bf get m14\_f21.map}
 ftp> {\bf quit}
% {\bf /user/alwyn/o/bin/es\_swapbytes}
 brick file{\bf : m14\_f21.map}
\end{verbatim} 

\section {How do I get my skeleton to my workstation?} 

The skeleton has to be made with the program bones. It can be run on any
sort of computer or directly on the workstation since the \mbox{\bf O} style file
produced is a formatted file. It can then be read into the user database
when starting the program or with the {\bf Read\_formatted} command.

\section{How do I build a complete molecule from a set of CA atoms?} 

Frequently, people deposit just CA atoms, and you may need a molecule
containing all of the atoms. This is easy to do in \mbox{\bf O} but many people do it
wrong. Suppose the CA coordinates are in a file {\tt ca.pdb} which has the
correct sequence and consists of residues 1-365. Start \mbox{\bf O} and do the
following:

\begin{verbatim} 
s_a_i  ca.pdb ca
copy all_residue_type ca_residue_type
s_init all
merge ca 1 365 all 1 ;
leg_aut_mc all 1 365
leg_aut_sc all 2 364
\end{verbatim} 

This will create everything from residue 2 to 364 with the side chains
taking up the most common rotamer. Use {\bf Baton\_build} to make the first and
last residue.

\section{How to rescue a corrupted database?}

If (heaven forbid) your \mbox{\bf O} database is corrupted such that you cannot read
it in at the start of a new session, don't give up hope! Start \mbox{\bf O} from
scratch and then do the following

\begin{verbatim} 
O > sam\_atom_in old_db.o
\end{verbatim} 

This will read in your database as far as it can. If the main point is to
save a particular molecule or skeleton, then use {\bf Sam\_at\_out} or {\bf
Write\_formatted}. Then start the program again from scratch and carry on
working.

%%% cryst_model %%%

\chapter{Crystallographic model building}

The strategy used to build structures with \mbox{\bf O} \cite{jones91}
will not be repeated here. Copies of the publication are available. The
user requires a minimum of 3 files:

\begin{enumerate}
\item {\bf An electron density map}.  At present this must be a special file
created with the mappage program. You can use the {\bf Frodo} map file
(defined with the DSN6 command) created on a Vax if you follow the example
in chapter \ref{ch-howto}. The version of {\bf Frodo } distributed by Dr. Phil
Evans uses a different structure for this map and is not at present
supported.

Our file is a binary, direct access file that is created by a program with
the generic name {\tt mappage}. A version of this program is included with the
distribution tape in {\tt export\_source}. This program can read in protein, CCP4,
X-PLOR, FFT-Y maps. On the Unix workstations, we do not have Protein
running at present so we have been unable to check if the program works.

The mappage distributed with X-PLOR produces standard files but works only
on the VAX. It is a much abused version of the original program and should
be burned.

If the map is made on a VAX and needs to be transferred to a UNIX machine,
use Ftp with the binary option. Then run {\tt swapbytes} on the UNIX machine.

\item {\bf A skeletonized electron density}.
This is a 3 step procedure run in the one program bones; namely make the
actual skeletonization, assign the main chain/side chain status codes,
output an \mbox{\bf O} style formatted data structures. The program needs a level and
step value. The step value can be the standard deviation of the map. The
base level may need some experimentation. Too low a value produces too many
bones atoms and becomes confusing. Too high a value gives too few. Try 1.25
sigma to start.  The program handles the same maps as {\tt mappage}.

\item {\bf A sequence}.
The user must prepare the sequence in a form suitable for input to \mbox{\bf O},
i.e. a formatted datablock. This describes the residue property {\tt
\_residue\_type} of the molecule to be built. The option {\bf
Sam\_init\_db} will then generate the rest of the datablocks. If you want
to use your own names for each residue then also load in a property {\tt
\_residue\_name}. Remember that both datablocks will be read in under
format control and must be left justified. See the tutorial for detailed
use.  This will be simplified in a future release, allowing one to read in
the sequence from external databases.

\end{enumerate}

%%% odl %%%

\chapter {General Drawing Instructions} \label{ch-ODL}

This chapter explains the design of the \mbox{\bf O} graphics descriptor language,
that can be used to draw anything on the screen, using primitives such as
move to, line to, sphere etc.

\section {The syntax of the O graphics descriptor language}

The \mbox{\bf O} graphic descriptor language can be used to draw anything the user
wants. In fact, some of the pictures generated by \mbox{\bf O} are done via the
graphics descriptors, e.g. the CPK models. The picture must be defined in
terms of a number of drawing instruction, that are saved in a text
datablock. The contents of this text datablock can the be drawn on the
screen using the command {\bf Draw\_object}.  The current list of
recognised instructions is as follows:

\begin {description}
   \item [begin\_object] [name] -- start object with give name

   \item [end\_object] - end current object

   \item [colour] [value] -- name (e.g. red) or packed integer
defining a new colour

   \item [line\_type]  [type] -- character value 
(dashed, solid, dotted, dash\_dot)

   \item [move]  [$x, y, z$] -- moveto (x, y, z)
 
   \item [line] [$x, y, z$] -- lineto (x, y, z)

   \item [move\_atom] [mol residue atom] -- move to (x, y, z) of the atom

   \item [line\_atom] [mol residue atom] -- line to (x, y, z) of the atom

   \item [dot] [ x, y, z] -- place dot at (x, y, z)

   \item [text] [x y z string] -- place text string at (x, y, z)

   \item [text\_size] [value] -- real value 0 \verb|->| 1.0, 
(small \verb|->| large)

   \item [text\_colour] [integer value] -- name (e.g. red) or 
packed integer defining a new colour

%%%\item [light] [value(3)] -- 3 real numbers 0 $\rightarrow$ 1, 
%%%light colour

%%%\item [Surf\_mode] [mode] [value(2)] -- 2 integers, 
%%%reflectance and shading method 

%%%\item {\bf Surf\_property } {\em props(5)} -- 5 reals defining the surface

   \item [poly] [number of vertices] [vertex](i) -- polygon using
current colour

   \item [poly\_colour] [colour] -- Set the polygon colour

%%%\item [Poly\_property]	 --- Integers to define the polygon properties

   \item [instance] [object] [datablock] -- Object to be instanced 
and datablock containing tranformation.

   \item [sphere\_atom] [mol res atom radius colour] -- sphere 
at coords mol/residue/atom with radius and colour

   \item [sphere\_xyz] [$x, y, z$ radius] -- sphere 
at coords $x ,y, z$ with the given radius.

   \item [stick] [mol res atm] [mol res atm] [radius] --
Draw a solid stick between 2 atoms, with given radius.

   \item [stick\_xyz]  [$x1, y1, z1$] [$x2, y2, z2$]
[radius] -- Draw a solid stick between two points in space, with the
given radius.

   \item [mode] [solid/line] -- Set the solid or line drawing mode.

   \item[cell] [cell parameters] -- Set the crystallographic unit cell
for the following commands.

   \item[fmove] [$x, y, z$] -- Move to (x, y, z), given in
fractional coordinates.

   \item[fline] [$x, y, z$] -- Line to (x, y, z), given in
fractional coordinates.

   \item[ftext] [x y z string] -- place text string at (x, y, z),
given in fractional coordinates.

\end{description}



\section {Using the Draw\_object command}  

This command allows one to draw objects that you have created. It can be
used for many different things. We find it useful for drawing the unit cell
(editing a database entry created by {\bf Symm\_cell } to include heavy atom
sites for example), for leaving little messages during map interpretation,
adding special, non-standard bonds {\em etc, etc}.

Quite complicated objects can be created, showing for example, 
non-crystallographic masks, or virus capsids.


%%% assoc_progs %%%

\chapter{Associated programs}  

Some data can be produced on computers other than the graphics workstation
and later used with \mbox{\bf O}.

\section {bones} \label{sec-bones}

Convert an electron density file into a skeleton with an \mbox{\bf O} data
structure. This is a formatted data structure so if the calculation is run
on a VAX, it can be ftp'ed and read into your Unix machine when starting
\mbox{\bf O} or with the {\bf Read\_formatted} command.

In the example, we define a start level approximately 1.3 sigma, and a step of
sigma. It is also necessary to decide what skeleton atoms are to be
classified as main chain and side chain. This is done by defining a minimum
connection length of 8. The user also specifies the molecule name to be
associated with the skeleton. The resulting file is formatted. The
following output has been edited to remove CCP4 excess listings.

\begin{verbatim} 
%{\bf ../bin/bones} 
 electron density file name: {\bf ano1.E} 
 map type ([ccp4]) : {\bf ccp4} 
 base level and step level for skeletonising : {\bf .020 .015} 
 Fourier parameters as read from the data-set
          Origin ................................    0    0    0
          Extent ................................   76   84   48
          Grid ..................................   76   84   48
          uvw (fast, medium, slow) ..............    Z    X    Y

          base level .......................................   0.020
          level increment ..................................   0.015
          number of levels .................................       5

 input map contains 24242 points (level>0)
 skeletonized map contains  7698 points (level>0)
no. of points in the bones : 7798( including spare points)
                     no. of spare points        :     100
                     no. of connections         :    8349
                     no. of branch-points       :    1058
                     no. of fragments
                                    size .le.  1 :  372
                                    size .le.  5 :  790
                                    size .le. 10 :   24
                                    size .le. 50 :   56
                                    size .le.100 :    6
                                    size .gt.100 :    4

 Length to define skeleton as main chain :{\bf 8} 
                     minimum mainchain lenght     :       8
                     no. of mainchain connections :    3875
                     no. of sidechain connections :    4473
 O Bones file name :{\bf q\_skl.o} 
  Histogram of bones types 1,2,3....
  Bone Type:     1  3893  3804   100     0     0     0     0     0  
 Associated O name:{\bf ano1} 
vega [36]# {\bf grep ANO1 q\_skl.o}
ANO1_ATOM_XYZ             R     23394 (3f10.3)
ANO1_ATOM_BONE            I      7798 (5i10)
ANO1_CONNECTIVITY         I      8349 (5i10)
ANO1_ATOM_COLOUR          I      7798 (5i10)
ANO1_RESIDUE_NAME         C         1 (5a)
ANO1_RESIDUE_TYPE         C         1 (5a)
ANO1_RESIDUE_POINTERS     I         2 (5i10)
vega [37]#
\end{verbatim} 


\section {mappage} \label{sec-mappage}

Creates a standard electron density file from external file
formats. Example of reading in a CCP4 map. It has been edited to remove
excess CCP4 listings.

\begin{verbatim} 
%{\bf ../bin/mappage}
          *** Mappage program ****
Input map name from your crystallographic system:{\bf ano1.E}
O style map name:{\bf q.map} 

 Fourier parameters as read from the data-set
          Origin ................................    0    0    0
          Extent ................................   76   84   48
          Grid ..................................   76   84   48
          uvw (fast, medium, slow) ..............    Z    X    Y

Do you wish to explicitly define Prod/Plus (y,[n])?{\bf n} 
Cell constants ....................  91.800  99.500  56.500  90.000  90
.000  90.000
Fourier type ......................N
Number of pages along x , y \& z    10   11    6

 Byte =    327.670 * density +         18
vega [32]# {\bf di q.map}
-rw-r-----   1 alwyn    oteam     394752 Dec 15 15:48 q.map
vega [33]#
\end{verbatim} 

Notice the program decided on the prod and plus values. These numbers are
to force the floating point number into a byte (i.e. an integer with values
1-255) via

\begin{verbatim} 
byte\_value = density\_value * prod + plus
\end{verbatim}

Any values outside the range are truncated. The {\em plus} value is therefore
important when negative values are to be contoured, and the {\em prod} values is
important for scaling.

\section {Brix --- yet another map paging program...} \label{sec-brix}
\index{brix}

{\tt Brix} is a program (Still Another!) to convert different formats of electron
density maps to \mbox{\bf O} format. {\tt Brix} was written to circumvent the problems of
fixed array boundaries, and allocates the memory it needs on the fly.
Thus, you are only limited by the virtual memory of the computer.

{\tt Brix} writes a new un-swapped version of the DSN6 file, independent of
endianism issues. Thus, you can use a bricked density file which has been
calculated on an ALPHA machine on a SGI. Also, the new format contains more
information in the header, most notably the SIGMA value of the map. Thus,
in your map macros, you will be able to put a `;' where you normally
specify the contouring level, to get a 1 sigma contouring.

The new bricked electron density format is understood by versions of \mbox{\bf O}
later than 5.9.2.

However, {\tt Brix} will still calculate the old, unportable, DSN6 format, if the
program is invoked under the name {\tt mappage} (uh, actually, it only needs to
*contain* the word mappage, so {\tt 4d\_mappage} is OK). In other words, you can
install a symbolic link (or normal link): \index{mappage}

\begin{verbatim}
% ln -s brix mappage
\end{verbatim}

and then run the {\tt mappage} version.

{\tt Brix} understands the following map formats: X-PLOR (formatted), CCP4, TNT
and EZD, it will automagically determine which format the map is, and allocate
the right amount of memory. It will also automatically slice the map correctly.

Here is a sample session of {\tt Brix}. The only input needed is the names of the
input map and the output brick file; these can be given on the command line:

\begin{verbatim}
kaktus 395% brix /xtal/morten/xplor/type3/m10.xmap  m10.omap
 brix> Convert ED maps to O format
 brix> Version 1.1, Nov 1993
 brix>
 brix> Mapfile: /xtal/morten/xplor/type3/m10.xmap
 brix> O brick file: m10.omap
 brix> ...file is formatted
 brix>
 brix> Map type is X-PLOR
 brix>
 brix> Parameters as read from the map file:
 brix> Grid .................        80        80       192
 brix> Origin ...............         6       -21        24
 brix> Extent ...............        75       105        76
 brix> Fast, medium, slow....         1         2         3
 brix> Cell axes ............     69.90     69.90    161.80
 brix> Cell angles ..........     90.00     90.00     90.00
 brix>
 brix> Reslicing XYZ --> YXZ
 brix> Fast, medium, slow....         2         1         3
 brix> Min, max, sigma ......  -4.53080   7.12510   0.98377
 brix> Scale ................     1.000
 brix>
 brix> Prod .................  21.87733
 brix> Plus .................        99
 brix> Bricks along x,y,z ...        10        14        10
kaktus 396%
\end{verbatim}

TNT maps do not store the cell parameters, so in that case the user will be 
prompted for the missing information.

\section{The averaging programs --- A} 

\index{averaging} \index{density modification} \index{A programs}
This \mbox{\bf O} has a number of programs that can be used for averaging electron
density maps. This describes just 2 of them {\tt bones\_mask} and {\tt
average}. More information is contained in the paper \cite{jones92}. A new
system of programs, RAVE \cite{kleiywegt93}, \index{RAVE} has been
developed from the A programs, and is available from the authors. In
particular, it improves on the mask handling and allows one to average
between different space groups.

To carry out averaging, one need a mask surrounding the object that forms
the non-crystallographic asymmetric unit. The unit contained in this mask
is the origin defining molecule. The mask can be made from skeleton atoms
in \mbox{\bf O} by the {\bf Bones\_mask} command. There is also a program {\bf
Pdb\_mask} to make it from a coordinate dataset.

One useful way of making the mask is to select one skeleton atom, roughly
in the middle of the molecule and generate a spherical mask from it using a
fairly large radius. This mask can then be edited with a simple macro such
that every skeleton atom that is identified, adds a small volume to the
mask. Such a macro would look like \index{mask, from skeleton}

\begin{verbatim} 
mask_set 1 1 3. 3. 8. red
mask_on centre_id wait_id
yes mask_contour
\end{verbatim} 

and would zap pixel points within 3\AA\ of the identified atom, contouring
within 8\AA. This process by-passes the tedious process of painting the
skeleton atoms to the desired colours.

The programs also need a set of transformation operators to describe the
non-crystallographic symmetry. These operators are applied to the points in
the mask of the origin molecule, to bring them into the related
molecule. If our origin molecule is called A, and the others are B and C,
we therfore need transformations A \verb|->| B and A \verb|->| C. 
These can come from \mbox{\bf O} and must be in \mbox{\bf O} datablocks.

The number of grid points along the axes must correspond to the values in
the electron density map. \index{bones\_mask}

\begin{verbatim} 
vega [39]# {\bf ../bin/bones\_mask} 
File name of mask datablock :{\bf ano1\_mask.o} 
Data block name :ANO1_MASK
Number of values   498
Unit cell constants :{\bf 91.8 99.5 56.5 90. 90. 90.} 
Number of grid points along each axis:{\bf 76 84 48}
    28.00004       37.93949       10.32552       3.000000
    57.00026       66.58566       43.87030       3.000000
Enter file name of transformation datablock :{\bf unit\_rt.o} 
  Data block name : {\bf unit\_rt}
  Mask atoms     498
  Origin          25     34      7
  Extent          36     37     41
  Grid            76     84     48
  RT operator   1.00000   0.00000   0.00000
  RT operator   0.00000   1.00000   0.00000
  RT operator   0.00000   0.00000   1.00000
  RT operator   0.00000   0.00000   0.00000
 Enter file name of transformation datablock :
 Enter file name of mask to written out:{\bf q.mask}
\end{verbatim} 

Any number of operators could have been defined. We just used the unit
transformation.

Now it can be averaged. One need the space group operators in \mbox{\bf O} database
format. The following is edited to remove CCP4 verbosity. \index{average}

\begin{verbatim} 
vega [40]# {\bf ../bin/average} 
Map a: {\bf ano1.E} 
 Read header.
 Fourier parameters as read from the data-set
          Origin ................................    0    0    0
          Extent ................................   76   84   48
          Grid ..................................   76   84   48
          uvw (fast, medium, slow) ..............    Z    X    Y

  Header done.
  Map read OK.
Map b mask: {\bf q.mask}
  Reading Mask.
  Mask read OK.
  Number of points in mask 13559
New averaged map (a CCP4 map): {\bf qq.E}
Expand map ([Y]/N) ? {\bf y} 
 Enter file name of space group operators (O style) :{\bf symmop.o} 
  Data block name :A_SYMMOP
Enter file name of transformation datablock (<cr> to quit) :{\bf unit\_rt.o} 
  Data block name :unit_rt
Enter file name of transformation datablock (<cr> to quit) :{\bf a\_to\_b.o} 
  Data block name :.LSQ_RT_A_TO_B
Enter file name of transformation datablock (<cr> to quit) :{\bf a\_to\_c.o} 
  Data block name :.LSQ_RT_A_TO_C
Enter file name of transformation datablock (<cr> to quit) :
 Average.
 Expand.
 Average in solvent=  -0.598989E-03
 Average in map    =   0.489301E-08

 Minimum density in map  = -0.04697   
 Maximum density         =  0.05885   
 Mean density            =  0.00000
 Rms deviation from mean =  0.01074

  Map written out.
vega [43]#
\end{verbatim} 

If one enters ``n'' to the expand prompt, one gets just the averaged map within
the same envelope as the mask. The expanded map fills up the same envelope
as the input map. The non-molecule grid points are set to a constant value
to make the average in the map equal to 0.0.

\section{mkcol} \label{sec-mkcol} \index{mkcol}

This is a Unix script to help generate \mbox{\bf O} datablocks of colour codes. In \mbox{\bf O},
the user is free to associate red-green-blue (RGB) mixes with colour
names. This program takes a file of RGB mixes and names, and outputs a file
containing 2 \mbox{\bf O} datablocks. The script is useful if you want to add or
remove colours, or to load up colours supported by your own X system:

\begin{verbatim} 
% {\bf /usr/bin/X11/showrgb \verb|>| rgb.txt}
% {\bf cat rgb.txt}
220 220 220          gainsboro
240 255 240          honeydew
255 228 225          mistyrose
112 128 144          slategrey
135 206 235          skyblue
176 196 222          light steel blue
224 255 255          lightcyan
 50 205  50          limegreen
154 205  50          yellowgreen
        [Output edited]
% {\bf mkcol rgb.txt \verb|>| rgb.} 
% {\bf cat rgb.o}
.colour_names t 224 12
alice_blue
aliceblue
antique_white
             [Output edited]
white
white_smoke
whitesmoke
yellow
yellow_green
yellowgreen
.colour_rgb r 672 (3f7.4)
 0.9412 0.9725 1.0000
 0.9412 0.9725 1.0000
 0.9804 0.9216 0.8431
    [Ouput edited]
 0.2510 0.8784 0.8157
 0.9333 0.5098 0.9333
%
\end{verbatim}


\section{dispcol} \label{sec-dispcol} \index{dispcol} \index{colours, available}

This is a Unix script to show you what all these colours correspond to on
your display. It takes a file of RGB colour names and creates a file of
\mbox{\bf O} draw commands that can be later displayed with the draw command.

\begin{verbatim}
Example:
% {\bf dispcol rgb.txt \verb|>| rgb\_obj.o} 
% {\bf cat rgb\_obj.o} 
begin coltst
text_colour alice_blue
text   -10.0     5.8 0.0 alice_blue
text_colour aliceblue
text   -10.0     5.6 0.0 aliceblue
text_colour antique_white
text   -10.0     5.4 0.0 antique_white
      [Output edited]
text_colour yellow
text     0.5    -1.8 0.0 yellow
text_colour yellow_green
text     0.5    -2.0 0.0 yellow_green
text_colour yellowgreen
text     0.5    -2.2 0.0 yellowgreen
end_object
%
\end{verbatim} 

In \mbox{\bf O} you would use the 2 files produced in the above examples by
issuing the following commands after starting \mbox{\bf O}:

\begin{verbatim} 
 O> {\bf read rgb.o}
 O> {\bf dra rgb\_obj.o} 
 O> {\bf cen\_xyz 0. 0. 0.} 
\end{verbatim} 

There should be a text object drawn with different colours. 

%%% oplot %%%

\section {oplot} \label{sec-oplot} \index{oplot} \index{plotting}

{\bf Oplot} is 3 dimensional object plotting program, giving the user full
control over the viewing parameters.  {\bf Oplot} reads a description of the
objects to be plotted on standard input, and produces a PostScript file on
standard output. In particular, {\bf oplot} will convert an plot output file from
\mbox{\bf O} to {\sc PostScript} format. However, the program is not specifically
intended for \mbox{\bf O}, but is generally applicable.  Command line options are

\begin{description}
\item [-z Set depth cueing on, so that lines closer to the viewer are 
drawn with thicker lines.]

\item [-f Draw a frame around the picture]

\item [-v Verbose mode. Output some information on the creation of
objects. Much more than you need. Probably only useful for debugging.]

\item [-r Print the revision level of the program, and exit.]

\item [-g GhostScript mode. Make a black background in the viewport, 
assuming the output plot is in colour, and will be viewed with ghostscript 
or some other previewer.]

\item [-b Black and white mode. All colour settings are ignored, 
and everything is drawn with black.]
\end{description}

If an input file name is given, oplot will read from that file, instead of
standard input.

\begin{verbatim} 
oplot < mola.plt > mola.ps

oplot -f  mola.plt > tmp ; gs tmp
\end{verbatim} 
%---
\subsection {The oplot output} \index{oplot output}

Version 5.9 of \mbox{\bf O} generates its plot metafiles in {\bf oplot} format, and
consequently, the strategy for generating Plots from \mbox{\bf O} has changed.  You
start by choosing {\bf Plot\_on}. This sets a flag internally in the
program, which causes all drawing instructions, which would normally go to
the graphics subsystem, to also be dumped to a file. All objects created in
\mbox{\bf O} from now on are dumped to the file, which grows very
quickly. Therefore, to ensure that you do not forget that {\bf Plot\_on} is
active, the dials have been deactivated. When the required objects have
been drawn to the screen, {\bf Plot\_off} is selected; this closes the plot
metafile, and reactivates the dials.

The template name of the plot metafile is defined in {\bf Plot\_setup}, and it
can optionally contain a format string, which is replaced by an integer
that is incremented by 1 each time a new plot is initiated.

For making Quick n' Dirty plots, the {\bf Plot} command can be used.  It
is restricted in several ways. It ONLY plots molecules and maps, and
colours are not used.

%Currently, maps and molecules get the SAME Z-thickening parameters, but
%this will change in future versions of oplot.

%---
\subsection {Hints for plotting with \mbox{\bf O}} 
It is also possible to make side-by-side stereo plots, and to plot the
screen menu. These options are chosen in the {\bf Plot\_setup} menu. The
parameters defining the stereo are in the last few lines of the \mbox{\bf O}
meta-file. The way this is done is to display the root object ({\tt disp\_all})
in the left viewport, then change the point of view slightly, and display
it again in the right viewport. The left and right viewports can overlap on
the paper, and you may have to play with these values to get things
right. The maximum viewports has a dimension of 1 in both directions, so
the plotting area is square

\begin{verbatim}
viewport 0 1 0 1
\end{verbatim} 

Use ghostscript to quickly check things.  In the same manner, the
Z-thickening can be changed. The Z-thickening is used to create an illusion
of three-dimensionality and is determined by the thickness of the
slab. Thus, if the object is near the far end of the viewing volume (that
is, near the back slab), it will be drawn with thin lines, and if is near
the front, it will be drawn with thick lines. The size of the text varies
in the same way. You can use the {\tt text\_size} command to adjust the
overall size of the text characters, and the slab to adjust the front and
back sizes of the letters.  Z-thickening can also be adjusted by changing
the values using the {\tt thick} command.  There is currently an unfortunate
limitation in oplot, which will be changed sometime: the viewing operation
is set when an object is displayed. This means that the same Z-thickening
is applied to all sub-objects in a composite object. In other words, the
{\tt disp\_bonds} object in the \mbox{\bf O} output file, may contain molecules,
maps and text, which will get the same Z-thickning parameters applied. The
way around this is to display molecule, text and map objects in their
individual objects, varying the slab parameter for each according to need.

%---
\subsection {The oplot input} \index{oplot input}
The input for {\bf oplot} is a description of three dimensional objects to be
plotted. The input consists of keywords followed by values. Keywords and
values are separated by spaces, newlines or tabs. The input is
completely free format, as the parser sees the input as a stream of
tokens. The parser automatically converts integer values to floating
point, but not vice versa. All {\bf oplot} commands must be lower case.

The syntax of the {\bf oplot} input is strict. Drawing commands, such as {\tt move},
{\tt line} or {\tt text} may only be present inside an open object. If {\bf oplot}
discovers a syntax error, it simply stops, with an indication of which
input line the error occured (usually, the next line is where the
problem lies).  However, the syntax is also simple, so hopefully it
should be easy to debug input files.  The {\bf oplot} input syntax is very
similar to the \mbox{\bf O} graphics descriptor language, but not completely
identical. 
 
\subsection {Viewing instructions } 

Since it is most likely that you will be changing the viewing parameters,
they will be described here. {\bf Oplot} is capable of producing views in either
parallel or perspective projections. The math of these viewing
transformations will not be explained here; instead, the user is referred
to a standard Computer Graphics text such as Foley \& Van Damm. The main
thing to remember is that the viewing coordinate system is left
handed. That is, if $x$ is horizontal, and $y$ is vertical on the plotting
surface, then $z$ is pointing away from you. Thus, the front of the viewing
volume, has a lower $z$-value than the back of the viewing volume. In the
default setting, (also used in \mbox{\bf O} metafiles) the position of the observer
is at (0,0,-1) and the look-at point is (0,0,0).

The following {\bf oplot} commands affect the viewing of the objects.   

\begin{description}
\item [window] [uwmin uwmax vwmin vwmax]. 
Specify the limits of the window in the plane of projection. The default
size of the window is (0, 1, 0, 1).

\item [viewport] [uvmin uvmax vvmin vvmax]. 
Where on the visible area to display the contents of the window. The limits
of the viewport must be given in the range [0:1]. The default size of the
viewport is (0, 1, 0, 1).

\item [view\_reference\_point]  [x y z]. 
Set the view reference point (the look-at point). The default value is
(0,0,0).

\item [view\_point\_normal] [x y z]. 
Set the view plane normal. Default is (0,0,-1).

\item [up\_direction] [x y z]. 
Set the view-up direction. Default is (0,1,0).

\item [parallel] [x y z]. 
Define the projection to be parallel, and specify the direction of the
projection. The default setting is (0,0,1) and the parallel projection mode
is default.

\item [perspective] [x y z]. 
Define the projection to be perspective, and specify the
center-of-projection (the eye point). Default is (0,0,-1). The default
projection mode is parallel.

\item [depth\_cue] [on / off].  
Set depth cueing on. Same as using the -z option. Default is off.

\item [slab] [front back]. Set the slab limits.

\item [zthick] [front back]. 
Set the value of the linethickness at the front and back slab limits. Only
has a visible effect if depth cueing is on. Default values are front = 4.0,
back = 1.0 .

\item [front\_clipping] [on / off]. 
Set clipping at the front slab limit on or off. Default value is off.

\item [back\_clipping] [on / off].  Set clipping at the back slab
limit on or off. Default value is off.

\item [display] [object]. 
Add an object to the display list. ONLY displayed objects will be visible
in the plot!
\end{description}

%---
\subsection {Example}  

The following example draws a box:

\begin{verbatim} 
begin box
#draw face 1
 move 0 0 0 	
line .1 0 0 	
line .1 .2 0 	
line 0 .2 0 	
line 0 0 0 	 

# draw face 2	
move 0 0 .5 	
line .1 0 .5 	
line .1 .2 .5 	
line 0 .2 .5 	
line 0 0 .5

# draw the connecting lines 	
move .0 0 0 
rline 0 0 .5 	
move .1 0 0 
rline 0 0 .5 	
move .1 .2 0 
rline 0 0 .5 	
move .0 .2 0 
rline 0 0 .5
end_object

display box    # display it 
\end{verbatim} 

Everything to be plotted must belong to an object, and objects {\em must be
displayed} to be visible. In the example above, the box is plotted in the
default window and viewport.
%---
\subsection{Some tricks} 

The {\bf oplot} output is {\sc PostScript}, but in combination with the
incredible ghostscript program, you can convert your plots to other device
formats. For example, to generate a GIF picture from your output file, you
can do the following:

\begin{verbatim} 
% oplot < input.plt > tmp.ps
% gs -sDEVICE=gif8 -sOutputFile=junk.gif tmp.ps
\end{verbatim} 

The GIF file can be then viewed using {\tt xv}, for example. GIF is a standard
image format, and you display it on the Mac if you have a public domain
program called Giffer. This will also enable you to create a PICT file,
which you can import into a word-processing or drawing program.

Ghostscript is also extremely convenient for getting previews of your
plots:

\begin{verbatim} 
% oplot -gz < plot.plt | gs -
\end{verbatim} 

and will save enormous amounts of paper.
%---
\subsection{Compiling oplot} 

{\bf Oplot} is written in vanilla C, and has been compiled without problems
on several computers. So, if the binaries available on rose.bmc.uu.se will
not run on your machine, you can fetch the source code. It is in a tar
archive called {\tt oplot\_v1.11.tar.Z}, or whatever the most recent version
number is. To compile, simply

\begin{verbatim} 
% uncompress oplot_v1.11.tar
% tar xvof oplot_v1.11.tar
% cd oplot_v1.11
% make
\end{verbatim} 

and the program should compile. To install the program in {\tt /usr/local/bin},
go (you need root permission):


\begin{verbatim} 
% make install
\end{verbatim} 

%---
\subsection{Known bugs \& limitations} 

Polygons are not clipped. 
Text is not clipped. 
You cannot specify the solid material
properties. 
You cannot set the light sources.  

{\bf Oplot} is capable of dealing with shaded polygons.  The hidden surface
removal algorithm employed is a depth-sorting, which takes place after an
object has been displayed. Thus, there is no hidden surface elimination
taking place between objects that are displayed individually.



\begin {thebibliography}{99}

\bibitem{carson87} Carson, M. (1987) Ribbon models of macromolecules. 
{\em J. Mol. Graphics} {\bf 5}, 103--106.

\bibitem {deisenhofer75} Deisenhofer, J. and Steigemann, W. (1975) {\em
Acta Cryst.}  {\bf B31}, 238--250.

\bibitem {greer74} Greer, J. (1974) Three-dimensional Pattern Recognition: 
An Approach to Automated Interpretation of Electron Density Maps of Proteins.
{\em J. Mol. Biol.} {\bf 82}, 270--302.

\bibitem {jones78} Jones, T.A. (1978) {\em J. Appl. Cryst.}, {\bf 11},
268--272.

\bibitem {jones82} Jones, T.A.  (1982) Computational Crystallography, 
Clarendon Press, Oxford, Editor D. Sayre., 303--317.

\bibitem {jones84} Jones, T.A. \& Liljas, L. (1984) {\em Acta Cryst.} {\bf
A40}, 50--57.

\bibitem {jones86} Jones, T.A.  \& Thirup, S. (1986) {\em EMBO J.}, {\bf  5},
819--822.

\bibitem {jones91} Jones, T.A,  Zou, J-Y., Cowan, S.W. \& Kjeldgaard, M. (1991) 
Improved Methods for Building Protein Models in Electron Density Maps and
the Location of Errors in these Models.
{\em Acta Cryst.} {\bf A47}, 110--119.

\bibitem {jones92} Jones, T.A. (1992) A, yaap, asap @\#*?. A set of
averaging programs. In {\em Molecular Replacement}, 
SERC Daresbury Laboratory, U.K., Editor E.Dodson, 91--105.

\bibitem {kabsch83} Kabsch, W. \& Sander, C. (1983), Dictionary of 
Protein Secondary Structure: Pattern Recognition of Hydrogen Bonded and 
Geometrical Features. {\em Biopolymers} {\bf 22}, 2577--2637.

\bibitem {kleiywegt93} Kleiywegt, G. \& Jones, T.A., to be published.

\bibitem {lesk82} Lesk, A. (1982) Computer-generated schematic diagrams 
of protein structures. {\em Science} {\bf 216}, 539--540

\bibitem {ponder87} Ponder \& F.Richards (1987) Tertiary Templates for Proteins. 
Use of  Packing Criteria in the Enumeration of Allowed Sequences for 
Different Structural Classes. {\em J. Mol. Biol.}, {\bf 193}, 775--791.

\bibitem{richardson81} Richardson, J. (1981) The anatomy and taxonomy of 
protein structure.{\em Adv. Prot. Chem.} {\bf 34}, 167--339.

\end{thebibliography}

\appendix
\chapter {TERMS OF AGREEMENT}

\begin{center} {\LARGE Licensee's Copy} \end{center}

Use of the \mbox{\bf O} system of molecular modelling programs implies acceptance
of the following terms.

\begin{enumerate}
\item  This program is non-exclusive and non-transferable for its use on a
computer system at the Licensee's institution.  Use of the program is
restricted to the licensee and collaborators at his/her institution.

\item DatONO AB retains ownership of all materials (including software and
documentation).  Any modifications or derivative works based on the
software are considered part of the software and ownership is retained by
DatONO AB.  Any such modifications are to be reported to DatONO AB and must
be made available upon request.

\item The program or any modifications thereof may not be disclosed to third
parties without written authorization from DatONO AB.

\item Copies for the purpose of maintenance, backup, or development may be
made in a reasonable number and must carry the copyright of DatONO AB.  All
copies are under the control of this license and must be destroyed upon
termination of the license.

\item Third party requests for the program made to the licensee are to be
referred to DatONO AB and are not to be fulfilled by the licensee.

\item Requests for the source code of this program may be made to DatONO AB.
The source code is under the control of this license and requests for it
are honored upon the discretion of DatONO AB.

\item THE SOFTWARE IS FURNISHED "AS IS" AND DatONO AB IS NOT RESPONSIBLE FOR
ANY OF ITS RESULTS NOR IN ANY WAY LIABLE FOR ANY USE WHICH THE LICENSEE
MAKES OF THIS SOFTWARE.

\item Publication of results or reports obtained with the program O must be
acknowledged by an appropriate citation.

\item This license is not limited in time.

\end{enumerate}

\chapter {Workstation Distribution of O} \label{app-dist}

The program for Unix workstations exported on a cassette, written with
tar. It can be retrieved by issuing the following command

\begin{verbatim} 
% tar xvo
\end{verbatim} 

This creates a number of subdirectories {\tt example/}, {\tt data/}, {\tt 
macros/}, {\tt export\_source/}, and {\tt bin/}.

The directory {\tt example/} contains files that allow you to start playing with
\mbox{\bf O}. The directory {\tt data/} contains the data bases and necessary startup
files. The directory {\tt macros/} contains a number of useful \mbox{\bf O} macros
that you can use as examples to create your own, personalised macros. The
directory {\tt bin/} contains the program \mbox{\bf O} and some related
programs. The Stardent GS1000/2000 programs have names starting with {\tt
gs\_}, the Stardent 1500 with {\tt dr\_}, the Evans \& Sutherland ESV with
{\tt es\_}, the Silicon Graphics with {\tt 4d\_}, and the Hewlett-Packard
with {\tt hp\_}.  The {\tt
export\_source/} directory contains programs to convert extrernal map
formats to a standard one, skeletonising and averaging programs and a
program swapbytes to convert Vax mappage maps sent to the workstation with
ftp.

All workstation implementations make use of dials. 

Add a new environment variable to your login shell file {\tt .cshrc} 

\begin{verbatim} 
% setenv ODAT /usr/people/alwyn/o/data/
\end{verbatim} 

to define where the {\tt data/} directory is located


\section{ESV specific installation} 

The ESV version needs a few changes for using stereo with the crystal eyes
stereo glasses. This version is the first release of E\&Ss new stereo
implementation and contains one little bug. However, because it is so much
better than the old implementation we are releasing it now.

1. Start Your X server with the multiple screen option If Your ESV login
 environment is controlled by the X display manager `xdm' then the file:

\begin{verbatim} 
/usr/lib/X11/xdm/Xservers
\end{verbatim} 

has to be modified, so that one of the screens is set to
`STEREOTALLSCR'. This must not be screen 0!  Example:
{\tt /usr/lib/X11/xdm/Xservers} should contain a line something like

\begin{verbatim} 
unix:0.0 local /usr/bin/X11/Xesv  -nscreens 3x3 -stereotallscr 6 
                   -stereoscr 2 -tc32scr 3 -dc32scr 4  -pc8scr 5
\end{verbatim} 

This has to be done by root. For this change to be activated, it
will be necessary to kill the display manager. This is done by exiting from
the session, then typing ALT-F4 to kill the xdm process. Then login as xdm
to restart the process.

Each user must also modify some files in their login directory. The window
manager {\tt mwm} must be started with multiple screens and you need 
{\tt csm} (Carys Screen Manager --- don't ask who Cary is or was).
Add the following 2 lines (if you do not have them already) to your file  
{\tt \$HOME/.xsession}

\begin{verbatim} 
mwm  -multiscreen 
csm \&
\end{verbatim} 

Now create or edit the file  {\tt \$HOME/.XSERVERRC} to include the line

\begin{verbatim} 
X -nscreens 3x3  -stereotallscr 6 -stereoscr 2 -tc32scr 3
                 -dc32scr 4 -pc8scr 5
\end{verbatim} 

It will then be necessary to reactivate the X-server with xinit. Ignore the
error messages (if any), exit the session and log back in.

The stereo expects one screen in `STEREOTALLSCR' mode. This mode has the
normal resolution in $x$-direction and half the resolution in the
$y$-direction. If the installation has been carried out as described above,
then a program sleeper is located in the {\tt bin/} directory. If this release is
obtained via ftp, then {\tt sleeper} and {\tt es\_ono\_5.7} must be in the same
directory. This program is started by \mbox{\bf O} and takes care of the movement
between screens. The bug in this release is that once stereo has been set,
after the user stops, the sleeper process is not deleted. Until fixed, you
will have to do it typing the following to get the process id:

\begin{verbatim} 
% ps -ae | grep sleeper
\end{verbatim}

and then issuing a kill command like

\begin{verbatim} 
% kill -9 <id>
\end{verbatim}

where $<$id$>$ is an integer.  If the STEREOTALLSCR stereo screen is not
installed \mbox{\bf O} will write a message: ``{\tt Stereoscreen is not
available}'' and a swap to stereo mode will be refused. After each transfer
to stereo, a Motif Stereo Adjustment widget allows the user to readjust
viewing parameters.

The stereo display window can be moved but not resized. It can be resized
in mono, and then it will have that size in stereo. The windows on this
screen are not overlapped as on the old implementation.

If \mbox{\bf O} crashes in stereo mode, return to the default screen via {\tt
csm}.  You may want to start a number of xterms in the stereo window. If so
you must specify the screen number e.g.

\begin{verbatim} 
xterm -display unix:0.6
\end{verbatim} 

would start xterm on screen 6.

\section {Running the Program.} 

To run the program, set the directory to {\tt example/} and then type (user
input in boldface) something like the following (it will, of course, depend
on your machine type) :

\begin{verbatim} 
% {\bf cd o/example} 
%{\bf  ../bin/es\_ono\_5.9} 
O> Use of this program implies acceptance of conditions
O> described in Appendix 1 of the O manual
O> O version 5.9, August 1993
O> Define an O file (terminate with blank) :{\bf p2.o}  
O> Define an O file (terminate with blank) :
O> Maximum inter-residue link distance = 2.00
O> There were 23 residues.
O>           175 atoms.
O>
\end{verbatim}

or simply

\begin{verbatim} 
%../bin/es_ono_5.9 p2.o
O > Use of this program implies acceptance of conditions
O > described in Appendix 1 of the O manual
O > O version 5.9, August 1993
O > Maximum inter-residue link distance = 2.00
O > There were 23 residues.
O >           175 atoms.
O > Do you want to use the display ? [Y],N :
O >
\end{verbatim}

After a delay, you should see a 3-D window, plus menu and prompt areas. The
3-D window shows a CA drawing of P2 myelin and a fatty acid. Move the mouse
to the command {\bf On\_off} and click any button. The names of the
currently displayed objects will appear. Click them on and off. To make a
larger object for timing purposes, move the mouse over the terminal window
and enter the following commands:

\begin{verbatim}
obj all z ; end
\end{verbatim} 

To make the picture spin, just type the command {\bf Spin}. It will update
100 times, changing by 3.6 degrees each time. To get a map, type the macro
{\bf @map\_a}. Edit the file to increase the volume of density being
displayed (in line 3, it defines a cube of 12\AA). Now read the manual and
look at the examples provided.

\chapter {Sorted Required Datablocks} \label{app-sorted-req}

\begin{verbatim}  
.Menu_major_name               c        42(2a)
\end{verbatim}
A list of names associated with the major menus

\begin{verbatim}
.Menu_minor_name               c       418 (2a)
\end{verbatim}
A list of names associated with the major menus

\begin{verbatim}
.menu_colour                   i        21 (10i10)
\end{verbatim}
The colour associated with the major menu and its associated minor menus.

\begin{verbatim}
.menu_displayed                i        21 (10i5)
\end{verbatim}
What major menus are being displayed.

\begin{verbatim}
.menu_integer                  i         3 (10i10)
.menu_real                     r         2 (5f10.0)
\end{verbatim}
Menu associated datablocks.

\begin{verbatim}
.menu_visible                  i        21 (10i5)
\end{verbatim}
Describes if the major menu is available to the user. 
Should {\em always} be 1.

\begin{verbatim}
.molec_obj_integer             i         9 (10i7)
\end{verbatim}
Used to store various data concerning the molecular objects.

\begin{verbatim}
.moving_atom t 8 80 .single_atom t 8 80 
\end{verbatim}
Describe how to draw a moving and single unbonded atom, respectively. There
are alternatives, icosahedron, tetrahedron, in {\tt \$ODAT}.

\begin{verbatim}
.torsion_information           t       100 72
\end{verbatim}
Describes how each residue is to be treated by the {\tt Tor\_residue} command.

\begin{verbatim}
RSR_dict_ASN             T         2        70
RSR_dict_ASP             T         2        70
RSR_dict_Ala             T         2        70
RSR_dict_Arg             T         3        70
RSR_dict_CYH             T         2        70
RSR_dict_CYS             T         2        70
RSR_dict_GLN             T         3        70
RSR_dict_GLU             T         3        70
RSR_dict_GLY             T         1        70
RSR_dict_HIS             T         2        70
RSR_dict_ILE             T         3        70
RSR_dict_LEU             T         2        70
RSR_dict_LYS             T         3        70
RSR_dict_MET             T         3        70
RSR_dict_MG              T         1        70
RSR_dict_PHE             T         2        70
RSR_dict_PRO             T         2        70
RSR_dict_SER             T         2        70
RSR_dict_THR             T         2        70
RSR_dict_TRP             T         2        70
RSR_dict_TYR             T         2        70
RSR_dict_VAL             T         2        70
\end{verbatim} 
Descriptions of how each residue is broken up into fragments for {\bf RSR\_zone}
and the {Move\_fragment} commands.


\chapter {Examples of Residue Tables} \label{app-tables}

{\tt Table\_charge.dat} a table of integers:

\begin{verbatim} 
ALA            0
ARG            1
ASN            0
ASP           -1
CYS            0
CYH            0
GLU           -1
GLN            0
GLY            0
HIS            1
ILE            0
LEU            0
LYS            1
MET            0
PHE            0
PRO            0
SER            0
THR            0
TYR            0
TRP            0
VAL            0
SOL            0
RTL            0
\end{verbatim}

{\tt Table\_size.dat}, a table of character*6 variables.

\begin{verbatim} 
ALA   SMALL
ARG   BIG
ASN   MEDIUM
ASP   MEDIUM
CYS   MEDIUM
CYH   MEDIUM
GLU   MEDIUM
GLN   MEDIUM
GLY   SMALL
HIS   MEDIUM
ILE   MEDIUM
LEU   MEDIUM
LYS   BIG
MET   BIG
PHE   BIG
PRO   SMALL
SER   SMALL
THR   SMALL
TYR   BIG
TRP   BIG
VAL   SMALL
SOL   SMALL
RTL   BIG
\end{verbatim}

{\tt Table\_delta\_g.dat}, a table of reals.

\begin{verbatim} 
ALA   .42
ARG   -1.37
ASN   -.82
ASP   -1.05
CYH   1.34
CYS   1.34
GLN   -.30
GLU   -.87
GLY   0.
HIS   .18
ILE   2.46
LEU   2.32
LYS   -1.35
MET   1.64
PHE   2.44
PRO   .98
SER   -.05
THR   .35
TRP   3.07
TYR   1.31
VAL   1.66
\end{verbatim} 

\chapter {Distributed Macros} \label{app-dist-macros}

The following macros are distributed with the program in the directory 
{\tt o/macros}

\section {@bones\_20a}

Select all bones atoms of type 1,2 \& 3 within 20A of an Id'ed atom
this creates an atomic object called {\tt 20a}, chosing skeleton atoms
from bones molecule {\tt ano1}:

\begin{verbatim} 
bone_setup ano1 20a 20.    1 2 3 ;
centre_id
\end{verbatim}


\section{@bones\_50a}
 Select all bones atoms of type 1 \& 3 within 50\AA of an Id'ed atom.
This creates an atomic object called  {\tt 50a}, chosing skeleton atoms
from bones molecule {\tt ano1}:

\begin{verbatim} 
bone_setup  ano1 50a 50.    1  3 ;
centre_id wait_id
bone_draw
\end{verbatim}

\section {@change\_id\_colour}
\begin{verbatim} 
print blue = 33023
print magenta = 16711935
print red = 16711680
print yellow = 16776960
print green = 65280
db_set_da .molec_obj_integer 8 8 #Define colour code e.g. 16711680 :#
\end{verbatim}

\section{@change\_id\_colour}
\begin{verbatim} 
print blue = 33023
print magenta = 16711935
print red = 16711680
print yellow = 16776960
print green = 65280
db_set_da .molec_obj_integer 8 8 #Define colour code e.g. 16711680 :#
\end{verbatim}

\section{@change\_id\_number}
\begin{verbatim} 
db_set_dat .molec_obj_integer 9 9 #How many Id's per object e.g. 3 :#
\end{verbatim}

\section{@Save\_as}

First an elaborate example of the {\bf @Save\_as} macro, where we make of
the UNIX operating system to change the content of the {\tt FILE\_O\_SAVE}
datablock.

\begin{verbatim}
! O Macro to change the Save file name

write file_o_save tmp ;

! Use UNIX to change last line of datablock
$ head -1 tmp > tmp1 
$ echo "New Save file? \c"
$ read file ; echo $file >> tmp1

! Read back the changed datablock
read tmp1
print "The new save file is called"
write file_o_save ;;

! Clean up after us
$ /bin/rm tmp tmp1

bell
print "Save file name changed"
\end{verbatim}

A simpler approach to the above is to delete the {\tt FILE\_O\_SAVE}
datablock, and take advantage of the fact that {\bf Save} asks for a
filename if it doesn't exist:

\begin{verbatim} 
db_kill FILE_O_SAVE
save #New file name :#
\end{verbatim}


\section{@map}
Contour a map at the current active centre. The map file name is defined by
a symbol \$map:
\begin{verbatim} 
message "Start contouring  map"
map_file $map
map_obj map
map_par 12. 12. 12. 1.5 coral .5 .1 0
map_act
map_draw
message '  '
\end{verbatim}

\section{@paint\_by\_atom\_type}
Paint a molecule by the atomic nmumbers z
The action takes place on the current molecule,
carbons - yellow, nitrogens - blue, oxygens - red, sulphurs - green
\begin{verbatim} 
Paint_case ato_z 4 6 7 8 16 yellow blue red green
\end{verbatim}

\section{@paint\_by\_b\_factor}
Paint by the atomic B-factors This assumes the presence of as atomic
property {\tt \_atom\_b} It colours from blue to red. Note that we force
it to have blue by defining RGB values. Using `blue' would make it go
through the rainbow to red, instead of via magenta.
\begin{verbatim} 
paint_ramp    atom_b    ; 3 0 255 red
\end{verbatim}

\section{@paint\_by\_internal\_residue}

Paint by the internal residue value of the protein. This paints on a
property called {\tt \_residue\_irc}, the internal residue count.  This
colouring scheme goes thru the rainbow.

\begin{verbatim} 
paint_ramp ;; red blue
\end{verbatim}


\section{@sphere}
Choose a spher of 10\AA around the next Id'ed atom the molecule name is
defined by the last atom ID'd symbol
\begin{verbatim} 
centre_id Wait_id
message "Displaying a sphere of atoms"
mol $.id_m c_at $.id_m $.id_r $.id_a obj sph spher 10. end
message '  '
\end{verbatim}

\section{@two\_molecules}
This is what one would call a serious macro.  Select density from 2
molecules and from 2 sets of atoms.  The screen centre is determined by
Id'ing an atom.  IMPORTANT: make sure it's from the reference molecule A
The molecules are defined by symbols {\tt \$mol\_a} and {\tt \$mol\_b} the
maps by {\tt \$map\_a} and {\tt \$map\_b}.

\begin{verbatim} 
centre_id ! Wait for an ID
message "Make sure its an atom from molecule A"
Wait_id
message "Start contouring B"
copy save_centre .active_centre
rot_trans_db .active_centre .lsq_rt_a_to_b .active_centre
map_file $map_b
map_obj mapb
map_par 9. 9. 9. 1.5 light_blue .5 .1 1
map_act
map_draw
rot_tran_obj .lsq_rt_b_to_a mapb
mol $mol_b obj sphb spher 10. end
! Now do the map from molecule A
message "Start contouring A"
copy .active_centre save_centre
map_file $map_a
map_obj mapa
map_par 9. 9. 9. 1.5 red .5 .1 1
map_act
map_draw
mol $mol_a obj spha spher 10. end
lsq_obj b_to_a sphb
message "  "
\end{verbatim} 

\section{Menu systems included}
Two menus are also included. One is useful for mutating residues ({\tt
menu\_replace.o}) and the other ({\tt menu\_pflugrath.o}) is part of a
system developed by Dr. J. Pflugrath at Cold Spring Harbor.


%%% refi_dict %%%

\chapter{The Refi Dictionary}
The dictionary used by \mbox{\bf O} and FRODO is described by Hermans \& Ferro in
Biopolymers, Vol. 10, pages 1121-1138. The connectivity is represented as
a tree structure of backward and forward pointers. Bond lengths and angles
are defined via the back pointers. The full dictionary of Jan Hermans also
has the possibility of defining non-bonded atom energy coefficients. The
first record is a title The next record defines the residue type and the
number of atoms in the dictionary description of the residue. The format is
{\tt (A4,6X,I5)}. A residue name END terminates the file. Each atom has one
record defining the name, back chain, lowest forward chain, highest forward
chain,a flag to define fixed or flexible torsion angle,a bond length, a bond
angle, a torsion angle. The format is {\tt (A4,2X,4I2,3F5.0)}.

\begin{description}

\item[The Atom Name]
The atom name contains 4 characters. Names with X or Y in them have
special significance and are used, especially, to close rings. These
special atoms act as ghosts of the atom which is named without the X or Y,
and they will have the same position as the real atom during regularisation.

\item[The Backward Chain]
The chain values act as pointers to atoms defined in the dictionary. For
example, the value 1 signifies the first atom in the residue being
described, and 5 would be the fifth. The backward chain represents a
connection from the present atom (call it the $i$'th) to an earlier atom in
the list (call it the $h$'th). It signifies a connection between the
present atom and a later atom in the list (call it the $j$'th). Then $i$ is
less than $j$ and there must be no backward chain connections to atom $i$
between the $i$'th and $j$'th atoms in the residue. It signifies a
connection between the present atom and a later atom in the list (call it
the $k$'th). Then there can be no backward chains to $i$ from atoms in the
list beyond $k$. There can be other connections to the $i$'th atom from
atoms in the list between positions $j$ and $k$, but these will be
described by backward chains.

\item [The Bond Length]
It is the value for the bond defined by the backward chain from this atom. 

\item [The Bond Angle] 
It is the value of the bond angle defined by 2 backward chains from this
atom. It is the value of the torsion angle defined by 3 backward chains
from this atom.

\item [The Torsion Angle Flag]
It takes the value 0 for fixed dihedrals and greater then 0 for flexible
ones. The angle concerned is best described with an example: The angle PHI
for an Amino Acid is defined by the atoms C, N, CA, C. It is flexible and its
flag is carried around with atom CA. Likewise, PSI is defined as flexible at
atom C and OMEGA at atom N.

\item [The Complication]
This comes for atoms with more than one forward chain. The highest forward
chain atom is straight forward. The torsion angle value held at the lowest
forward chain atom now takes on a special meaning and defines how much this
atom is out of the plane defined by $h$, $i$ and $k$ as defined above. In
particular, if we hold $h$ towards us and look down the $i$ to $k$ bond, it
is the angle made by line $hi$ and $ij$ in projection. It is quite easy to
get this value wrong by 180 degrees (or wrong sign) when making a new type
of residue.

\item [Warning]
This is meant as a help to someone who has to make a new entry in the
dictionary. It is not a full description. You are advised to look at the
existing entries and draw out how they have been built up. With a little
practise it is not difficult, honest. The distributed version 
%of FRODO
skips over all atoms begining with `H'.

\end{description}

\printindex

\end{document}

%%% end of file %%%
