User Guide


The mwtab package is a Python library that facilitates reading and writing files in mwTab format used by the Metabolomics Workbench for archival of Mass Spectrometry (MS) and Nuclear Magnetic Resonance (NMR) experimental data.

The mwtab package provides facilities to convert mwTab 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 vice versa.

The mwtab package can be used in several ways:

  • As a library for accessing and manipulating data stored in mwTab format files.
  • As a command-line tool to convert between mwTab format and its equivalent JSON representation.


The mwtab 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 mwtab

Install on Windows

py -3 -m pip install mwtab

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 mwtab         # install mwtab as usual

$ 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 mwtab package depends on several Python libraries. The pip command will install all dependencies automatically, but if you wish to install them manually, run the following commands:

  • docopt for creating mwtab 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
  • schema for validating functionality of mwTab files based on JSON schema.
    • To install the schema Python library run the following:

      python3 -m pip install schema  # On Linux, Mac OS X
      py -3 -m pip install schema    # On Windows

Basic usage

The mwtab package can be used in several ways:

  • As a library for accessing and manipulating data stored in mwTab formatted files.

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

    • Process each MWTabFile instance:

      • Process mwTab 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 MWTabFile objects.
  • As a command-line tool:

    • Convert from mwTab file format into its equivalent JSON file format and vice versa.
    • Validate data stored in mwTab file based on schema definition.


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