UniDecImporter

UniDecImporter is a standalone Python package for reading mass-spectrometry data into NumPy arrays. It was extracted from UniDec, but has no runtime dependency on UniDec or IsoDec.

The same high-level API covers single spectra, LC-MS, CD-MS, and ion-mobility MS:

from UniDecImporter import get_importer

with get_importer("run.mzML") as reader:
    spectrum = reader.get_avg_scan(time_range=(2.0, 2.5))
    tic = reader.get_tic()
    bpc = reader.get_bpc()

Installation

python -m pip install UniDecImporter

For Thermo RAW support on Windows x86-64, install the optional bridge too:

python -m pip install "UniDecImporter[thermo]"

Python 3.10–3.13 is supported on Windows, macOS, and Linux. Open formats are tested on x86-64 and ARM64 across these operating systems. The package includes Windows-only Thermo .NET assemblies as data files, but importing and using open-format readers does not load them.

Thermo proprietary software: Installing or using the bundled Thermo RawFileReader assemblies means you accept Thermo's separate license, included in the distribution. End users may not redistribute those assemblies. Commercial exploitation requires Thermo's prior written consent. The BSD license covers this project's Python code, not the Thermo binaries. See THERMO_RAWFILEREADER_TERMS.md.

RawFileReader reading tool. Copyright © 2016 by Thermo Fisher Scientific, Inc. All rights reserved.

Format support

NPZ single-scan files must contain an array named data. Numeric arrays load without pickle support. Legacy CD-MS files with object-backed data arrays are also supported, but emit a warning because they require pickle deserialization; load those files only from trusted sources.

The four Thermo RawFileReader assemblies are bundled under their separate proprietary terms. Waters and Agilent SDK licenses do not permit this project to redistribute those binaries, so users must obtain them separately. Set THERMO_RAW_FILE_READER_DIR to override the bundled Thermo assembly directory, MASSLYNX_RAW_DLL to a licensed Waters DLL, or AGILENT_DA_SDK_DIR to a licensed Agilent Data Access assembly directory. Unsupported platforms and missing runtimes raise VendorReaderUnavailableError with an actionable message.

Core API

get_importer(file_path, **options) inspects the path and returns the appropriate reader. file_path may be a string or path-like object; options are passed to the format-specific reader. Unknown extensions raise UnsupportedFormatError, while an unavailable proprietary SDK or platform raises VendorReaderUnavailableError.

All readers inherit from UniDecImporter.Importer.Importer. They expose scans (ordered scan identifiers), times (retention times in minutes), levels (MS order when available), and an inclusive scan_range. Ordinary spectra and chromatograms are NumPy N x 2 arrays. Specialized return shapes are noted below.

Spectrum access

Supplying time_range selects the nearest endpoint scans and takes precedence over a simultaneously supplied scan_range. With neither argument, averaging uses the full reader range.

Scan metadata and coordinate conversion

Chromatograms

TIC and EIC access require reader.chrom_support. get_bpc() is available through a format-independent scan-based implementation, with native vendor chromatograms used when supported:

CD-MS and ion mobility

Check reader.cdms_support and reader.imms_support before calling these methods:

Calling an unsupported specialized method raises NotImplementedError.

Construction and resource management

Importer.__init__(file_path, **kwargs) initializes the shared state, but applications should construct readers through get_importer. close() releases open files, database connections, or vendor handles; the base implementation is a no-op. __enter__() and __exit__() provide context-manager support, call close() on exit, and do not suppress exceptions. Prefer with whenever practical:

with get_importer("run.mzML") as reader:
    data = reader.get_avg_scan()

For a two-column single spectrum:

from UniDecImporter import get_importer

reader = get_importer("spectrum.csv")
data = reader.get_avg_scan()
assert data.shape[1] == 2

For CD-MS:

with get_importer("ions.dmt") as reader:
    events = reader.get_cdms_data()
    mz, intensity, scan, inverse_injection_time, time = events.T

Development

git clone https://github.com/michaelmarty/UniDecImporter.git
cd UniDecImporter
python -m pip install -e ".[test]"
python -m pytest

The suite includes fast numerical/unit tests, cross-platform integration tests against the bundled open formats, native ARM64 tests on Linux and Windows, and separately marked Windows x86-64 vendor tests:

python -m pytest -m "not integration and not vendor"
python -m pytest -m "integration and not vendor"
python -m pytest -m vendor

See the documentation, PUBLISHING.md, and THIRD_PARTY_NOTICES.md for full details.

Change Log

Version 1.0.4

Added get_bpc() for base-peak chromatograms and get_chrom() for unified TIC, BPC, and EIC dispatch. Thermo, Waters, and Agilent readers use their native chromatogram APIs where available; other formats calculate the maximum intensity in each scan. Added unit, integration, and paired-format consistency tests.

Version 1.0.3

Fixes to Thermo centroid importing.

Added linux and Windows ARM builds, which won't support the full vendor formats but will work for open formats.

Version 1.0.2

Well, we got too fancy and burned up a bunch of GitHub LFS bandwidth, so this version uses a smaller set of test files and removes Git LFS from the repository.

Improved test coverage for mzML, mzXML, and NPZ readers.

Harmonized sum vs average behavior to have average by default and sum only when sum_mode=True.

Version 1.0.1

Fix to npz bug.

Version 1.0.0

Initial release of standalone package.