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

.. _tutorial_combine_receptors:

CombineReceptors tutorial
---------------------------

Combining receptors is an optional step that can be used to take information
found in multiple receptors to create a new, merged, receptor.

:ref:`combine_receptors_usage` is intended to
be used in an automated fashion where the output aligned receptors
should be included with the original receptors when running 
:ref:`chapter_posit`.  As such, the output receptor files
are automatically named based on the input filenames and
only receptors that are capable of merging produce output.

This is particularly helpful when using small bound fragments to try and
predict binding poses for larger ligands.  Combining receptors works
by supplying a list of potential receptors and only receptors that
are deemed worthy or merging are output.  To be worthy of merging:
 
 1. It must be possible to align the protein sequences.
 2. The ligands must overlap, but be different enough to indicate
    that the combined receptor has more information content than
    each independently.

.. _tut_merge1:

.. figure:: ../images/merge1.png
   :scale: 85
   :align: center
   :alt: Merged receptors

   **Merged Receptors:**
   Merging the receptors 2IKO and 2IKU capture more potential
   interaction constraints than either does alone

.. _tut_merge2:

.. figure:: ../images/merge2.png
   :scale: 85
   :align: center
   :alt: Merged receptors

   **Ligand Posed to Merged Receptors:**
   REN9 is correctly predicted by the merged receptor

For example, consider the merged receptor shown in figure:
:ref:`Merged Receptors<tut_merge1>`.  In this case, one of the
ligands binds to a pocket that is not present in the other.
The expectation is that the combination of both ligands
has more information content than either alone.

For each valid
merge, two output files are generated, one in each reference frame.
See the :ref:`combine_receptors_usage` section for more details.