.. _spruce_examples_extract_biounits_ref:

Extracting Biounits by aligning to a reference protein
=======================================================

Biounit (BU) extraction is one of the more basic functionalities offered through the
**Spruce TK**.  This example shows how to extract BUs using a sequence alignment to a reference protein.

Command Line Interface
----------------------

This example takes in an extraction PDB file, a reference PDB file, and optionally the minimum score for the alignment to the reference as well as a boolean flag to instruct the code to superimpose the output BU to the input reference protein (see :oe:func:`OESpruce::OEExtractBioUnits` for details on the API).

.. code-block:: console

   prompt> extract_biounits_ref <extract protein PDB> <reference protein PDB> [min score] [superpose]

Code
----------------------

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`extract_biounits_ref.py <../../../../wrappers/python/examples/spruce/extract_biounits_ref.py>`
         and both
         :download:`4OBD.pdb <../../../../sublibs/tklibs/spruce/tests/data/4OBD.pdb>`
         (the extraction PDB file)
         and
         :download:`2UPJ.pdb <../../../../sublibs/tklibs/spruce/tests/data/2UPJ.pdb>`
         (the reference PDB file)


   .. :ref:`Full listing. <listing-extract_biounits_ref.py>`

   ..   literalinclude:: ../../../../wrappers/python/examples/spruce/extract_biounits_ref.py

   .. only:: oepdf

      .. oe:source:: extract_biounits_ref.py
         :language: python


.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`extract_biounits_ref.cpp <../../../../sublibs/tklibs/spruce/examples/extract_biounits_ref.cpp>`
         and both
         :download:`4OBD.pdb <../../../../sublibs/tklibs/spruce/tests/data/4OBD.pdb>`
         (the extraction PDB file)
         and
         :download:`2UPJ.pdb <../../../../sublibs/tklibs/spruce/tests/data/2UPJ.pdb>`
         (the reference PDB file)

   .. only:: oepdf

      .. oe:source:: extract_biounits_ref.cpp
         :language: c++


Example
--------------------------------------------------------------------------------

.. oe:language:: c++

   .. code-block:: console

      prompt> extract_biounits_ref 4OBD.pdb 2UPJ.pdb

.. oe:language:: python

   .. code-block:: console

      prompt> extract_biounits_ref.py 4OBD.pdb 2UPJ.pdb

will generate the following output:

::

   Writing biounit 0 to 4OBD_BU_0.oeb.gz
   Writing biounit 1 to 4OBD_BU_1.oeb.gz

.. seealso::

   * :oe:func:`OESpruce::OEExtractBioUnits` function
   * :ref:`OEBioUnitExtractionOptions <OESpruce_OEBioUnitExtractionOptions>` class
