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()

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 work on all three 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

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(path, **options) returns the appropriate reader. The common methods are:

• get_single_scan(scan) → N x 2 array (m/z, intensity)
• get_all_scans() → list of N x 2 arrays
• get_avg_scan(scan_range=..., time_range=...) → merged N x 2 array
• get_tic() / get_eic(mass, mz_tol, rt_range=None) → chromatogram N x 2 arrays
• get_cdms_data() → N x 5 (m/z, intensity, scan, inverse injection time, time)
• get_imms_scan(scan) / get_imms_avg_scan(...) → N x 3 (m/z, drift time, intensity)
• get_polarity(), get_ms_order(scan), scan/time conversion helpers, and close()

Check reader.chrom_support, reader.cdms_support, and reader.imms_support before calling specialized methods. Readers are context managers, so with is preferred.

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

Large test fixtures use Git LFS:

git clone https://github.com/michaelmarty/UniDecImporter.git
cd UniDecImporter
git lfs pull
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, and separately marked Windows 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.