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

.. program:: brood

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

This section has a series of example **BROOD** command line executions.  Most **BROOD**
runs are carried out using **vBROOD**. Each example is followed by a brief
description of its behavior.

If you would like to execute the following examples as written, 
the appropriate paths to the executable file and the database file must be
included.  In addition, the query file :file:`q1.oeb` will need to be in the
working directory.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31

This command will execute BROOD with the default parameters. The file :file:`q1.oeb` is opened 
as the query, and the database is read from the chembl31 folder. The default hit list
will be written to :file:`brood_hitlist.oeb.gz`, using the default -prefix argument “brood”. 
Similarly, the informational output files :file:`brood_hitlist_rpt.csv`, :file:`brood_log.txt` 
and :file:`brood_parm.txt` will also be written.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -prefix 4dfr

This command is the same as the previous except that the prefix to all of the output files 
has been changed from “brood” to “4dfr” (for example, the log file will be written to 
:file:`4dfr_log.txt` rather than :file:`brood_log.txt`).

.. code-block:: bash

   prompt> brood -param 4dfr_parm.txt

This execution of **BROOD** will read all the command line arguments from the file
:file:`4dfr_param.txt`.  Every time **BROOD** is executed, a param file is generated
that can be used to exactly reproduce the run (*vida infra*).  This option is
most useful when the job is set up in **vBROOD** and the query and param file are
written out for later execution.  Using the command detailed here with a query
and param file from **vBROOD** will give the same results as running the search
from within **vBROOD**.

.. code-block:: bash

   prompt> brood -param 4dfr_parm.txt -ringOnly 0

This example illustrates two points: that command line arguments take
precedence over arguments in the :file:`.param` file, and that the
:option:`-ringOnly` flag is an important flag in altering **BROOD** results.  This
command line will execute **BROOD** with the parameters from ":file:`4dfr_parm.txt`",
but the :option:`-ringOnly` parameter will be overridden (taking precedence)
over the :option:`-ringOnly` parameter that is specified in :file:`4dfr_parm.txt`.
A similar outcome could be achieved by editing :file:`4drf_parm.txt` in a text
editor, but this command line alteration is a more direct means to the same
behavior.

By default, **BROOD** only returns fragments that have at least two ring atoms on
the shortest path between attachment points, or at least three ring atoms total
if there is only one attachment point.  This example shows that a user can turn
off this constraint using the :option:`-ringOnly` flag.  If one wants to
generate results that *only* avoid the rings as described above, one can pass
**-1** to the :option:`-ringOnly` parameter.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -quickLook 120

This execution will use the query in :file:`q1.oeb` to search the
fragments in the database :file:`chembl31`.  The use of the
:option:`-quickLook` parameter will limit the search to approximately the number of seconds (120) 
provided after the flag. The parameter is a great way to get a quick notion of interesting
results.  The databases are organized to allow rapid identification of
some interesting results.  The full search can take minutes to hours, and is
often more appropriate when designing molecules that may take days or weeks to
synthesize; nevertheless, in an iterative design session, it can be useful to
quickly generate ideas using the :option:`-quickLook` parameter.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -neutralpH false -tautomers false

When **BROOD** is building analogs by putting similar fragments into a molecular
framework, sometimes the electronic environment of certain functional groups
changes dramatically (amines converted to amides for instance).  To properly
handle these cases, it is useful for **BROOD** to normalize the ionization and
tautomer states of the new molecules before generating the final hit list.  In
some cases, users are better served without these normalizations.  The
ionization and tautomer normalizations can be turned off with the
:option:`-neutralpH` and :option:`-tautomers` flags, respectively.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -scoreType linkOnly

By default, **BROOD** compares the shape, chemistry, electrostatics, and attachment
geometry of fragments in order to suggest analog molecules.  For some
applications, such as joining fragments or closing rings, it is useful to build
fragments into empty space.  In these cases, one wants to only compare the
attachment geometry of fragments, in a manner similar to the original CAVEAT
searches [Lauri-1994]_. The :option:`-scoreType` ``linkOnly`` flag instructs **BROOD**
to compare fragments using only their ability to form low-energy bridges
between attachment points.

.. code-block:: bash

   prompt> brood -in q1.oeb -db chembl31 -property false

By default, **BROOD** filters the final analog hit list with a series of property
filters, each specified with a pair of range parameters.  While this can be
useful, on some occasions, users prefer to avoid all of the property filters.
By passing *false* to the :option:`-property` flag, all of the property filters
can be turned off in one easy step.
