User Guide#

Description#

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.

Installation#

The mwtab package runs under Python 3.6+. 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: MoseleyBioinformaticsLab/mwtab

You can either clone the public repository:

$ https://github.com/MoseleyBioinformaticsLab/mwtab.git

Or, download the tarball and/or zipball:

$ curl -OL https://github.com/MoseleyBioinformaticsLab/mwtab/tarball/master

$ curl -OL https://github.com/MoseleyBioinformaticsLab/mwtab/zipball/master

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 setup.py install

Dependencies#

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
  • jsonschema for validating functionality of mwTab files based on JSON schema.

    • To install the jsonschema Python library run the following:

      python3 -m pip install jsonschema  # On Linux, Mac OS X
py -3 -m pip install jsonschema    # On Windows
  • pandas for working with tabular data sections within the mwTab format.

    • To install the pandas Python library run the following:

      python3 -m pip install pandas  # On Linux, Mac OS X
py -3 -m pip install pandas    # On Windows
  • setuptools-scm for handling versioning.

    • To install the setuptools-scm Python library run the following:

      python3 -m pip install setuptools-scm  # On Linux, Mac OS X
py -3 -m pip install setuptools-scm    # 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.

Note

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