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

..  program:: brooddbmerge

.. _brooddbmerge:

*********************************
BroodDBMerge
*********************************

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

The **BROOD** distribution includes a utility, **BroodDBMerge**, that allows users to
create a single database by merging two databases, such as BROOD's default
database and their own corporate database.  **BroodDBMerge** accomplishes this task
using three required parameters: :option:`-in1`, :option:`-in2` and
:option:`-out`.  This allows combining two databases in the directories
specified by the two *in* options and writing a new database to the directory
specified by the :option:`-out` flag.  By default, **BroodDBMerge** will not
overwrite a database.

**BROOD** databases are complex structures with many precalculated parameters and
indices organized into multiple binary files for fast access of multiple
fragments in an efficient manner.  Because of this complex structure, it is not
possible to simply string two database files together in order to merge
databases.  Instead, **BroodDBMerge** reorganized the molecular fragments and
recalculates the database indexes. 

By default **BroodDBMerge** removes duplicate fragments from the new database (see
:option:`-removeDuplicates`).  When **BroodDBMerge** identifies a unique
fragment, it is written to the new database.  If a second copy of a fragment is
identified, it is discarded.  The database passed in using the :option:`-in1`
parameter takes precedence in duplicate removal Duplicate fragments in the
database specified by :option:`-in2` will be discarded.  In addition, if a
fragment appears twice in either database, the later instance will be
discarded.  The user can use the database input order to control which
duplicate fragments will be present in the final database.


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

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

.. code-block:: console
   
   > brooddbmerge --help

will generate the following output:

::

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

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

This section has a brief series of examples of **BroodDBMerge** command-line
executions.  Each example is followed by a brief description of its behavior.

.. code-block:: bash

   prompt> brooddbmerge -in1 dbA -in2 dbB -out dbAB


This is the most basic merge of the two databases dbA and dbB into the new
database dbAB.  By default, the new database dbAB will not contain any
duplicate fragments, but will contain all of the unique fragments that were
present in either dbA or dbB.

.. code-block:: bash

   prompt> brooddbmerge -in1 dbA -in2 dbB -out dbB

In this execution, it is most likely the user accidentally used :file:`dbB` for
the output.  Rather than allow this typo to accidentally erase or corrupt the
:file:`dbB` database, the execution will stop.  This behavior can be overridden with the
:option:`-overwrite` flag.

.. code-block:: bash

   prompt> brooddbmerge -in1 dbA -in2 dbB -out dbAB -removeDuplicates false

This execution of **BroodDBMerge** will not include duplicate removal.  All of the
fragments that are in :file:`dbA` and :file:`dbB` will occur in :file:`dbAB` no
matter how many times any fragment may appear in either or both databases.
When **BROOD** searches the resulting database, each instance will be treated
separately.


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

.. option:: -in1 (-i1)

   This option is for loading the first **BROOD** database.  The value passed with
   the flag should point at the directory of the database rather than any files
   inside the database.

.. option:: -in2 (-i2)

   This option is for loading the second **BROOD** database to be merged with the
   database specified by the :option:`-in1` flag.  

.. option:: -out (-o)

   This option indicates the new database to create based on merging the
   databases specified by the :option:`-in1` and :option:`-in2` flags.  By
   default **BroodDBMerge** will require you to specify a new directory for the new
   database (see :option:`-overwrite` for details).

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

.. option:: -verbose (-v)

   This flag controls the amount of output generated by the program.  By
   default, all essential information is presented in a summary.  When the flag
   is set, a large amount of detailed information is also written to stdout.
   [Default=false]

.. option:: -overwrite (-over)

   By default, **BroodDBMerge** will only write a new database (it will not
   overwrite another file or directory).  Brood databases can be quite
   expensive to generate; to avoid accidental erasure of databases **BroodDBMerge**
   will not overwrite a previous database.  If you *want* to overwrite a
   database, you can set the :option:`-overwrite` flag. [Default=false]

.. option:: -removeDuplicates (-duplicates)

   When merging two databases, users can choose whether to remove duplicates.
   By default, any fragment that is present more than once in the combined
   databases will only be written one time.  No fragment-level merging occurs;
   only the first instance of a fragment is written.  [Default=true]





