\documentclass{article}
\usepackage{a4}

\newcommand{\pf}{\mbox{\bfseries ProFit}}
\title{ProFit V2.2}
\author{Dr.\ Andrew C.R.\ Martin,\\ University of Reading}
\date{Document First Written: 25th July, 1996 (University College %
London)\\Last updated: 20th March, 2001}

\begin{document}
\maketitle

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction and Methodology}

\pf\ (pronounced Pro-Fit, not profit!) is designed to be the ultimate
program for performing least squares fits of two protein
structures. It performs a very simple and basic function, but allows
as much flexibility as possible in performing this procedure. Thus one
can specify subsets of atoms to be considered, specify zones to be
fitted by number, sequence, or by sequence alignment.

\pf\ does not try to address the question of sorting out equivalent
atoms for you beyond doing a sequence alignment. There are other
programs such as SSAP and GAFIT which address that problem. You must
specify which residues and atoms you consider to be equivalent
although the program supports internal sequence alignment to set the
zones automatically.

As of \pf\ V2.0, iterative updating of fitting zones is now
supported. Thus you may give just a small fragment to initiate the
fitting process (a minimum of 3 amino acids). Fitting is performed on
this region and then all residue pairs within 3\AA\ are included in
the fitting zones and the fitting is repeated. This iterates until the
C$\alpha$ RMSd converges to within 0.01\AA. This is particularly
useful in conjunction with the initial zone specification based on
sequence alignment. Convergence typically takes 3--4 cycles.

\pf\ V2.0 also introduces multiple structure fitting. The first
structure file is used as a reference set for the first fitting stage
but the coordinates are averaged after each stage to derive a template
used for subsequent fitting. i.e.\ Given $N$ files to fit, file 2 is
fitted to file 1 and an averaged structure, $A$, is calculated, file 3
is then fitted to $A$ and a new average, $A'$ is calculated. This
continues until all $N$ structures have been fitted. The whole
procedure iterates until convergence (typically 3 or 4 cycles).

The program will output an RMS deviation and optionally the fitted
coordinates.  RMS deviations over alternate zones and atoms may also
be calculated without performing a new fit. Thus the zones for
calculating the RMS deviation can be different from those used for
fitting.

While optimised for proteins, non-protein structures may also be
fitted if they are stored in the standard Protein Databank (PDB) format.

\pf\ is written to be as easily portable between systems as possible
and uses a command-driven interface. It is planned to add an optional
Expectk graphical interface at some future date.

\pf\ uses the McLachlan fitting algorithm, essentially a steepest
descents minimisation, as described in McLachlan, A.D. (1982)
\emph{Rapid Comparison of Protein Structures}, \emph{Acta Cryst.}\
{\bfseries A38}, 871--873. This part of the code is based on an
implementation by Dr.\ Mike Sutcliffe.


In summary, \pf\ has the following features:

\begin{enumerate}
\setlength{\parsep}{0pt}
\setlength{\parskip}{0pt}
\setlength{\itemsep}{0pt}
\item Portability between different operating systems
\item Ability to specify atom subsets
\item Ability to specify zones:
\begin{itemize}
        \setlength{\parsep}{0pt}
        \setlength{\parskip}{0pt}
        \setlength{\itemsep}{0pt}
        \item Numerically
        \item By sequence
        \item By auto sequence alignment
\end{itemize}
\item Output RMS deviation over:
\begin{itemize}
        \setlength{\parsep}{0pt}
        \setlength{\parskip}{0pt}
        \setlength{\itemsep}{0pt}
        \item Fitted reglon
        \item Any other reglon
        \item Any other atom set
\end{itemize}
\item Optionally output fitted coordinates in PDB format
\item Integrated help facility
\item Fitting zones derived from sequence alignment
\item Iterative updating of fitting zones
\item Multiple structure fitting
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Starting the program}

The program is started from the command line by typing the command:
\begin{verbatim}
   profit
\end{verbatim}
Once the program is started, you may read in structures to be
fitted. Alternatively, the PDB files may be specified on the command
line:
\begin{verbatim}
   profit reference.pdb mobile.pdb
\end{verbatim}
By default, \pf\ does not read HETATM records from the PDB file. This
may be changed from the command line by using the -h flag:
\begin{verbatim}
   profit -h
   profit -h reference.pdb mobile.pdb
