.. _section_oespruce_releasenotes_100:

Spruce TK 1.0.0
================================================================================

New features
--------------------------------------------------------------------------------

* The :oe:func:`OESpruce::OEExtractBioUnits` function has become a stable API.
  The final implementation includes an options class, :ref:`OEBioUnitExtractionOptions <OESpruce_OEBioUnitExtractionOptions>`,
  to control its behavior.

* A new function, :oe:func:`OESpruce::OEMakeDesignUnits`, has been added that generates
  :ref:`OEDesignUnit <OEBio_OEDesignUnit>` from structures read from PDB or mmCIF files.
  The function takes a number of options to control its behavior; therefore, the
  following options classes have been defined:

  * :ref:`OEMakeDesignUnitOptions <OESpruce_OEMakeDesignUnitOptions>`: a high-level options class that
    holds the options classes below.

  * :ref:`OEDesignUnitPrepOptions <OESpruce_OEDesignUnitPrepOptions>`: a high-level options class that
    holds other options classes, determining how a design unit is prepped.

  * :ref:`OEDesignUnitBuildOptions <OESpruce_OEDesignUnitBuildOptions>`: a low-level class that sets whether to build caps and
    missing sidechains.

  * :ref:`OEProtonateDesignUnitOptions <OESpruce_OEProtonateDesignUnitOptions>`: a low-level class that sets whether and how to
    protonate the design unit, including whether to generate tautomers.

  * :ref:`OEDesignUnitSplitOptions <OESpruce_OEDesignUnitSplitOptions>`: a low-level class that determines how to handle
    alternate locations, how a system is split, locating the ligand, etc.

  The :oe:func:`OESpruce::OEMakeDesignUnits` function also takes the
  :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>` class as input. The
  :ref:`OEStructureMetadata <OESpruce_OEStructureMetadata>` class holds experimental data if known
  and can be used to indicate which is the ligand, what the sequence of the protein
  is, and other relevant pieces of information.

* The function :oe:func:`OESpruce::OEMakeDesignUnits` is a high-level function
  that works on the two intermediate functions, :oe:func:`OESpruce::OEMakeBioDesignUnits`
  and :oe:func:`OESpruce::OEEnumerateSites`, which can be run separately if intermediate
  results are desired. The high-level :oe:func:`OESpruce::OEMakeDesignUnits` function
  has a deduplication step built in; this function is highly recommended.

* A new function, :oe:func:`OESpruce::OEMakeDesignUnit`, has been added that creates an
  :ref:`OEDesignUnit <OEBio_OEDesignUnit>`.

* A new function, :oe:func:`OESpruce::OEProtonateDesignUnit`, has been added that ensures that
  protons in an :ref:`OEDesignUnit <OEBio_OEDesignUnit>` are optimized. The high-level function
  :oe:func:`OESpruce::OEMakeDesignUnits` calls this by default unless it is turned off in options.

* The :oe:func:`OESpruce::OEBuildSidechains` function has been updated to allow building
  all possible clusters even if one fails due to clashes.
  The function still returns ``false`` in this case.

Major bug fixes
--------------------------------------------------------------------------------

* An issue in the :oe:func:`OESpruce::OEExtractBioUnits` function that caused a segfault due
  to an improper PDB header format has been fixed.

* An issue in the alternate location expansion that left atoms on top
  of each other due to unconventional location definitions has been fixed.

Minor bug fixes
--------------------------------------------------------------------------------

* An issue with :oe:func:`OESpruce::OECapTermini` preventing caps from being
  built in some very specific instances has been fixed.

* :oe:func:`OESpruce::OEBuildSidechains` no longer
  builds sidechains on packing residues.

Documentation changes
--------------------------------------------------------------------------------

* A new example, :ref:`spruce_examples_make_design_units`, has been added that
  illustrates the usage of the high-level :oe:func:`OESpruce::OEMakeDesignUnits`
  function for biomolecular structure preparation. This example takes a PDB file
  as input and outputs a set of fully prepared :ref:`OEDesignUnit <OEBio_OEDesignUnit>` objects
  to a temporary file.