.. _chapter_protein_prep:

********************************************************************************
Protein Preparation
********************************************************************************

Protein preparation is the process of transforming a macromolecular structure
into a form more suitable for a computational experiment. The specific set of
tasks required depends on the experiment and the source of the structure.
Tools for several common prep tasks are described below.
For a demonstration of how these can be combined, see
the :ref:`section_example_oebio_proteinprep` example.

For a more comprehensive protein preparation process, :ref:`sprucetk_prep_advanced_example` shows an
end-to-end preparation workflow to process protein structures for molecular modeling.
For more information on **Spruce TK** see the associated :ref:`Theory <sprucetk_theory>`
and :ref:`Spruce API <oespruce_part_api>`.

.. _section_process_alt_locations:

Processing Alternate Locations
================================================================================

.. index:: AltLoc AltConf OEAltLocationFactory

Protein structures rarely describe whole molecules. Instead, they are usually
missing atoms that could not be resolved well. In addition, many structures
contain *multiple* copies of atoms called alternate ("alt") locations
or alternate conformations that can indicate that part of the structure is
moving. As the resolution of X-ray crystal structures improves, alt locations
can be expected to become ubiquitous. These conformations are indexed by an
ID character such as ``A`` or ``B`` that is stored in the residue information
for that atom (see :ref:`section_biopolymer_residues`).

Having extra copies of atoms can interfere with some experiments, such as
docking. One way to handle this is to eliminate all but one conformation.
By default, **OEChem TK** drops all but the ``A`` or *blank* conformations when
reading atoms in  a PDB format file. To prevent this, the file
must be read with the :oe:const:`OEChem::OEIFlavor::PDB::ALTLOC` flavor.

.. oe:source:: PrepStepsDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-FLAVOR
   :refnum:   1
   :caption:  Setting the PDB Flavor to Retain All Alts

.. oe:source:: PrepStepsDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-FLAVOR
   :refnum:   1
   :caption:  Setting the PDB Flavor to Retain All Alts

.. oe:source:: PrepStepsDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-FLAVOR
   :refnum:   1
   :caption:  Setting the PDB Flavor to Retain All Alts

.. oe:source:: PrepStepsDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-FLAVOR
   :refnum:   1
   :caption:  Setting the PDB Flavor to Retain All Alts

Another way to drop all but one conformation is to use the
:ref:`OEAltLocationFactory <OEBio_OEAltLocationFactory>` object (see the
:ref:`section_alternate_location_factory` section) and generate, for example,
a molecule that retains only the highest occupancy conformation of each location
group. This object can be used to iterate through each combination of
alt locations (for example, when a group is moving in an active site).

.. oe:source:: PrepStepsDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-PRIMARY
   :refnum:   2
   :caption:  Keeping the Highest Occupancy Alt Locations

.. oe:source:: PrepStepsDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-PRIMARY
   :refnum:   2
   :caption:  Keeping the Highest Occupancy Alt Locations

.. oe:source:: PrepStepsDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-PRIMARY
   :refnum:   2
   :caption:  Keeping the Highest Occupancy Alt Locations

.. oe:source:: PrepStepsDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-ALTLOCFACT-PRIMARY
   :refnum:   2
   :caption:  Keeping the Highest Occupancy Alt Locations

.. _section_place_hydrogens:

Adding Hydrogens and Optimizing Hydrogen Bonds
================================================================================

.. index:: HBonds OEPlaceHydrogens

Traditionally, most protein structures have been generated with either no
explicit hydrogens or only polar hydrogens.
However, having all atoms explicitly represented and positioned to make
appropriate hydrogen bonds is sometimes necessary.
The function :oe:func:`OEBio::OEPlaceHydrogens` does this by adding and
placing hydrogens and by "flipping" certain functional groups
(e.g., sidechain amides and imidazoles) as required.

.. figure:: images/1eocN403FLIPS405.*
   :scale:  100
   :align:  center

   **Asparagine has been flipped and serine oriented to H-bond with main-chain atoms**

.. oe:source:: PrepStepsDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-BASIC
   :refnum:   3
   :caption:  Adding and Optimizing the Positions of Hydrogens

.. oe:source:: PrepStepsDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-BASIC
   :refnum:   3
   :caption:  Adding and Optimizing the Positions of Hydrogens