\end{verbatim}
Alternatively, once in the program you may give the \verb1HETATOMS1 
command before reading in the structures (see Section~\ref{sec:read}.

If compiled with XMAS\footnote{XMAS is an XML-like file format
developed at Inpharmatica, Ltd.\ which is designed for leaf-heavy data
such as protein structure data} file support, the \verb1-x1 flag may
be used to specify that the files named on the command line are XMAS
files instead of PDB files. Note that the program currently will only
write PDB format files.
\begin{verbatim}
   profit -x reference.xmas mobile.xmas
\end{verbatim}

If \verb|COPT  =| 
in the Makefile is changed to \verb|COPT  = -DGUNZIP_SUPPORT| 
then the program can read gzipped PDB files. This will only work on
unix-like platforms and assumes that the \verb|gunzip| program is in
your path. Note that the uncompressed files will remain in \verb|/tmp|
with a name like \verb|readpdb_12345| where 12345 is a process
number. You will need to delete these regularly!

Once in the program, you issue commands by typing at the
keyboard. These commands may always be abbreviated to the minimum
non-ambiguous string. The program is also case insensitive; you may
mix upper and lower case at will, though uppercase will be used
throughout this documentation.

You exit from the program by typing \verb1QUIT1.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Reading Structures}
\label{sec:read} 
\pf\ reads files in PDB format. If compiled with XMAS support, then
XMAS files may also be read, but only PDB files may be written. It
uses the concept of a \emph{reference} structure and a \emph{mobile}
structure. The reference structure remains static in space and the
mobile structure is fitted onto it.  When the files are specified on
the command line, the reference structure is specified first, the
mobile structure second.

Once in the program, you may read the reference structure using the
\verb1REFERENCE1 command and the mobile structure using the
\verb1MOBILE1 command. Using these commands causes the equivalent
current structure to be deleted from the program's memory
first. However, any zone and atom specifications (see
Sections~\ref{sec:atoms} and~\ref{sec:zone}) are not deleted.  For
example, you can read p3hfl.pdb as a new reference structure using the
command:
\begin{verbatim}
   REFERENCE p3hfl.pdb
\end{verbatim}
and read p3hfm.pdb as a new mobile structure with:
\begin{verbatim}
   MOBILE p3hfm.pdb
\end{verbatim}

If compiled with XMAS support, then the XMAS format is specified by
placing the keyword \verb1XMAS1 after the commands \verb1REFERENCE1 or
\verb1MOBILE1: 
\begin{verbatim}
   REFERENCE XMAS p3hfl.pdb
   MOBILE XMAS p3hfm.pdb
\end{verbatim}

When you read a structure containing insertions, you will receive a
warning message to this effect. This dates from when the program was
unable to handle residue specifications containing insertion codes,
but is still useful to draw your attention to the fact that they are
present.

Note that atoms with coordinates of 9999.00, 9999.00, 9999.00 will
be ignored during all calculations allowing atoms with undefined 
coordinates to be handled. 

When fitting multiple structures (new in \pf\ V2.0), you use the
\verb1MULTI1 command to read in the structures. See
Section~\ref{sec:multi}. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Getting Help}

To get help within the programs simply type \verb1HELP1 and you will
be presented with a list of commands which the help facility knows
about. The \verb1ProFit>1 prompt will also change to \verb1Help>1. You
may then type the name of a command to get help on that
command. Typing \verb1HELP1 once in the help facility will repeat the
list of available help topics. Like the main command interface, the
help facility will accept upper or lower case and you may abbreviate
commands. If your abbreviation is ambiguous (i.e.\ more than one
command starts with the letters you have specified), help will be
supplied on all the commands which match\footnote{The one exception to
this is if the letters you supply are an abbreviation of {\tt HELP},
when the list of help topics will be shown again.}.

If the help text is longer than 21 lines, you will see a prompt saying
\begin{verbatim}
   More...
\end{verbatim}
in which case you should hit the Return (or `Enter') key to get the
next page of help.

Once at the \verb1Help>1 prompt, you should simply hit the Return (or
`Enter') key to get back to the main \verb1ProFit>1 prompt.

If you know the topic on which you need help, you may type the name of
the command after the \verb1HELP1 keyword at the main \verb1ProFit>1
prompt. After the help message is printed, you will be returned
directly to the \verb1ProFit>1 prompt. For example, if you want help
on the \verb1ZONE1 command, you may type:
\begin{verbatim}
   HELP ZONE
\end{verbatim}

Allied to help, is the \verb1STATUS1 command. This tells you the
current status of the program: what structures are loaded, fitting
zones, atoms and the like.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Fitting Structures}

Having read in a reference and a mobile structure, you actually fit
them by giving the \verb1FIT1 command. When you do this, you will get
a message like:
\begin{verbatim}
   Fitting structures...
   RMS: 0.366
\end{verbatim}
However, this will only work if the two structures are of identical
composition i.e.\ if the sequences are the same and the same atoms are
present in both. If there are any mismatches, the first such mismatch
will be reported and the RMS deviation will not be calculated.  

Since you will frequently need to fit non-identical structures, you
may use the \verb1ZONE1 and \verb1ATOMS1 commands to specify which
residues should be considered equivalent and which atoms should be
considered in the calculation.

