This guide provides instructions for setting up an environment for developing nmrglue and an overview of the project layout and contribution process.
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.
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.
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.
The directory layout of the nmrglue project is as follows.
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
When working with the nmrglue source code please consider the following when preparing patches.
Tests for verifying the functionality of nmrglue are available in the test directory. These tests use the nose testing infrastructure.
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.
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.
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.
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.