.. include:: ../../toolkit-substitutions

.. oe:namespace:: OESpruce

.. meta::
   :keywords: OEExtractBioUnits

..  _OESpruce_OEExtractBioUnits:

.. oe:function:: OEExtractBioUnits

  .. attention::

      |TWOLANGUAGE|

  .. oe:language:: c++ java csharp

     .. oe:api::

        OESystem::OEIterBase<OEChem::OEMolBase>*OEExtractBioUnits(const OEChem::OEMolBase& extractProtein,
                                                                  const OEChem::OEMolBase& refProtein,
                                                                  const OEBioUnitExtractionOptions& opts = OEBioUnitExtractionOptions())
        OESystem::OEIterBase<OEChem::OEMolBase>*OEExtractBioUnits(const OEChem::OEMolBase& extractProtein,
                                                                  const OEBioUnitExtractionOptions& opts = OEBioUnitExtractionOptions())

  .. oe:language:: python

     .. oe:api:: python

        OEExtractBioUnits(extractProtein: Union[OEGraphMol,OEMol,OEQMol],
                          refProtein: Union[OEGraphMol,OEMol,OEQMol],
                          opts: OEBioUnitExtractionOptions = OEBioUnitExtractionOptions()) -> Iterable[Union[OEGraphMol, OEMol, OEQMol]]
        OEExtractBioUnits(extractProtein: Union[OEGraphMol,OEMol,OEQMol],
                          opts: OEBioUnitExtractionOptions = OEBioUnitExtractionOptions()) -> Iterable[Union[OEGraphMol, OEMol, OEQMol]]



  Extracts BUs using either the PDB remarks when a single :ref:`OEMolBase <OEChem_OEMolBase>` is
  provided, or a sequence alignment to a reference if two :oe:cls:`OEMolBases <OEChem::OEMolBase>`
  are provided.
  The :oe:func:`OESpruce::OEExtractBioUnits` is overloaded with to take an :ref:`OEBioUnitExtractionOptions <OESpruce_OEBioUnitExtractionOptions>` options class.
  This function returns an iterator of :ref:`OEMolBase <OEChem_OEMolBase>` objects, one for each
  of the BUs.

  .. note::

     If atoms are on the symmetry axis causing them to be duplicated by symmetry expansion, they are handled
     specially to avoid clashes in the output. If the duplication results in atoms of a molecule that are perfectly
     overlapping, e.g. a water molecule oxygen, then the duplicated water is deleted. If the overlap is not complete,
     but instead creates partially overlapping molecules, then the BU is enumerated into multiple BUs. The nearly identical
     BUs are tagged in generic data with an index number used by Spruce.

  **Parameters :**

  *extractProtein*
     The protein from which the BUs will be extracted.
  *refProtein*
     The reference protein that will be used for sequence alignment.
  *OEBioUnitExtractionOptions*
     :ref:`OEBioUnitExtractionOptions <OESpruce_OEBioUnitExtractionOptions>` options class defining biological unit extraction options.

  The ``extractProtein`` structure must have crystal symmetry set (e.g. loaded from a CRYST1 record) for biounit extraction to succeed.

  .. admonition:: Code Example

      * :ref:`spruce_examples_extract_biounits_ref` example
      * :ref:`spruce_examples_extract_biounits_remarks` example