If you are using zone or atom specifications, the RMS deviations will
be displayed over the atoms and zones specified in those commands.

Normally the fitting procedure will not be completed if there are
any mismatched atoms or atoms missing from one of the two structures. 
The program issues an error message about atoms missing in the mobile 
structure which are found in the reference structure. The 
\verb1IGNOREMISSSING1 command causes the program to issue a warning
instead of an error and the fitting proceeds ignoring the mismatched
atoms. The default behaviour is restored by using the
\verb1NOIGNOREMISSING1 command.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Specifying Atom Subsets}
\label{sec:atoms}
The \verb1ATOMS1 command is used to specify a subset of atoms to be 
used in the calculations. It has the syntax:
\begin{verbatim}
   ATOMS atm[,atm]...
\end{verbatim}
i.e.\ you specify the \verb1ATOMS1 keyword followed by one or more
atom names separated by commas. A \verb1*1 may be used to specify all
atoms and a \verb1~1 or \verb1^1 may be placed at the beginning of the
specification to inverse the selection. For example, to fit only
C$\alpha$ atoms:
\begin{verbatim}
   ATOMS CA
\end{verbatim}
to fit N, C$\alpha$, C and O atoms:
\begin{verbatim}
   ATOMS N,CA,C,O
\end{verbatim}
to fit sidechains only (i.e.\ everything except N, C$\alpha$, C and O atoms):
\begin{verbatim}
   ATOMS ^N,CA,C,O
\end{verbatim}
to return to fitting all atoms:
\begin{verbatim}
   ATOMS *
\end{verbatim}

The PDB atom name field is 4 characters wide followed by a space.  The
first two characters are the right-justified element type, so for
normal protein and DNA atoms consist of a space followed by a N, C, O,
S or P. Thus the atom name field for a C$\alpha$ contains
`~CA~'. HETATMs such as calcium will contain the two characters CA in
the first two fields. i.e.\ `CA~~'. When you specify an atom type it is
matched against the atom name field from the \emph{second character onwards},
unless you preceed it with a \verb1<1. Thus to match a C$\alpha$ you use
\verb1CA1, but to match Calcium, you use \verb1<CA1. For example, as
stated above, to match C$\alpha$ atoms:
\begin{verbatim}
   ATOMS CA
\end{verbatim}
while to match calcium atoms
\begin{verbatim}
   ATOMS <CA
\end{verbatim}
and to match both C$\alpha$ and calcium:
\begin{verbatim}
   ATOMS <CA,CA
\end{verbatim}


Wildcards are also allowed. A \verb1%1 or a \verb1?1 may be used to
match a single letter at any point in the specification while a
\verb1*1 may be used to match all remaining characters (thus \verb1C*1
is allowed, but \verb1*G1 is not). These special characters may be
escaped by preceding them with a \verb1\1. For example to fit all
carbons:
\begin{verbatim}
   ATOMS C*
\end{verbatim}
or to match all atoms at the $\gamma$ position:
\begin{verbatim}
   ATOMS ?G*
\end{verbatim}
and to match the \verb1C4*1 atoms in DNA:
\begin{verbatim}
   ATOMS C4\*
\end{verbatim}

If atom names contain spaces (e.g.\ in heme groups) the whole atom
specification must be enclosed in double inverted commas:
\begin{verbatim}
   ATOMS "N A,N B,N C"
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Specifying Zones}
\label{sec:zone}
The \verb1ZONE1 command is used to specify zones in the two structures
which are considered equivalent. The complete syntax for the command
is:

\begin{verbatim}
   ZONE CLEAR|((*|(X...[,n][/m])|(j-k))[:(*|(X...[,n][/m])|(j-k))])
\end{verbatim}
where \verb1X...1 is an amino acid sequence, \verb1n1 is a number of
residues, \verb1m1 is the occurrence number, \verb1j1 and \verb1k1 are
residue specifications of the form \emph{[chain]resnum[insert]}. Items
in square brackets are optional and alternatives are marked by a
\verb1|1 and grouped in parentheses.

\verb1ZONE1 commands are cummulative. Thus each zone you specify is
added to those currently active. To clear all zones (i.e.\ fit all
residues), the \verb1ZONE CLEAR1 or \verb1ZONE *1 command may be
given.

Although it appears complex, the syntax is actually very simple and
consists of two identical sections separated by a colon (:). The left
half is applied to the reference structure and the right half to the
mobile structure. In its simplest form, the right hand half of the
expression is absent and the specification is applied to both
reference and mobile structures. For example:
\begin{verbatim}
   ZONE 24-34
\end{verbatim}
will set the zone to include residues 24--34 in both structures. If you
wanted to fit 24--34 in the reference structure with 25--35 in the
mobile structure, this simply becomes:
\begin{verbatim}
   ZONE 24-34:25-35
