Metadata-Version: 2.4
Name: alex123-converter
Version: 0.3.2
Summary: ALEX123 Converter - RAW to TXT mass spectrometry data converter
Author-email: Sergii Mamedov <sergii.mamedov@embl.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
License-File: LICENSE-EXCEPTION.txt
Keywords: lipidomics,mass-spectrometry,rawfilereader,thermo
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Requires-Dist: pythonnet>=3.1.0
Provides-Extra: test
Requires-Dist: numpy>=1.20; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# 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):
```cmd
winget install Microsoft.DotNet.Runtime.8
```
Or download it manually from the [official .NET 8.0 page](https://dotnet.microsoft.com/download/dotnet/8.0) (choose **.NET Runtime** → Windows → your CPU architecture); see the [Windows install guide](https://learn.microsoft.com/dotnet/core/install/windows).

**Linux (Ubuntu/Debian)**:
```bash
sudo apt install dotnet-runtime-8.0
```

**macOS**:
```bash
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`:
> ```bash
> export DOTNET_ROOT=/opt/homebrew/opt/dotnet@8/libexec
> ```

## Installation

Install the package:
```bash
pip install alex123-converter
```

Then download the Thermo RawFileReader assemblies (one-time):
```bash
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:
```bash
alex123-converter --setup --from /path/to/downloaded/nupkgs
```

## Usage

```bash
alex123-converter config_file.txt
```

Or via the Python module:
```bash
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](https://www.gnu.org/licenses/gpl-3.0.html)), 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.