.. _section_oespruce_releasenotes_110:

Spruce TK 1.1.0
================================================================================

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

* Two new APIs,
  :oe:func:`OESpruce::OEBuildSingleLoop` and :oe:func:`OESpruce::OEBuildLoops`, have been added
  that provide loop modeling capability.
  This capability relies on either the SEQRES in the PDB header (or equivalent for
  MMCIF files) or the user passing metadata about the sequences. The functions
  take an options class, :ref:`OELoopBuilderOptions <OESpruce_OELoopBuilderOptions>`, as an argument
  to specify the file name of the required loop template database.
  This database is available for
  `download <http://www.eyesopen.com/db-downloads>`_
  in a platform-independent format.

* A new parameter, ``siteResidue``,  has been added to the
  :oe:func:`OESpruce::OEMakeDesignUnits` function. This allows users to specify a single
  residue in the binding site for APO structures when using the
  :oe:func:`OESpruce::OEEnumerateSites` function. The function checks whether the detected
  site has a large enough volume and whether there is anything in the binding site that the
  splitter failed to identify as a potential ligand.

* The options class :ref:`OEDesignUnitBuildOptions <OESpruce_OEDesignUnitBuildOptions>` has been updated to
  hold options classes for the different builder options available. This also changes
  the options class structure for :ref:`OEMakeDesignUnitOptions <OESpruce_OEMakeDesignUnitOptions>`.

* A new low level class, :ref:`OECapBuilderOptions <OESpruce_OECapBuilderOptions>`, that determines behavior
  when building caps on proteins, has been added to replace passing different parameters to the functions :oe:func:`OESpruce::OECapTermini`,
  :oe:func:`OESpruce::OECapNTermini`, and :oe:func:`OESpruce::OECapCTermini`.

* :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>`, a low level class that determines
  the behavior when building sidechains on proteins, replaces passing different
  parameters to the function :oe:func:`OESpruce::OEBuildSidechains`.

* The preliminary API options class ``OEDesignUnitMutationOptions`` has been removed.
  :oe:func:`OESpruce::OEMutateResidues` has been added to take a map of mutations, along with
  :ref:`OESidechainBuilderOptions <OESpruce_OESidechainBuilderOptions>` to control the behavior when building
  the mutated residue sidechain.

* A new function, :oe:func:`OESpruce::OEFixBackbone`, has been added that builds =O
  and/or OXT, if necessary, and ensures that all formal charges and valence states are
  correct on all backbone atoms. The function removes a residue completely if
  the primary backbone atoms, N, CA, and C, are missing. The residues can be built
  correctly later with :oe:func:`OESpruce::OEBuildLoops`.

* A strict protonation mode has been added to :ref:`OEDesignUnitPrepOptions <OESpruce_OEDesignUnitPrepOptions>`,
  enforcing that when an error occurs during addition and optimization of hydrogens to the system,
  the preparation processes now stop and fail.

* A new options class, :ref:`OEPlaceHydrogensOptions <OEBio_OEPlaceHydrogensOptions>`, has been added to
  :ref:`OEProtonateDesignUnitOptions <OESpruce_OEProtonateDesignUnitOptions>`.  This option allows users more control
  over the protonation processes; for example, by passing a bypass or no-flip predicate that
  will prevent the protonation process from altering the residues in the predicate.

* The design units produced by :oe:func:`OESpruce::OEMakeDesignUnits` are now ordered
  by the quality of the Iridium classification data.


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

* A bug in :oe:func:`OESpruce::OEExtractBioUnits` that occurred when using a reference
  has been fixed. Previously, it resulted in incorrect biological units being produced
  under certain conditions. The algorithm has also been improved to more often produce
  the correct biological unit based on symmetry expansion.


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

* Metal co-factors previously had not been properly identified in the binding site during design
  unit generation due to the distance threshold from a ligand that was too strict. This has been fixed.

* Ligands with an incorrect alternate location assignment but that were in the same location
  were previously not correctly identified and were assigned alternate locations. This was due
  to the threshold being too strict and has been fixed.

* In cases where a residue is itself converted to a cap and where building a cap would
  result in the cap strongly clashing, the cap number no longer adds an insert code or
  alters the residue number. In addition, valence states resulting from the residue
  conversion are being more thoroughly validated and fixed, if necessary.

* Some instances of functions changing the location of the ``OEThrow`` output and their levels
  have been fixed.

* An issue in :oe:func:`OESpruce::OEExtractBioUnits` had previously occurred when structures
  with the historical convention of putting waters and metals into specific chain IDs
  (i.e., W and S, respectively) caused the molecules, after symmetry expansion, to
  have identical residue information.  This has been fixed.

* An issue with the side-chain builder miscounting side-chain atoms when involving a residue
  in cross-linking has been fixed.

* An issue that occurred when a single ligand atom (per design) was not properly detected as a
  ligand has been fixed.

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

* Documentation and examples have been modified to omit the step where alternate locations are
  collapsed. The function :oe:func:`OESpruce::OEMakeDesignUnits` handles alternate
  location collapse or enumeration and should provide all available data.

* Examples in C++ and Python have been enhanced to include passing electron
  density maps, and a new example has been added for making APO design units using
  a site residue or reference structure. The examples also illustrate how to enable
  **Spruce TK** to build missing loops.
