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

.. _scorepose:

***************
ScorePose
***************

.. program:: scorepose

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

:ref:`SCOREPOSE` scores poses in a :option:`-dbase` database in the context
of a single :ref:`receptor <receptor_theory>`, using the
:ref:`theory_algorithm_chemgauss4` scoring function.  Poses may also optionally
be optimized with the :option:`-optimize` option vs. :ref:`theory_algorithm_chemgauss4`.

.. note::

  :ref:`SCOREPOSE` does not dock molecules, it only rescores and optionally
  optimizes molecules within the context of a :ref:`receptor <receptor_theory>` site.


.. _scorepose_ligand_preparation:

Input Preparation
===================

Ligand Preparation
------------------

The ligand input to :ref:`SCOREPOSE` should already be docked into the
:ref:`receptor <receptor_theory>` site.  For the purposes of this document, we'll
call the file(s) of poses to be scored the database file(s), or dbase file(s).
Supported formats of the database file include SDF, MOL2 and PDB.
:ref:`SCOREPOSE` determines the database file format from the file extension,
:file:`.sdf` or :file:`.mol` for SDF, :file:`.mol2` for MOL2, :file:`.pdb` or
:file:`.ent` for PDB. Gzip compressed files of these same formats are allowed
as well. :ref:`SCOREPOSE` will interpret :file:`infile.sdf.gz` as a gzip'ed
SDF file.

.. note::

   Note that even though all these formats are supported, using SDF, PDB or MOL2
   can result in a loss of speed due to the I/O penalty of these formats.  We
   recommend using Gzipped OEB format for maximum speed.

By default :ref:`SCOREPOSE` will interpret conformers in the database file(s)
as part of a single multi-conformer molecule as long as they:

* Are contiguous in the input file.
* Have the same numbers of atoms and bonds in the same order
* Have identical atom and bond properties with their order
  correspondent in the subsequent connection table
* Have the same atom and bond stereochemistry

While this may appear to be a restrictive list, many programs write
multi-conformer molecules into SDF or MOL2 files such that the above rules
will be satisfied. If the conformers are named differently, (*i.e.* they
have a conformer number appended to the base name like acetsali_1,
acetsali_2), :ref:`SCOREPOSE` will still consider them part of a single
multi-conformer molecule if the criteria above are met.

Receptor Preparation
--------------------

.. note::

  Beginning with :ref:`SCOREPOSE` 4.0.0,  :ref:`SCOREPOSE` now only accepts an OEDU with receptor as the
  receptor input file.

:ref:`SCOREPOSE` requires the :ref:`receptor<receptor_theory>` file that the
ligands in the database were docked to.  This should generally already be available
if the ligands were docked with :ref:`chapter_fred` or :ref:`chapter_hybrid`.  If the ligands were
docked with another program a receptor can be created using one of the following
programs.

.. tabularcolumns:: |l|l|p{10cm}|

=======================================  ============  ==========================================
Program                                  Type          Description
=======================================  ============  ==========================================
:ref:`chapter_makereceptor`              GUI           Interactive GUI for creating a receptor.
---------------------------------------  ------------  ------------------------------------------
:ref:`ReceptorInDU`                      Command Line  Generates a receptor inside a prepared
                                                       OEDesignUnit in an OEDU file.
---------------------------------------  ------------  ------------------------------------------
:ref:`OEB2DUReceptor`                    Command Line  Converts a molecule based receptor OEB or
                                                       OEB.GZ file into a receptor inside
                                                       an OEDesignUnit, in an OEDU file
=======================================  ============  ==========================================

.. note::

   Receptors can also be created using the OpenEye Docking Toolkit (see the
   Docking Toolkit documentation).

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

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

.. code-block:: console

   > scorepose --help

will generate the following output:

::

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


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

.. option:: -receptor <receptor file>

   Receptor file to rescore poses with.

   [Aliases=**-rec**]

.. option:: -dbase <input filename1> [<input filename2> ...]

   File(s) containing ligand poses to rescore
   (see section :ref:`scorepose_ligand_preparation`).

   The following file formats are supported.

   ============ ===========================
   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
   ------------ ---------------------------
   MacroModel   .mmod .mmod.gz
   ============ ===========================

   More than one file can be specified.

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

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

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

.. include:: common_flags/flag_param.rstinc

.. include:: common_flags/flag_molnames.rstinc


Score Options
-------------

