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

.. program:: rocs 

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

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


Input Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -mcquery
 
   Combine contiguous conformers in :option:`-query` file into a
   multi-conformer query molecule, following the same rules for
   combining sequential conformers in the :option:`-dbase` file. By
   default, this is false and each connection table in the
   :option:`-query` file is treated as a separate query. Labelling 
   the conformer by adding a wart to the name 
   can be set using the :option:`-qconflabel` parameter.

   [Default=false]

.. option:: -scdbase

   Don't combine contiguous conformers in :option:`-dbase` file into
   a multi-conformer molecule. 

   .. note::

      For :file:`.oeb` files that store a
      multi-conformer molecule directly, this switch has no effect. 

   [Default=false]

General Output Options
^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -prefix <name>

   Prefix used to name output files. Using :samp:`-prefix FOO` will
   create a hits structure file named like :file:`FOO_hits_1.sdf` and
   a report file, :file:`FOO_1.rpt`, where :samp:`_1` will be
   replaced by a sequential number corresponding to the index of the
   query in the :option:`-query` file. Additionally, a parameter file
   containing all options for the current run will be written to
   :file:`FOO.parm`. This parameter file can be used with the
   :option:`-param` switch. 

   [Default=rocs]

.. option:: -outputdir <dirname>

   Output directory for output files. The directory specified by this parameter
   must exist otherwise it will be ignored.

.. option:: -besthits <N>

   Search entire dbase file and keep a hitlist, sorted
   by score given by :option:`-rankby` switch. Size of hitlist is determined by
   integer value N. Note that all members of the hitlist must pass the
   :option:`-cutoff`, if given, so the final size can be smaller than the N
   requested. This switch is ignored if :option:`-maxhits` is given. Note, that if
   this is set to zero (0) and :option:`-maxhits` is also zero (0), then no 
   hitlist will be maintained and all results will be streamed directly to 
   the respective output files.  

   [Default=500]

.. option:: -cutoff <F>

   Cutoff (F) to determine whether a specific
   overlay should be considered good enough for hitlist inclusion. This
   is a floating point value and the actual parameter used for the
   scoring is as defined by the :option:`-rankby` switch. 

   [Default=-1.0]

.. option:: -rankby <score>

   Score to use for ranking the hitlist. Legal values include: 

   * TanimotoCombo
   * ShapeTanimoto (tanimoto)
   * ColorTanimoto
   * RefTverskyCombo
   * RefTversky (tverskyq)
   * RefColorTversky        
   * FitTverskyCombo
   * FitTversky (tverskyd)
   * FitColorTversky
   * Overlap (overlap)

   [Default=TanimotoCombo]

.. option:: -maxconfs <N>

   Maximum number of overlays returned for each
   comparison of a dbase molecule with a query molecule. This defaults to 1.
   As an example, if the query has ``n`` conformers and a given dbase
   molecule has ``m`` conformers, then a total of ``nxm`` overlays
   will be performed. By default, the single best one (1) will be returned 
   (if it passes any :option:`-cutoff` given).  Choosing an alternate value for
   :option:`-maxconfs` will cause up to the top ``N`` of these overlays to be 
   returned and merged into the hitlist. In the hitlist, these conformers will
   not be associated with each other. Throughout a run, some can drop off the
   hitlist while others remain. 

   [Default=1]

.. option:: -maxhits <N>

   Maximum number of hits to return. This option causes ROCS to finish
   as soon as N molecules are in the hitlist. Useful for a quick check
   of a query to see what hits it is finding; this option overrides
   any value for :option:`-besthits`. 

   [Default=0]

Hits Output Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -conflabel

   Controls where the conformer index from a database molecule gets labeled on output molecules.  
   The allowed values are none, title, sdtag, and both.

   [Default=title]

.. option:: -qconflabel

   Controls whether the conformer index from a query molecule gets labeled on output molecules.  
   The allowed values are none and title.

   [Default=title]

.. option:: -outputquery

   Put the query structures at the top of the 
   output structure file. This is very useful for keeping the query structure
   in the same file as the hits, so that for instance, you only need to load
   one file into VIDA to browse the results. For a grid query, a copy of the 
   grid will be written to PREFIX\_ref.grd, where PREFIX is defined by the
   :option:`-prefix` commandline option.
   
   [Default=true]

.. option:: -nostructs

   Don't write a structure file. There are times when all you really
   want are the numerical results from ROCS. If you don't want or need
   an output structure file, you can prevent its creation with this
   switch.

   [Default=false]

.. option:: -hitsfile <filename>

   Instead of writing to :file:`PREFIX_hits_n.sdf` (for example) where
   PREFIX is provided by the :option:`-prefix` commandline flag, write all hit
   structures to the file provided with this flag. Can be a filename
   or full/relative path.  Also, if the name provided is actually a
   molecule file format extension (i.e. .sdf, .mol2.gz, .oeb, etc.),
   ROCS will write to :file:`stdout` using the format derived from the file
   extension. For example if the following is used:

   .. code-block:: bash

      -hitsfile .sdf

   then ROCS will write all the hits out to :file:`stdout` in SDF format.
  
   Note that this option will only work for a single query. If more
   than one query is provided along with the :option:`-hitsfile` option, ROCS will 
   issue an error and stop.


.. option:: -oformat <extension>

   Format for the output structure file(s). This option gives a file
   extension to be used for all output structure files.  The format
   for the file is determined from the extension. Valid values include
   all the molecule file formats listed in the table above for
   :option:`-query` files.

   [Default=oeb.gz]

.. option:: -sdTags

   This parameter controls whether to attach score information to output molecules as SD data. 


