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.
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.
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
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.
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 :ref:`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
data: Suggested location to hold the :ref:`test data <test_data>`.
sandbox: Suggested location to store code, data, etc not yet ready to be include in nmrglue.
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.
- :ref:`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
examplesdirectory. Contributions of additional example are welcome and appreciated.
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
Running the unit tests
After ensuring that all required packages are installed and
correctly points to the location of the test data directory, the unit tests can
be run using the following:
Unit tests for a specific module can be run using:
Additional information on the usage of the nosetest command is available.
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.