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

.. program:: brood

======================
Parameters
======================

.. include:: ../../common/file_options.irst

.. option:: -in (-qMol, -queryMol)

   Molecular file encapsulating the query.  It contains the primary molecule of
   interest, the query fragment, description of the query potential function
   and constraints, and the protein structures for the active site and for
   selectivity.  

.. option:: -out (-o)

   Output filename to be generated. Accepted file formats are:
   ``cxsmiles``, ``ism``, ``mol2``, ``oeb``, ``oez``, ``sdf``, ``smi``.

.. include:: ../../common/new_mpi_execute_options.irst

-----------------
BROOD App Options
-----------------

.. option:: -db (-database) 

  Specified the directory containing the **BROOD** database files.  Additional
  details on the files contained in the directory can be found in the section
  on the :ref:`fragmentDatabase`.

.. option:: -cpddb 

  The user can specify a file of available compounds (either commercial or
  internal) with this flag.  If specified, molecules from this file that
  are similar to any created analogs will be used to annotate the newly
  suggested molecule. More details about analog similarity is described in
  :ref:`brood_compound_similarity` method. 

.. option:: -quickLook <n> (-quick)

   This flag allows a user to do a quick **BROOD** search (in ``n`` number of seconds).
   **BROOD** is designed to identify as many interesting hits as soon as possible.
   Thus while a thorough search may take minutes to hours, useful preliminary
   results can be generated in approximately ``n`` seconds with this option.

------------------------------
BROOD Hit List Builder Options
------------------------------

.. option:: -idea (-cluster)

   This flag determines if the hit list will be organized according to a reduced
   graph hierarchy.  This is quite useful for clustering similar analogs and
   thus allowing a user to quickly scan the different analog families and
   drill down into the most interesting clusters without needing to examine
   hundreds of analogs. [Default=true]

.. option:: -maxHits (-maxHit)

   This flag determines the number of compounds saved in the hit list.
   Allowable range is 1–50000.  **The legal range of this parameter has been
   increased by an order of magnitude.**  [Default=1000]

.. option:: -buildType 

   This flag determines the type of building to perform. Accepted values are
   ``2d`` (2 dimensional build), ``noopt3d`` (3 dimensional build without optimization),
   and ``optimized`` (3 dimensional build with optimization). [Default=optimized]

.. option:: -checkBond

   If this flag is set to ``True``, **BROOD** will check all bonds formed between
   new fragments and the rest of the query molecule and eliminate fragments
   that form bond types that are typically unstable.  Rather than being
   discarded entirely, these hits will be written in the
   :file:`brood_removed.oeb.gz` file by default. [Default=true]

.. option:: -deltaLocalStrain 
  
   Boolean flag indicating if the relative local strain between
   query and analog should be used as a measure of strain. [Default=false]

.. option:: -maxLocalStrain 
  
   Maximum local strain allowed to fit an analog molecule on top of a query. [Default=6.5]


.. option:: -neutralpH

   This flag controls whether the final molecules are set to an ionization
   state suitable at pH=7.4.  Because new bonds are formed in the process of
   generating analogs, functional groups sometimes need adjustment even if
   their state was properly normalized prior to fragmentation. This flag allows
   the user to turn off pKa normalization. [Default=true]

.. option:: -tautomers (-tautomer)

   Similarly, the :option:`-neutralpH` adjustment of tautomer states can be
   necessary after joining the new fragments with the static portions of the
   original molecule. This flag allows the user to turn off this normalization.
   [Default=true]

--------------------
BROOD Match Options
--------------------

.. option:: -attachCutoff  (-attachmentCutoff, -attachCut)

   Minimum acceptable attachment point score cutoff.  The cutoff is for the
   shape overlap score of the beginning and ending atom of each attachment
   bond.  The default was chosen empirically to assure all fragments in the
   hit list would have sensible attachment geometries.  This value does not
   affect runs when the :option:`-scoreType` flag is set to ``linkOnly``. [Default=0.78]

