pymsio 0.1.13

MS I/O readers with optional vendor bindings

Pymsio

Pymsio is a lightweight module for reading mass-spectrometry data files into a unified NumPy/Polars representation.
Its design and implementation are based on the AlphaRaw project: https://github.com/MannLabs/alpharaw/.

It currently supports:

• Thermo RAW files (via pythonnet + Thermo Fisher CommonCore DLLs)
• mzML files

Both formats are exposed through a common interface.

---

Requirements

• Supported OS: Windows, Linux
• Python: >= 3.8
• Thermo RAW:
  • Requires Thermo Fisher CommonCore DLLs (ThermoFisher.CommonCore.Data.dll, ThermoFisher.CommonCore.RawFileReader.dll) obtained from the RawFileReader project (https://github.com/thermofisherlsms/RawFileReader).
  • Linux also needs Mono (use install_mono.sh).

---

Installation

1. Clone the repository

   git clone https://github.com/bertis-informatics/pymsio.git
   cd pymsio
   

2. Quick Install (recommended)

   The install script downloads the Thermo RawFileReader DLLs (with license agreement) and installs pymsio in one step.

   Windows PowerShell

   .\install.ps1
   

   Linux / macOS

   chmod +x install.sh
   ./install.sh
   

3. Manual Install

   Click to expand manual installation steps

   a. Provide the Thermo DLLs (only needed for Thermo RAW)

   • Linux only: ensure Mono is installed (required by pythonnet). Use the helper script:

     ./install_mono.sh
     

   1. Download (or git clone) RawFileReader: https://github.com/thermofisherlsms/RawFileReader
   2. Copy the two DLLs from RawFileReader/Libs/Net471/:
      • ThermoFisher.CommonCore.Data.dll
      • ThermoFisher.CommonCore.RawFileReader.dll
   3. Make the DLLs discoverable:
      • Option A — Bundle DLLs inside the package <path-to-pymsio>/pymsio/dlls/thermo_fisher/
        • Copy the DLLs into pymsio/dlls/thermo_fisher/ before running pip install -e . so they ship with the installation.
        • Example:

          mkdir -p pymsio/dlls/thermo_fisher
          cp /path/to/RawFileReader/Libs/Net471/*.dll /path/to/pymsio/pymsio/dlls/thermo_fisher/
          

      • Option B — Set up an environment variable PYMSIO_THERMO_DLL_DIR
        • Windows example:

          setx PYMSIO_THERMO_DLL_DIR "<path-to-your-dll-folder>"
          

        • Linux example:

          export PYMSIO_THERMO_DLL_DIR="<path-to-your-dll-folder>"
          

          (Add the export line to ~/.bashrc to keep it persistent.)
        • Copy the DLLs into the folder referenced by the variable.

   b. Install pymsio

   pip install .
   

---

Quick Test

Run the test suite with pytest:

# Basic tests (import check, DLL binding check)
pytest tests/

# With reader tests (provide file paths)
pytest tests/ --raw "path/to/file.raw" --mzml "path/to/file.mzML"

Tests for readers whose file path is not provided will be automatically skipped.

---

Code Example

Click to expand

from pathlib import Path
from pymsio.readers import ReaderFactory

path = Path("path/to/your/file.raw")  # or .mzML

# 1) Get appropriate reader (Thermo RAW or mzML)
reader = ReaderFactory.get_reader(path)

# 2) Read metadata (Polars DataFrame)
meta_df = reader.get_meta_df()
print(meta_df.head())

# 3) Read one frame (np.ndarray, shape (N, 2), columns: [mz, intensity])
frame_num = int(meta_df.item(0, "frame_num"))
peaks = reader.get_frame(frame_num)
print(peaks.shape)

# 4) Load full dataset
msdata = reader.load()
print(msdata.peak_arr.shape)

---

License

This project is licensed under the Apache License 2.0.

Note: The Thermo RawFileReader DLLs are proprietary and subject to their own license. They are not included in this repository.