\end{verbatim}

You may also specify chain names and insertion code. The chain name is placed
before the residue number and the insertion code afterwards. For example:
\begin{verbatim}
   ZONE L25A-L30
\end{verbatim}
fits residues 25A--30 in the L chain of both structures.

Simple wildcards may also be used. For example
\begin{verbatim}
   ZONE H*:B*
\end{verbatim}
fits the reference H chain with the mobile B chain,
\begin{verbatim}
   ZONE -10:50-59
\end{verbatim}
fits from the first residue to residue 10 in the reference structure
with 50--59 in the mobile structure.
\begin{verbatim}
   ZONE *:1-100
\end{verbatim}
fits all residues in the reference structure with 1-100 in the mobile
structure.  

If the structure file contains negatively numbered residues and you
are using residue numbering, you can escape the minus sign in the
residue number using a backslash:
\begin{verbatim}
    ZONE \-4-10:\-1-13
\end{verbatim}
will fit residues $-4$ to 10 in one structure with $-1$ to 13 in the
other.

Alternatively, you may specify the zones to be fitted by giving a
sequence fragment. Together with that fragment, you may specify the
number of residues to consider starting at that point. If the fragment
occurs more than once in the sequence you may specify which occurence
you wish to consider. For example:
\begin{verbatim}
   ZONE CAR:VNS
\end{verbatim}
fits the first occurence of CAR in the reference set with first
occurence of VNS in the mobile set;
\begin{verbatim}
   ZONE CAR,10:VNS,10
\end{verbatim}
fits 10 residues starting at the  first occurence of CAR in the 
reference set with 10 residues from the first occurence of VNS in 
the mobile set;
\begin{verbatim}
   ZONE CAR,5/2
\end{verbatim}
fits 5 residues from second occurence of CAR in both structures;
\begin{verbatim}
   ZONE 24-34:EIR,ll
\end{verbatim}
fits 24-34 in the reference set with 11 residues starting at the 
first occurence of EIR in the mobile set.

By default, \pf\ works in `Residue Number' mode, i.e.\ the numbers
used in zone commands are the numbers seen in the PDB file. The
alternative mode is `Sequential' mode where residues are numbered
sequentially throughout the structure (including throughout multiple
chains). Any chain names appearing in zone specifications will be
ignored in Sequential mode. To switch mode, you use the {\tt NUMBER
SEQUENTIAL} or {\tt NUMBER RESIDUE} commands.


\subsection{Sequence Alignment}
%------------------------------
Another way of specifying zones is to let the program do it. \pf\
does not provide any facilities for calculating structural
equivalences, but does allow you to perform a simple Needleman and
Wunsch sequence alignment and to apply zones automatically derived
from that sequence alignment. This is done by issuing the \verb1ALIGN1
command. The sequence alignment is displayed, any currently active
fitting zones are cleared and replaced by zones derived from the
alignment. 

Currently the \verb1ALIGN1 command may only be used if the structures
contain only one chain.

Additional zones may also be specified in the usual way.

Clearly, it will normally be necessary to use the \verb1ATOMS1 command
to specify that only backbone or C$\alpha$ atoms are included in the
fitting.

The \verb1GAPPEN1 command allows you to specify an integer gap penalty
for the sequence alignment performed by the \verb1ALIGN1 command. The
default value is 5.


\subsection{Reading an Alignment}
%--------------------------------

If you have an alignment performed outside \pf\ you may use this to
specify the equivalent zones. Any previously defined fitting zones are
automatically cleared first. As with the \verb1ALIGN1 command, this
can currently only be used with structures having a single chain.  

The alignment should be a file in PIR format using -- characters to
align the sequences. The two sequences are represented by separate
entries, i.e.\ each must have a header of the form:
\begin{verbatim}
>P1;xxxxxx
title text .......
\end{verbatim}

If the PIR file contains multiple chains, it will be rejected. The
first sequence will be assumed to be that of the the reference 
structure and the second is that of the the mobile structure. Any
other sequences in the file are ignored.

The \verb1READALIGNMENT1 command is used to read in the PIR file.




\subsection{Limiting Zones Read From an Alignment}
%-------------------------------------------------

When obtaining fit zones from a sequence alignment, either from
ALIGN or from READALIGNMENT, it can be useful to limit the zones of
residues used. Normally all aligned residue pairs will be used.

For example, if the alignment were:
\begin{verbatim}
                       1         2         3
              123456789012345678901234567890123
              ASAHSTGEHNM--PLELLGHISLAM---NPRTY
              ---HSTADHNLRTPLEVLG--SLAMEDRQPRTY
\end{verbatim}
the zones would normally be taken from the following positions
in the alignment: 4-11, 14-19, 22-25, 29-33

