User Guide


The nmrstarlib package provides a simple Python interface for parsing and manipulating data stored in NMR-STAR format files used by Biological Magnetic Resonance Data Bank (BMRB) for archival of Nuclear Magnetic Resonance (NMR) experimental data.

The nmrstarlib package provides facilities to convert NMR-STAR formatted files into their equivalent JSONized (JavaScript Object Notation, an open-standard format that uses human-readable text to transmit data objects consisting of attribute-value pairs) representation and visa versa.

The nmrstarlib package also provides facilities to create simulated peak lists for different types of standard solution and solid-state NMR experiments from chemical shifts and assignment information deposited in NMR-STAR files.

In addition, the nmrstarlib package provides facilities to visualize assigned chemical shift data.


The nmrstarlib package runs under Python 2.7 and Python 3.4+. Starting with Python 3.4, pip is included by default. To install system-wide with pip run the following:

Install on Linux, Mac OS X

python3 -m pip install nmrstarlib

Install on Windows

py -3 -m pip install nmrstarlib

Install inside virtualenv

For an isolated install, you can run the same inside a virtualenv.

$ virtualenv -p /usr/bin/python3 venv  # create virtual environment, use python3 interpreter

$ source venv/bin/activate             # activate virtual environment

$ python3 -m pip install nmrstarlib    # install nmrstarlib as usually

$ deactivate                           # if you are done working in the virtual environment

Get the source code

Code is available on GitHub:

You can either clone the public repository:


Or, download the tarball and/or zipball:

$ curl -OL

$ curl -OL

Once you have a copy of the source, you can embed it in your own Python package, or install it into your system site-packages easily:

$ python3 install


The nmrstarlib package depends on several Python libraries, it will install all dependencies automatically, but if you wish to install them manually run the following commands:

  • docopt for creating nmrstarlib command-line interface.
    • To install docopt run the following:

      python3 -m pip install docopt  # On Linux, Mac OS X
      py -3 -m pip install docopt    # On Windows
  • graphviz for visualizing assigned chemical shift values.
    • To install the graphviz Python library run the following:

      python3 -m pip install graphviz  # On Linux, Mac OS X
      py -3 -m pip install graphviz    # On Windows
    • The only dependency of the graphviz Python library is a working installation of Graphviz (Graphviz download page).

Optional dependencies

  • numpy for generating noise values from random distribution during peak list simulation.
    • To install the numpy Python library run the following:

      python3 -m pip install numpy  # On Linux, Mac OS X
      py -3 -m pip install numpy    # On Windows
    • If the numpy is not installed distributions from the Python standard library random module will be used.

Basic usage

The nmrstarlib package can be used in several ways:

  • As a library for accessing and manipulating data stored in NMR-STAR format files.

    • Create the StarFile generator function that will generate (yield) single StarFile instance at a time.

    • Process each StarFile instance:

      • Process NMR-STAR files in a for-loop one file at a time.
      • Process as an iterator calling the next() built-in function.
      • Convert the generator into a list of StarFile objects.
  • As a command-line tool:

    • Convert from NMR-STAR file format into its equivalent JSON file format and vice versa.
    • Create standard solution and solid-state NMR simulated peak lists from chemical shift values and assignment information.
    • Visualize (organize) assigned chemical shift values.


Read The nmrstarlib Tutorial to learn more and see code examples on using the nmrstarlib as a library and as a command-line tool.