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 is a useful Python package management system.

Note: NMRPy will not work using Python 2.

On Debian and Ubuntu-like systems these can be installed with the following terminal commands:

$ sudo apt install python3
$ sudo apt install python-pip

On Windows, the CPython download from https://www.python.org/ comes pre-installed with pip.

The Anaconda 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.

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 environment. We will use virtualenvwrapper, which works out of the box on Linux and MacOS. On Windows, virtualenvwrapper can be used under an MSYS environment in a native Windows Python installation. Alternatively, you can use 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:

$ sudo pip install virtualenv
$ sudo pip install virtualenvwrapper

On Windows in a Python command prompt:

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):

$ mkvirtualenv -p python3.7 nmr

The new virtual environment will be activated automatically, and this will be indicated in the shell prompt. E.g.:

(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 be installed directly from PyPI into a virtual environment (if you are currently using one) using pip.

$ pip install nmrpy

Testing the installation

Various tests are provided to test aspects of the NMRPy functionality within 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:

nmrpy.test(tests='all')

:keyword tests: Specify tests to run (default 'all'). Running only a subset
                of tests can be selected using the following arguments:
'fidinit'       - Fid initialisation tests
'fidarrayinit'  - FidArray initialisation tests
'fidutils'      - Fid utilities tests
'fidarrayutils' - FidArray utilities tests
'plotutils'     - plotting utilities tests

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.

Working with NMRPy

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:

$ jupyter-notebook

If you will be using the peak-picking and range-selection widgets from within the Jupyter Notebook, this requires the jupyter-matplotlib extension (ipympl). This is installed automatically but the extension needs to be activated at the beginning of every notebook thus:

In [1]:   %matplotlib ipympl

Documentation

Online documentation is available at https://nmrpy.readthedocs.io. The documentation is also distributed in PDF format in the docs subfolder of the nmrpy folder in site-packages where the package is installed.

The docs folder also contains an example Jupyter notebook (quickstart_tutorial.ipynb) that mirrors the Quickstart Tutorial.