NMRPy · torogi94 · May 19, 2023 · Aug 22, 2023 · Sep 5, 2023 · Sep 5, 2023
diff --git a/README.md b/README.md
@@ -6,9 +6,7 @@
 
 NMRPy is a Python 3 module for the processing and analysis of NMR spectra. The
 functionality of NMRPy is structured to make the analysis of arrayed NMR
-spectra more intuitive.
-
-Read the docs at http://nmrpy.readthedocs.io/
+spectra more intuitive.Read the docs at http://nmrpy.readthedocs.io/
 
 ## Installation
 
@@ -24,6 +22,9 @@ For installation with pip:
 For installation with conda:    
 `conda install -c bioconda -c conda-forge -c jmrohwer nmrpy`
 
+For EnzymeML support, install with the `enzymeml` extra:    
+`pip install nmrpy[enzymeml]`
+
 Detailed installation instructions are available at
 https://nmrpy.readthedocs.io/en/latest/installation.html
 

diff --git a/docs/source/_static/quickstart_16.png b/docs/source/_static/quickstart_16.png
diff --git a/docs/source/_static/quickstart_17.png b/docs/source/_static/quickstart_17.png
diff --git a/docs/source/_static/quickstart_18.png b/docs/source/_static/quickstart_18.png
diff --git a/docs/source/_static/quickstart_19.png b/docs/source/_static/quickstart_19.png
diff --git a/docs/source/_static/quickstart_20.png b/docs/source/_static/quickstart_20.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,6 +16,7 @@ Contents:
     quickstart
     data_objects
     plotting_objects
+    utility_objects
 
 Indices and tables
 ==================

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -168,6 +168,20 @@ into your virtual environment using ``pip``.
 
     (nmr) $ pip install nmrpy
 
+Optional EnzymeML dependencies
+==============================
+
+EnzymeML integration features are optional and are not required for standard
+NMRPy workflows. If you want to use EnzymeML-specific functionality, install
+the optional extra dependencies with:
+
+.. code:: bash
+
+    (nmr) $ pip install nmrpy[enzymeml]
+
+This extra installs ``pyenzyme`` and ``sympy`` in addition to the core
+dependencies.
+
 Testing the installation
 ========================
 
@@ -192,6 +206,10 @@ Only a specific subset of tests can be run by providing an additional argument:
 When testing the plotting utilities, a number of ``matplotlib`` plots will 
 appear. This tests that the peak and range selection widgets are working 
 properly; the plot windows can be safely closed.
+
+EnzymeML-related capabilities and tests require the optional EnzymeML
+dependencies to be installed. Core NMRPy tests and workflows do not depend on
+these optional packages.
 
 Working with NMRPy
 ==================

diff --git a/docs/source/intro.rst b/docs/source/intro.rst
@@ -6,6 +6,20 @@ NMRPy is a Python 3 module for the processing and analysis of NMR spectra. The
 functionality of NMRPy is structured to make the analysis of arrayed NMR
 spectra more intuitive.
 
