README on autobondrot                                  JMW - 8/6/99

Using the -autobondrot command line flag, probe can generate multiple
molecular conformations by rotating atoms around defined dihedral axes
and perform other transformations. To use this function you must construct an
input script defining rotatable bonds, etc. Usually called .rotscr files
they are quite similar to the @bondrot sections in a kinemage file. The
probe command iterates over each conformation and generates a tabular output
of the probe score and the conformation angles.

Atomic coordinates for specific conformations (in PDB format) can be
output.

A simple example of how to use -autobondrot is to explore the range of
probe scores for all conformations of a given amino acid sidechain
to analyze how it interacts with itself and its static neighbors.

HOW TO MAKE A SIDECHAIN CONFORMATION MAP IN UNIX OR LINUX

First, take the PDB file (with hydrogens from reduce) and use
prekin to make a rotatable group or mutation. In this example,
tyrosine 61 in the PDB file 1ah7H is examined and prekin we used
prekin to create "1ah7y61bondrot.kin".

The script for sampling the scores is created with mkrotscr, which
translates the @bondrot sections of the .kin file into the proper
syntax for the .rotscr file.

   mkrotscr 1ah7y61bondrot.kin 61 1ah7H > 1ah7y61.rotscr

When running mkrotscr, the residue and PDB file are listed after the
kinemage filename, so that mkrotscr can construct a plausible suggested
command line for a sidechain rotation in the .rotscr file. Executing
this command will invoke probe to calculate contacts and summarize the
result as a probe score. The proposed probe command reads the autobondrot
information until the END_OF_INPUT marker is seen. To make this file
an executable UNIX shell script simply "chmod +x filename".

When the residue numbers are unique, an alternative way to create
this rotation script is to use pdb2rotscr, a simple command script
which combines prekin and mkrotscr. In our example, the command
would be as follows.

   pdb2rotscr 1ah7H 61 tyr > 1ah7y61.rotscr

This .rotscr file needed to be edited because mage wrote out a third
rotatable bond (the OH) which we did not want to explore. In addition,
we modified the bounds of the search of chi2 from 0-359 (by 5) to 0-179
(by 10) because the phenyl ring is symmetric and it is not neccessary
to scan chi2 as finely as chi1. To make the file more informative
changed the rotation names from "rot1" and "rot2" to "chi1" and "chi2".
We only want a torsional penalty applied to chi1 so we took out all but
the first "cos" record.

A duplicate copy of the atom record for C-zeta was deleted for neatness.
Finally, since this residue does not have any branch points which require
independent nested rotations we can safely delete the SAVE/RESTORE pair:
"(" and ")". The final result is as follows:

probe -q -stdbonds -3 -drop -once "file1" "file1 | file2 alta not water not(sc 61)" -auto - 1ah7H <<END_OF_INPUT
atom      1  cb  tyr    61      34.219  17.937   4.659  1.00  0.00
bondrot:chi1:78.7:  0:359:5:33.138:18.517: 5.531:34.219:17.937: 4.659
cos:-3:60:3:
atom      1 1hb  tyr    61      34.766  18.777   4.206  1.00  0.00
atom      1 2hb  tyr    61      34.927  17.409   5.315  1.00  0.00
atom      1  cg  tyr    61      33.836  16.989   3.546  1.00  0.00
bondrot:chi2:-11.8:  0:179:10:34.219:17.937: 4.659:33.836:16.989: 3.546
atom      1  cd1 tyr    61      32.578  16.433   3.418  1.00  0.00
atom      1  cd2 tyr    61      34.803  16.657   2.603  1.00  0.00
atom      1  ce1 tyr    61      32.294  15.554   2.393  1.00  0.00
atom      1  ce2 tyr    61      34.520  15.798   1.551  1.00  0.00
atom      1  cz  tyr    61      33.249  15.259   1.456  1.00  0.00
atom      1  hd1 tyr    61      31.793  16.694   4.142  1.00  0.00
atom      1  hd2 tyr    61      35.813  17.084   2.693  1.00  0.00
atom      1  he1 tyr    61      31.299  15.089   2.328  1.00  0.00
atom      1  he2 tyr    61      35.291  15.550   0.807  1.00  0.00
atom      1  oh  tyr    61      32.991  14.372   0.421  1.00  0.00
atom      1  hh  tyr    61      33.803  14.287  -0.156  1.00  0.00
END_OF_INPUT

