mzmlpy 0.5.0

A lightweight Python library for parsing mzML mass spectrometry files.

A lightweight Python library for parsing mzML mass spectrometry files. Implements a type-safe, lazy-loading API with direct support for modern mzML structures (>= 1.1.0).

Installation

pip install mzmlpy

Optional extras:

pip install mzmlpy[numpress]   # MS-Numpress decoding
pip install mzmlpy[zstd]       # Zstandard compression
pip install mzmlpy[rapidgzip]  # Parallel gzip decompression (recommended for .gz files)

Quick Start

from mzmlpy import Mzml

with Mzml("path/to/file.mzML") as reader:
    print(f"File: {reader.file_name}  |  Spectra: {len(reader.spectra)}")

    for spectrum in reader.spectra:
        mz = spectrum.mz
        intensity = spectrum.intensity
        print(f"  {spectrum.id} MS{spectrum.ms_level} — {len(mz)} peaks")

Both .mzML and .mzML.gz files are supported. Metadata is parsed eagerly; binary data is decoded on demand.

Reading Gzipped Files

When opening .mzML.gz files, the gzip_mode parameter controls how the file is accessed:

Mode	Description
"extract" (default)	Decompress to <tmpdir>/mzmlpy/ and cache across sessions. First open pays decompression cost; subsequent opens reuse the cache instantly. The OS clears tmp on reboot.
"indexed"	Seekable access to the compressed file using rapidgzip. No decompression to disk. Requires pip install mzmlpy[rapidgzip].
"stream"	Stream sequentially. Lowest startup cost but no efficient random access.

For most use cases, "extract" or "indexed" is recommended:

# Default — extracts to tmp, cached across sessions
with Mzml("data.mzML.gz") as reader:
    spec = reader.spectra[0]

# Indexed — no extraction, seekable access (requires rapidgzip)
with Mzml("data.mzML.gz", gzip_mode="indexed") as reader:
    spec = reader.spectra[0]

To reclaim disk space before the OS clears tmp on reboot:

from mzmlpy import clear_cache
clear_cache()

Performance

"extract" pays a one-time decompression cost then matches plain .mzML speed on later opens (the extracted copy is cached). "indexed" pays a one-time index-build cost for seekable access with no disk copy. "stream" has the lowest startup cost but random access re-scans from the start, so it's sequential-only in practice. See benchmarks/ for a reproducible harness with real numbers on real files, including a head-to-head against pyteomics and pymzml.

mzmlpy vs pymzml

Compared against pymzml 2.6.0 on a Bruker timsTOF file with ion mobility (10 spectra, 6.7 MB):

Benchmark	mzmlpy	pymzml	Ratio
Startup	0.012s	0.092s	8.0x faster
Iterate (decode)	0.039s	0.228s	5.8x faster
Random access	0.012s	0.110s	9.2x faster

Both libraries produce identical m/z and intensity arrays. The gap narrows on smaller files (~1.1--1.3x) and widens on larger, more complex files. See the full results in the Benchmarks page or run benchmarks/bench_vs_pymzml.py yourself.

For full usage examples see the Getting Started guide and API Reference.

Using an AI coding assistant? Point it at llms.txt — a compact, accurate API guide for generating correct mzmlpy code.

Benchmarks

benchmarks/ contains a reproducible harness comparing mzmlpy against pyteomics and pymzml on compression-format support, throughput, and gzip handling. See benchmarks/README.md for how to run it and current results.

Development

just lint     # ruff check
just format   # ruff isort + format
just ty       # ty type checker
just test     # pytest

# or all at once:
just check