.. _spruce_example:

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

.. program:: spruce

======================
Example Commands
======================

The simplest way to run **SPRUCE** is by passing in an input biomolecular structure file (PDB or mmCIF) as the only argument.

.. code-block:: bash

   prompt> spruce -in 3fly.cif.gz

Here, **SPRUCE** will correctly split and prepare :file:`3fly.cif.gz` with the :option:`-in` parameter and the standard set of default options. The output will generally be a set of OEDesignUnit (.oedu) files,
depending on the number of ligands and biological units in the asymmetric unit. In this case a single design unit file is produced (:file:`3FLY_A__DU__FLY_A-361.oedu`).

There are also many options that can be invoked from **SPRUCE** on the command line. For instance, several options are available to help **SPRUCE** determine the ligand based on molecular features like the number of residues in a peptidic ligand:

So for example:

.. code-block:: bash

   prompt> spruce -in 4obd.cif.gz -max_lig_residues 20


will correctly split and prepare :file:`4obd.cif.gz`, based on the :option:`-max_lig_residues` which sets the maximum number of residues that can still be considered a ligand (required for larger, peptidic ligands like those in 4OBD).

Alternatively, one may want to prepare a biomolecular structure file based on the structure of a similar reference system. For instance, one may construct an OEDesignUnit with a set of site residues defined using a reference that includes a ligand:

.. code-block:: bash

   prompt> spruce -ref 4OBD.oedu -in 1hhp.cif

Here, an mmCIF file (:file:`1hhp.cif`) is prepared using the site defined in the output OEDesignUnit file prepared using the :option:`-ref` option and an output .oedu file from the example above.

This could also have been done by specifying a site residue, for example (note the blank character for the insert code):

.. code-block:: bash

   prompt> spruce -site_residue "ASP:25: :A" -in 1hhp.cif

To calculate the Iridium classification as a metric of structure quality, one must provide the map file that corresponds to experiment from which the biomolecular structure was derived:

.. code-block:: bash

   prompt> spruce -map 3rox_validation_2fo-fc_map_coef.cif.gz -in 3rox.cif.gz

Here a set of OEDesignUnit files will be produced from :file:`3rox.cif.gz`, where each oedu file will include its own Iridium score taken from a calculation on the density passed in through the :option:`-map` option (:file:`3rox_validation_2fo-fc_map_coef.cif.gz`). The Iridium score can be extracted from any OEDesignUnit file using the **spruce TK** API, but it will also be reported in the **spruce** application's output.

.. note::

   The :option:`-map` option accepts structure factor CIF files (``.cif``, ``.cif.gz``) as provided by
   :ref:`GetStructure <chapter_getstructure>` and the RCSB, as well as legacy MTZ files (``.mtz``).

Several options in **SPRUCE** are available to help control how the system is prepared. For instance by default, **spruce** calculates partial charges and adds any hydrogen atoms missing from the experimental structure. However, if you have a have a downstream application that does not require certain time-consuming computations, like calculating partial charges or adding missing hydrogen atoms, you can tell **SPRUCE** to turn these features off:

.. code-block:: bash

   prompt> spruce -protonate false -charge_radii false -in 3tpp.cif.gz

Here, **SPRUCE** will not add partial charges or hydrogen atoms to the output structures during the preparation process of :file:`3tpp.cif.gz` by using the boolean options :option:`-protonate` and :option:`-charge_radii`, both of which are set to ``true`` by default.


To prevent continually over-writing output files, the :option:`-prefix` input parameter.
allows you to give unique names to these files.

.. code-block:: bash

   prompt> spruce -in 3fly.cif.gz -prefix FOO

will write the output structure into a file named :file:`FOO_3FLY_A__DU__FLY_A-361.oedu`.

Finally, to help **spruce** identify ligands in the biomolecular structure file, use the
:option:`-ligand_names` flag as in this example with :file:`3b3n.cif.gz`.

.. code-block:: bash

   prompt> spruce -ligand_names JI2 -in 3b3n.cif.gz
