hivetoolkit

hivetoolkit is a Python helper library that supports interactive mass spectrometry (MS) data analysis by providing graphical visualization capabilities in notebook-based environments.

It is designed for use in interactive development and execution environments such as Jupyter Notebook, JupyterLab, Google Colab, Deepnote, and VS Code.

Features

• Interactive visualization of chromatograms from MS and related detectors
• Overlay and comparison of multiple chromatograms
• Visualization of mass spectra and diode array spectra
• Two-dimensional spectral maps across retention time and m/z (or wavelength)

Prerequisites

hivetoolkit operates on mass spectrometry data converted into the Hive data format and depends on the Hive Data Access API for Python (hive-data-access), which provides programmatic access to Hive-format mass spectrometry data.

The Hive data format includes two types of files:

• .mzB: an open Hive-based format distributed via public repositories such as DDBJ MetaboBank
• .hmD: a licensed Hive format converted from vendor-specific raw MS data

Both formats are generated by converting raw MS data from major instrument vendors. Analysis of .hmD files requires a valid Hive Runtime license, while .mzB files can be used without one.

Requirements

• Python 3.10 or later
• Hive Data Access API for Python (hive-data-access)
• An interactive Python environment (Jupyter Notebook, JupyterLab, Google Colab, Deepnote, or VS Code)

Installation

hivetoolkit depends on the Hive Data Access API for Python (hive-data-access), which provides programmatic access to Hive-format mass spectrometry data.

By installing or using hivetoolkit, you also agree to the Hive Data Access API Public Distribution License (PDL), which governs the use of the Hive Data Access API.

Note: The PyPI package name is hive-data-access, but it is imported as hive_data_access in Python.

git clone https://github.com/ddbj/hivetoolkit.git
cd hivetoolkit
pip install .

If you want to install with the notebook environment, install it as follows: pip install .[notebook]

Quick Start

The following example demonstrates a minimal workflow for visualizing MS data in an interactive Python environment.

import hive_data_access
import hivetoolkit

# Open a Hive file
hive = hive_data_access.HiveFile("sample/sample_quan1.mzB")

# Access the first measurement and analysis
analysis = hive.get_measurement(0).get_quan_analysis(0)

# Visualize the chromatogram
hivetoolkit.draw_chromatogram(analysis)

If the full Hive Data Access API is not yet available in your environment, you will be prompted with clear instructions on how to complete the setup.

Note
Additional technical details are available under the docs/ directory.

Tutorials

Practical examples are provided as Jupyter notebooks:

• Qualitative analysis tutorial
• Quantitative analysis tutorial

These notebooks demonstrate typical interactive analysis workflows using hivetoolkit together with hive-data-access.

Licensing

hivetoolkit is released by DDBJ (DNA Data Bank of Japan) under the MIT License. The dependency hive-data-access is distributed by Reifycs Inc. under the Hive Data Access API Public Distribution License (PDL).

To read .hmD files using this project, Hive Runtime is required. For details about Hive Runtime, please refer to the Hive product information page: https://www.reifycs.com/products/hive/