Developement Guide

This guide provides instructions for setting up an environment for developing nmrglue and an overview of the project layout and contribution process.

Requirements

To create an environment for developing nmrglue the following must be installed and available.

In addition the following Python packages are highly recommended.

A easy way of obtaining and installing these packages is to use a Python distribution which provides these packages, such as EPD. Detailed information on installing a Scipy stack is available.

Finally, other NMR software packages must be installed to process and convert the test and example data. These are not required for using nmrglue, but are needed to verify its functionality and to run some of the examples.

Source Code

nmrglue uses github for source code hosting. For access to the source code, see the nmrglue github site.

To check out the latest version of nmrglue use git:

git clone git://github.com/jjhelmus/nmrglue.git

nmrglue is a pure python module, the root directory can be included in your PYTHONPATH directly, or a symbolic link can be added to the site-packages directory of your Python install. In this way any modifications to the nmrglue source tree will be picked up when nmrglue is imported.

Test and Example Data

nmrglue uses experimental and simulated NMR data for testing and in many examples, this data is divided into two archives, the test data set and additional data needed for the examples.

The nmrglue test data sets must be downloaded and unpacked into a directory (a directory named data under the root directory is recommended but not required). The conversions scripts contained in the archive must be run to convert and process the time domain NMR data. Additional NMR software (NMRPipe, etc) are requires for this processing and conversion, see the README file in the test data archive for details. After installing this test data edit the setup.py file in the test directory and the make_links.sh file in the examples directory to correctly point to the location of the test data directory.

Additional data required for the nmrglue examples can be downloaded as a single archive. Unpack this archive in the examples directory. Run the make_links.sh shell script to make symbolic links to the test data which reused in a number of example. On operating systems which do not support symbolic links (Windows), the data in the test data directory will need to be copied by hand into the appropiate locations.

Project Layout

The directory layout of the nmrglue project is as follows.

  • nmrglue : source code for the project.
  • doc : contains the setup file and source code for building the nmrglue documentation using Sphinx.
  • tests : unit tests which use the nose framework to verify the functionality of nmrglue. See the Testing section for details.
  • example : contains numerous examples in which nmrglue is used to solve many real world NMR problems.

Two additional directories can be created to aid in developements. These are not required but will be ignored by git using the default .gitignore file

  • data : Suggested location to hold the test data.
  • sandbox : Suggested location to store code, data, etc not yet ready to be include in nmrglue.

Suggestions

When working with the nmrglue source code please consider the following when preparing patches.

  • Coding Style : The nmrglue source code trys to follow the PEP8 style guide. Consider using a tool, such as pep8 or pylint to check your Python code against these conventions.
  • Documentation : All public functions and classes should have docstring which follows the NumPy/SciPy documentation standard. Prive functions and classes may have shorter dostrings. The nmrglue documentation is build using Sphinx. Sphinx translates reST formatted documents (including docstring) into html. When adding new function, classes or parameter to nmrglue please update the docstring and make any necessary changes to the Sphinx files in the doc directory.
  • Testing : Tests are available for verifying the functionality of nmrglue, please include a tests when adding new functionality to the package.
  • Examples : Numerous example showing real world use of nmrglue are provided in the examples directory. Contributions of additional example are welcome and appreciated.

Testing

Tests for verifying the functionality of nmrglue are available in the test directory. These tests use the nose testing infrastructure.

Requirements

To run these tests NumPy, SciPy, nmrglue, and nose must be installed and in the Python search path. NMRPipe must be installed to run the pipe_proc tests.

In addition, the location of the the test data sets must be specified in the setup.py file in the test directory. The nmrglue test data is available for download.

In order to run all nmrglue unit tests, the tests data sets must be downloaded, unpacked, and the all conversions scripts contained in the archive must be run. Many of these scripts require additional NMR software (NMRPipe, etc), see the README file in the test data achive for additional details. A subset of the full test suite can be run without installing any additional software.

Running the unit tests

After ensuring that all required packages are installed and setup.py correctly points to the location of the test data directory, the unit tests can be run using the following:

nosetest

Unit tests for a specific module can be run using:

nosetest tests/test_pipe.py

Additional information on the usage of the nosetest command is available.

Reporting Bugs

The preferred location for submitting feature requests and bugs reported is the github issue tracker. Reports are also welcomed on the nmrglue mailing list or by contacting Jonathan Helmus directly.

Contributions

Contribution of source code or examples to nmrglue is welcomed provided the contents can be distributed under the New BSD License. The preferred method for contributing is by creating a feature branch on a github fork of nmrglue and submitting a pull request, although patches are also accepted. Refer to the Numpy/SciPy git workflow for details on how to prepare a patch or submit a pull request.