By using the command:
\begin{verbatim}
      LIMIT 20 28
\end{verbatim}
only the zone from 22-25 would be included.

This is particularly useful in conjunction with the ITERATE command
(Section~\ref{subsec:iterate}) and when fitting multiple structures
(Section~\ref{sec:multi}).

The \verb|LIMIT OFF| command restores the default behaviour of
deriving the zones from the whole alignment.




\subsection{Iterative Updating of the Fitting Zones}
%---------------------------------------------------
\label{subsec:iterate}

The \verb1ITERATE1 command switches on the iterative updating of
fitted zones during subsequent \verb1FIT1 commands. The \verb1ITERATE1
command ma be followed by an optional parameter to specify the cutoff
used to include or exclude pairs from the zones.  (\verb1ITERATE OFF1
is used to switch it off again.)

Currently the \verb1ITERATE1 command may only be used if the structures
contain only one chain.

Note that this immediately does an \verb1ATOMS CA1 since iteration of
zones is only performed on C$\alpha$ atoms. The program gives an
informational message to this effect. See notes below if you want to
calculate an RMSd over other atoms.

After the initial fit on the specified zones, the zones are updated
such that residue pairs with C$\alpha$ atoms within a specified cutoff
(default 3.0\AA) are included and those more distant are excluded. The
optimum set of equivalences is obtained using a dynamic programming
method.

After updating the zones, the structures are refitted and the
procedure iterates to convergence of $<0.01$\AA, (typically 3 or 4
cycles). The RMSd on C$\alpha$ atoms is shown after each cycle unless
the \verb1QUIET1 command is given.

You may specify a minimal initial zone of say 3 amino acids on which
to fit first. The zone iteration will expand the zones until as many
residues as possible can be equivalenced. Alternatively, this option
is particularly useful in conjunction with the \verb1ALIGN1
command. Using \verb1ALIGN1 followed by \verb1ITERATE1 gives a
particularly convenient method of fitting two arbitrary structures.

As stated above, the \verb1ITERATE1 command implies 
\verb1ATOMS CA1. Having fitted on C$\alpha$ atoms, you can of course
display the RMSd over other atom sets in the usual way using the
\verb1RATOMS1 command (e.g.\ \verb1RATOMS N,CA,C,O1 will display the
backbone RMSd).

Should you wish to refit on another atom set using the iterated zones,
simply use \verb1ITERATE OFF1 to switch off iteration, select the atom
set required using the \verb1ATOMS1 command and use \verb1FIT1 to
refit the structures in the usual way. For example, to fit on backbone
atoms:

\begin{verbatim}
   ITERATE OFF
   ATOMS N,CA,C,O
   FIT
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Multiple Structure Fitting}
\label{sec:multi}

The \verb1MULTI1 command allows a multiple set of structures to be
read in for fitting. The filename specified for \verb1MULTI1 is a
`file of files' i.e.\ it contains a list of filenames which will be
read.

\verb1MULTI1 is used in place of \verb1REFERENCE1 and \verb1MOBILE1 to
read in a set of structure files. The first structure file is used as
a reference set for the first fitting stage, but the coordinates are
averaged after each fitting stage to derive an averaged template used
for subsequent fitting.

i.e.\ Given $N$ files to fit, file 2 is fitted to file 1 and an
averaged structure, $A$, is calculated, file 3 is then fitted to $A$
and a new average, $A'$ is calculated. This continues until all $N$
structures have been fitted. The whole procedure iterates until
convergence (typically 3 or 4 cycles).

Progress and RMSds are reported at each iteration unless the \verb1QUIET1
command is used.

The resulting fitted files are written with the \verb1MWRITE1 command.
Note that there is no ``reference'' set in the sense used for normal
2-structure fitting; fitted versions of all $N$ files will be written
since the reference set is actually an averaged template.

When the \verb1MWRITE1 command is used, the output filenames are the
same as the input files, but with the extension replaced by that
specified in the \verb1MWRITE1 command. If no extension is specified,
then `.fit' will be used. If the input structure files contained no
extension, then the extension specified will be appended to the
filenames.

Note that since only the extension is changed when writing back the
fitted files, you must have permission to write to the directory from
which the original files were read.

Note that multiple structure fitting and zone interation can be very
slow as these have been added to the earlier pair-wise fitting
engine. An increase in speed needs a complete re-design of the code.

\subsection{Specifying Zones With Multiple Structure Fitting}
%------------------------------------------------------------

Currently, the ZONE command may only be used with multiple structure
fitting when the same zone specification may be applied to every
structure. i.e.\ You cannot specify a zone for each structure
separating the zones with a colon (:)

Thus, the following are legal zones:
\begin{verbatim}
  ZONE 20-30
  ZONE C,3