.. option:: -optimize <level> [No Default]

   If this parameter is specified each pose will be optimized with a systematic solid
   body optimization with a resolution given by the table below.

   ========= ====================== ===================
   Level     Translational Stepsize Rotational Stepsize
   ========= ====================== ===================
   High      0.5 Ångström           0.5 Ångström
   Standard  0.5 Ångström           0.75 Ångström
   Low       0.75 Ångström          1.0 Ångström
   ========= ====================== ===================

   If this parameter is not specified poses will not be optimized prior to scoring.

   [Aliases=**-opt**]

   .. seealso::

      * :ref:`OEDocking::OEDockOptions::SetResolution <OEDocking_OEDockOptions_SetResolution>` in the **OEDocking TK** manual.

Output Files
------------

.. option:: -prefix <value> [Default=rescore]

   This flag prefixes all default output filenames with the specified value.

   .. note::

      This flag does not affect output filenames explicitly set by the user.

.. note::

   Values in parenthesis are default values.

.. option:: -rescored_molecule_file <output filename> [Default=scored.oeb.gz]

   File rescored molecules will be written to.  The file format is
   controlled by the extension of the filename.  The following output
   formats are supported.

   ================ ===========================
   Format           Extension
   ================ ===========================
   OEBinary         .oeb
   ---------------- ---------------------------
   SDF              .sdf
   ---------------- ---------------------------
   Gzipped OEBinary .oeb.gz
   ---------------- ---------------------------
   Gzipped SDF      .sdf.gz
   ================ ===========================

   Scores will be attached as SD data to each pose with the tag
   **FRED Chemgauss4 Score**, unless the :option:`-score_tag` option is used
   to specify another tag.

   By default the top 500 scoring molecules will be outputted to this
   file (see :option:`-hitlist_size` flag).

   .. note::

      If this flag is not set by the user the default filename (i.e., scored.oeb.gz)
      will be automatically prefixed with the setting of the
      :option:`-prefix` flag.

   [Aliases=**-rescored_mol_file**,**-rescored_file**,**-rescored**,**-out**]

.. include:: common_flags/flag_score_file.rstinc

.. include:: common_flags/flag_report_file.rstinc

.. include:: common_flags/flag_settings_file.rstinc

.. include:: common_flags/flag_status_file.rstinc

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

.. option:: -hitlist_size <num>    [Default=500]

   This parameter controls whether docked molecules are outputted as they are
   docked or in an internal hitlist and outputted at the end of the run.

   If -hitlist_size is zero the run will be in serial mode, i.e. each molecule
   will be outputted as it is docked (unsorted).  For single processor runs this
   will be the order the molecules appear in the database file(s).  For
   MPI runs the order will not be strictly the order the molecules appear in the
   database file(s).

   If -hitlist_size is non-zero a sorted internal hitlist of docked molecules
   that will be maintained and outputted at the end of the run.  The maximum
   size of the hitlist is -hitlist_size.  If more than this number of molecules
   are docking during the run only the top scoring molecules will be outputted
   and the rest will be discarded.

   There is no formal limit on the number of molecule that can be sorted
   and outputted at the end of the run.  However, retaining a large
   number of molecules significantly increases the memory requirements.
   A good rule of thumb is that the setting total number of poses retained
   should not be larger than 10,000.

   [Aliases=**-hitlist_size**,**-hitlist**]

.. option:: -sort_poses    [Default=false]

   If this option is selected the poses of each molecule will be sorted by score.

   If the molecules in the database do not have multiple poses this flag has no
   effect.

   [Aliases=**-sortposes**]

.. option:: -score_tag <tag>  [No Default]

   This parameter overrides the default SD Data Tag used to store molecule
   scores (the default is **FRED Chemgauss4 Score**).

   [Aliases=**-scoretag**]

.. include:: common_flags/flag_annotate_scores.rstinc

.. include:: common_flags/flag_save_component_scores.rstinc

.. option:: -no_extra_output_files    [Default=false]

    When set the only default output to the program will be the docked structure
    file (see :option:`-rescored_molecule_file`).

    Using this flag suppresses the default output of the following

    ====================== ================== ===================================
    Output                 Default file       Parameter
    ====================== ================== ===================================
    text score file        score.txt          :option:`-score_file`
    ---------------------- ------------------ -----------------------------------
    report file            report.txt         :option:`-report_file`
    ---------------------- ------------------ -----------------------------------
    settings file          settings.param     :option:`-settings_file`
    ---------------------- ------------------ -----------------------------------
    status file            status.txt         :option:`-status_file`
    ====================== ================== ===================================

    Only default output is suppressed.  If any of these output parameters are
    explicitly set by the users the relevant output file will still be written
    even if this switch is turned on.

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

.. include:: common_flags/flag_no_dots.rstinc
