\section{Tutorial on using \MODELLER\ for comparative modeling}\index{tutorial}
\label{SECTION:tutorial}

This section is a `hands on' description of the most basic use of 
\MODELLER\ in comparative modeling. For an outline of the main
stages in comparative modeling, see Section~\ref{SECTION:primer}.
For ``frequently-asked-questions'' (FAQ), see Section~\ref{SECTION:faq}.
An introductory, hands-on primer to comparative modeling with several 
\MODELLER\ examples can be found in \citen{SanSalRev98}.

The input are Protein Data Bank (PDB) atom files of known 
protein structures and their alignment with the target sequence to be
modeled. The output is a model for the target that includes all
non-hydrogen atoms. Although \MODELLER\ can calculate sequence and 
structure alignments, it is better to prepare the alignment
carefully by other means.  The alignment can also contain very short
segments such as loops, secondary structure motifs, \etc.

This tutorial assumes that \MODELLER\ is already installed on your
computer and that appropriate changes have been made to your login
script to install you as a \MODELLER\ user. See
Section~\ref{SECTIONinstall} for more details on
installation (also in the {\tt INSTALLATION} file in the 
\MODELLER\ distribution directory).


\subsection{Preparing input files}

The sample input files in this tutorial can be found in the 
{\tt examples/tutorial-model} directory of the \MODELLER\ distribution. 

There are three kinds of input files: Protein Data Bank
atom files with coordinates for the template structures, the alignment
file with the alignment of the template structures with the
target sequence, and the \MODELLER\ command or script file that tells 
\MODELLER\ what to do.

\subsubsection{Atom files}

Each atom file is named {\tt code.atm} where {\tt code} is a short protein
code, preferably the PDB code; for example, {\it Peptococcus aerogenes} 
ferredoxin would be in a file {\tt 1fdx.atm}. The code must be used as 
that protein's identifier throughout the modeling. The atom sets do
not have to be superposed by the user before comparative modeling
is done.

\subsubsection{Alignment file}\index{alignment}

One of the formats for the alignment file is related to the PIR database
format; this is the preferred format for comparative modeling:

\longpage

\verbatimfile{../examples/tutorial-model/alignment.ali}

See Section~\ref{alignmentformat} for a detailed description of the
alignment file format and Section~\ref{SECTION:editalignment} for the 
meaning of the alignment in \MODELLER. Influence of the alignment on the 
quality of the model cannot be overemphasized. Command \C{CHECK\_ALIGNMENT} 
can be used to find some trivial alignment mistakes.

\subsubsection{Script file}\index{script file}

The script file contains commands for \MODELLER, in the 
\TOP\ language (Chapter~\ref{CHAPTERTOP}). A sample script file 
{\tt model-default.top} to produce one model of sequence {\tt 1fdx} from 
the known structure of {\tt 5fd1} and from the alignment between the 
two sequences is

{\small
\verbatimfile{../examples/tutorial-model/model-default.top}
}

See Section~\ref{model-script} for information on the {\tt model}
script and its arguments.


\subsection{Running \MODELLER}

To run \MODELLER\ with the script file {\tt model-default.top}, execute the 
following command:

\begin{verbatim}
    mod model-default
\end{verbatim}

A number of intermediary files are created as the program proceeds. After 
about 30 seconds on a Pentium III workstation, the final {\tt 1fdx} model 
is written to file {\tt 1fdx.B99990001}. Examine the {\tt model-default.log} 
file for information about the run. In particular, one should always
check the output of the \C{CHECK\_ALIGNMENT} command, which you can
find by searching for `{\tt chkaln}'. Also, check for warning
and error messages by searching for `{\tt \_W>}' and `{\tt \_E>}',
respectively. There should be no error messages; most often, there are 
some warning messages that can usually be ignored.


\subsection{Fully automated comparative modeling}

Fully automated comparative modeling requires only the target sequence
and the coordinates of templates.
The structural alignment of the known 3D structures and their alignment
with the target sequence is derived automatically. However, the single
most important factor that determines the quality of a model is the 
quality of the alignment. If the alignment is
incorrect, the model will also be incorrect. \textbf{For this reason,
the fully automated option for comparative modeling should not be used unless
the sequences are so similar that the calculated alignment is likely to be 
correct (this usually requires more than 50\% sequence identity).} 
Instead, the alignment should be carefully inspected, optimized 
by hand, and checked by the \C{CHECK\_ALIGNMENT} command before 
used in modeling (Section~\ref{SECTION:primer}). 
Moreover, several iterations of alignment 
and modeling may be necessary in general. See Section~\ref{SECTION:primer} 
for an outline of a general comparative modeling case.

The sample input files for fully automated comparative modeling are located 
in directory \\ {\tt examples/align-model-steps}. The sample \TOP\ file is

\verbatimfile{../examples/align-model-steps/model-default.top}

\vspace{3mm}

\noindent The {\tt alignment.seg} file is

\verbatimfile{../examples/align-model-steps/alignment.seg}


\subsection{Improved modeling of loops in \MODELLER-6}

See Section~\ref{SECTION:loops} for more information.