\end{verbatim}
while the following are not:
\begin{verbatim}
  ZONE 24-34:25-35
  ZONE CAR:VNS
  ZONE 24-34:EIR,11
\end{verbatim}

For normal use, it is recommended that the ALIGN and READALIGN
commands (possibly in conjunction with the LIMIT command) are used for
specifying zones when fitting multiple structures.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Calculating the RMSd Over Other Zones and Atoms}
Having fitted the structures using the \verb1ZONE1 and \verb1ATOMS1
commands to specify which residues and atoms should be included in the
fitting, the RMS deviation may then be calculated over a different
region of the structure and/or a different atom set.

This is achieved using the \verb1RZONE1 and \verb1RATOMS1
commands. The syntax of these commands is identical to that of the
\verb1ZONE1 and \verb1ATOMS1 commands described in
Sections~\ref{sec:atoms} and~\ref{sec:zone}.

As each \verb1RZONE1 or \verb1RATOMS1 command is given, the RMS
deviation is reported over the new set of zones or over the new atom
set. Don't forget the \verb1RZONE1 commands are cummulative, like the
\verb1ZONE1 commands. Note that the \verb1RZONE *1 or \verb1RZONE1
\verb1CLEAR1 behaves slightly differently from \verb1ZONE *1 or
\verb1ZONE1 \verb1CLEAR1 since it resets the zones to be the same as
those specified for the fitting using \verb1ZONE1, \verb1ALIGN1 or
\verb1READALIGNMENT1 commands.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Obtaining Output}

\subsection{The Fitted Structure}
%--------------------------------
The fitted mobile structure may be written to a file in PDB format
using the \verb1WRITE1 command:
\begin{verbatim}
   WRITE fitted.pdb
\end{verbatim}
If the first character of the filename is a pipe character ($\mid$),
then the results will be piped into the specified program. For
example:
\begin{verbatim}
   WRITE |less
\end{verbatim}
will cause the coordinates to be displayed on the screen using the
\verb1less1 pager program.

The reference set may also be written:
\begin{verbatim}
   WRITE REFERENCE ref_fitted.pdb
