mzmlpy 0.9.0

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)

MCP integration

Version 0.9.0 preserves the stored numeric dtype when decoding arrays, including exact int64 values. Numpress retains its float64 reconstruction. Code requiring float64 can use .astype(np.float64). See the numeric type migration guide.

An optional local MCP server exposes file discovery, full acquisition metadata, validation, metadata inventories and comparisons, and bounded array access to AI clients. Background jobs, reference resources, workflow prompts, and optional lossless JSONL exports support larger tasks. Spectrum processing stays in Spectacular, and plotting stays in companion visualization tools. Install with pip install "mzmlpy[mcp]" and launch with python -m mzmlpy mcp --root /absolute/path/to/data. See the MCP guide.

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:

"auto" is the default. It selects an embedded index first, then a current extracted cache, then complete rapidgzip sidecars, and finally creates an extracted cache. The selected route is available through reader.access_strategy.

Self-indexed gzip files created by write_indexed_gzip are detected automatically when in_memory=False. Their index lives inside the gzip header, so random access needs no extracted copy, sidecar index, or optional dependency.

from mzmlpy import Mzml, write_indexed_gzip

write_indexed_gzip("data.mzML", "data.indexed.mzML.gz")

with Mzml("data.indexed.mzML.gz", in_memory=False) as reader:
    spec = reader.spectra["controllerType=0 controllerNumber=1 scan=1234"]

The writer also accepts an ordinary .mzML.gz input. It preserves the decompressed mzML bytes exactly and writes the destination atomically. The embedded layout is compatible with pyMZML's FU version 1 indexed gzip reader.

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

# Automatic selection with observable behavior
with Mzml("data.mzML.gz", in_memory=False) as reader:
    print(reader.access_strategy)
    spec = reader.spectra[0]

# Indexed — no extraction, seekable access (requires rapidgzip)
with Mzml("data.mzML.gz", gzip_mode="indexed", in_memory=False) 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):

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.

Validation and filtering

from mzmlpy import Mzml, validate

report = validate("data.mzML", decode_binary=True)
print(report.valid, report.issues)

with Mzml("data.mzML", in_memory=False) as reader:
    for spectrum in reader.spectra.filter(ms_level=2, retention_time=(60, 180)):
        print(spectrum.id)

Validation reports structural and decoding problems without repairing the input. Filtering uses metadata and inclusive retention-time bounds in seconds, without decoding arrays. See the guide for check scope, precursor filters, cache behavior, and python -m mzmlpy CLI commands.

Citation

Citation metadata are provided in CITATION.cff. The archived v0.6.0 release is available from Zenodo at doi:10.5281/zenodo.21960080.

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