Metadata-Version: 2.4
Name: UniDecImporter
Version: 0.1.0
Summary: Standalone, cross-platform readers for mass-spectrometry data
Author-email: "Michael T. Marty" <mtmarty@utexas.edu>
License-Expression: BSD-3-Clause AND LicenseRef-Thermo-RawFileReader
Project-URL: Homepage, https://github.com/michaelmarty/UniDecImporter
Project-URL: Repository, https://github.com/michaelmarty/UniDecImporter
Project-URL: Issues, https://github.com/michaelmarty/UniDecImporter/issues
Project-URL: Documentation, https://michaelmarty.github.io/UniDecImporter/
Keywords: mass spectrometry,mzML,mzXML,CD-MS,ion mobility
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: THERMO_RAWFILEREADER_TERMS.md
Requires-Dist: h5py>=3.8
Requires-Dist: numpy>=1.23
Requires-Dist: pymzml>=2.5
Requires-Dist: pyteomics[XML]>=4.6
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Provides-Extra: thermo
Requires-Dist: pythonnet>=3.0; (platform_system == "Windows" and platform_machine == "AMD64") and extra == "thermo"
Provides-Extra: agilent
Requires-Dist: pythonnet>=3.0; (platform_system == "Windows" and platform_machine == "AMD64") and extra == "agilent"
Provides-Extra: vendor
Requires-Dist: pythonnet>=3.0; (platform_system == "Windows" and platform_machine == "AMD64") and extra == "vendor"
Dynamic: license-file

# 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:

```python
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

```shell
python -m pip install UniDecImporter
```

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

```shell
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`](THERMO_RAWFILEREADER_TERMS.md).
>
> RawFileReader reading tool. Copyright © 2016 by Thermo Fisher Scientific, Inc. All
> rights reserved.

## Format support

| Format | Data types | Platforms | Reader dependency |
|---|---|---|---|
| mzML, indexed mzML.gz | LC-MS, MS/MS, CD-MS, IM-MS | Windows, macOS, Linux | pymzML |
| mzXML | LC-MS, MS/MS, CD-MS | Windows, macOS, Linux | pyteomics |
| TXT, DAT, CSV | Single scan, CD-MS, IM-MS | Windows, macOS, Linux | NumPy |
| NPZ, BIN | Single scan, CD-MS | Windows, macOS, Linux | NumPy |
| I2MS, DMT | CD-MS | Windows, macOS, Linux | Python sqlite3 |
| Thermo RAW | LC-MS, MS/MS, CD-MS | Windows x86-64 only | Thermo RawFileReader + pythonnet |
| Waters RAW directory | LC-MS, IM-MS | Windows x86-64 only | Waters MassLynx SDK |
| Agilent `.d` | LC-MS, MS/MS | Windows x86-64 only | Agilent MassHunter Data Access SDK + pythonnet |

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:

```python
from UniDecImporter import get_importer

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

For CD-MS:

```python
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:

```shell
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:

```shell
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](https://michaelmarty.github.io/UniDecImporter/),
[`PUBLISHING.md`](PUBLISHING.md), and [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)
for full details.