\end{verbatim}
(only the three letters `REF' of the REFERENCE parameter are
required). This is only useful if the CENTRE command has been used
(see below).

\subsection{Centering the Coordinates}
%-------------------------------------
By default, the mobile structure is moved to the coordinate frame of
the reference set. If the \verb1CENTRE1 (or \verb1CENTER1) command is
given then the centre of geometry of the fitted coordinates will be
located at the origin.

If only two structures are fitted then the \verb1WRITE REFERENCE1
command must be used to write the reference set in the origin-centred
coordinate frame. If multiple structures are fitted and written using
\verb1MWRITE1 then the reference set will be written automatically.





\subsection{Details of the Fitting}
%----------------------------------

More details about the fitting may be obtained by using the
\verb1MATRIX1 command. This displays the centres of geometry, the
rotation matrix and the translation vector which is the vector between
the centres of geometry. Thus to superimpose the mobile structure onto
the reference structure using these data, you should translate the
mobile set to the origin, apply the rotation matrix, translate back to
the original centre of geometry and finally apply the translation
vector.

Note that the rotation matrix is not orthogonal and cannot therefore
be used to extract Euler angles. This is a result of the fitting
method used.

The \verb1NFITTED1 command displays the number of atom pairs which
were fitted in the last fitting operation. Note that this will not
be the number of residues fitted unless you are only fitting one
atom type per residue (typically C$\alpha$ atoms).


\subsection{By-residue RMS Deviation}
%------------------------------------

The \verb1RESIDUE1 command is used to obtain a by-residue RMS
deviation on the currently specified RMS atoms in the currently
specified RMS zone. If no \verb1RATOMS1 and \verb1RZONE1 commands have
been used, the atoms and zones used for the fitting will be used.

The \verb1RESIDUE1 command may be followed by an optional filename
parameter in which case output is directed to the specified file. If
the file cannot be opened or a filename is not specified, output
appears on the screen. If the first character of the filename is a
pipe character ($\mid$), then the results will be piped into the
specified program. For example:
\begin{verbatim}
   RESIDUE |less
\end{verbatim}
will cause the results to be displayed on the screen using the
\verb1less1 pager program.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Modifying the Fit}

Normally, no weighting is applied during the fitting i.e.\ all atoms
are weighted equally. The \verb1WEIGHT1 command causes the fitting to
be weighted by the mean of the B-values in the equivalent
atoms. Normally, you wouldn't use this with real B-values, but with
some other weight parameter (e.g.\ SSAP scores).

The \verb1BWEIGHT1 command weights the fitting by the inverse of the
mean of the B-values in the equivalent atoms. This is useful for
genuine weighting by B-values (i.e.\ the mobile set atoms will be less
heavily weighted).

The \verb1NOWEIGHT1 command switches off weighting.

Atoms can also be removed from consideration in the fitting and RMS
deviation calculations using temperature factors as a cutoff. The
\verb1BVALUE1 command allows you to specify a B-value cutoff and any
atoms with B-values greater than this value will be \emph{ignored
completely} in both the fitting and RMS deviation calculations. The
B-value may not be higher than this value in either the reference set
or the mobile set. For example, if you specify $10$, then atoms with
B-values greater than $10$ will be ignored.

By specifying a negative value for \verb1BVALUE1, you require that any
atoms with B-values less than the absolute value you specify will be
ignored. For example, if you specify $-10$, then atoms with B-values
less than $10$ will be ignored.

The value may be followed by an optional \verb1REF1 or \verb1MOB1
parameter which restricts checking of B-values to the specified
structure.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Miscellaneous Commands}

The \verb1RMS1 command may be used to reprint the RMS deviation over
the currently defined set of RMS zones and RMS atoms.

Any operating system command may be run from withing \pf\ by
preceeding it with a \verb1$1. The string following the \verb1$1 is
passed to the operating system exactly as given and is useful for
obtaining directory listings, typing, editing or copying files.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Command Summary}

\begin{description}

\item[\$ \emph{command}] Passes command to the operating system.

\item[ALIGN] Performs Needleman and Wunsch sequence alignment on the
sequences of the two structures and derives zones from the equivalent
regions in the alignment.

\item[ATOMS \emph{atm[,atm]\ldots}] Specifies the atom subset to fit.

\item[BVALUE \emph{cutoff} [ REF$\mid$MOB]] Specify a B-value
cutoff. Any atoms with B-values greater than this value will be
ignored completely. A negative cutoff specifies that atoms with
B-values less than the absolute cutoff should be ignored. The optional
\verb1REF1 or \verb1MOB1 parameter restricts B-value checking to
the specified structure.

\item[BWEIGHT] Weight the fitting by the inverse of the mean of the
B-values in the equivalent atoms.

\item[CENTER [ OFF]] See \verb1CENTRE1.

\item[CENTRE [ OFF]] Cause the coordinates to be written (using
the \verb1WRITE1 or \verb1MWRITE1 commands), with the centre of
geometry located at the origin instead of in the same coordinate frame
as the reference set.

\item[FIT] Performs the actual fitting. Returns the RMS deviation over
the atoms included in the fit.

\item[GAPPEN \emph{val}] Specify an integer gap penalty for the
sequence alignment performed by the \verb1ALIGN1 command.

\item[HETATOMS] Read HETATM records with subsequent \verb1MOBILE1 and
\verb1REFERENCE1 commands.

\item[IGNOREMISSING] Ignore any atom mismatches and proceed with the
fitting. Such atoms are listed as warnings.

\item[ITERATE [ (\emph{limit} $\mid$ OFF)]] Switches on (or off) iterative
updating of the zones for fitting. The \verb1ITERATE1 command may be
followed by an optional distance cutoff (default: 3.0\AA) or by the
keyword `OFF' to switch off iterative zone calculation.

\item[LIMIT (\emph{pos1 pos2} $\mid$ OFF)] Limits the range in an
alignment (from ALIGN or READALIGNMENT) used to derive
zones. \verb|LIMIT OFF| restores the default behaviour.

\item[MATRIX] Displays the centres of geometry, rotation matrix and
translation vector.

\item[MOBILE [ XMAS]] \emph{\bfseries filename} Reads a mobile PDB
structure.  If compiled with XMAS support, then the XMAS keyword
specifies that the input is in XMAS format.

\item[MULTI \emph{filename}] Reads a file of files containing a list
of structures for multiple fitting.

\item[MWRITE [ \emph{ext}]] Write the results of multiple structure
fitting. The structures are written back using the same filenames with
which they were read, but with the extension changed to that
specified. If no extension is given, then `.fit' is used. Note
therefore, that you must have write permission to the directory from
which the input files were read.

\item[NFITTED] Reports the number of atom pairs fitted.

\item[NOHETATOMS] Do not read HETATM records with subsequent
\verb1MOBILE1 and \verb1REFERENCE1 commands.

\item[NOIGNOREMISSING] Restore the default behaviour of issuing an
error message for any atom mismatches and halting the fitting
proceedure.

\item[NOWEIGHT] Normal, non-weighted fitting.

\item[NUMBER (RESIDUE$\mid$SEQUENTIAL)] Specifies whether zones are
based on residue numbers in the PDB file or on sequential numbering
(running through all chains).

\item[QUIET [ OFF]] Switches on (or off) quiet mode. In quiet
mode, warning messages are suppressed and progress of iterative zone
updating and multiple structure fitting is not reported.

\item[QUIT] Exits from the program.

\item[RATOMS \emph{atm[,atm]\ldots}] Specifies atoms over which to
calculate the RMS deviation. Fitting must already have been performed.

\item[READALIGNMENT \emph{filename}] Reads an alignment in PIR
sequence file format and sets zones based on that alignment.

\item[REFERENCE [ XMAS]] \emph{\bfseries filename} Reads a reference PDB
structure.  If compiled with XMAS support, then the XMAS keyword
specifies that the input is in XMAS format.

\item[RESIDUE [ \emph{filename}]] Gives a by-residue RMS deviation.
If the first character of the (optional) filename is a pipe character
($\mid$), then the results will be piped into the specified
program. For example:
\begin{verbatim}
   RESIDUE |less
\end{verbatim}
will cause the results to be displayed on the screen using the
\verb1less1 pager program.

\item[RMS] Recalculate the RMS deviation over the zones and atoms
currently defined with \verb1RZONE1 and \verb1RATOMS1.

\item[RZONE \emph{zonespec}] Adds a zone specification to the list of
zones considered in RMS deviation calculation. \verb1RZONE *1 or
\verb1RZONE1 \verb1CLEAR1 resets the zones for RMSD calculation to be
the same as that specified with the \verb1ZONE1 command.

\item[STATUS] Reports current program status.

\item[WEIGHT] Weight the fitting by the mean of the B-values in the
equivalent atoms.

\item[WRITE [ REFerence]] \emph{\bfseries filename} Writes the fitted structure
to a PDB file. If the first character of the filename is a pipe
character ($\mid$), then the results will be piped into the specified
program. For example:
\begin{verbatim}
   WRITE |less
\end{verbatim}
will cause the coordinates to be displayed on the screen using the
\verb1less1 pager program.

If the \verb1REFERENCE1 keyword is given (only the letters `REF' are
required), then the reference set will be written. This is used in
conjunction with the \verb1CENTRE1 command.

