.. _spruce_introduction:

.. include:: ../../apps-substitutions

************
Introduction
************

==============
Overview
==============
The SPRUCE application provides the facilities to prepare biomolecules (that is, proteins and nucleic acids) for modeling tasks.


==============
Applications
==============

The **SPRUCE** distribution comprises these applications:

   :ref:`SPRUCE <chapter_spruce>`

   The :ref:`SPRUCE <chapter_spruce>` program is used for biomolecule preparation, from experimental or modeled structures.
   The process involves, 1) expansion of the :term:`asymmetric unit` to the :term:`biological unit` (if structure is from an X-ray crystallography
   experiment and it is necessary), 2) enumeration (default) or collapse of alternate locations, 3) building missing pieces, for example, partial
   sidechains, capping chain breaks, and modeling missing loops, 4) placement and optimization of hydrogen atoms including tautomer enumeration of ligands and cofactors,
   as well as evaluation of those tautomer states in the biomolecule structure.

   :ref:`Superposition <chapter_superposition>`

   The :ref:`Superposition <chapter_superposition>` program is used to superpose biomolecule structures onto a reference structure. Several different
   superposition methods are included, that are either based on sequence or secondary structure.


==================
Utility Programs
==================

The following utility programs are also included in this distribution:

   :ref:`LoopDB_Builder <chapter_loopdb_builder>`

   The :ref:`LoopDB_Builder <chapter_loopdb_builder>` program is used to build a database of known loops from a set of protein structures. This
   database can then be passed as an option to :ref:`SPRUCE <chapter_spruce>` to enable loop modeling of gaps in protein structures.

   :ref:`GetStructure <chapter_getstructure>`

   The :ref:`GetStructure <chapter_getstructure>` utility program can be used to download biomolecular structure files (PDB, mmCIF, structure factor CIF) for downstream prepping with :ref:`SPRUCE <chapter_spruce>`.

   :ref:`Du2pdb <chapter_du2pdb>`

   The :ref:`Du2pdb <chapter_du2pdb>` utility program can be used to convert DesignUnit oedu files to PDB file format.

   :ref:`EnumSites <chapter_enumsites>`

   The :ref:`EnumSites <chapter_enumsites>` program can be used to enumerate sites from prior bio-design units produced by :ref:`SPRUCE <chapter_spruce>`.
   This is particularly useful when enumerating potentially allosteric apo sites, that where not known when the structure was
   prepared the first time - enumeration ensures that the structure is not re-prepared but just focused into a site of interest.


====================================
Utilizing a Loop Template Database
====================================

Included in the SPRUCE product is a large database of loop templates, described further in the :ref:`Spruce theory <sprucetk_theory>` section.

To use it during prep:

   -loop_db_filename rcsb_spruce.loop_db

The database can be appended to (updated) using the :ref:`LoopDB_Builder <chapter_loopdb_builder>` utility. This would be in the event that the user has
a collection of internal/proprietary structures, or if specific structures are released to the public PDB between OpenEye updates of the database that are
crucial for a given target that is less well described by the existing templates. 

Loop building will only be done when a loop template database is provided.

For more information, see the :ref:`theory explanation for the Spruce toolkit <sprucetk_theory>` and
the :ref:`Iridium chapter of that toolkit <chapter_sprucetk_iridium>`.

.. previous .. include directives did not do the right thing with oe:source display

.. .. include:: ../../../toolkits/sprucetk/theory/theory.rst

.. .. include:: ../../../toolkits/sprucetk/theory/iridium.rst