We make the script executable

   chmod +x 1ah7y61.rotscr

A table of scores is generated by running this rotation script, which
feeds the records up to the END_OF_INPUT to probe after the -auto flag.
This system makes use of the "<<LABEL ... LABEL" UNIX syntax for inline
data. The run may take several minutes.

   1ah7y61.rotscr > 1ah7y61.map
   
Finally, the scores can be contoured by kin2Dcont and viewed in mage.
The range of contour levels can be customized as required.

   kin2Dcont 1ah7y61.map -kin -group -sampled -wrap 0 360 0 180 \
   -gxy 5 10 -sxy 4 8 -multi -200 -20 20 orange -6 -2 2 brown \
   -level 0 grey -multi 2 50 2 sea > 1ah7y61.cont.kin

   mage 1ah7y61.cont.kin

A similar program, kin3Dcont, makes contours of 3 dimensional datasets.
Our data is uniformly sampled (-sampled) and the data are cyclic so that
360 deg is the same as 0 deg (-wrap # # # #). This is why we only
sampled the data up to 355 and 175 degrees in the two dimensions.
The -gxy 5 10 and -sxy 4 8 control the size of the sampling grid in each
dimension  (5 deg by 10 deg) and the size of the spot filter
(sdev x = 4 deg, sdev y = 8 deg) used to smooth the data. If the grid
spacing is the same in each dimension a combined setting may be used
(-g# and -s#). The spot filter can be varied to either increase smoothing
(-sxy 10 20) or eliminate any smoothing (-s0). For sampled data, setting
the spot size about equal to the grid spacing seems to work well.

THE ELEMENTS OF AN AUTOBONDROT SCRIPT

The input script for autobondrot is composed of records of the following
types-
   three transformation types: BONDROT (aka ROT), TRANS, NULL
   three function types:       COS, POLY, CONST
   the atomic coordinates:     ATOM
   branching control:          SAVE, RESTORE aka "(" and ")"
   orientation specifier:      GO
   include files:              @
   comments:                   #
   
The information on each record (except ATOM) is separated by colons and must
be all on one line. Any line beginning with a # is ignored, providing a
convenient means of including comments in the script. For rotations, BONDROT
and COS records head each section of ATOM records which are subject to the
same rotation.

*BONDROT - Both the current angle of the rotatable bond and the range
of angles to be sampled are defined on the BONDROT record, along with the
end points of the axis. It consists of eleven data fields: the axis name,
current angle, beginning rotation angle, final rotation angle, the amount
of rotation, and finally the x, y and z values of the beginning and end
of the rotation axis.

The axis name does not have to be a number (e.g., chi1 or phi).

The current angle can be measured with the measures tool within mage.

Any atoms listed before the first BONDROT will be output but their
coordinates will not be altered. Subsequent BONDROT records are treated
as nested rotations. Use SAVE and RESTORE records to control where these
nested rotations begin and end.

The nested chi1, chi2 rotations in our tyrosine example are:

   bondrot:chi1: 78.7:  0:359:5:   33.138:18.517:5.531:  34.219:17.937:4.659
      ... atoms rotate about chi1 ...
   bondrot:chi2:-11.8:  0:179:5:  34.219:17.937:4.659:  33.836:16.989:3.546
      ... atoms rotate about chi1 then chi2 ...

Here the chi1 dihedral axis is defined by the C-alpha and C-beta atoms
while chi2 is defined by C-beta and C-gamma.

Note that the axis does not have to be along a bond. For example,
an entire molecule could be rotated around the coordinate axes.

*TRANS - Probe can also translate atoms. In this case, the axis defines
the direction of the translation, and instead of angles we have angstroms.

*NULL - A null transformation does not modify the position of any atoms.
It has no data fields.

*COS - after the transformation record (e.g., BONDROT) one or more records
can be provided which define a bias function. The most generally useful
is the COS record which is used to add a torsional penalty to probe scores
as we rotate around a dihedral. It consists of up to four data fields:
scalefactor, phase offset, frequency, and a seldom used offset which defaults
to 1. In our example, we use a torsion only with chi1

   cos:-3:60:3:

This describes the following function: -3*(1 - cos(3*(x - 60)))/2,
a cosine with three peaks with a value of 0.0 at -60, +60 and 180 and
a value of -3.0 at 0, 120 and 240.

More complicated functions may be built frome those provided by ganging-up
more than one COS, POLY or CONST record.

*POLY - A polynomial can be built from one or more POLY records. It has
three data fields: a scalefactor, offset and degree.

   poly:5.0:0.0:2:

results in the following quadratic: 5.0*(x - 0.0)^2

*CONST - a constant value can be added to the score. This record has
one data field: the value.

*ATOM - Rotations and other transformations operate on ATOM records, listing
each atom which is subject to the bond rotation. ATOM records may also
be supplied prior to any BONDROT record, in which case they are not
subject to any rotation. All ATOM records are in PDB-atom record
format.

The critical data fields are the full atom name, residue name, residue
number and x,y,z position. The format requires data to be in specific
columns.

   atom        1hb  tyr    61      34.766  18.777   4.206  1.00  0.00

*SAVE - Abbreivated "(", SAVE saves the current transformation on a stack.

*RESTORE - Abbreivated ")", RESTORE backs up to the last previously saved
transformation. Save and restore are used to organize transformations
for branching groups. For example when rotating the all sidechain angles
of an isoleucine (including the methyl groups) the following SAVE/RESTORE
grouping is required:

   bondrot:chi1: ...
   ...
   (
   bondrot:chi2: ...
   ...
   bondrot:CD1 meth: ...
   ...
   )
   bondrot:CG2 meth: ...
   ...

*GO - GO records are optional. If included, they  consist of a set of angles,
one for each BONDROT or TRANS, in the same order. Many GO records can be
included in a single .rotscr file.

If there are no GO records, autobondrot will generate all permutations
of conformations defined on the BONDROT records. If one or more GO
records are found, autobondrot will not grind through all these
permutations but will instead run the command on the specific
conformation listed. A series of GO records will sample a discrete
set of conformations.

   go: 60: 90:
   
In the our example the above sets chi1 to 60 deg and chi2 to 90 deg.

If the -verbose option (versus -quiet or -q) is used, probe will write
atom records for the transformed coordinates to standard error, once
for each GO record. This may be useful as a way of generating coordinates
for a specific orientation. To capture this standard error output in
a file along with standard output, UNIX provides the command line 
syntax "command >& outputfile".

*Include files - These records are also optional. If a line begins with
an at sign the following text is treated as a filename (@filename) and
probe attempts to start reading autobondrot commands from this file, to
the end, before continuing on with the current file. Include files can be
nested. The most common use for includes is to add in pre-defined
batches of go statements which sample set regions of conformation
space for a residue type.

REQUIRED SOFTWARE

An ensemble of programs, available for UNIX or LINUX, are required
to run probe with the -autobondrot flag.

mkrotscr    - an awk script (executable ascii text file)
probe       - version 2.0  or later, a C   program (binary executable)
reduce      - version 2.12 or later, a C++ program (binary executable)

maxv        - optional awk script used when the maximum value must
              be selected for certain ranges of conformations.
	      For example, to select the best OH angle for a serine
	      for each Chi1 angle.

Each of these programs must be placed in a directory listed in your
PATH. If the download process has not made the files executable,
each must be made executable with the command: "chmod +x filename".

Awk is a interpreted scripting language for processing text files which
is available on almost all UNIX systems.

Probe is used in the example above to calculate contact dot scores.

Reduce is listed above because hydrogens are neccessary for successful
use of probe. Add the hydrogens to the PDB file before running prekin
and the rest of the operations listed above.
   
Programs are available at http://kinemage.biochem.duke.edu
