new: update documentation for conda install

README.md

@@ -9,12 +9,20 @@ Read the docs at http://nmrpy.readthedocs.io/
 ## Installation
 
 NMRPy is a pure Python module and works on Windows, Linux and macOS. 
-Installation is via pip and dependencies are pulled in automatically. The
+Installation is via pip and dependencies are pulled in automatically. 
+Conda packages are also provided for installation on Anaconda. The
 package is best installed in a separate virtual environment to ensure that 
 it does not interfere with other installed packages and modules.
 
+For installation with pip:    
 `pip install nmrpy`
 
+For installation with conda:    
+`conda install -c bioconda -c conda-forge -c jmrohwer nmrpy`
+
+Detailed installation instructions are available at
+https://nmrpy.readthedocs.io/en/latest/installation.html
+
 ## Changelog
 
 Read the changelog [here](CHANGELOG.rst)

docs/source/installation.rst

@@ -3,73 +3,170 @@ Installation
 ############
 
 The following are some general guidelines for installing NMRPy, and
-are by no means the only way to install a Python package. First be sure to have
-Python 3 and ``pip`` installed.
-`Pip <https://en.wikipedia.org/wiki/Pip_(package_manager)>`_ is a useful Python
-package management system.
+are by no means the only way to install a Python package. 
+
+NMRPy is a pure Python package that runs on Windows, macOS and Linux. In 
+addition to the option of installing directly from source 
+(https://github.com/NMRPy/nmrpy), we provide binary installers for ``pip`` and 
+``conda``.
+
+Abbreviated requirements
+========================
+
+NMRPy has a number of requirements that must be met before
+installation can take place. These should be
+taken care of automatically during installation. An abbreviated list of
+requirements follows:
+
+- A Python 3.x installation (Python 3.6 or higher is recommended)
+- The full SciPy Stack (see http://scipy.org/install.html).
+- Jupyter Notebook (https://jupyter.org/)
+- Matplotlib (https://matplotlib.org) with the ``ipympl`` backend
+- Lmfit (https://lmfit.github.io/lmfit-py)
+- Nmrglue (https://www.nmrglue.com)
 
 .. note::
 
     NMRPy will not work using Python 2. 
 
+Installation on Anaconda
+========================
+
+The `Anaconda Distribution 
+<https://www.anaconda.com/products/individual#Downloads>`_, which is 
+available for Windows, macOS and Linux, comes pre-installed with 
+many packages required for scientific computing, including most of the 
+dependencies required for NMRPy.
+
+A number of the dependencies (lmfit, nmrglue and ipympl) are not available from 
+the default conda channel. If you perform a lot of scientific or 
+bioinformatics computing, it may be worth your while to add the following 
+additional conda channels to your system, which will simplify installation 
+(this is, however, not required, and the additional channels can also be 
+specified once-off during the install command):
+
+.. code:: bash
+    
+    (base) $ conda config --add channels bioconda
+    (base) $ conda config --add channels conda-forge
+
+Virtual environments
+--------------------
+
+Virtual environments are a great way to keep package dependencies separate from
+your system files. It is highly recommended to install NMRPy into a separate 
+environment, which first must be created (here we create an environment 
+called ``nmr``). It is recommended to use a Python version >=3.6 (here we use 
+Python 3.7). After creation, activate the environment:
+
+.. code:: bash
+    
+    (base) $ conda create -n nmr python=3.7
+    (base) $ conda activate nmr
+
+Then install NMRPy:
+
+.. code:: bash
+    
+    (nmr) $ conda install -c jmrohwer nmrpy
+    
+Or, if you have not added the additional channels system-wide:
+
+.. code:: bash
+    
+    (nmr) $ conda install -c bioconda -c conda-forge -c jmrohwer nmrpy
+
+
+Direct ``pip``-based install
+============================
+
+First be sure to have Python 3 and ``pip`` installed.
+`Pip <https://en.wikipedia.org/wiki/Pip_(package_manager)>`_ is a useful Python
+package management system.
+
 On Debian and Ubuntu-like systems these can be installed with the following 
-terminal commands: ::
+terminal commands:
+
+.. code:: bash
 
     $ sudo apt install python3
-    $ sudo apt install python-pip
+    $ sudo apt install python3-pip
+
+On Windows, download Python from https://www.python.org/downloads/windows;  
+be sure to install ``pip`` as well when prompted by the installer, and add the 
+Python directories to the system PATH. You can verify that the Python paths are 
+set up correctly by checking the ``pip`` version in a Windows Command Prompt:
 
-On Windows, the CPython download from https://www.python.org/ comes 
-pre-installed with pip.
+.. code:: bash
 
-The `Anaconda Distribution <https://www.anaconda.com/distribution/>`_, which is 
-available for Windows, macOS and Linux, comes pre-installed with ``pip`` as 
-well as most of the other dependencies required for NMRPy.
+    > pip -V
+    
+On macOS you can install Python directly from 
+https://www.python.org/downloads/mac-osx, or by installing
+`Homebrew <https://docs.brew.sh/Installation>`_ and then installing Python 3 
+with Homebrew. Both come with ``pip`` available. 
+
+.. note:: 
+
+    While most Linux distributions come pre-installed with a version of Python 
+    3, the options for Windows and macOS detailed above are more advanced and 
+    for experienced users, who prefer fine-grained control. If you are 
+    starting out, we strongly recommend using Anaconda!
 
 Virtual environments
-====================
+--------------------
 
-Virtual environments are a great way to keep package dependencies separate from
-your system files. There are several options for setting up your working
+As for an Anaconda-based install, it is highly recommended to install NMRPy 
+into a separate virtual environment.
+There are several options for setting up your working
 environment. We will use `virtualenvwrapper 
-<https://virtualenvwrapper.readthedocs.io/en/latest/index.html>`_, which works 
-out of the box on Linux and MacOS. On Windows, virtualenvwrapper can be used 
+<https://virtualenvwrapper.readthedocs.io/en/latest/index.html>`_, 
+which works 
+out of the box on Linux and macOS. On Windows, virtualenvwrapper can be used 
 under an `MSYS <http://www.mingw.org/wiki/MSYS>`_ environment in a native 
 Windows Python installation. Alternatively, you can use `virtualenvwrapper-win 
 <https://pypi.org/project/virtualenvwrapper-win/>`_. This will take care of
 managing your virtual environments by maintaining a separate Python
 *site-directory* for you.
 
-Install virtualenvwrapper using ``pip``. On Linux and MacOS: ::
+Install virtualenvwrapper using ``pip``. On Linux and MacOS:
+
+.. code:: bash
 
-    $ sudo pip install virtualenv
-    $ sudo pip install virtualenvwrapper
+    $ sudo -H pip install virtualenv
+    $ sudo -H pip install virtualenvwrapper
 
-On Windows in a Python command prompt: ::
+On Windows in a Python command prompt:
 
-    pip install virtualenv
-    pip install virtualenvwrapper-win
+.. code:: bash
+
+    > pip install virtualenv
+    > pip install virtualenvwrapper-win
     
-Make a new virtual environment for working with NMRPy (e.g. nmr), and specify
-that it use Python 3 (we used Python 3.7): ::
+Make a new virtual environment for working with NMRPy (e.g. ``nmr``), and 
+specify that it use Python 3 (we used Python 3.7):
+
+.. code:: bash
 
     $ mkvirtualenv -p python3.7 nmr
 
 The new virtual environment will be activated automatically, and this will be
-indicated in the shell prompt. E.g.: ::
+indicated in the shell prompt, e.g.:
+
+.. code:: bash
 
     (nmr) $
 
 If you are not yet familiar with virtual environments we recommend you survey
 the basic commands (https://virtualenvwrapper.readthedocs.io/en/latest/) before
 continuing.
 
-Pip install
-===========
+The NMRPy code and its dependencies can now be installed directly from PyPI 
+into your virtual environment using ``pip``.
 
-The NMRPy code and its dependencies can be installed directly from PyPI 
-into a virtual environment (if you are currently using one) using ``pip``. ::
+.. code:: bash
 
-    $ pip install nmrpy
+    (nmr) $ pip install nmrpy
 
 Testing the installation
 ========================
@@ -79,7 +176,8 @@ the ``unittest`` framework. The tests should be run from a terminal and can be
 invoked with ``nmrpy.test()`` after importing the *nmrpy* module.
 
 Only a specific subset of tests can be run by providing an additional argument: 
-::
+
+.. code:: python
 
     nmrpy.test(tests='all')
     
@@ -102,32 +200,38 @@ Though the majority of NMRPy functionality can be used purely in a scripting
 context and executed by the Python interpreter, it will often need to be used
 interactively. We suggest two ways to do this:
 
-IPython
--------
-
-IPython is an interactive Python shell with some useful functionalities like
-tab-completion. This has been installed by default with NMRPy and can be
-launched from the command line with: ::
-
-    $ ipython
-
 Jupyter Notebook
 --------------------
 
-For those who prefer a "notebook"-like experience, the Jupyter Notebook may be
-more appropriate. It has also been installed by default with NMRPy and 
-can be launched with: ::
+The recommended way to run NMRPy is in the Jupyter Notebook environment. It has 
+been installed by default with NMRPy and 
+can be launched with (be sure to activate your virtual environment first):
 
-    $ jupyter-notebook
+.. code:: bash
 
-If you will be using the peak-picking and range-selection widgets from within 
-the Jupyter Notebook, this requires the 
+    (nmr) $ jupyter-notebook
+
+The peak-picking and range-selection widgets in
+the Jupyter Notebook require the 
 `Matplotlib Jupyter Integration <https://github.com/matplotlib/ipympl>`_
-extension (*ipympl*). This is installed automatically but the extension needs to 
-be activated at the beginning of every notebook thus: ::
+extension (*ipympl*). This is installed automatically but the extension needs 
+to be activated at the beginning of every notebook thus:
+
+.. code:: python
+
+    In [1]:  %matplotlib widget
+
+IPython
+-------
+
+If you rather prefer a shell-like experience, IPython is an interactive Python 
+shell with some useful functionalities like tab-completion. This has been 
+installed by default with NMRPy and can be launched from the command line with:
+
+.. code:: bash
+
+    (nmr) $ ipython
 
-    In [1]:   %matplotlib widget
-    
 Documentation
 =============
 

docs/source/intro.rst

@@ -2,6 +2,26 @@
 Introduction
 ############
 
-NMRPy is a Python3 module for the processing and analysis of NMR spectra. The
+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.
+
+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].
+
+References
+==========
+
+1. Eicher, J. J.; Snoep, J. L. & Rohwer, J. M. (2012)
+   Determining enzyme kinetics for systems biology with Nuclear Magnetic 
+   Resonance spectroscopy.
+   *Metabolites* 2:818-843.
+   DOI: `10.3390/metabo2040818 <https://doi.org/10.3390/metabo2040818>`_
+
+2. Badenhorst, M.; Barry, C. J.; Swanepoel, C. J.; van Staden, C. T.; 
+   Wissing, J. & Rohwer, J. M. (2019)
+   Workflow for data analysis in experimental and computational 
+   systems biology: Using Python as 'glue'.
+   *Processes* 7:460.
+   DOI: `10.3390/pr7070460 <https://doi.org/10.3390/pr7070460>`_

docs/source/quickstart.rst

@@ -18,7 +18,7 @@ dataset will be processed. The following topics are explored:
 
 This tutorial will use the test data in the nmrpy install directory: ::
     
-    nmrpy/tests/test_data/test1.fid
+    site-packages/nmrpy/tests/test_data/test1.fid
 
 The dataset consists of a time array of spectra of the phosphoglucose isomerase 
 reaction:
@@ -28,7 +28,7 @@ reaction:
 An example Jupyter notebook is provided in the ``docs`` subdirectory of
 the nmrpy install directory, which mirrors this Quickstart Tutorial. ::
 
-    nmrpy/docs/quickstart_tutorial.ipynb
+    site-packages/nmrpy/docs/quickstart_tutorial.ipynb
 
 
 .. _quickstart_importing:
@@ -43,10 +43,15 @@ an array of spectra.
 
 The simplest way to instantiate an :class:`~nmrpy.data_objects.FidArray` is by
 using the :meth:`~nmrpy.data_objects.FidArray.from_path` method, and specifying
-the path of the *.fid* directory: ::
+the path of the *.fid* directory:
+
+.. code:: python
 
     >>> import nmrpy
-    >>> fid_array = nmrpy.from_path(fid_path='./tests/test_data/test1.fid')
+    >>> import os, sysconfig
+    >>> fname = os.path.join(sysconfig.get_paths()['purelib'], 'nmrpy', 
+                             '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
@@ -370,7 +375,7 @@ saved to file using the :meth:`~nmrpy.data_objects.FidArray.save_to_file` method
 
 And reloaded using :meth:`~nmrpy.data_objects.FidArray.from_path`: ::
 
-    >>> fid_array = nmrpy.data_objects.FidArray.from_path(fid_path='fidarray.nmrpy')
+    >>> fid_array = nmrpy.from_path(fid_path='fidarray.nmrpy')
 
 
 .. _quickstart_script:

docs/source/quickstart_script.rst

@@ -3,9 +3,12 @@ The full script for the quickstart tutorial:
 .. code:: python
 
     import nmrpy
+    import os, sysconfig
     from matplotlib import pyplot as plt
 
-    fid_array = nmrpy.from_path(fid_path='./tests/test_data/test1.fid')
+    fname = os.path.join(sysconfig.get_paths()['purelib'], 'nmrpy', 
+                         'tests', 'test_data', 'test1.fid')
+    fid_array = nmrpy.from_path(fid_path=fname)
     fid_array.emhz_fids()
     #fid_array.fid00.plot_ppm()
     fid_array.ft_fids()
@@ -56,4 +59,4 @@ The full script for the quickstart tutorial:
     plt.show()
     
     #fid_array.save_to_file(filename='fidarray.nmrpy')
-    #fid_array = nmrpy.data_objects.FidArray.from_path(fid_path='fidarray.nmrpy')
+    #fid_array = nmrpy.from_path(fid_path='fidarray.nmrpy')