Metadata-Version: 2.4
Name: alex123-extractor
Version: 0.4.2
Summary: This tool uses `target lists`, generated by the ALEX123 Target List Generator, to search peak lists for lipid molecules and fragment m/z values.
Author-email: Sergii Mamedov <sergii.mamedov@embl.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: calibration,ftms,gui,lipidomics,lock-mass,mass-spectrometry,ms2
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
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: numpy~=2.4.0
Requires-Dist: pandas~=2.3.0
Requires-Dist: pyside6-essentials~=6.10.0
Requires-Dist: scipy~=1.17.0
Description-Content-Type: text/markdown

# ALEX123 Extractor

A PySide6 GUI application for mass spectrometry data extraction and offline lock mass recalibration.

## Overview

ALEX123 Extractor processes spectral files against target lists to find peaks, calculate calibration offsets, and generate detailed output tables. It supports offline lock mass recalibration using known reference ions, targetlist processing with optional calibration correction, and gap analysis for quality control. MS1, MS2, and MS3 data are handled in separate tabs, with MS2/MS3 organized by precursor m/z directories.

## Features

- Peak detection in spectral data within a configurable m/z tolerance (ppm or absolute)
- Offline lock mass recalibration using up to 5 reference ions per MS level
- Gaussian peak fitting for precise centroid m/z, FWHM, and fit quality (R²)
- Targetlist processing with optional lock mass correction
- MS2/MS3 support with precursor m/z directory matching and collision-energy parsing
- Gap analysis (min/max/mean/median m/z gaps) for data quality assessment
- Save and load configurations per tab (`presets.lxx`)
- Cross-platform (Windows, macOS, Linux)

## Requirements

- Python >= 3.11

PySide6, pandas, numpy, and scipy are installed automatically as dependencies.

## Installation

```bash
pip install alex123-extractor
```

## Usage

Run the application:

```bash
alex123-extractor
```

Or via the Python module:

```bash
python -m alex123_xtractor
```

Then, in the app:

1. **Select the target directory** -- where `targetlist_ms*.txt` and output files live. Presets are loaded automatically if a `presets.lxx` is present.
2. **Select the spectral directory** -- the folder with the spectral `.txt` files.
3. **Switch to the MS1, MS2, or MS3 tab.**
4. **Configure lock mass ions** (optional) -- reference m/z values and their tolerance/offset settings.
5. **Click "Check calibration"** to run offline lock mass recalibration; gap analysis runs automatically afterwards.
6. **Set the general search tolerance and offset**, then **click "Search"** to process the target list.

## Input Files

| File                                                               | Description                                                          |
|--------------------------------------------------------------------|----------------------------------------------------------------------|
| `targetlist_ms1.txt` / `targetlist_ms2.txt` / `targetlist_ms3.txt` | Tab-separated target lists (from ALEX123-TLG)                        |
| Spectral `.txt` files                                              | Two columns (m/z, intensity), sorted by m/z (from ALEX123 Converter) |

## Output Files

Written to the target directory:

| File                      | Description                                                                              |
|---------------------------|------------------------------------------------------------------------------------------|
| `lockmasses.tab`          | Offline lock mass recalibration results (per file, per reference ion)                    |
| `results_alex123_ms*.tab` | Targetlist processing results (original columns plus matched peaks and calibration data) |
| `maxgap.tab`              | Gap analysis statistics per spectral file                                                |
| `presets.lxx`             | Saved tab configuration (JSON)                                                           |

## License

alex123-extractor is licensed under the **GNU General Public License v3.0 or later**
([full text](https://www.gnu.org/licenses/gpl-3.0.html)). The `LICENSE` file is included in
the package distribution.

This application uses PySide6 (Qt for Python) under the **GNU Lesser General Public License v3.0
(LGPLv3)**. PySide6 and Qt are not part of this project; they are installed from PyPI and remain
under their own license.
