MScompress

MScompress is a multi-threaded lossless and lossy compression tool for Mass Spectrometry data. We introduce a novel compressed file format, .msz, which enables random-access to the compressed file without a full decompression.

Features

🌟 A graphical user interface supported on all platforms (Windows, macOS, Linux) (x86, Apple Silicon).

🌟 Multi-threaded compression and decompression.

🌟 State-of-the-art compression/decompression speeds.

🌟 Random-access to compressed file without full decompression.

🌟 Python library (pip install mscompress) and Node.js/TypeScript library (npm install mscompress) for programmatic access.

🌟 Full TypeScript type definitions and ESM support.

MScompress's multi-threaded implementation achieves state-of-the-art compression/decompression speeds with mzML files compared to general-purpose compression tools and previous work in MS data compression while maintaining comparable compression ratios.

Tests conducted on an Intel Core i9-12900K paired with a Samsung 980 Pro NVMe:

MScompress can be utilized as a standalone GUI application or through the command line interface. Additionally, we provide Python and Node.js/TypeScript libraries to utilize our preprocessing, compression, and decompression functions programmatically.

Installation

CLI

Our application is packaged as a portable executable containing all necessary dependencies with no installation required. Find the latest version for your platform under the Releases tab.

Python

uv add mscompress
# or
pip install mscompress

Node.js / TypeScript

npm install mscompress

Reporting Bugs

Our implementation is still currently in its pre-release stage undergoing further testing. If you experience any issues, we ask to please open a new Issue.

Command-Line Usage

Compression

To compress an .mzML file to lossless .msz format in same directory:

./mscompress in.mzML

or

./mscompress in.mzML out.msz

Decompression

To decompress, specify .msz file as first argument. Will output to out.mzML:

./mscompress out.msz

Lossy Compression

Currently, we support the following lossy formats: cast, log, delta(16, 32), and vbr.

To specify delta32 lossy compression for m/z data and vbr lossy compression for intensity data:

./mscompress --mz-lossy delta32 --int-lossy vbr in.mzML

Extract Spectrum

MScompress can extract spectra from either .mzML or compressed .msz files. Specific indicies, scan numbers, or MSn level can be extracted.

Ex. Extracting scan numbers 100-110 and 200-220

./mscompress --extract --extract-scans [100-110,200-220] in.mzML

or

./mscompress --extract --extract-scans [100-110,200-220] in.msz

Ex. Extracting all spectra with MS level 1

./mscompress --extract --ms-level 1 in.mzML

or

./mscompress --extract --ms-level 1 in.msz

Versioning

Versioning and releases are automated with release-please, driven by Conventional Commits. The version source of truth is version.txt at the repo root; CMake reads it, and pyproject.toml, python/mscompress/__init__.py, and all package.json files are kept in sync by release-please.

You do not bump the version manually. On every push to main, release-please opens (or updates) a release PR that bumps version.txt and the package files and updates CHANGELOG.md based on the commits since the last release. Merging that release PR creates the vX.Y.Z tag and GitHub Release, which in turn builds and publishes the CLI binaries, Python wheels (PyPI), Node packages (npm), and Docker image.

Bump sizing follows commit types: feat: → minor, fix:/perf:/refactor: → patch, and feat!:/BREAKING CHANGE → major.

Compilation

Our repository relies on CMake to support cross-platform compilation. Ensure that the necessary dependencies are installed for compilation.

Prerequisites

Linux (Ubuntu/Debian)

• Install the following build dependencies: git, build-essential, cmake

sudo apt update
sudo apt install git build-essential cmake

macOS

• Install latest version of CMake: https://cmake.org/download/

  • Once installed, run CMake CLI installation script:
    • Open Terminal app
    • Run sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install

• Install Xcode command line tools:

  • Open Terminal app
  • Run xcode-select --install

Windows

Instructions coming soon.

Command-line Tool

To compile the CLI version of MScompress:

1. Clone the repository if you haven't so already. Make sure to include the --recurse-submodules flag to properly fetch all dependencies.

git clone --recurse-submodules https://github.com/chrisagrams/mscompress.git

2. Navigate to cli directory and create a build directory

cd mscompress/cli
mkdir build

3. Navigate to build directory and configure the build

cd build
cmake ..

4. Build the executable

cmake --build ..

Node.js/TypeScript Library

To compile the Node.js library:

1. Once cloned, navigate to node-ts/

cd node-ts/

2. Install dependencies and download pre-built native binary

npm install

3. Build TypeScript sources

npm run build

4. Run tests

npm test

Pre-built native binaries are available for macOS (x64, ARM64), Linux (x64, ARM64), and Windows (x64). If a pre-built binary is not available for your platform, the native addon will be compiled from source during npm install (requires a C++17 compiler and CMake).

Electron GUI Application

To run/build Electron application:

1 . Navigate to electron/

cd electron/

2. To run in dev mode:

npm run start

3. To compile:

npm run build