.. _spruce_examples_make_design_units_using_metadata:

Creating OEDesignUnits Using Provided Metadata
===============================================

Preparation of a biological structure file (PDB, mmCIF) to a fully charged,
hydrogenated, molecular componentized object (design unit, or DU; :ref:`OEDesignUnit <OEBio_OEDesignUnit>`)
is one of the more advanced functionalities offered through **Spruce TK**. Metadata can be provided to **Spruce TK**
to identify the target ligand, the desired ligand tautomeric state, and the DU title. In the case where
SEQRES data is not present for the structure, the sequence specified in the metadata can be used to build missing gaps and identify
natural termini versus termini that need to be capped.

Metadata can be provided in the form of a JSON. The example below shows a template for it. It was generated by 
exporting an :oe:cls:`OESpruce::OEStructureMetadata` class.

.. code-block::
   
   {
      "StructureID": "",
      "Author": "",
      "Keywords": [],
      "RevisionDate": "",
      "Revision": "",
      "ExperimentDate": "",
      "ExperimentType": "UNKNOWN",
      "IridiumData": {
         "Category": "NA",
         "LaD": 0.0,
         "ASaD": 0.0,
         "POL": false,
         "POAS": false,
         "AltConfs": false,
         "PackRes": false,
         "Excp": false,
         "IrrRFree": false,
         "PossCov": false,
         "DPI": 20.0,
         "RFree": 0.0,
         "Resolution": 0.0,
         "HasMTZ": false
      },
      "SequenceMetadata": [],
      "HeterogenMetadata": []
   }

This example shows how to construct DUs with a specific ligand tautomer by providing ligand metadata.


Command Line Interface
----------------------

This example uses an input PDB/mmCIF file and a metadata JSON file, and will output a set of DUs with the specified
ligand tautomers. Setting the -generate_tautomers option to false ensures that only the tautomers specified in the metadata
file are considered. Setting the -opt_expt_protons option to true ensures that experimental protons are optimized and thus
the tautomeric state can be changed based on the provided metadata. The provided script can be used with a modified metadata
file to accomplish the other mentioned examples as well.


.. code-block:: console

     prompt> make_design_unit_using_metadata.py -in <PDB/mmCIF file> -loop_db <loop database> -metadata <metadata JSON> -generate_tautomers false -opt_expt_protons true

Code
----------------------

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`make_design_unit_using_metadata.py <../../../../wrappers/python/examples/spruce/make_design_unit_using_metadata.py>`
         and both the
         :download:`5CDO.cif <../../../../wrappers/test_data/OESpruceTests/5CDO.cif>`
         (the input mmCIF file),
         :download:`53M_ligand.json <../../../../wrappers/test_data/OESpruceTests/53M_ligand.json>`
         (the input metadata file), and
         :download:`spruce_bace.loop_db <../../../../wrappers/test_data/OESpruceTests/spruce_bace.loop_db>`
         (the input loopDB file)

   .. :ref:`Full listing. <listing-make_design_unit_using_metadata.py>`

   ..   literalinclude:: ../../../../wrappers/python/examples/spruce/make_design_unit_using_metadata.py

.. only:: oepdf

      .. oe:source:: make_design_unit_using_metadata.py
         :language: python

.. seealso::

   * :oe:func:`OESpruce::OEMakeDesignUnits` function
   * :oe:func:`OEBio::OEReadDesignUnit` and :oe:func:`OEBio::OEWriteDesignUnit` functions in the **OEChem TK** manual
   * :ref:`OEDesignUnit <OEBio_OEDesignUnit>` class in the **OEChem TK** manual
   * :oe:cls:`OESpruce::OEStructureMetadata` class