.. option:: -bondOrder (-bo)

   When this Boolean flag is set, only fragments with the same attachment bond
   orders as the query fragment are allowed. [Default=true]

.. option:: chargeType (-fileChrg)

   When this flag is set to ``fileChrg``, the partial charges for electrostatic Tanimoto
   calculations are taken from the input files.  If this flag is set to ``mmff94``, or the
   input file does not contain partial charges, MMFF94 charges will be used.  The
   partial charges on the database molecules are pregenerated.  [Default=mmff94]

.. option:: -checkGeometry

   By default, regardless of the attachment score (used primarily to drive the
   optimization), the fit of a fragment at the attachment points is controlled
   by geometric constraints.  These require that the two attachment vectors
   that will be jointed into a bond are overlapping and pointing in roughly
   opposite directions.  In some cases, particularly when the required geometry
   is unusual or strained, it can be useful to turn off this constraint check.
   [Default=true]

.. option:: -property (-prop)

   This Boolean flag indicates whether ANY of the molecular properties should
   be used to eliminate compounds from consideration.  While these filters can
   be useful, if a user expects to see a particular fragment or analog and it
   does not appear in the hit list, it will often have been eliminated by the
   property filters.  The :ref:`reportFile` will indicate which, if any, property
   filter affected each fragment.  If set to false, all of the related flags
   below become irrelevant. [Default=false]

.. option:: -ringOnly (-ring)

   This is a complex flag whose purpose is to allow the user to control the
   number of ring atoms in the selected fragments.  It allows input of "-2,
   -1, 0, or an integer 1 <= x <= 12".  This flag has to do with a count
   of the number of ring atoms in the shortest path between attachment points
   in a fragment.  In cases with more than two attachment points, all shortest
   paths are calculated and the number of ring atoms is summed.

   By default, the flag is set to "-2" (true) and requires at least two ring atoms in
   the path.  If the flag is set to "0" (false), no ring atom filtering is done,
   while if the flag is set to "-1" (none), only fragments without ring atoms in the
   shortest paths are returned.  If the flag is set to a number between 0 and
   13, then that will be the **minimum** number of ring atoms required.
   [Default=-2]

.. option:: -shapeCutoff

   Indicates the minimum required shape Tanimoto score required for a fragment
   to appear in the color, elect, or queryAnalog hit lists.  This cutoff is
   useful for cases when few shape-similar fragments exist in the database
   being searched.  [Default=0.6]

--------------------
BROOD Score Options
--------------------

.. option:: -attachScale (-attachmentScale, -attach, -aScale)

   This floating point value determines the balance between the chemical color
   score and the attachment point scores.  Higher values indicate more
   weighting for the attachment-point alignment.  This parameter has complex
   effects; please use it with care. [Default=1.5]

.. option:: -bumpRadius

   This real number flag determines the minimum distance between ligand heavy
   atoms and protein heavy atoms in the final relaxed solution for there to be
   considered a clash.  New analogs with atoms closer than this cutoff to the
   active site protein are discarded from the hit list.  If a selectivity
   protein is being used, at least one clashing atom must be found in order for
   the hit list ligand to be retained.  Because the molecular model of the
   protein is rigid, it may be advantageous for this cutoff to be
   shorter than in a system with a flexible protein model. [Default=2.25]


.. option:: -ignoreProtein (-noqueryprot, -noqueryprotein)

  When a query is created with the GUI and an active site protein is included,
  the section active site protein becomes part of the query.  This flag makes
  **BROOD** ignore the active site protein even though it is part of the query.
  The flag makes it easy to run the **BROOD** job with and without the active site
  protein. [Default=false]

.. option:: -ignoreProteinSelect (-noqueryselectionprotein, -noqueryselection)

  When a query is created with the GUI and a selectivity protein is included, the
  selectivity protein becomes part of the query.  This flag makes **BROOD** ignore the
  selectivity protein even though it is part of the query.  The flag makes it
  easy to run the **BROOD** job with and without the selectivity protein. [Default=false]