+NMRPy is equipped with an integrated NMR data model based on the ``md-models``
+library (https://fairchemistry.github.io/md-models/) for FAIR and reproducible
+data management. It allows saving all relevant NMR data and metadata to structured
+data exchange formats like JSON. Most users can complete standard workflows without
+interacting with model internals directly, while advanced users can engage with
+the model when needed.
+
+NMRPy has optional hooks for working with EnzymeML documents, which are an XML-based
+data exchange format for enzyme kinetics data. These hooks allow users to link species
+information from EnzymeML with picked peaks in the spectra, and thus use them
+conveniently in concentration calculations. EnzymeML-related capabilities are optional,
+so users can use NMRPy without installing the optional EnzymeML dependencies if they
+do not need these features.
+
 A particular use case is the bulk processing and integration/deconvolution of 
 arrayed NMR spectra obtained for enzyme reaction time-courses, with a view to 
 determining enzyme-kinetic parameters for building systems-biology models [1,2].

diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -8,12 +8,16 @@ This is a "quickstart" tutorial for NMRPy in which an Agilent (Varian) NMR
 dataset will be processed. The following topics are explored:
 
     * :ref:`quickstart_importing`
+
+        * :ref:`quickstart_data_model`
+
     * :ref:`quickstart_apodisation`
     * :ref:`quickstart_phasecorrection`
     * :ref:`quickstart_calibration`
     * :ref:`quickstart_peakpicking`
     * :ref:`quickstart_deconvolution`
     * :ref:`quickstart_exporting`
+    * :ref:`enzymeml_support`
     * :ref:`quickstart_script`
 
 This tutorial will use the test data in the nmrpy install directory: ::
@@ -59,7 +63,21 @@ several attributes, most of which are of the form ``fidXX`` where *XX* is
 a number starting at 00. These are the individual arrayed
 :class:`~nmrpy.data_objects.Fid` objects.
 
+.. _quickstart_data_model:
+
+Data model
+----------
 
+The ``md-models``-based data model is woven into the core NMRPy data objects and
+is used to store all relevant NMR data and metadata in a structured way. The full
+model is stored in :attr:`~nmrpy.data_objects.FidArray.data_model` of the
+:class:`~nmrpy.data_objects.FidArray` object, while each individual
+:class:`~nmrpy.data_objects.Fid` has a subset of the model, the
+:class:`~nmrpy.nmrpy_model.FidObject`, stored in its
+:attr:`~nmrpy.data_objects.Fid.fid_object` attribute of
+:class:`~nmrpy.data_objects.Fid`. You can use the full quickstart tutorial
+without directly interacting with the model internals. However, at any time you may
+call the ``data_model`` attribute to retrieve the current state of the model.
 
 .. _quickstart_apodisation:
 
@@ -445,6 +463,97 @@ The :class:`~nmrpy.data_objects.FidArray` can be reloaded using
     >>> fid_array = nmrpy.from_path(fid_path='fidarray.nmrpy')
 
 
+.. _enzymeml_support:
+
+Working with EnzymeML
+====================
+
+To utilise the EnzymeML-related capabilities of NMRPy, the optional EnzymeML
+dependencies need to be installed. This can be achieved by installing NMRPy
+with the `enzymeml` extra: ::
+
+    >>> pip install nmrpy[enzymeml]
+
+EnzymeML documents can be created in a number of ways, e.g. with the ``PyEnzyme``
+Python package, with the ``EnzymeML Suite`` application, or even using the EnzymeML
+Excel template. Once you have an EnzymeML document, it can be loaded into NMRPy and
+linked to the :class:`~nmrpy.data_objects.FidArray` using the 
+:attr:`~nmrpy.data_objects.FidArray.link_enzymeml` property: ::
+
+    >>> import pyenzyme as pe
+    >>> edoc = pe.EnzymeMLDocument.read_enzymeml('my_enzymeml_document.json')
+
+    >>> fid_array.enzymeml_document = edoc
+
+Having loaded the EnzymeML document, the species information contained in the EnzymeML
+document can be linked to the picked peaks in the spectra. For this, the methods
+:meth:`~nmrpy.data_objects.FidArray.assign_species` and
+:meth:`~nmrpy.data_objects.Fid.assign_species` can be used to assign species to
+previously picked peaks for the whole array or for individual Fids, respectively.
+Both methods have a GUI widget that allows the user to conveniently select peaks and
+assign species from the EnzymeML document to these peaks. Alternatively, species can be
+assigned programmatically by providing the appropriate arguments to the methods. ::
+
+    >>> fid_array.assign_species()
+
+.. image:: _static/quickstart_16.png
+   :width: 75%
+   :align: center
+
+After concentrations have been calculated from the deconvoluted peak integrals,
+these have to be assigned to the :attr:`~nmrpy.data_objects.FidArray.concentrations`
+attribute of the :class:`~nmrpy.data_objects.FidArray` for use in kinetic calculations,
+using the species IDs from the EnzymeML document as keys to the dictionary of concentrations.
+
+Sometimes it may be necessary to adjust the first time point t0, as the first spectrum may
+have been acquired separately from the rest of the array, or because the time array from
+the spectrometer does not reflect the actual time-course of the reaction. The time array can
+be adjusted with the :meth:`~nmrpy.data_objects.FidArray.add_t0_to_enzymeml` method of
+:class:`~nmrpy.data_objects.FidArray`, which allows to shift the time array by a specified
+offset, use t1 as t0, or set t0 manually. Again, a GUI widget is provided for this method,
+but the time array can also be adjusted programmatically by providing the appropriate
+arguments to the method. ::
+
+    >>> fid_array.add_t0_to_enzymeml(measurement_id=1)
+
+.. image:: _static/quickstart_17.png
+   :width: 75%
+   :align: center
+
+.. image:: _static/quickstart_18.png
+   :width: 75%
+   :align: center
+
+Usually, there are multiple measurements to be processed for one experiment. The necessary
+``Measurement`` objects within the EnzymeML document can be conviently created at the end
+of an NMRPy workflow with the
+:meth:`~nmrpy.data_objects.FidArray.create_new_enzymeml_measurements` method, preparing
+the EnzymeML document and Jupyter Notebook for the next run for the next measurement. Using
+the method, a new ``Measurement`` is created either based on a template measurement in the
+EnzymeML document that the user chooses, or without a template from scratch. In the former
+case, the new measurement inherits all metadata from the template but can be adjusted as 
+needed. In the latter case all metadata needs to be added manually. Again, a GUI widget is
+provided for this method, but it can also be run programmatically by providing the
+appropriate arguments to the method. ::
+
+    >>> fid_array.create_new_enzymeml_measurements()
+
+.. image:: _static/quickstart_19.png
+   :width: 75%
+   :align: center
+
+.. image:: _static/quickstart_20.png
+   :width: 75%
+   :align: center
+
+The updated EnzymeML measurement can be extracted from NMRPy and appended to any EnzymeML
+document using the :meth:`~nmrpy.data_objects.FidArray.apply_to_enzymeml` method and 
+subsequently saved using pyenzyme's `write_enzymeml` method: ::
+
+    >>> edoc = fid_array.apply_to_enzymeml(measurement_id=1)
+
+    >>> pe.write_enzymeml(edoc, 'my_enzymeml_document.json')
+
 .. _quickstart_script:
 
 Full tutorial script

diff --git a/docs/source/utility_objects.rst b/docs/source/utility_objects.rst
@@ -0,0 +1,6 @@
+###############
+Utility Objects
+###############
+
+.. automodule:: nmrpy.utils
+   :members: