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

.. program:: brood

======================
Input Files
======================

Typically, a user will find it most convenient to generate the **BROOD** query
using the graphical interface.  Even if one wants to run **BROOD** on a
cluster or other machine where it isn't convenient to use the graphical
interface, the graphical interface can be used to generate the necessary input
and then **BROOD** can be executed on a different machine after moving the
input files.  **BROOD** requires one input file, a query fragment file.  With a
default installation, the **BROOD** application can search either one of the default
fragment database or a user-generated database.

.. _queryfiles:

-----------------------
Query Files
-----------------------

The entire query is encapsulated into a single query file, typically generated
in the GUI.  When generated, the GUI names the file *brood_1_query.oeb.gz*
where the *1* is replaced with the next appropriate integer to maintain unique
file names.  This **BROOD** query includes the original molecule, the fragment that
the user has chosen to replace, and the user-edited description of the shape,
chemistry, and electrostatics of the query.  In addition, if the query includes
protein structures either for bump-check or selectivity-check, these too will
be encapsulated in the query file.

**BROOD** carries out a 3D search, and a 3D search is required for the search and
is usually included in the query file.  The **BROOD** GUI can take either a 2D or a
3D query file.  If the original input is 2D, a 3D structure will be generated
in the GUI and used during the search.

.. _fragmentDatabase:

----------------------------------------
Fragment Database
----------------------------------------

As mentioned in the theory section, **BROOD** comes with a pregenerated,
multiconformer fragment database.  This database is made from fragments of
known molecules that contain 1-15 heavy atoms and 1-3 attachment sites.

**BROOD** can also search user-generated fragment files.  A custom database 
can be created using :ref:`chapter_chomp`.

.. _queryFileExamples:

-----------------------------------
Example Fragment Files
-----------------------------------

The database file used for **BROOD** searches is in a highly optimized format with
many precalculated properties and a complex structure intended to minimize
disk access during the time-critical search.  These database files can be
generated by the **CHOMP** program included with your **BROOD** distribution.  By
default, **CHOMP** will generate fragments from complete molecules.  On the other
hand, if a user has their own fragment files they would like to search, these
can be loaded directly into the **CHOMP** program and used to generate a searchable
database.

In this case, an input database fragment for bioisosteric searching must be a
molecular fragment with one or more "attachment points".  An attachment point
represents a bond from the fragment to the rest of the molecule.  Inside
**OEChem TK**, this is represented as a bond to an atom with atomic number 0 (termed a
"Dummy Atom").  If it is necessary to uniquely distinguish these dummy
atoms, Map Indices can be used via the :ref:`SetMapIdx and GetMapIdx methods of OEAtomBase <oechem_OEAtomBase>`.

The input fragment does not need to have 3D coordinates (they can, optionally, be generated
on-the-fly).  This makes SMILES and 2D SDF file formats the most convenient 
for query fragment input.  On the other hand, the fragment database should 
contain 3D coordinates with multiple conformers per fragment.  In the examples
below, a simple amide fragment with generic (amide) and uniquely labeled
(amideR) dummy atoms are shown.

SMILES format:

::

   *C(=O)N* amide
   [*:1]C(=O)N[*:2] amideR

SDF format:

::

   amide
     -OEChem-01040614232D

     5  4  0     0  0  0  0  0  0999 V2000
       0.0000    0.0000    0.0000 *   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 *   0  0  0  0  0  0  0  0  0  0  0  0
     1  2  1  0  0  0  0
     2  3  2  0  0  0  0
     2  4  1  0  0  0  0
     4  5  1  0  0  0  0
   M  END
   $$$$
   amideR
     -OEChem-01040614232D

     5  4  0     0  0  0  0  0  0999 V2000
       0.0000    0.0000    0.0000 R#  0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0
       0.0000    0.0000    0.0000 R#  0  0  0  0  0  0  0  0  0  0  0  0
     1  2  1  0  0  0  0
     2  3  2  0  0  0  0
     2  4  1  0  0  0  0
     4  5  1  0  0  0  0
   M  RGP  2   1   1   5   2
   M  END
   $$$$

---------------------------
Molecular File Formats
---------------------------

**BROOD** can read and write a variety of molecular file formats.  The file format 
is automatically interpreted from the filename suffix.

.. _molecular_file_formats_table:

.. list-table::
   :widths: 20 20 50
   :header-rows: 1

   * - File Type
     - Input | Output
     - Extension
   * - SMILES
     - Output
     - :file:`.smi .ism .smi.gz .ism.gz`
   * - CXSMILES
     - Output
     - :file:`.cxsmiles .cxsmiles.gz`
   * - SDF
     - Input and Output
     - :file:`.sdf .sdf.gz`
   * - MOL2
     - Input and Output
     - :file:`.mol2 .mol2.gz`
   * - OEBinary v2
     - Input and Output
     - :file:`.oeb .oeb.gz .oez`
   * - List files
     - Input
     - :file:`.lst .list .lst.gz .list.gz`


Gzipped OEBinary version 2 (:file:`oeb.gz`) is the recommended output
format.

**BROOD** is capable of piping formatted input and output.  The simple "-" can be 
used in place of a filename to indicate :file:`std::cin` or :file:`std::cout` 
with the default SMILES format.


.. code-block:: bash

   prompt> brood -in .oeb.gz -db myDB < brood.query_1.oeb.gz

This execution will run **BROOD** with :file:`std::cin` as the input with *.oeb.gz*
format.  The format is controlled by the suffix.