.. oe:source:: PrepStepsDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-BASIC
   :refnum:   3
   :caption:  Adding and Optimizing the Positions of Hydrogens

.. oe:source:: PrepStepsDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-BASIC
   :refnum:   3
   :caption:  Adding and Optimizing the Positions of Hydrogens

There are several :ref:`OEPlaceHydrogensOptions <OEBio_OEPlaceHydrogensOptions>` parameters
that control the process. For example, it is possible to prevent the
bond lengths of any covalent bonds to pre-existing hydrogens from
being altered:

.. oe:source:: PrepStepsDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-OPTIONS
   :refnum:   4
   :caption:  Setting Options for Placing Hydrogens

.. oe:source:: PrepStepsDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-OPTIONS
   :refnum:   4
   :caption:  Setting Options for Placing Hydrogens

.. oe:source:: PrepStepsDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-OPTIONS
   :refnum:   4
   :caption:  Setting Options for Placing Hydrogens

.. oe:source:: PrepStepsDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-OPTIONS
   :refnum:   4
   :caption:  Setting Options for Placing Hydrogens

There are also :oe:cls:`OEPlaceHydrogensOptions<OEBio::OEPlaceHydrogensOptions>`
parameters for restraining which states a mover group is sampled over.
:oe:src:`Listing 5<SNIPPET-IS-SAME-RESIDUE-PRED-PlaceHydrogensPredDoc>` shows a predicate for identifying
atoms belonging to a specific residue.

.. oe:source:: PlaceHydrogensPredDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-IS-SAME-RESIDUE-PRED
   :refnum:   5
   :caption:  Predicate for Residue Equivalence

.. oe:source:: PlaceHydrogensPredDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-IS-SAME-RESIDUE-PRED
   :refnum:   5
   :caption:  Predicate for Residue Equivalence

.. oe:source:: PlaceHydrogensPredDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-IS-SAME-RESIDUE-PRED
   :refnum:   5
   :caption:  Predicate for Residue Equivalence

.. oe:source:: PlaceHydrogensPredDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-IS-SAME-RESIDUE-PRED
   :refnum:   5
   :caption:  Predicate for Residue Equivalence

We can use that predicate to prevent a selected residue from flipping:

.. oe:source:: PlaceHydrogensPredDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-PRED
   :refnum:   6
   :caption:  Preventing a Residue from Flipping

.. oe:source:: PlaceHydrogensPredDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-PRED
   :refnum:   6
   :caption:  Preventing a Residue from Flipping

.. oe:source:: PlaceHydrogensPredDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-PRED
   :refnum:   6
   :caption:  Preventing a Residue from Flipping

.. oe:source:: PlaceHydrogensPredDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-PRED
   :refnum:   6
   :caption:  Preventing a Residue from Flipping

Using an :ref:`OEPlaceHydrogensDetails <OEBio_OEPlaceHydrogensDetails>` object enables examination
of the results, showing the clusters of movable groups explored and the scores.
A simple way to get at this information is to display a summary description:

.. oe:source:: PrepStepsDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-DETAILS
   :refnum:   7
   :caption:  Examining the Details of Placing Hydrogens

.. oe:source:: PrepStepsDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-DETAILS
   :refnum:   7
   :caption:  Examining the Details of Placing Hydrogens

.. oe:source:: PrepStepsDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-DETAILS
   :refnum:   7
   :caption:  Examining the Details of Placing Hydrogens

.. oe:source:: PrepStepsDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-PLACE-HYDROGENS-DETAILS
   :refnum:   7
   :caption:  Examining the Details of Placing Hydrogens

The following is a fragment from a details object description:

