chg: Update documentation with new functionality

Author: jmrohwer

docs/source/_static/quickstart_15.png

@@ -132,7 +132,7 @@
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
-tml_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/conf.py

@@ -48,11 +48,12 @@ the path of the *.fid* directory:
 .. code:: python
 
     >>> import nmrpy
-    >>> import os, sysconfig
-    >>> fname = os.path.join(sysconfig.get_paths()['purelib'], 'nmrpy', 
+    >>> import os
+    >>> fname = os.path.join(os.path.dirname(nmrpy.__file__),
                              'tests', 'test_data', 'test1.fid')
     >>> fid_array = nmrpy.from_path(fname)
-
+    
+    
 You will notice that the ``fid_array`` object is instantiated and now owns
 several attributes, most of which are of the form ``fidXX`` where *XX* is
 a number starting at 00. These are the individual arrayed
@@ -81,8 +82,9 @@ visualise the result: ::
 
 .. image:: _static/quickstart_2.png
 
-Finally, we Fourier-transform the data into the frequency domain: ::
+Finally, we zero-fill and Fourier-transform the data into the frequency domain: ::
 
+    >>> fid_array.zf_fids()
     >>> fid_array.ft_fids()
     >>> fid_array.fid00.plot_ppm()
 
@@ -327,7 +329,18 @@ Peak integrals of the entire :class:`~nmrpy.data_objects.FidArray` are stored in
 individual :class:`~nmrpy.data_objects.Fid` as
 :attr:`~nmrpy.data_objects.Fid.deconvoluted_integrals`.
 
-We could easily plot the species integrals using the following code:
+Plotting the time-course
+========================
+
+The acquisition times for the individual :class:`~nmrpy.data_objects.Fid` 
+objects in the :class:`~nmrpy.data_objects.FidArray` are stored in an array 
+:attr:`~nmrpy.data_objects.FidArray.t` for easy access. Note that when each 
+:class:`~nmrpy.data_objects.Fid` is collected with multiple transients/scans on 
+the spectrometer, the acquisition time is calculated as the *middle* of its 
+overall acquisition period.
+
+We could thus easily plot the time-course of the species integrals using the 
+following code:
 
 .. code:: python
 
@@ -365,6 +378,52 @@ We could easily plot the species integrals using the following code:
 
 .. _quickstart_exporting:
 
+
+Deleting individual `Fid` objects from a `FidArray`
+===================================================
+
+Sometimes it may be desirable to remove one or more 
+:class:`~nmrpy.data_objects.Fid` objects from a 
+:class:`~nmrpy.data_objects.FidArray`, e.g. to remove outliers from the 
+time-course of concentrations. This can be conveniently achieved with the 
+:meth:`~nmrpy.data_objects.FidArray.del_fid()` method, which takes as argument 
+the :attr:`~nmrpy.data_objects.Fid.id` of the :class:`~nmrpy.data_objects.Fid` 
+to be removed. The acquisition time array 
+:attr:`~nmrpy.data_objects.FidArray.t` is updated accordingly by removing the 
+corresponding time-point. After this, 
+:meth:`~nmrpy.data_objects.FidArray.deconv_fids` has to be run again to update 
+the array of peak integrals.
+
+A list of all the :class:`~nmrpy.data_objects.Fid` objects in a 
+:class:`~nmrpy.data_objects.FidArray` is returned by the 
+:meth:`~nmrpy.data_objects.FidArray.get_fids` method. ::
+
+    >>> print([f.id for f in fid_array.get_fids()])
+        ['fid00', 'fid01', 'fid02', 'fid03', 'fid04', 'fid05', 'fid06', 'fid07', 
+         'fid08', 'fid09', 'fid10', 'fid11', 'fid12', 'fid13', 'fid14', 'fid15', 
+         'fid16', 'fid17', 'fid18', 'fid19', 'fid20', 'fid21', 'fid22', 'fid23']
+         
+    >>> for fid_id in [f.id for f in fid_array.get_fids()][::4]:
+            fid_array.del_fid(fid_id)
+            
+    >>> print([f.id for f in fid_array.get_fids()])
+        ['fid01', 'fid02', 'fid03', 'fid05', 'fid06', 'fid07', 'fid09', 'fid10', 
+         'fid11', 'fid13', 'fid14', 'fid15', 'fid17', 'fid18', 'fid19', 'fid21', 
+         'fid22', 'fid23']
+         
+    >>> print(['{:.2f}'.format(i) for i in fid_array.t])
+        ['3.48', '5.80', '8.12', '12.76', '15.08', '17.40', '22.04', '24.36', '26.68',
+         '31.32', '33.64', '35.96', '40.60', '42.92', '45.24', '49.88', '52.20', '54.52']
+         
+The gaps left by the deleted :class:`~nmrpy.data_objects.Fid` objects are clearly visible in the plotted 
+:class:`~nmrpy.data_objects.FidArray`: ::
+
+    >>> fid_array.plot_array(upper_ppm=7, lower_ppm=-1, filled=True, azim=-68, elev=25)
+
+.. image:: _static/quickstart_15.png
+   :width: 75%
+   :align: center
+
 Saving / Loading
 ================
 

docs/source/quickstart.rst

@@ -3,11 +3,11 @@ The full script for the quickstart tutorial:
 .. code:: python
 
     import nmrpy
-    import os, sysconfig
+    import os
     from matplotlib import pyplot as plt
 
-    fname = os.path.join(sysconfig.get_paths()['purelib'], 'nmrpy', 
-                         'tests', 'test_data', 'test1.fid')
+    fname = os.path.join(os.path.dirname(nmrpy.__file__), 'tests',
+                         'test_data', 'test1.fid')
     fid_array = nmrpy.from_path(fid_path=fname)
     fid_array.emhz_fids()
     #fid_array.fid00.plot_ppm()
@@ -58,5 +58,14 @@ The full script for the quickstart tutorial:
     ax.legend(loc=0, frameon=False)
     plt.show()
     
+    print([f.id for f in fid_array.get_fids()])
+
+    #delete selected Fids from array
+    for fid_id in [f.id for f in fid_array.get_fids()][::4]:
+        fid_array.del_fid(fid_id)
+    print([f.id for f in fid_array.get_fids()])
+    print(['{:.2f}'.format(i) for i in fid_array.t])
+    #fid_array.plot_array(upper_ppm=7, lower_ppm=-1, filled=True, azim=-68, elev=25)
+    
     #fid_array.save_to_file(filename='fidarray.nmrpy')
     #fid_array = nmrpy.from_path(fid_path='fidarray.nmrpy')

docs/source/quickstart_script.rst

@@ -537,10 +537,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Peak integrals of the complete `FidArray` are stored in `deconvoluted_integrals`, or in each individual `Fid` as `deconvoluted_integrals`.\n",
+    "Peak integrals of the complete `FidArray` are stored in `deconvoluted_integrals`, or in each individual `Fid` as `deconvoluted_integrals`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plotting the time-course"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The acquisition times for the individual `Fid` objects in the `FidArray` are stored in an array `t` for easy access. Note that when each `Fid` is collected with multiple transients/scans on the spectrometer, the acquisition time is calculated as the middle of its overall acquisition period.\n",
     "\n",
-    "The species integrals can easily be plotted using the following code:\n",
-    "    "
+    "We could thus easily plot the time-course of the species integrals using the following code:    "
    ]
   },
   {
@@ -578,6 +591,60 @@
     "ax.legend(loc=0, frameon=False)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Deleting individual `Fid` objects from a `FidArray`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Sometimes it may be desirable to remove one or more `Fid` objects from a `FidArray`, e.g. to remove outliers from the time-course of concentrations. This can be conveniently achieved with the `del_fid()` method, which takes as argument the `id` of the `Fid` to be removed. The acquisition time array `t` is updated accordingly by removing the corresponding time-point. After this, `deconv_fids()` has to be run again to update the array of peak integrals.\n",
+    "\n",
+    "A list of all the `Fid` objects in a `FidArray` is returned by the `get_fids()` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print([f.id for f in fid_array.get_fids()])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for fid_id in [f.id for f in fid_array.get_fids()][::4]:\n",
+    "        fid_array.del_fid(fid_id)\n",
+    "\n",
+    "print([f.id for f in fid_array.get_fids()])\n",
+    "print(['{:.2f}'.format(i) for i in fid_array.t])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The gaps left by the deleted `Fid` objects are clearly visible in the plotted `FidArray`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fid_array.plot_array(upper_ppm=7, lower_ppm=-1, filled=True, azim=-68, elev=25)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -609,7 +676,23 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "And reloaded using `from_path()`:"
+    "The filename need not be specified, if not given the name is taken from `fid_path` and the *.nmrpy* extension is appended. If the file exists, it is not overwritten; a forced overwrite can be specified with:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fid_array.save_to_file(filename='fidarray.nmrpy', overwrite=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `FidArray` can be reloaded using `from_path()`:"
    ]
   },
   {
@@ -622,7 +705,7 @@
    },
    "outputs": [],
    "source": [
-    "fid_array = nmrpy.data_objects.FidArray.from_path(fid_path='fidarray.nmrpy')"
+    "fid_array = nmrpy.from_path(fid_path='fidarray.nmrpy')"
    ]
   }
  ],
@@ -642,13 +725,16 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.2"
+   "version": "3.9.6"
   },
   "toc": {
+   "base_numbering": 1,
    "nav_menu": {},
    "number_sections": true,
    "sideBar": true,
    "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
    "toc_cell": false,
    "toc_position": {},
    "toc_section_display": "block",

nmrpy/docs/quickstart_tutorial.ipynb

@@ -1,4 +1,4 @@
-{% set version = "0.2.5" %}
+{% set version = "0.2.6" %}
 
 package:
   name: nmrpy