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

.. program:: posit

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

Input Options
-------------

.. option:: -dbase <filename>

   Input molecules to pose-predict.  3D molecules must be input as
   conformational expansion is not performed prior to fitting.

   :option:`-dbase` is the fastest way to
   run **POSIT** on large datasets. The expected input is a
   pre-generated database of **OMEGA**
   generated conformers.

   .. code-block:: console

     > omega2 -in renin/all.smi -out all.oeb.gz -rangeIncrement 1 \
        -maxConfRange 200,200,300,400,500,600,700,800,900,1000,1100,1200,1300,1400,1500,1600

     > posit -receptor receptor.oedu -dbase all.oeb.gz

   Supported input file formats are:

    ============   ===========================
    File type      Extension
    ============   ===========================
    OEBinary       .oeb .oeb.gz
    ------------   ---------------------------
    SDF            .sdf .mol .sdf.gz .mol.gz
    ------------   ---------------------------
    MOL2           .mol2 .mol2.gz
    ------------   ---------------------------
    PDB            .pdb .ent .pdb.gz .ent.gz
    ============   ===========================

   [Aliases=**-db**,**-database**]

.. option:: -molnames

      This flag specifies a text file with the names of one or more molecules in
      supplied to the :option:`-dbase` flag.  If specified, only molecules with matching
      names will be read by the :option:`-dbase` flag.  If this flag is not specified all
      molecules will be read normally.  Molecules names should be listed one per line.

      The general purpose of this flag is to provide an easy mechanism for reading
      a few specific molecules that are contained in a large database, without
      having to extract those molecules by hand from the database.


Multiprocessing Options
-----------------------

.. include:: ../../common/mpi_execute_options.irst


Dock Options
------------

.. option:: -ignore_nitrogen_stereo

   When examining the ligands to pose predict for stereo, ignore any
   missing nitrogen chirality.  (This is normally caused by time
   averaging of crystal structures).

   When expanding stereo, nitrogen stereo centers will not be assigned.

   **POSIT** now always expands missing stereo.

   .. note::

      **POSIT** may complain about stereo centers being changed by the
      optimization, this is more likely when ignoring nitrogen stereo
      centers since the optimization may decide a different stereo
      configuration is optimal.

   [Default=true]

   [Aliases=**-ignoreNitrogenStereo**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetIgnoreNitrogenStereo <OEDocking_OEPositOptions_SetIgnoreNitrogenStereo>` in the **OEDocking TK** manual.

.. option:: -minimum_probability

   Minimum probability for poses of interest. **POSIT** only outputs poses
   that has the minimum required probability.  To output all poses,
   set :option:`-minimum_probability` to 0.

   [Default=0.33]

   [Aliases=**-minProbability**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetMinProbability <OEDocking_OEPositOptions_SetMinProbability>` in the **OEDocking TK** manual.

.. option:: -allowed_clashes

   Clashes allowed in the generated poses. There are three levels:

   =============   ===========================================
   Allowed Clash   Description
   =============   ===========================================
   noclashes       No clashes are allowed.
                   Actually there is a little wiggle room here
                   less than 0.2 |A| penetration is not
                   considered a clash.
   -------------   -------------------------------------------
   mildclashes     Clashes involving hydrogen are allowed, but
   hclashes        those between heavy atoms are disallowed.
   -------------   -------------------------------------------
   allclashes      All clashes are allowed.
   =============   ===========================================

   All poses that are accepted by the probability calculation yet clash with
   the protein are written to the fail file (if specified).

   [Default=mildclashes]

   [Aliases=**-allowedClashes**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetAllowedClashType <OEDocking_OEPositOptions_SetAllowedClashType>` in the **OEDocking TK** manual.

.. option:: -relax

   Flag indicating if post pose prediction relaxation should be performed. The
   relaxation is performed by allowing flexibility to the ligand and parts of
   the receptor. Turning on relaxation can significantly slow down the calculations.
   There are three options:

   =============   ===========================================
   Relax Mode      Description
   =============   ===========================================
   none            No relaxation is performed.
   -------------   -------------------------------------------
   clashed         Relaxation is performed on poses that
                   contains clashes.
   -------------   -------------------------------------------
   all             Relaxation is performed on all poses.
   =============   ===========================================

   [Default=none]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetPoseRelaxMode <OEDocking_OEPositOptions_SetPoseRelaxMode>` in the **OEDocking TK** manual.

.. option:: -num_poses

   Number of alternative poses to be generated for each docked molecule.  The default
   is to only generate a single most probable pose.

   [Default=1]

   [Aliases=**-numposes**]

.. option:: -best_Receptor_Pose_Only

   If this flag set to ``false`` the pose prediction is performed using all of the
   receptors and the best set of poses from all of the receptors combined is provided
   as the results. With the default setting of ``true`` pose prediction is only performed
   on the ``best receptor`` for any given ligand. Note that, setting the flag to ``false``
   could increse the runtime significantly depending on the number of receptors used
   for the calculation.

   [Default=true]

   [Aliases=**-bestReceptorPoseOnly**]

   .. seealso::

      * :ref:`OEDocking::OEPositOptions::SetBestReceptorPoseOnly <OEDocking_OEPositOptions_SetBestReceptorPoseOnly>` in the **OEDocking TK** manual.

Output File Options
-------------------

**POSIT** writes docked structure results to a single file,
:option:`-docked_molecule_file` -- Ligand only output in one file.

By default, not all poses may be written to the output, to see
where ligands were placed, consult the log file for more details.
To control this behavior use the :option:`-outputall` flag, which
writes all output to the file specified by :option:`-docked_molecule_file` in order
of input molecule.

.. option:: -docked_molecule_file <filename>

   If specified, this flag overrides the default name of the docked molecule
   output file.  Only .oedu, .oeb, and .oeb.gz formats are allowed. An .oedu
   file is generated by default, and is the preferred output format.

   .. note::

      The default file is posit_docked.oedu, or
      <-prefix>_docked.oedu if the :option:`-prefix` flag is specified.

   Ligands are written to the output file based on the desired
   sort order (see the :option:`flynn -sortBy` flag).

   [Aliases=**-docked_mol_file**,**-docked_file**,**-docked**,**-out**]

.. option:: -undocked_molecule_file

    If specified this flag overrides the default name for the undocked molecule
    file.

    .. note::

       The default filename is posit_undocked.oeb.gz, or
       <-prefix>_undocked.oeb.gz if :option:`-prefix` is specified.

   [Aliases=**-undocked_mol_file**,**-undocked_file**,**-undocked**]

.. option:: -score_file

    If specified overrides the default name of the output text file containing
    the scores of the docked molecules.

    .. note::

       The default filename is posit_score.txt or <-prefix>_score.txt if the
       :option:`-prefix` flag is specified.

   [Aliases=**-scorefile**,**-score**]

.. option:: -report_file

    If specified  overrides the default output filename for the report file.

    .. note::

       The default filename for the report file is posit_report.txt or
       <-prefix>_report.txt if the :option:`-prefix` flag is specified.

   [Aliases=**-report**]

.. option:: -status_file

    If specified overrides the default filename for the status file.

    .. note::

       The default status file name is posit_status.txt or
       <-prefix>_status.txt if the :option:`-prefix` flag is specified.

   [Aliases=**-statusfile**,**-status**]

.. option:: -rejected_file

    If specified overrides the default filename for the reject file.

    The reject file is a tab separated file containing the
    input ligand number, the ligand title and the reason for
    the ligand being undocked.

    Example output:

    .. code-block:: none

       Ligand #        Title#Status
       0       lig1    No conformers above minimum probability
       1       lig2    No conformers above minimum probability
       2       lig3    No conformers above minimum probability
       3       lig4    No conformers above minimum probability

    .. note::

       The default status file name is posit_rejected.txt or
       <-prefix>_rejected.txt if the :option:`-prefix` flag is specified.

   [Aliases=**-rejected**]

.. option:: -settings_file

    If specified overrides the default output filename for the setting file.

    .. note::

       The default settings filename is posit_settings.param or
       <-prefix>_settings.param if the :option:`-prefix` flag is specified.

   [Aliases=**-settingsfile**,**-settings**]

.. _clash_file:

.. option:: -clashed_molecule_file <filename>

   Occasionally **POSIT** rejects ligands that probably have the correct binding mode
   but also display uncorrectable clashes.  If this
   flag is set, clashed molecules will be written to this file in no specific
   output order.

   It is important to be aware that because these are likely binding
   modes there is a chance that the clashed poses are still correct but the
   protein has reconfigured to accept the clashed pose.

   [Aliases=**-clashed_mol_file**,**-clashed_file**,**-clashed**,**-clash**]

Output Options
--------------

.. option:: -score_tag

   Overrides the default tag used to attach the score to the
   output molecules

   [Aliases=**-scoretag**]

.. option:: -no_extra_output_files

   Suppress the default output of the score, status,
   settings, report and undocked files.

   [Aliases=**-no_extra**,**-noextra**,**-noextraoutputfiles**,**-no_extra_output**,**-noextraoutput**]

.. option:: -no_dots

   Suppress writing a dot (.) to standard error for each docking
   molecule (or *x* in the case of a failure).

   [Aliases=**-nodots**]

.. option:: -prefix

   The text passed to this parameter will be preappended to all
   default output filenames (it does not affect output filenames explicitly
   set by the users).

   [Default=posit]

.. option:: -outputall

   Shorthand to write all output including clashed or nonprobable molecules.

.. option:: -verbose

   Set verbose output for logging.

   [Default=false]