.. code-block:: bash

   OEBio 2.1.1: score system MMFF-NIE: flip bias 2.000
   87 clusters : 5 flips
   cluster 0  : score -53.935!
                CG  ASN44(A)   :      amide:   -6.084  (o=-53.93!,f=-8.42!)
                NZ  LYS47(A)   : NH3 150deg:  -14.865
                CG  HIS80(A)   :    +bothHN:   -5.628  (o=-53.93!,f=-15.89!)
                OG1 THR81(A)   : OH   65deg:    1.255
                CD  GLN87(A)   :FLIP  amide:   -4.976  (o=-26.48!,f=-53.93!)
                CG  ASN126(A)  :      amide:   -5.193  (o=-53.93!,f=-35.33!)
                CG  ASN169(A)  :      amide:   -2.230  (o=-53.93!,f=-33.02!)
                CD  GLN203(A)  :      amide:   -1.400  (o=-53.93!,f=-15.53!)
                CG  HIS205(A)  :    +bothHN:   -8.693! (o=-53.93!,f=-6.89!)
                OG1 THR232(A)  : OH  179deg:    9.120
                O3B XYP601(A)  : OH  280deg:   -5.020
                O2B XYP601(A)  : OH  173deg:    3.917
                O4B XYP601(A)  : OH   50deg:    1.236
                O3  XIF602(A)  : OH   29deg:   -3.688
   cluster 1  : score -85.724!
                CG  HIS85(A)   :    +bothHN:   -7.737! (o=-85.72!,f=-84.85!)
                OG  SER86(A)   : OH  241deg:    2.116
                OG  SER139(A)  : OH  185deg:    3.367!
                OH  TYR171(A)  : OH   25deg:   -3.384
                CG  ASN172(A)  :      amide:    1.153  (o=-85.72!,f=-68.75!)
                NZ  LYS179(A)  : NH3 188deg:  -39.497
   ...
   single  13 : OG1 THR2(A)    : OH  151deg:    1.545
   single  14 : OG  SER25(A)   : OH  292deg:    2.046
   single  15 : OH  TYR29(A)   : OH  199deg:   -1.262
   single  16 : OG  SER35(A)   : OH  254deg:    1.935
   ...

.. seealso::

   * the :oe:meth:`OEBio::OEPlaceHydrogensDetails::Describe` method
     for more details about the output above
     and the ``MMFF-NIE`` scoring system that generated it.

.. _section_split_mol_complex:

Splitting Macromolecular Complexes
================================================================================

.. index:: PDB Splitting, OESplitMolComplex, OEGetMolComplexComponents, OEGetMolComplexFragments, OECombineMolComplexFragments

One common step in preparing a macromolecular complex
for use as input to a calculation is to separate components based
on their functional roles.
For example, a **SZMAP** calculation on a four-chain protein crystal structure
might require one of four copies of the ligand to be extracted
and the protein-complex associated with that ligand binding site
to be separately extracted, ignoring any waters, buffers, etc.

:oe:src:`Listing 8<SNIPPET-SPLIT-MOL-COMPLEX-SIMPLE-SplitMolComplexOptDoc>` uses the
:oe:func:`OEBio::OESplitMolComplex` function to separate the input molecule
into the ligand for the first binding site, the protein-complex
(including cofactors) for that site, the binding site waters,
and everything else. In this example, the ligand is identified automatically
and the binding site contains components near the ligand. If a ligand cannot be
located, the entirety of each protein and everything nearby defines each
binding site. If the input molecule is empty or there is some other
problem that prevents processing, :oe:func:`OEBio::OESplitMolComplex`
will return ``false``.

.. oe:source:: SplitMolComplexOptDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SIMPLE
   :refnum:   8
   :caption:  Splitting an Input Molecule

.. oe:source:: SplitMolComplexOptDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SIMPLE
   :refnum:   8
   :caption:  Splitting an Input Molecule

.. oe:source:: SplitMolComplexOptDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SIMPLE
   :refnum:   8
   :caption:  Splitting an Input Molecule

.. oe:source:: SplitMolComplexOptDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SIMPLE
   :refnum:   8
   :caption:  Splitting an Input Molecule

