alex123-converter 0.3.1

ALEX123 Converter - RAW to TXT mass spectrometry data converter

ALEX123 Converter

A Python package for extracting mass spectrometry data from Thermo RAW files and converting them to TXT format.

Overview

This tool extracts and averages spectral data stored in proprietary .RAW files. Specifically, scan-filter-specific peak lists are saved as searchable .txt files in dedicated folders named according to the originating scan filter.

Requirements

• Python >= 3.11
• .NET 8 runtime (Windows, Linux, or macOS)
• Thermo RawFileReader assemblies (installed once with alex123-converter --setup)

The Thermo RawFileReader assemblies are proprietary and are not distributed with this package. After installing, run alex123-converter --setup once to download them directly from Thermo's official repository (you will be asked to accept Thermo's license). They are stored in a per-user data directory; set the ALEX123_LIB_DIR environment variable to use a different location.

Installing the .NET 8 runtime

The converter loads Thermo's RawFileReader .NET assemblies through pythonnet, so a .NET 8 runtime must be present on the machine.

Windows — run in an elevated terminal (or use the Microsoft Store):

winget install Microsoft.DotNet.Runtime.8

Or download it manually from the official .NET 8.0 page (choose .NET Runtime → Windows → your CPU architecture); see the Windows install guide.

Linux (Ubuntu/Debian):

sudo apt install dotnet-runtime-8.0

macOS:

brew install --cask dotnet-runtime

Verify the runtime is on PATH:

dotnet --list-runtimes

The output must contain a Microsoft.NETCore.App 8.x line.

macOS / Homebrew note. The converter auto-detects the .NET runtime in the usual locations (including Homebrew's keg-only dotnet@8). If it still reports "Could not initialise the .NET runtime", set DOTNET_ROOT to the directory that contains host/fxr:

export DOTNET_ROOT=/opt/homebrew/opt/dotnet@8/libexec

Installation

Install the package:

pip install alex123-converter

Then download the Thermo RawFileReader assemblies (one-time):

alex123-converter --setup

This fetches the assemblies from Thermo's official repository after you accept Thermo's license. If you are offline or behind a proxy, download the .nupkg files manually and point setup at them:

alex123-converter --setup --from /path/to/downloaded/nupkgs

Usage

alex123-converter config_file.txt

Or via the Python module:

python -m alex123_converter config_file.txt

Configuration

Create a JSON configuration file (see examples/config_file.txt for an example) with the following options:

• input_dir - Directory containing RAW files
• output_dir - Directory for output TXT files
• state_file - File to track processed files (enables incremental processing)
• data_format - "profile" or "centroid" (centroid is only available for FTMS scans)
• skip_scans - Number of scans to skip at the beginning/end of each file
• include_filters - Glob pattern to filter scan types
• named_averages - Define specific scan ranges to average

License

alex123-converter is licensed under the GNU General Public License v3.0 or later (full text), with an additional permission under GPL section 7 that allows combining it with Thermo Fisher Scientific's RawFileReader assemblies. The LICENSE and LICENSE-EXCEPTION.txt files are included in the package distribution.

The Thermo RawFileReader assemblies are not part of this project and are not distributed with it. They are downloaded by alex123-converter --setup directly from Thermo Fisher Scientific and remain subject to their own proprietary license (the RawFileReader Software License Agreement), which prohibits commercial exploitation and redistribution. You are responsible for complying with that license.