.. include:: substitutions
.. include:: ../apps-substitutions

.. program:: rotfit

.. _chapter_rotfit:

***************
RotFit
***************

====================
Overview
====================

**RotFit** is a side-chain fitting tool that quickly fits sidechains to 
the surrounding density.  Currently only a MTZ file can be used for
density Side chains can be fit using several techniques:

  1. Using the most probably rotamers and ranking based on 
     real space correlation (RSCC) to the density.

  2. pep-flipping the rotamer and ranking on RSCC.

  3. Full MMFF/Shape fitting in to the density.

By default **RotFit** searches the rotamers and pep-flips.

For **RotFit** to apply a changed residue, their has to have an
increase in RSCC and be above a minium value (currently 0.4).
Additionally, the RSCC must be greater by a minimum amount (0.05).

=================
Example Commands
=================


====================
Command Line Help
====================

A description of the command line interface can be obtained by executing ROTFIT
with the `--help` option.

.. code-block:: console
   
   > rotfit --help


will generate the following output:

::

  Help functions:
    rotfit --help simple      : Get a list of simple parameters
    rotfit --help all         : Get a complete list of parameters
    rotfit --help defaults    : List the defaults for all parameters
    rotfit --help <parameter> : Get detailed help on a parameter
    rotfit --help html        : Create an html help file for this program
    rotfit --help versions    : List the toolkits and versions used in the application


====================
Required Parameters
====================

.. option:: -in <proteinfile>

  Input protein structure.  The side chains of this protein will be optimized.

  [Aliases=**-prot**,**-protein**]

.. option:: -map <mtz file>

  The input MTZ file to fit side chains against.

  [Aliases=**-grid**,**-density**]

.. option:: -out <protein>

  The protein structure with optimized side chains will be outputted to this file.

.. option:: -param <parameter filename>

   A parameter file is a text file that lists parameter settings to be used
   during a run.   If a parameter is specified both on the command line and in
   the parameter file, the value specified on the command line is used.

   The format of the parameter file is as follows:

   * One parameter per line.

   * For non-list parameters one key-value pair per line.

   * For list parameters a key followed by all the values.

   * Boolean parameters must be listed as a key followed by true or false.

   * The parameter file may not contain the :option:`-param` parameter.

   * Lines beginning with # are considered comments.

   [Aliases=**-com**]

.. option:: -verbose <true or false>

   Ouptuts copious extra information.

   [Default=false]


====================
Optional Parameters
====================

.. option:: -fixup_rotamers <true or false>

   Search the most probable rotamers and choose the one that fits best to
   the surrounding density.

   [Default=true]

   [Aliases=**-fixup-rotamers**]

.. option:: -fixup_pepflips <true or false>

   Search the pep-flips and pick the one that fits best to the surrounding
   density.

   [Default=false]

   [Aliases=**-fixup-pepflips**] 

.. option:: -fixup_shapefit_residues <true or false>

   Use MMFF/Shape to fit the residue into the surrounding density.
   Normally it is best to use **-fixup_rotamers** in conjunction with
   this flag.

   [Default=false]

   [Aliases=**-fixup-shapefit-residues**]

.. option:: -minimum_rscc <number>

   For a give residue if the best tested RSCC of any conformation is below this
   value the residue will not be modified.  This prevents optimization from
   happenening when the is no density anywhere near the side chain.

   [Default=0.4]

.. option:: -minimum_rscc_increase <number>
   
   For a given residue if the best tested RSCC of any conformation is not this
   much better than the starting conformation, then the residue will not be
   modified.

   [Default=0.05]

   [Aliases=**-increase**]

.. option:: -autoMTZ <true or false>

   Automatically try to open the mtz file using the DELWT and
   FDELWT columns from REFMAC5 mtz files.

   See :ref:`OESystem_OEReadMTZ` and
   :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` in **OEChem TK** for map and
   column conventions.

   [Default=true]

.. option:: -Fc <columnname>

   Column to use for Fc.  *Note, to load arbitrary columns, you can use the **-Fc**
   and **-Phic** columns and the **Fc** maptype.*

   [Default=FC]

.. option:: -Fdelwt <columnname>

   Column to use for Fdelwt or difference map amplitudes

   See :ref:`OESystem::OEMTZMapType::Fdelwt <OESystem_OEMTZMapType_Fdelwt>` in **OEChem TK** for map
   type details.

   [Default=DELFWT]

.. option:: -Fobs <columnname>

   Column to use for FObs.

   [Default=F]

   [Aliases=**-Fo**]

.. option:: -Phi <columnname>

   Column to use for Phi.

   [Default=PHI]

.. option:: -Fwt <columnname>

   Column to use for Fwt or regular map amplitudes.

   See :ref:`OESystem::OEMTZMapType::Fwt <OESystem_OEMTZMapType_Fwt>` in **OEChem TK** for map
   type details.

   [Default=FWT]

.. option:: -Phic <columnname>

   Column to use for Phic.

   [Default=PHIC]

.. option:: -Phidelwt <columnname>

   Column to use for Phdelwt or difference map phases.

   [Default=PHDELWT]


.. option:: -Phiwt <columnname>

   Column to use for Phwt or regular map phases.

   [Default=PHWT]

.. option:: -SigmaA <columnname>

   Column to use for SigmaA.
