The SPRUCE application provides the facilities to prepare biomolecules (i.e. proteins and nucleic acids) for modeling tasks.


The SPRUCE distribution comprises 3 applications:


The SPRUCE program is used for biomolecule preparation, from experimental or modeled structures. The process involves, 1) expansion of the asymmetric unit to the biological unit (if structure is from an X-ray crystallography experiment and it it is necessary), 2) enumeration (default) or collapse of alternate locations, 3) building missing pieces e.g. partial sidechains and capping chain breaks, 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.


The 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.


The EnumSites program can be used to enumerate sites from prior bio-design units produced by 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.


The GetStructure utility program can be used to download biomolecular structure files (PDB, mmCIF, mtz) for downstream prepping with SPRUCE.


Spruce TK is used to process PDB or mmCIF files containing the structures, resulting from X-ray crystallography, Nuclear Magnetic Resonance (NMR) spectroscopy, or electron microscopy (EM) experiments. into molecules usable for molecular modeling. Due to the nature of the experiments and data, some processing is required before use in modeling. SpruceTk provides an end-to-end preparation workflow using the OEMakeDesignUnits API. Options (see OEMakeDesignUnitOptions and associated options classes) are available to control for the desired behavior. Metadata (see OEStructureMetadata) can be supplied to infuse experimental data, like the proper variant sequence and also fix common problems reading from PDB files (e.g. bond order perception). Spruce has a built in Chemical Components Dictionary matching 3-letter residue codes to SMILES, derived from the corresponding one at the RCSB, but curated to fix improper SMILES. The workflow automatically runs through the below steps to produce OEDesignUnit objects:

  1. Biological unit extraction (see OEExtractBioUnits)
  2. If structure is from X-ray, it will also generate packing residues for visualization of crystal contacts
  3. Alternate location assignment or enumeration (see the OEAlternateLocationOption namespace)
  4. Splits the system into components, e.g. identifying ligands, cofactors, excipients.
  5. Building missing side-chains and capping chain breaks (see OEBuildSidechains and OECapTermini)
  6. Hydrogen placement and optimization, including searching ligand tautomer states (see OEProtonateDesignUnit)
  7. Assignment of partial charges to the entire system (see OEDesignUnitCharges)
  8. Superposition to a common reference frame (see OEStructuralSuperposition and OESecondaryStructureSuperposition)
  9. An OEInteractionHintContainer encoded for visualization and more
  10. An estimate of the model quality using Iridium [Warren-2012] stored in OEIridiumData


Multiple design units are often produced. This results from multiple biological units generated during step 1, and further expanding that set when enumerating the alternate locations in step 2. The Iridium categorization (see section_sprucetk_iridium_categorization) should be helpful in choosing which (if not all) of the produced units to use in downstream modeling tasks. We find that the Iridium categories are also helpful for managing modeling expectations, having a quality measure of the input data for modeling.


  1. Biological Unit (BU) - the biologically relevant unit for a protein to use in modeling. For example, in Trypsin the BU is a monomer, in HIV Protease the BU is a homo-dimer. See Biological Unit below.
  2. Asymmetric Unit (ASU) - the contents of a PDB or mmCIF file from X-ray contain an asymmetric unit as the output of the experiment. This is sometimes equivalent to the BU, but often requires manipulation to create a correct BU.
  3. Design Unit (DU) - the result of preparation in spruce is a collection of molecules from a single BU, extracted and ready to use for modeling tasks. See Design Unit below for more details.
  4. Alternate locations (alt locs) - X-ray experiments can often contain results with atoms occupying more than one location. Crystallographers denote this with a measure of the amount of time an atom occupies a given set of coordinates. A well resolved atom will have an occupancy of 1.0, meaning that 100% of the time it is in that location. Sometimes, the atom exists in two positions, alternate locations, and these appear in the input file with single letter designations and with occupancy < 1.0.

Biological Unit

In short, the biological unit (BU) is an object that contains the biologically relevant parts of an ASU, which have not been split into various molecular components and are not yet prepped for modeling. For a more detailed explanation of BUs, refer to Introduction to Biological Assemblies and the PDB Archive hosted at the RCSB.

A BU can be constructed from a single PDB from the PDB’s own header remarks, or by using a sequence alignment to an input reference protein. To extract a BU or set of BUs from a PDB, one should use the helper function in Spruce TK called OEExtractBioUnits. The following example shows how to extract BUs from the PDB remarks:

Using the same function, one can also extract BUs from a PDB using an input reference protein. The following example shows how to use OEExtractBioUnits to extract BUs from a given reference:

Design Unit

The design unit (DU) is an object that contains the extracted and prepared parts of a single BU, ready for modeling. The parts include:

  1. Protein
  2. Ligand (not always, an apo DU will not contain a ligand)
  3. Site residues
  4. Packing residues (if any exist near the site)
  5. Excipients (if any exist near the site)

Protein Superposition

A protein can be structurally superimposed on to a reference protein structure using the OESpruce TK. Proteins can be superimposed with either atomic coordinates in the OEStructuralSuperposition class, or with secondary structure elements using the OESecondaryStructureSuperposition class.

The OEStructuralSuperposition class can superimpose proteins using any of the following four methods:

  1. The global method (default for OEStructuralSuperposition). This method uses all matching heavy atoms from the reference and fit proteins as the region for performing the superposition calculation (see OESuperpositionType::Global).
  2. The Difference Distance Matrix method. This method calculates the pairwise distance matrix of C-alpha atoms for both the reference and fit proteins, then takes the difference of these two matrices to find the difference distance matrix (DDM). The longest contiguous region of the resulting difference distance matrix (DDM) is used for the structural superposition calculation (see OESuperpositionType::DDM).
  3. The weighted-DDM method. This method uses the DDM matrix, and calculates Gaussian weighting factors for all matching C-alpha atoms. These Gaussian weights are used as a weighting function in the superposition calculation (see OESuperpositionType::Weighted).
  4. The site residue method. This method uses a set of site residues (given as a set of unique residue strings) as a constraint on the protein superposition. Site residues must be set with the SetSiteResidues member function of the OESuperpositionOptions class (see OESuperpositionType::Site).

The OESecondaryStructureSuperposition class can superimpose proteins using the following method:

  1. The secondary structure superposition method. This method takes two proteins and performs a structural superposition on them based on the shape overlap of the secondary structure elements of the two proteins.


All structural superposition methods in the OEStructuralSuperposition class have a corresponding score from the sequence alignment that was used to find the matching atoms of both proteins. This score comes from the output of the OESequenceAlignment class, where a larger score indicates a better sequence alignment, and scores below a small threshold (around 200) should be considered a bad alignment.


All structural superposition methods in the OEStructuralSuperposition class have a corresponding RMSD value for superposition that can be loosely associated with the quality of the superposition. The OESecondaryStructureSuperposition class does not have an RMSD value, but instead uses the Tanimoto score from the underlying shape overlap calculation.

How to Correctly Read a PDB File

Reading a PDB file correctly for use in subsequent modeling tasks can be challenging. To correctly read a PDB, one must be aware that PDB header information as well as information about alternate location codes within the PDB file will be lost unless a specific combination of PDB-centric OEIFlavor‘s are used. Furthermore, the protein itself must be processed by OEAltLocationFactory in order to create a molecule with all alternate location atoms retained. With that in mind, we recommend reading PDB files for use in OESpruce TK using the following pattern as shown in ReadProteinFromPDB below:


The mmCIF reader was designed to read all the necessary input by default, and therefore no specific OEIFlavor‘s are necessary to read them.