.. option:: -rangeOffset

   By default, the range of fragment heavy atoms specified by the
   :option:`-rangeSize` flag is centered around the same number of heavy atoms
   as the original query fragment.  Instead, the user can use this flag to bias a
   search toward smaller or larger fragments with positive or negative values
   passed to this flag. [Default=0]

.. option:: -rangeSize

   By default, only fragments with a number of heavy atoms +/- N from the
   fragment being replaced are considered.  This flag lets the user control
   this setting.  It should not be necessary to change this value except in
   unusual circumstances.  This flag determines the range of heavy atoms around
   query fragment's number of heavy atoms to examine. [Default=6]

.. option:: -scoreType  

   This flag can have three legal values: ``rocs``, ``et``, and ``linOnly``.
   If set to ``rocs``, the shape and color Tanimoto
   similarities are calculated. If set to ``et``, the electrostatic Tanimoto
   similarity is calculated on all of the fragments that also have a good shape score. 
   If this flag is set to ``linkOnly``, then the shape and chemistry of the fragment are
   ignored and ONLY the attachment point geometry (and constraints) are used to
   identify similar fragments. This is similar to Bartlett's Caveat algorithm,
   one of the first algorithms in this genre.  This type of search can be
   useful when trying to bridge one or more fragments without any prior
   knowledge, such as when linking two fragments in fragment-based design.[Default=rocs]
 
-------------------------
Molecule Property Options
-------------------------

.. option:: -eganEgg (-egan)

   This Boolean parameter determines whether analog compounds will be required
   to fulfill the "Egan egg" measure of bioavailability.  This measure was
   published by Bill Egan while at Pharmacopia [Egan-2000]_, and rejects
   compounds with a LogP > 5.88 or a PSA > 131.6. [Default=true]

.. option:: -veber (-gsk)

   This Boolean parameter determines whether analog compounds will be required
   to fulfill the measure of bioavailability Veber published at GSK
   [Veber-2002]_.  His measure of bioavailability eliminates compounds with a
   PSA > 140 or more than 10 rotatable bonds. [Default=false]


-------------------------
Extrinsic Property Values
-------------------------

.. option:: -minAcceptors (-minLipinskiAcceptors, -minLipinskiAcc)
.. option:: -maxAcceptors (-maxLipinskiAcceptors, -maxLipinskiAcc)

   These flags indicate the upper and lower bound of the Lipinski hydrogen bond
   acceptor range of any analog.  Analogs higher or lower in number of Lipinski
   hydrogen bond acceptors than these cutoffs will be eliminated from
   consideration.  For the purpose of this measure, hydrogen bond acceptors are
   determined by the method of Lipinski [Lipinski-1997]_.  [Default=2, 11]

.. option:: -minComplexity (-minComp)
.. option:: -maxComplexity (-maxComp)

   These flags indicate the upper and lower bound of the molecular complexity
   range of any analog.  Analogs higher or lower in molecular complexity than
   these cutoffs will be eliminated from consideration.  For more on molecular
   complexity, please see the theory section.  [Default=0.0, 2.5]

.. option:: -minDonors (-minLipinskiDonors, -minLipinskiDon)
.. option:: -maxDonors (-maxLipinskiDonors, -maxLipinskiDon)

   These flags indicate the upper and lower bound of the Lipinski hydrogen bond
   donor range of any analog.  Analogs higher or lower in number of Lipinski
   hydrogen bond donors than these cutoffs will be eliminated from
   consideration.  For the purpose of this measure, hydrogen bond donors are
   determined by the method of Lipinski [Lipinski-1997]_.  [Default=1,8]

.. option:: -minFrequency (-minFreq)
.. option:: -maxFrequency (-maxFreq)

   These flags indicate the upper and lower bound of the frequency range of any
   analog.  Analogs higher or lower in frequency than these cutoffs will be
   eliminated from consideration.  For the purpose of this calculation, the
   frequency is a percentile number indicating the frequency of each fragment
   normalized relative to the frequency of fragments in ChEMBL.  Frequency as
   assessed here is a measure of how common each fragment is among the source
   molecules.  The most commonly occurring fragment would be in the 99th
   percentile, while the least commonly occurring fragments would be in the
   1st percentile. [Default=0, 100]