\item[ZONE \emph{zonespec}] Adds a zone specification to the list of
zones considered in fitting. \verb1ZONE *1 or \verb1ZONE1 \verb1CLEAR1
removes all zone specifications.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Copyright}

Please note that the program is called \pf\ --- not PROFIT, Profit or
profit; this attempts to avoid confusion with the threading program
known as PROFIT. \pf\ was written first and released to the public
around the same time.

\pf\ was initially written by me while self-employed and trading as
{\sffamily SciTech Software}. As such it is owned by me alone. Under
the conditions of the copyright statement included in the code,
enhancements made since at UCL also become my property.

\begin{quotation}
This program is not in the public domain.

It may not be copied or made available to third parties, but may be
freely used by non-profit-making organisations and commercial
companies who have obtained it directly from the author or by FTP or
HTTP from the author's web sites.

If you did not register the program via the web site, you are
requested to send EMail to the author to say that you are using this
code so that you may be informed of future updates.

The code may not be made available on other FTP or Web sites without
express permission from the author.

The code may be modified as required, but any modifications must be
documented so that the person responsible can be identified. If
someone else breaks this code, the author doesn't want to be blamed
for code that does not work! You may not distribute any modifications,
but are encouraged to send them to the author so that they may be
incorporated into future versions of the code.

Such modifications become the property of Dr.\ Andrew C.R.\ Martin and
{\sffamily SciTech Software} though their origin will be acknowledged.

While the compiled \pf\ program may be used by commercial companies,
it may not be sold commercially or included as part of a commercial
product. The source code or any derivative works may not be sold
commercially or used for commercial purposes outside of \pf\ without
prior permission from the author.
\end{quotation}

This manual was written while at UCL and updated while at Reading as
part of consultancy work to Inpharmatica. It is based on the help file
included with the program. As such it is joint property of Andrew
Martin, UCL and Inpharmatica.
\vspace{2em}

While this software is provided ``as is'' and free of charge, I
do appreciate hearing from people who use it and find it useful. An
EMail or a postcard would be nice.

If you find \pf\ useful, please tell your colleagues about it. Please
\emph{do not} pass copies of \pf\ on to them directly; ask them to
obtain it \emph{via} my World Wide Web page
(\verb1http://www.bioinf.org.uk/software/profit1)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{How do I Reference \pf?}

No paper has been published describing \pf\ itself since it is simply
a convenient program (I hope) to let you use a standard fitting
algorithm; consequently, it is a little difficult to reference. The
exact wording is up to you and dependent on the context, but I suggest
something similar to:

\begin{quotation}
Fitting was performed using the McLachlan algorithm (McLachlan, A.D.,
1982 ``Rapid Comparison of Protein Structres'', Acta Cryst A38,
871-873) as implemented in the program ProFit (Martin, A.C.R.,
\verb1http://www.bioinf.org.uk/software/profit/1) 
\end{quotation}

\end{document}
