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

Output format

Each output file is tab-separated and always has the same five columns:

m/z	Intensity	Resolution	Noise	Baseline

With "data_format": "centroid" every column is filled in:

m/z	Intensity	Resolution	Noise	Baseline
200.0688811488	205.53098	145672.6	1056.29781	-22.48422

With "data_format": "profile" the last three columns are left empty — profile spectra simply do not carry per-peak resolution, noise and baseline. The fields are empty rather than 0, NaN or -, so that nothing can be mistaken for a measurement:

m/z	Intensity	Resolution	Noise	Baseline
198.0141160672	0.00000			

A caveat about Noise

When several scans are averaged, the reported Noise is not measured on the averaged spectrum. The instrument software propagates it as sqrt(sum(noise_i²)) / N, so it falls as 1/sqrt(N) purely by construction — averaging one and the same scan N times lowers it just as much as averaging N different scans.

Real noise in direct-infusion data does not keep falling that way: the chemical background repeats from scan to scan and does not average out, so the measured noise floor levels off at roughly N ≈ 8 scans. If you compute S/N from this column over long acquisitions, expect it to be optimistic — on our test data, about threefold too high at 59 averaged scans.

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.