.. option:: -minLipinski 
.. option:: -maxLipinski 

   These flags indicate the upper and lower bound of the Lipinski violations
   range of any analog.  Analogs higher or lower in number of Lipinski
   violations than these cutoffs will be eliminated from consideration.
   [Lipinski-1997]_.  In Lipinski's work, in order to segregate molecules that
   progressed through clinical trials, he determined that one violation was
   acceptable, but two were not.  [Default=0, 1]

.. option:: -minlogp 
.. option:: -maxlogp

   These flags indicate the upper and lower bound of the calculated LogP range of any analog.
   Analogs higher or lower in LogP than these cutoffs will be eliminated from consideration.  
   [Default=-1.0,5.0]


.. option:: -minMartin (-minAbbott, -minABS)
.. option:: -maxMartin (-maxAbbott, -maxABS)

   These flags indicate the upper and lower bound of the Abbott Bioavailability
   Score (ABS) range of any analog.  Analogs higher or lower in ABS than these
   cutoffs will be eliminated from consideration.  This floating point ABS
   parameter (range 0.0-1.0) indicates the minimum allowable probability that F
   will be >10% in rats according the QSAR model developed and published by
   Yvonne Martin [Martin-2005]_. A value of 0.0 will allow all compounds to
   pass. [Default=0.2, 1.0]


-------------------------
Intrinsic Property Values
-------------------------

.. option:: -minAromFJCt
.. option:: -maxAromFJCt

   These flags indicate the upper and lower bound of the aromatic ring range of
   any analog.  Analogs higher or lower in number of aromatic rings than these
   cutoffs will be eliminated from consideration. For the purpose of this
   calculation, the number of aromatic rings is the number of aromatic rings is
   #aromatic bonds - #aromatic atoms + 1. [Default=0, 5]


.. option:: -minFsp3C
.. option:: -maxFsp3C

   These flags indicate the upper and lower bound of the fraction of carbons
   that are sp\ :sup:`3` range of any analog.  Analogs higher or lower in the fraction of
   carbons that are sp\ :sup:`3` than these cutoffs will be eliminated from
   consideration.  There is some evidence that increasing the fraction of
   carbons in a series that are sp\ :sup:`3` (escaping from "Flatland") improved success
   in clinical trials [Lovering-2009]_. [Default=0.3, 1.0]


.. option:: -minHvyAtom (-minHeavyAtom)
.. option:: -maxHvyAtom (-maxHeavyAtom)

   These flags indicate the upper and lower bound of the heavy atom range of
   any analog.  Analogs higher or lower in number of heavy atoms than these
   cutoffs will be eliminated from consideration.  [Default=7,35]


.. option:: -minMolWt (-minmolecularweight)
.. option:: -maxMolWt (-maxmolecularweight)

   These flags indicate the upper and lower bound of the molecular weight range of any analog.
   Analogs higher or lower in molecular weight than these cutoffs will be eliminated from consideration.  
   [Default=100,500]


.. option:: -minRotBond (-minRotatableBond)
.. option:: -maxRotBond (-maxRotatableBond)

   These flags indicate the upper and lower bound of the rotatable bond range
   of any analog.  Analogs higher or lower in number of rotatable bonds than
   these cutoffs will be eliminated from consideration.  [Default=0,13]

.. option:: -minpsa (-mintpsa)
.. option:: -maxpsa (-maxtpsa)

   These flags indicate the upper and lower bound of the topological polar
   surface area (TPSA) range of any analog.  Analogs higher or lower in TPSA
   than these cutoffs will be eliminated from consideration.  [Clark-1999]_
   [Ertl-2000]_.  [Default=60,150]


.. _exampleExecutions:

