This section describes commands for dealing with Cartesian
coordinates of a 3D model: for reading, writing, creating and
transforming them.


\Command      {READ\_MODEL}{read coordinates for MODEL}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{name of the coordinates' file} 
\OptLine{ATOM_FILES_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MODEL_SEGMENT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MODEL_FORMAT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{WATER_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HETATM_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HYDROGEN_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION}  
}

\Description  {This command reads the atomic coordinates, atom 
names, residue names, residue numbers, isotropic temperature factors
and segment specifications for MODEL, assigns residue types, and defines
the dihedral angles listed in the {\tt \$RESDIH\_LIB} library.
For \V{CHARMM} and \V{UHBD} file formats, it also reads the atomic 
charges. However, it does not assign \CHARMM\ and \MODELLER\ atom types, 
internal coordinates, charges (in the case of the \Z{PDB} format), or patches 
(such as disulfides); to make these assignments, which are necessary for 
almost all energy commands, use \C{GENERATE\_TOPOLOGY}. All real and pseudo 
atoms are selected. The PDB residue type \Z{HIS} is assigned the
\CHARMM\ residue type \Z{HSD}, which is the neutral His with H on ND1.
The PDB types \Z{ASP} and \Z{GLU} are assigned the corresponding charged
\CHARMM\ residue types, as are \Z{LYS} and \Z{ARG}. These conventions
are relevant only if electrostatic terms and/or hydrogens are used.

\K{MODEL\_SEGMENT} sets the beginning and ending residue identifiers 
for the contiguous sequence of residues to be read from the PDB file 
(this option does not work yet for the other file formats). The format 
of residue identifiers is described in Section~\ref{alignmentformat}. 
In addition, the following rule applies: If there is no `:' in the first
residue specification, the segment specification is taken from the 
alignment entry with the specified code. Similarly, if there is 
no `:' in the second residue specification, the PDB filename is taken
from the alignment entry with the specified code. The two codes do 
not have to be the 
same. For example, \K{MODEL\_SEGMENT} = \Z{4ape} \Z{4ape} will take the
segment specification and atom filename for entry \V{4ape} in the
alignment.
}

\Example{../examples/commands/read_model.top}



\Command      {READ\_MODEL2}{read coordinates for MODEL2}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{name of the coordinates' file} 
\OptLine{ATOM_FILES_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MODEL2_SEGMENT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MODEL_FORMAT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{WATER_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HETATM_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HYDROGEN_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command reads a coordinate file for MODEL2. See
the description of the \C{READ\_MODEL} command for more information. 
The ability to have a second, independent set of coordinates in memory is 
used in conjunction with the \C{SUPERPOSE}, \C{TRANSFER\_\-RES\_\-NUMB}, 
\C{REORDER\_ATOMS} and some other commands, as well as for changing 
the format of the atom file.
}
 
\SeeExample{\C{READ\_MODEL}}



\Command      {WRITE\_MODEL}{write MODEL}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{name of the coordinates' file} 
\OptLine{OUTPUT_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MODEL_FORMAT}{TYPE}{VALUES}{DEFAULT}{selects output atom file type: 
        \Z{PDB} \OR\ \Z{CHARMM} \OR\ \Z{UHBD} \OR\ \Z{GRASP}}
\OptLine{WRITE_ALL_ATOMS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{NO\_TER}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {MODEL}

\Description  {This command writes the current MODEL to a file in the
selected format. If the file format is \Z{PDB}, only the selected atoms 
are written out when \K{WRITE\_ALL\_ATOMS} = \V{off}; otherwise all 
atoms are written out.

The \Z{GRASP} format is the same as the \Z{PDB} format, except that it 
includes two special lines at the top of the file
and the atomic radii and charges in the columns following the
Cartesian coordinates of atoms. This format is useful for input to
program \GRASP, written by Anthony Nicholls in the group of Barry Honig
at Columbia University \cite{NicShaHon91}.
}

\SeeExample{\C{READ\_MODEL}}




\Command      {WRITE\_MODEL2}{write MODEL2}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{name of the coordinates' file} 
\OptLine{OUTPUT_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MODEL_FORMAT}{TYPE}{VALUES}{DEFAULT}{selects output atom file type: 
         \Z{PDB} \OR\ \Z{CHARMM} \OR\ \Z{UHBD} \OR\ \Z{GRASP}}
}

\Requirements {MODEL2}

\Description  {This command writes MODEL2 to a file in the selected format.
}

\SeeExample{\C{READ\_MODEL}}


\Command      {BUILD\_MODEL}{build MODEL coordinates from topology}     

\Options{
\OptLine{INITIALIZE\_XYZ}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{RAND\_SEED}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{BUILD\_METHOD}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {topology file \AND\ parameters file \AND\ MODEL topology}

\Description  {This command builds Cartesian coordinates of the MODEL.

If \K{INITIALIZE\_XYZ} is \V{on}, all coordinates are built. Otherwise
only the undefined coordinates are built. The latter is useful because
some coordinates may be undefined after the \C{READ\_MODEL} or 
\C{TRANSFER\_XYZ} command.
The undefined coordinates have a value of $-999.$ when written to
a PDB file.

If \K{BUILD\_METHOD} is \Z{INTERNAL\_COORDINATES},
the Cartesian coordinates are built from the
ideal values of the internal coordinates as obtained from the IC
entries in the residue topology library. If an appropriate IC entry does
not exist, the ideal value of the internal coordinate is calculated
from the corresponding energy term in the parameter library. If some
coordinates still cannot be built, they are set to values
close to those of the neighboring atoms. If even this fails, they
are set randomly.

If \K{BUILD\_METHOD} is \Z{3D\_INTERPOLATION},
the Cartesian coordinates are built by linearly interpolating between the
two defined atoms that span the contiguous undefined segment of atoms.
In this mode, both the mainchain and sidechain conformations of
all inserted residues are random and distorted. This build-up mode 
is useful because it may eliminate a knot and minimize the 
extended nature of the insertion obtained by \K{BUILD\_METHOD} = 
\Z{INTERNAL\_COORDINATES}. In the end, the coordinates of each of the
interpolated atoms are slightly randomized ($\pm 0.2\Ang$) to prevent 
numerical problems with colinear angles and colinear dihedral angles.
If one or both of the spanning atoms are undefined, the \Z{ONE\_STICK} 
option (below) is used.

If \K{BUILD\_METHOD} is \Z{ONE\_STICK}, the Cartesian coordinates are 
built by ``growing'' them linearly out of the N-terminal spanning atom
(C-terminal atom for the undefined N-terminal), away from the gravity center 
of all the defined atoms. If there is no spanning atoms, the spanning atom 
is defined randomly. 

If \K{BUILD\_METHOD} is \Z{TWO\_STICK}, the loop is broken into two equal 
pieces and the \Z{ONE\_STICK} algorithm is applied to both halves of the 
loop separately.
}


\Example{../examples/commands/build_model.top}


\Example{../examples/commands/all_hydrogen.top}





\Command      {TRANSFER\_XYZ}{copy templates' coordinates to MODEL}

\Options{
\OptLine{CLUSTER\_CUT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{CLUSTER\_METHOD}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ATOM\_FILES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ATOM\_FILES\_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{WATER\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HETATM\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{HYDROGEN\_IO}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {alignment and MODEL}

\Description  {This command transfers coordinates of the equivalent atoms 
and their isotropic temperature factors from the template structures to
MODEL.
   
The alignment has to be in memory. The target sequence
is the last protein in the alignment and has to be the same as the
MODEL sequence. The template structures are all
the other proteins in the alignment.
  
Before transferring coordinates, the template structures generally have to be
explicitly least-squares superposed onto each other. This is most conveniently
achieved with the \C{MALIGN3D} command called just before
\C{TRANSFER\_XYZ}. This is an important difference relative to
\MODELLER-3, which did not require explicit superposition by the user.
Note, however, that the {\tt 'model'} script does this superposition 
automatically.

If \K{CLUSTER\_CUT} is less than 0, the transferred coordinates for a given 
target atom are the average of the coordinates of all the equivalent template 
atoms. Otherwise, the transferred coordinates are the average of the
templates in the largest cluster of the atoms. This cluster is obtained
as follows (it only works when all templates and the target have exactly the 
same topology): For each residue position separately, calculate the maximal 
inter-template equivalent atom--atom distances (\K{CLUSTER\_METHOD} = 
\Z{MAXIMAL\_DISTANCE}) or atomic \RMS\ deviation (\K{CLUSTER\_METHOD} = 
\Z{RMSD}) for all template--template 
comparisons. Use the weighted pair-group average clustering
method (the same as in the \C{DENDROGRAM} command) to obtain the clustering
tree for the given residue position. Find the clusters that contain 
residues joined above \K{CLUSTER\_CUT} angstroms (1\Ang\ is a good value). 
Use the largest cluster in the averaging for the target coordinates.
The number of residue positions at which each template contributes to 
the consensus is written to the \logf\ file
(\Z{The largest cluster occupancy}). Sometimes the first template contributes
many more times than the rest of the templates. This results from having many
residue positions where all ``clusters'' have one template only (the first 
cluster/template is then picked by default). This artifact can be corrected by 
specifying a larger \K{CLUSTER\_CUT}.

Both kinds of averaging, but especially the cluster averaging,
are useful for deriving a consensus model from an ensemble of models 
of the same sequence. If the consensus model is optimized by the conjugate
gradients method, it frequently has a significantly lower value of the 
objective function than any of the contributing models. Thus, the
construction of a consensus model can also be seen as part of an 
efficient optimization. The reason why consensus construction 
frequently results in better models is that the
consensus model generally picks the best (\ie, most frequent) 
conformation for the regions that are variable in the individual 
models, while it is very unlikely that a single model will have
optimal conformation in all of the variable regions. The consensus
construction may not work when two or more locally optimal conformations
are inconsistent with each other (\eg, because of the atom overlaps).

Two atoms are equivalent if they have exactly the same name and are 
in the equivalent residues. Note that the {\tt \$ATMEQV\_LIB} library of
equivalent residue--residue atom pairs, which is used in the construction 
of homology-derived distance restraints, is not used here. The atom 
names in the target may not correspond to the atom names in the template 
files. In such a case, if you want to copy the template atoms' coordinates, 
you have to edit the atom names in the template atom files so that they 
correspond to the \MODELLER\ atom names (which you can see in the {\tt .ini} 
atom file). At least for water molecules, this is usually better than
letting the optimizer deal with grossly incorrect starting positions.

The atoms with undefined coordinates in MODEL are flagged by setting the
coordinates to $-999$. The coordinates of the undefined 
atoms of the MODEL can be set with the \C{BUILD\_MODEL} command,
which relies on the internal coordinates specified in the residue
topology library or on various types of geometric interpolation
and extrapolation.
}  


\Example{../examples/commands/transfer_xyz.top}



\Command      {TRANSFER\_RES\_NUMB}{residue numbers from MODEL2 to MODEL}

\Options{
\OptLine{ALIGN\_CODES}{\String}{2}{DEFAULT}{MODEL2 code, MODEL code} 
}

\Requirements {MODEL \AND\ MODEL2 [\AND\ alignment]}

\Description  {This command transfers residue numbers and chain ids from 
MODEL2 to MODEL. It uses the current alignment if present, otherwise 
a 1:1 correspondence is assumed. MODEL2 and MODEL must correspond to
the first and second protein in the alignment, respectively. 
The \K{ALIGN\_CODES} variable is used only for output to the 
\logf\ file, not in the calculation. Both MODEL and MODEL2 must already be 
in memory.}


\Example{../examples/commands/transfer_res_numb.top}




\Command      {RENAME\_SEGMENTS}{rename MODEL segments}

\Options{
\OptLine{SEGMENT\_IDS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{RENUMBER\_RESIDUES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {MODEL}

\Description  {This command re-labels residue numbers in each chain
(\ie, segment) so that they start with \K{RENUMBER\_RESIDUES}[iseg].
In addition, the single character PDB chain id's are also assigned:
They are obtained from the corresponding elements of \K{SEGMENT\_IDS}.
Thus, there should be as many elements in \K{SEGMENT\_IDS} and
\K{RENUMBER\_RESIDUES} as there are chains in the current MODEL.
}


\Example{../examples/commands/rename_segments.top}




\Command      {PICK\_ATOMS}{select atoms in MODEL}

\Options{
\OptLine{PICK\_ATOMS\_SET}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SELECTION\_SEARCH}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{RES\_TYPES}{TYPE}{VALUES}{DEFAULT}{residue type selection: 
         \Z{ALL} \OR\ \Z{HET} \OR\ \Z{STD} \OR\ \CHARMM\ 4-letter codes}
\OptLine{ATOM\_TYPES}{TYPE}{VALUES}{DEFAULT}{atom type selection:
\Z{ALL} \OR\ \Z{SDCH} \OR\ \Z{MNCH} \OR\ IUPAC atom names}
\OptLine{SELECTION\_FROM}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SELECTION\_MODE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SELECTION\_STATUS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\bull\ For \K{SELECTION\_SEARCH} = \Z{SEGMENT}: \\
\OptLine{SELECTION\_SEGMENT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{GAP\_EXTENSION}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MAX\_LOOP\_LENGTH}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
{\bull\ For \K{SELECTION\_SEARCH} = \Z{SPHERE}:} \\
\OptLine{SPHERE\_CENTER}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SPHERE\_RADIUS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SELECTION\_SLAB}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
{\bull\ For \K{SELECTION\_SEARCH} = \Z{SPHERE\_SEGMENT}:} \\
\OptLine{SELECTION\_SEGMENT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{GAP\_EXTENSION}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SPHERE\_RADIUS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description{This command adds atoms to, removes atoms from, or initializes 
any one of the three independent sets of selected atoms of MODEL. There
are three selection sets because it is convenient to have different 
sets used by different \MODELLER\ commands.

\K{PICK\_ATOMS\_SET} specifies the set of selected atoms. Set 1 is 
used in the \C{PICK\_RESTRAINTS}, \C{ROTATE\_DIHEDRALS}, \C{RANDOMIZE\_XYZ}
and \C{MUTATE\_MODEL} commands. Sets 2 and 3 are used in the 
\C{MAKE\_RESTRAINTS} command. 

\K{SELECTION\_STATUS} determines whether the selected atoms are added 
(\Z{ADD}), removed (\Z{REMOVE}), or a set is
initialized and then the selected atoms are added (\Z{INITIALIZE}).

The selection of atoms is a hierarchical two level process.
The first level of selection consists of specifying how the
atoms will be scanned. The second level consists of
selecting by the specified atom and residue names.

How the atoms are scanned is specified by setting the \K{SELECTION\_SEARCH} 
variable to either \Z{SEGMENT}, \Z{SPHERE}, or \Z{SPHERE\_SEGMENT}:

\begin{enumerate}  
\item \Z{SEGMENT} mode: Only a single stretch of residues specified by the 
beginning and ending residue identifiers in \K{SELECTION\_SEGMENT} 
(Section~\ref{alignmentformat}) is scanned.
Alternatively, if \K{SELECTION\_SEGMENT}[1] has the special value \Z{LOOPS} 
only residues in loops are scanned. Loops are defined as those
residues in the MODEL that are aligned with only gap positions
in the templates (MODEL has to be the last sequence in the current 
alignment), are within \K{GAP\_POSITIONS}[1] of an insertion in MODEL, or
are within \K{GAP\_POSITIONS}[2] positions of a deletion in MODEL, and 
are not in a loop segment longer than \K{MAX\_LOOP\_LENGTH}.
This selection mode is useful for automatic selection of loops to be 
refined by the loop modeling procedure.

\item \Z{SPHERE} mode: Only those atoms that are closer than \K{SPHERE\_RADIUS}
angstroms to the \K{SPHERE\_CENTER} atom, after the center atom was 
translated by $(xtrans, ytrans, ztrans)$ angstroms specified in 
\K{SELECTION\_SLAB}[3:5], are scanned. If the first element of 
\K{SPHERE\_CENTER} is 
string \Z{INDEX}, the second element is an integer atom index of the center 
atom; otherwise, the first and second element are the residue identifier 
(Section~\ref{alignmentformat}) and the IUPAC atom name, respectively. 
\K{SELECTION\_SLAB}[1:2] specifies the interval on the $Z$-axis relative
to the $Z$ coordinate of the translated central atom that imposes another 
condition on the selected atoms: $Zcen+dz1 < Z+ztrans < Zcen+dz2$. Larger 
$Z$ values are in front, so $dz1$ specifies the plane that is further away 
than the $dz2$ plane. To pick any atoms, $dz1 < dz2$.

\item \Z{SPHERE\_SEGMENT} mode: Only atoms within a sphere around the atoms 
in the specified segment of residues are scanned. This is useful, for 
example, when a 
neighborhood of a loop needs to be selected. As for the \Z{SEGMENT} mode,
if \K{SELECTION\_SEGMENT}[1] has the special value \Z{LOOPS}, only
loop atoms are scanned for their neighbours.
\end{enumerate}  

If \K{SELECTION\_FROM} is \Z{SELECTED}, scanning specified above is
restricted only to the atoms that were already selected before
calling \C{PICK\_ATOMS}.

Once the method for scanning the atoms is specified, each of the scanned
atoms is checked against the specified atom name(s) (\K{ATOM\_TYPES})
and residue name(s) (\K{RES\_TYPES}). If \K{SELECTION\_MODE} is
\Z{RESIDUE}, all atoms in a residue with at least one atom that matches
both the residue and atom name criteria are selected. Otherwise,
only those atoms that have both the specified residue and atom names are 
selected. The \K{RES\_TYPES} and \K{ATOM\_TYPES} keywords can contain several
residue and atom names in one quoted string or in several quoted strings. 
For example, both \Z{CA} \Z{N} and \Z{CA N} are valid specifications selecting 
the CA and N atoms. The following groups of residues and atoms are defined:

\begin{itemize}
\item If \K{RES\_TYPES} contains word \Z{ALL}, all residues
will be selected.

\item If \K{RES\_TYPES} contains word \Z{HET}, all `HETATM' residues
will be selected (\eg, all residue types with the \MODELLER\ residue code 
larger than 27; see library \$RESTYP\_LIB). 

\item If \K{RES\_TYPES} contains word \Z{BLK}, all `BLK' residue types 
will be selected (Section~\ref{SECTION:block}).

\item If \K{RES\_TYPES} contains word \Z{STD}, all standard residue types 
will be selected. Standard residue types are all residue types but 
`HETATM' and `BLK' types. 

\item If \K{ATOM\_TYPES} contains word \Z{ALL}, all atoms
will be selected.

\item If \K{ATOM\_TYPES} contains word \Z{MNCH}, all mainchain
atoms will be selected. Mainchain atoms are N, C, CA, O, and OXT. 

\item If \K{ATOM\_TYPES} contains word \Z{SDCH}, all sidechain
atoms will be selected. Sidechain atoms are all non-mainchain
atoms, including non-mainchain atoms in `HETATM' and `BLK' residues.
\end{itemize}
}


\Example{../examples/commands/pick_atoms.top}






\Command      {PICK\_HOT\_ATOMS}{pick atoms violating restraints}

\Options{
\OptLine{VIOL\_REPORT\_CUT}{TYPE}{VALUES}{DEFAULT}{cutoffs for selecting violated restraints} 
\OptLine{PICK\_HOT\_CUTOFF}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{SELECTION\_MODE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{EXTEND\_HOT\_SPOT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION}
\rule{6.5mm}{0cm} The \C{ENERGY} command keywords
}

\Description  {This command selects those selected atoms (set 1) in the MODEL 
that should be optimized to remove hot spots in the MODEL; only selected 
restraints are considered.

More precisely, the command first flags
violated selected atoms. An atom is violated if it is part of a violated
restraint. A restraint of physical group $i$ (Table~\ref{tab:physrsrtypes}) 
is violated when its 
relative deviation from the optimal value is larger than specified in
\K{VIOL\_REPORT\_CUT}[i]. For restraints that are based on probability 
density functions, relative violation is defined as the difference
between the actual and the ideal values divided by the standard deviation 
(`relative heavy violation'); energy based restraints have
{\it ad hoc} definition of violations (Table~\ref{tab:restrtypes}).

The command then flags those selected atoms that are within the 
\K{PICK\_HOT\_CUTOFF} angstroms of any of the already flagged atoms. 

Next, if \K{SELECTION\_MODE} is \Z{RESIDUE}, all atoms in the residues 
that have at least one atom flagged are also flagged. In addition, the
contiguous segments of flagged residues are 
extended for \K{EXTEND\_\-HOT\_\-SPOT} residues on either side.

This command is usually followed by the \C{PICK\_RESTRAINTS} 
and \C{OPTIMIZE} commands to select all the restraints that operate
on selected (hot) atoms and optimize positions of these hot atoms.

In addition to the keywords above, all the keywords for the \C{ENERGY} 
command also apply here.
}


\Example{../examples/commands/pick_hot_atoms.top}





\Command      {RANDOMIZE\_XYZ}{randomize MODEL coordinates}

\Options{
\OptLine{DEVIATION}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{RAND\_SEED}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command randomizes the Cartesian coordinates of the 
selected atoms (set 1) in MODEL. If \K{DEVIATION} is positive,
the coordinates are randomized by the {\it addition} 
of a random number uniformly distributed in the interval from
$-\K{DEVIATION}$ to $+\K{DEVIATION}$ angstroms. If \K{DEVIATION} is
negative, the coordinates are {\it assigned} a random value
uniformly distributed in the interval from $-\K{DEVIATION}$ to 
$+\K{DEVIATION}$ angstroms.
}



\Example{../examples/commands/randomize_xyz.top}




\Command      {IUPAC\_MODEL}{standardize certain dihedral angles}

\Requirements {MODEL}

\Description  {This routine swaps specific pairs of atoms within some
residues of MODEL so that certain dihedral angles are within $\pm 90$\degr,
satisfying the IUPAC convention \cite{IUPAC70,KenKlyLif70}. 
These residues, pairs of atoms, and dihedral angles are:
\begin{itemize}
\item Phe, Tyr: (CD1, CD2), (CE1, CE2); $\chi_2$;
\item Asp: (OD1, OD2); $\chi_2$;
\item Glu: (OE1, OE2); $\chi_3$;
\item Arg: (NH1, NH2); $\chi_4$.
\end{itemize}

It is possible that for distorted sidechains, neither of the two
possibilities satisfies the IUPAC convention. In such a case, a 
warning message is written to the \logf\ file.
}


\Example{../examples/commands/iupac_model.top}


\Command      {REORDER\_ATOMS}{standardize order of MODEL atoms}

\Requirements {topology library \AND\ MODEL}

\Description  {This routine reorders atoms within the residues
of MODEL so that they follow the order in the current residue topology 
library.
}


\Example{../examples/commands/reorder_atoms.top}





\Command      {ROTATE\_DIHEDRALS}{change dihedral angles} 

\Options{
\OptLine{DIHEDRALS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{CHANGE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{DEVIATION}{TYPE}{VALUES}{DEFAULT}{amplitude of dihedral angle randomization} 
\OptLine{RAND\_SEED}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Requirements {\ \\
    \mbox{for \K{CHANGE}=\Z{OPTIMIZE}: topology \AND\ MODEL \AND\ restraints} \\
    \mbox{for \K{CHANGE}=\Z{RANDOMIZE}: topology \AND\ MODEL} }

\Description{This command changes the dihedral angles in MODEL.

\K{CHANGE} selects an optimization (when equal to \Z{OPTIMIZE}) or
randomization (when equal to \Z{RANDOMIZE}):

\begin{enumerate}
\item When optimizing, this command finds the first selected restraint 
that restrains the specified dihedral angle of each selected residue. 
It then sets the value of that dihedral to the most likely value.
A residue is selected if any of its atoms is in the set 1 of selected
atoms. 

\item When randomizing, the command changes the specified dihedral angle 
of each selected residue by adding a random value distributed uniformly 
from $-\K{DEVIATION}$ to $+\K{DEVIATION}$ degrees. The value of the random 
seed variable, \K{RAND\_SEED}, is changed after returning from the 
\K{RANDOMIZE} command. Use a negative integer from $-2$ to $-50000$ as 
the seed for the random number generator.
\end{enumerate}
  
\K{DIHEDRALS} can be either a vector of dihedral angle names or a
single string containing all the dihedral angle names separated by 
blanks. The dihedral angles involved in cyclic structures are not changed
(\eg, sidechain dihedral angles in disulfide bonds and prolines).
The dihedral angles that can be changed are listed at the top
of the \V{\$RESDIH\_LIB} library: {\tt alpha, phi, psi, omega,
chi1, chi2, chi3, chi4, chi5}. Dihedral angle \Z{alpha} is the 
virtual \Calpha\ dihedral angle defined by four consecutive
\Calpha\ atoms.
  
The bond connectivity of the MODEL has to exist before this command
is executed. If you read in the model by \C{READ\_MODEL}, the bond
connectivity is defined by subsequent calls to \C{READ\_TOPOLOGY} and 
\C{GENERATE\_TOPOLOGY} (also make sure that \K{SEQUENCE} entry does 
not exist in the alignment or that no alignment is in memory).
}


\Example{../examples/commands/rotate_dihedrals.top}





\Command      {ORIENT\_MODEL}{center and orient MODEL}

\Description  {This command translates the MODEL so that its gravity center
is at the origin of the coordinate system and that the 
three principal axes of the model's inertia ellipsoid 
correspond to the $x$, $y$, and $z$ axes of the coordinate system.
It may even be used for approximate superposition if
molecules have a similar non-spherical shape. Information about
the principal axes is written to the \logf\ file.
}


\Example{../examples/commands/orient_model.top}





\Command      {ROTATE\_MODEL}{rotate and translate MODEL}

\Options{
\OptLine{TRANSLATION}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ROTATION\_MATRIX}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ROTATION\_ANGLE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ROTATION\_AXIS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command transforms the Cartesian coordinates of MODEL.

Translation is specified by a translation vector \K{TRANSLATION} 
and is done first.

Rotation is specified by a rotation matrix \K{ROTATION\_MATRIX} that 
is given as a vector of 9 elements (three rows times three columns),
with column index running first: $a_{11}, a_{12}, a_{13}, a_{21}, a_{22}, 
a_{23}, a_{31}, a_{32}, a_{33}$. The rotation matrix 
pre-multiplies the Cartesian coordinate vectors. The matrix corresponds to 
the view matrix of \QUANTA\ and to the rotation matrix of \MOLSCRIPT.

The second kind of rotation is specified by a screw transformation,
given by the \K{ROTATION\_AXIS} axis and \K{ROTATION\_ANGLE} rotation
around the axis (in degrees). This is done last.

If only some transformations are desired, set the other values to 0.
}


\Example{../examples/commands/rotate_model.top}





\Command      {WRITE\_DATA}{write derivative MODEL data}
\label{COMMAND:writedata}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{root of output filename(s)} 
\OptLine{ACCESSIBILITY\_TYPE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION}
\OptLine{TOPOLOGY\_MODEL}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION}
\OptLine{RADII\_FACTOR}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION}
\OptLine{PSA\_INTEGRATION\_STEP}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION}
\OptLine{PROBE\_RADIUS}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION}
\OptLine{OUTPUT}{TYPE}{VALUES}{DEFAULT}{what to calculate and write out:
\Z{ALL} \OR\ \Z{PSA} \OR\ \Z{ATOMIC\_SOL} \OR\ \Z{NGH} \OR\ \Z{DIH} \OR\ \Z{SSM} \OR\ \Z{CRV}}
}

\Requirements {topology file \AND\ TOPOLOGY\_MODEL}

\Description  {This command writes the selected types of data about the
MODEL to a corresponding file and to the `fourth' column of the model.
The root of the output filenames is given by the \K{FILE} variable. In 
addition to the output files, the $B_{\mbox{iso}}$ field of the model (`fourth
column' in the PDB file) will be assigned the last selected property from
the following list: atomic or residue accessibility, dihedral type 
\K{ACCESSIBILITY\_TYPE} (from 1 to 9 for $\alpha$, $\Phi$, $\Psi$, 
$\omega$, $\chi_1$, $\chi_2$, 
$\chi_3$, $\chi_4$, and $\chi_5$; where $\alpha$ is the virtual 
dihedral angle between four successive \Calpha\ atoms), number of 
residue neighbors, the secondary structure type, and the local mainchain 
curvature. For accessibility, when \K{OUTPUT} contains \V{ATOMIC\_SOL}, 
atomic accessibilities in $\Ang^2$ are assigned to $B_{\mbox{iso}}$, 
otherwise residue accessibility of type \K{ACCESSIBILITY\_TYPE} (from 1 
to 10, for the columns in the {\tt .psa} file) is assigned.

The data to be calculated are specified by concatenating the 
corresponding keywords in the \K{OUTPUT} variable:

\begin{itemize}
\item \Z{ALL}: All types of data are written to the corresponding files.

\item \Z{PSA}: The atomic and residue solvent accessibilities are
written to the {\tt .sol} and {\tt .psa} files, respectively. The algorithm
for the solvent contact areas is described in \cite{RicRic78}. The
normalization for the fractional areas is carried out as described in 
\cite{HubBlu87}, with the normalization factors courtesy of Simon Hubbard
(personal communication). The single reference is
\citen{SalOve94}. Accessibilities are calculated with scaled radii from 
the \V{\$MODELS\_LIB} library, as specified by \K{TOPOLOGY\_MODEL}. The 
radii are scaled by \K{RADII\_FACTOR}, which should usually be set to 1.

\item \Z{NGH}: Residue neighbors of each residue are listed to a {\tt .ngh} 
file. The \MODELLER\ definition of a residue--residue contact used in
restraints derivation is applied \cite{SalBlu93}: Any pair of residues 
that has any pair of atoms within 6\AA\ of each other are in contact.

\item \Z{DIH}: All the dihedral angle types defined in the {\tt
\$RESDIH\_LIB} library (virtual \Calpha, mainchain, and sidechain 
dihedral angles) are written to a {\tt .dih} file. 

\item \Z{SSM}: Secondary structure assignments are written to a {\tt .ssm} 
file. The algorithm for secondary structure assignment depends on the
\Calpha\ positions only and is based on the distance matrix idea
described in \cite{RicKun88}. For each secondary structure type, a `library' 
\Calpha\ distance matrix was calculated by averaging distance matrices for 
several secondary structure segments from a few high resolution protein 
structures. Program \DSSP\ was used to assign these secondary structure 
segments \cite{KabSan83}. % ({\tt ~/modeller/progs/ss/prog\_for\_average\_ss}).
Outlier distances were omitted from the averaging. Currently, there
are only two matrices: one for the $\alpha$-helix (secondary structure
type 2) and one for the $\beta$-strand (type 1). The algorithm for
secondary structure assignment is as follows:

\begin{enumerate}
\item For each secondary structure type (begin with a helix, which can
      thus overwrite parts of strand if they overlap):

   \begin{itemize}
   \item Define the degree of the current secondary structure fit for each 
         \Calpha\ atom by \DRMS\ deviation ($P_1$) and maximal distance 
         difference 
         ($P_2$) obtained by comparing the library distance matrix with
         the distance matrix for a segment starting at the given \Calpha\ 
         position;
  
   \item Assign the current secondary structure type to all \Calpha's
         in all segments whose \DRMS\ deviation and maximal distance 
         difference are 
         less than some cutoffs ($P_1<cut_1$, $P_1<cut_2$) and are not 
         already assigned to `earlier' secondary structure types;
   \end{itemize}

\item Split kinked contiguous segments of the same type into separate segments:

      Kinking residues have both DRMS and maximal distance difference beyond
      their respective cutoffs ($P_1>cut_3$, $P_2>cut_4$). The actual single 
      kink residue separating the two new segments of the same type is the 
      central kinking residue. Note: we are assuming that there are no multiple 
      kinks within one contiguous segment of residues of the same secondary 
      structure type. The kink residue type is $-2$.

\item If the current secondary structure type is $\beta$-strand: Eliminate 
      those runs of strand residues that are not close enough to other
      strand residues separated by at least two other residues: $P_3$ is 
      minimal distance to a non-neighboring residue of the strand type 
      ($P_3 < cut_3$). Currently, only one pass of this elimination is done,
      but could be repeated until self-consistency.

\item Eliminate those segments that are shorter than the cutoff ($cut_6$)
      length (\eg, 5 or 6).

\item Remove the isolated kinking residues (those that occur on their own
      or begin or end a segment).
\end{enumerate}

\item \Z{CRV}: Local mainchain curvatures are written to a {\tt .crv} 
file. Local mainchain curvature at residue $i$ is defined as
the angle between the least-squares lines through \Calpha\ atoms 
$i-3$ to $i$ and $i$ to $i+3$. 
\end{itemize} 
}


\Example{../examples/commands/write_data.top}

\Command      {WRITE\_PDB\_XREF}{write residue topology library}
\label{write-topology-model}

\Options{
\OptLine{FILE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{OUTPUT\_DIRECTORY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{MODEL\_SEGMENT}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ALIGN\_CODES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{ATOM\_FILES}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command writes the correspondence between the 
PDB residue numbers and residue indices for the selected part of
the MODEL. It is more useful than one would think because of
its interaction with the alignment data and the option to use
wild characters to specify the beginning and ending residues.
}

\Example{../examples/commands/write_pdb_xref.top}



\Command      {MAKE\_REGION}{define a random surface patch of atoms}
\label{write-topology-model}

\Options{
\OptLine{ATOM\_ACCESSIBILITY}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{REGION\_SIZE}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
\OptLine{RAND\_SEED}{TYPE}{VALUES}{DEFAULT}{DESCRIPTION} 
}

\Description  {This command defines a contiguous patch of exposed
atoms of the specified size. First, the exposed atoms in MODEL are 
identified by using the \K{ATOM\_ACCESSIBILITY} cutoff (in $\Ang^2$).
The seed atom is picked randomly among the exposed atoms. The patch
is expanded by iteratively adding the exposed atom that is closest
to the gravity center of the currently selected patch atoms. Thus,
the patch is defined deterministically once the seed atom is picked.
The patch is defined by setting the fourth column parameter ($B_{iso}$) 
to 1 for the patch atoms and to 0 for the remaining atoms. The
``temperature'' color option of Rasmol can be used to display the
patch graphically.

To obtain surface patches that look good in visual inspection,
it is necessary to use a non-obvious scaling factor for atomic radii and 
probe radius for solvent calculation by \C{WRITE\_DATA}, as well as the 
accessibility cutoff for \C{MAKE\_REGION}.
}

\Example{../examples/commands/make_region.top}

\vfill