:oe:src:`Listing 8<SNIPPET-SPLIT-MOL-COMPLEX-SIMPLE-SplitMolComplexOptDoc>` uses the defaults,
so no attempt would be made to recognize covalent ligands.
:oe:src:`Listing 9<SNIPPET-SPLIT-MOL-COMPLEX-SPLIT-COVALENT-SplitMolComplexOptDoc>` uses an option
to turn on the splitting of covalent ligands. There are a
large number of options to control the process of splitting
a molecule. See :ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>`
for a complete list.

.. oe:source:: SplitMolComplexOptDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SPLIT-COVALENT
   :refnum:   9
   :caption:  Splitting Covalent Ligands

.. oe:source:: SplitMolComplexOptDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SPLIT-COVALENT
   :refnum:   9
   :caption:  Splitting Covalent Ligands

.. oe:source:: SplitMolComplexOptDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SPLIT-COVALENT
   :refnum:   9
   :caption:  Splitting Covalent Ligands

.. oe:source:: SplitMolComplexOptDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-SPLIT-COVALENT
   :refnum:   9
   :caption:  Splitting Covalent Ligands

A related approach uses :oe:func:`OEBio::OEGetMolComplexComponents`
to return an iterator of molecules.
:oe:src:`Listing 10<SNIPPET-SPLIT-MOL-COMPLEX-ITER-LIGNAME-SplitMolComplexIterDoc>` also illustrates
providing an explicit ligand residue name that must match
for the ligand to be identified.

.. oe:source:: SplitMolComplexIterDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-LIGNAME
   :refnum:   10
   :caption:  Iterating Over Split Components

.. oe:source:: SplitMolComplexIterDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-LIGNAME
   :refnum:   10
   :caption:  Iterating Over Split Components

.. oe:source:: SplitMolComplexIterDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-LIGNAME
   :refnum:   10
   :caption:  Iterating Over Split Components

.. oe:source:: SplitMolComplexIterDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-LIGNAME
   :refnum:   10
   :caption:  Iterating Over Split Components

The process used by the :oe:func:`OEBio::OESplitMolComplex`
and :oe:func:`OEBio::OEGetMolComplexComponents` functions involves
two steps:

#. separating components and assigning functional roles
#. filtering by roles to select the desired components

:oe:func:`OEBio::OESplitMolComplex` accesses separate filters
for ``lig``, ``prot``, ``wat``, and ``other`` from the
:ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>` object.
In :oe:func:`OEBio::OEGetMolComplexComponents`,
the combination of the ligand, protein, and water filters
is used to select the output components. The options method
:oe:meth:`OEBio::OESplitMolComplexOptions::ResetFilters`
can be used for basic changes to the filters, such as selecting
a different binding site (see :oe:src:`Listing 11<SNIPPET-SPLIT-MOL-COMPLEX-ALL-SITES-SplitMolComplexOptDoc>`).

.. oe:source:: SplitMolComplexOptDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ALL-SITES
   :refnum:   11
   :caption:  Resetting Filters for All Sites

.. oe:source:: SplitMolComplexOptDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ALL-SITES
   :refnum:   11
   :caption:  Resetting Filters for All Sites

.. oe:source:: SplitMolComplexOptDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ALL-SITES
   :refnum:   11
   :caption:  Resetting Filters for All Sites

.. oe:source:: SplitMolComplexOptDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ALL-SITES
   :refnum:   11
   :caption:  Resetting Filters for All Sites

The function :oe:func:`OEBio::OECountMolComplexSites`
returns the number of binding sites.

:oe:src:`Listing 12<SNIPPET-SPLIT-MOL-COMPLEX-COMBINE-FILTERS-SplitMolComplexOptDoc>`
shows a more involved case, combining protein-complex
and binding-site waters into
the protein filter and nothing in the water filter.

.. oe:source:: SplitMolComplexOptDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-COMBINE-FILTERS
   :refnum:   12
   :caption:  Modifying Filters

.. oe:source:: SplitMolComplexOptDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-COMBINE-FILTERS
   :refnum:   12
   :caption:  Modifying Filters

.. oe:source:: SplitMolComplexOptDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-COMBINE-FILTERS
   :refnum:   12
   :caption:  Modifying Filters

.. oe:source:: SplitMolComplexOptDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-COMBINE-FILTERS
   :refnum:   12
   :caption:  Modifying Filters


:oe:src:`Listing 13<SNIPPET-SPLIT-MOL-COMPLEX-ITER-FILTER-SplitMolComplexIterDoc>`
illustrates using an explicit filter when
iterating. :ref:`OEMolComplexFilter <OEBio_OEMolComplexFilter>` objects
can be of arbitrary complexity.

.. oe:source:: SplitMolComplexIterDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-FILTER
   :refnum:   13
   :caption:  Explicit Filter When Iterating

.. oe:source:: SplitMolComplexIterDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-FILTER
   :refnum:   13
   :caption:  Explicit Filter When Iterating

.. oe:source:: SplitMolComplexIterDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-FILTER
   :refnum:   13
   :caption:  Explicit Filter When Iterating

.. oe:source:: SplitMolComplexIterDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITER-FILTER
   :refnum:   13
   :caption:  Explicit Filter When Iterating