Report Output Options 
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -reportfile <filename>

   Instead of writing to :file:`PREFIX_n.rpt` where PREFIX is provided
   by the :option:`-prefix` commandline flag, write all report
   information (stats) to the file provided with this flag. Can be
   filename or full/relative path. Note that if more than one query
   molecule is provided, this flag will not work unless the
   :option:`-report` flag is also set to :samp:`one` to put all report
   info into one report file.

.. option:: -report

   Controls report file generation. The default, :samp:`each`, writes a
   separate report file for each query in the :option:`-query` file. If
   :samp:`one` is chosen, stats for multiple queries in the same
   :option:`-query` file will be placed in a single report file. This is
   useful for computing a NxN comparison of a file as both the dbase
   and query. Finally, to prevent ROCS from writing report files, use
   :samp:`none`. 

   [Default=each]

.. option:: -stats

   Determines which stats get placed into report files.  Values
   include :samp:`hits` (the default), :samp:`best` and :samp:`all`.
   The default is to include just the stats for the compounds in the
   hitlist. If :samp:`best` is chosen, the report file will include
   stats for the best overlay(s) for every dbase molecule. The number
   of best overlay score is determined by the value of
   :option:`-maxconfs`.  Finally, if :samp:`all` is given, stats for
   every single overlay will be placed in the report file. Be
   careful. For a multi-conformer query against a large dbase file,
   :samp:`all` can generate a HUGE amount of data.

   [Default=hits]

Status Output Options 
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -statusfile <filename>

   Instead of writing to :file:`PREFIX_n.status` where PREFIX is provided
   by the :option:`-prefix` commandline flag, write all status
   information to the file provided with this flag. Can be
   filename or full/relative path. Note that if more than one query
   molecule is provided, the status written to this file is only for the
   most recently processed query.

.. option:: -status

   Controls status file generation. The default, :samp:`each`, writes a
   separate status file for each query in the :option:`-query` file. If
   :samp:`one` is chosen, the status for multiple queries in the same
   :option:`-query` file will be placed in a single status file.
   Note that if more than one query
   molecule is provided, the status written to this file is only for the
   most recently processed query.
   Finally, to prevent ROCS from writing status files, use
   :samp:`none`. 

   [Default=each]

Log Output Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -logfile <filename>

   Filename for log file. Overrides log filename created from :option:`-prefix`.

.. option:: -progress <method>

   Method for showing job progress on the command line. Choices include:

   * percent - show a percent complete progress bar (DEFAULT)
   * log     - echo the log message for each molecule
   * logoutput - write each log line to screen
   * dots    - show dots
   * none    - print nothing to console 

.. option:: -verbose


   Add extra verbosity to log file.

Shape Options
^^^^^^^^^^^^^^^^^^^^^^
   [Aliases=**-v**]

.. option:: -tanimoto_cutoff <F>

   Flag that can be used to limit output hits to only those with some
   minimum shape score. This can be used regardless of which score is
   chosen (:option:`-rankby`) for ranking the hitlist. For example, using:

   .. code-block:: bash
  
      -rankby TanimotoCombo -cutoff 1.1 -tanimoto_cutoff 0.6


   any molecule with Shape Tanimoto <= 0.6 will not be
   retained. Additionally, the constraint on TanimotoCombo to be at
   least 1.1 implies that Color Tanimoto must also be > 0.5 so that
   the sum can be greater than 1.1.

   [Default=0.0]

.. option:: -randomstarts <N>
   
   Specifies number (N) of random starting positions to try instead of
   inertial frame overlay as described in the theory section. Since
   inertial frame alignment involves 4 (or 8 in the case of highly
   symmetric molecules) starting positions, setting
   :option:`-randomstarts` to a value much larger will result in much
   slower run times.

.. option:: -subtan

   Also calculate sub-Tanimoto score. See the :ref:`rocs_reportfile` section 
   for a complete description of how sub-Tanimoto is calculated.


.. option:: -subrocs

   Specifies starting the search at all heavy atoms of the larger molecule 
   as well as the default inertial starts.  The larger molecule is chosen
   by comparing the self shape-overlap terms of the query and database molecule.
   The :option:`-subrocs` option is especially useful when the query and database
   molecules have a large difference in size.

.. option:: -shapeonly

   A color force field is used by default and
   optimization against shape and color is the default overlap method. It is
   incompatible with a shape file. As an easy way to run ROCS with just shape
   overlap, this flag is the equivalent of setting:

   ::
   
      -chemff none
      -optchem false
      -rankby tanimoto

.. option:: -scoreonly

   Perform scoring calculation only on input molecules. Sets the following flags:

   :: 

      -opt false
      -optchem false
      -besthits 0
      -maxhits 0
      -scdbase  

.. option:: -opt

   Turn optimizer on if true, off if false. Not normally used
   by itself, but with other flags via the :option:`-scoreonly` flag. 
   
   [Default=true]


Color Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -chemff <cffname>

   Color-force-field name. Either the name of one of the built-in
   color force fields (ImplicitMillsDean or ExplicitMillsDean) or the
   name of a user-defined color force field file. The format of this
   file is given in the :ref:`colorforcefield` section.
  
   [Default=ImplicitMillsDean]

.. option:: -optchem

   Use color force field forces and gradients as part of 
   overlay optimization. Ignored when :option:`-opt` is ``false``.

   [Default=true]

.. option:: -coloronly

   Enables overlay optimization against only the color components, i.e., color
   atoms for a molecule or color gaussians for a shape query, of the query. This
   provides a color equivalent option of the corresponding ``-shapeonly``
   option.

   [Default=false]