For more complex workflows, it is useful to explicitly separate
the tasks of assigning roles and filtering, if only to avoid
the expense of assigning roles multiple times.
:oe:src:`Listing 14<SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-FRAGMENT-SplitMolComplexLowLevelDoc>`
shows how to assign roles to each fragment in a molecule
for later use.

.. oe:source:: SplitMolComplexLowLevelDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-FRAGMENT
   :refnum:   14
   :caption:  Assigning Roles to Each Mol Fragment

.. oe:source:: SplitMolComplexLowLevelDoc.py
   :language: python
   :noindent:
   :frag:    SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-FRAGMENT
   :refnum:   14
   :caption:  Assigning Roles to Each Mol Fragment

.. oe:source:: SplitMolComplexLowLevelDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-FRAGMENT
   :refnum:   14
   :caption:  Assigning Roles to Each Mol Fragment

.. oe:source:: SplitMolComplexLowLevelDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-FRAGMENT
   :refnum:   14
   :caption:  Assigning Roles to Each Mol Fragment

In :oe:src:`Listing 15<SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-COMBINE-SplitMolComplexLowLevelDoc>`,
the role information for each fragment is used to determine the
number of binding sites and is filtered
to produce ligand and protein complex mols.

.. oe:source:: SplitMolComplexLowLevelDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-COMBINE
   :refnum:   15
   :caption:  Filtering Mol Fragments

.. oe:source:: SplitMolComplexLowLevelDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-COMBINE
   :refnum:   15
   :caption:  Filtering Mol Fragments

.. oe:source:: SplitMolComplexLowLevelDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-COMBINE
   :refnum:   15
   :caption:  Filtering Mol Fragments

.. oe:source:: SplitMolComplexLowLevelDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-LOWLEVEL-COMBINE
   :refnum:   15
   :caption:  Filtering Mol Fragments

The basic idea behind automatic ligand identification is
that the list of compounds that are *not* ligands (cofactors,
buffers, etc.) grows faster than the list of ligands.
The :ref:`OEResidueCategoryData <OEBio_OEResidueCategoryData>` object
contained within an :ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>`
is a database of these non-ligands. Although this database
is being updated as we run across more cofactors, buffers, etc.,
it is possible for users to update the database as needed.
:oe:src:`Listing 16<SNIPPET-SPLIT-MOL-COMPLEX-ADD-COFACTOR-SplitMolComplexIterDoc>` shows how
this is done, involving the Russian nesting doll-like organization of a
:ref:`OEResidueCategoryData <OEBio_OEResidueCategoryData>` within a
:ref:`OEMolComplexCategorizer <OEBio_OEMolComplexCategorizer>` within a
:ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>` object.

.. oe:source:: SplitMolComplexIterDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ADD-COFACTOR
   :refnum:   16
   :caption:  Adding a Cofactor

.. oe:source:: SplitMolComplexIterDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ADD-COFACTOR
   :refnum:   16
   :caption:  Adding a Cofactor

.. oe:source:: SplitMolComplexIterDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ADD-COFACTOR
   :refnum:   16
   :caption:  Adding a Cofactor

.. oe:source:: SplitMolComplexIterDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ADD-COFACTOR
   :refnum:   16
   :caption:  Adding a Cofactor

.. note::

   Please help **OpenEye** maintain and expand
   the built-in :ref:`OEResidueCategoryData <OEBio_OEResidueCategoryData>`
   by informing us of any oversights or mistakes.

The most important :ref:`OESplitMolComplexOptions <OEBio_OESplitMolComplexOptions>` parameters
can be controlled from the command line using
:oe:func:`OEBio::OEConfigureSplitMolComplexOptions` and
:oe:func:`OEBio::OESplitMolComplexSetup`
(see :oe:src:`Listing 17<SNIPPET-SPLIT-MOL-COMPLEX-ITF-SplitMolComplexDoc>`).

.. oe:source:: SplitMolComplexDoc.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITF
   :refnum:   17
   :caption:  Command Line Options

.. oe:source:: SplitMolComplexDoc.py
   :language: python
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITF
   :refnum:   17
   :caption:  Command Line Options

.. oe:source:: SplitMolComplexDoc.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITF
   :refnum:   17
   :caption:  Command Line Options

.. oe:source:: SplitMolComplexDoc.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SPLIT-MOL-COMPLEX-ITF
   :refnum:   17
   :caption:  Command Line Options
