Metadata-Version: 2.4
Name: alex123-unifier
Version: 0.2.0
Summary: This tool combines search results from multiple ALEX123 extractor searches into a single output file.
Author-email: Sergii Mamedov <sergii.mamedov@embl.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: alex123,lipidomics,mass-spectrometry
Classifier: Development Status :: 4 - Beta
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
Description-Content-Type: text/markdown

# ALEX123 Unifier

This tool combines search results from multiple ALEX123 extractor searches into a single output file.

## Overview

An ALEX123 data search produces a directory with multiple subdirectories, one per MS range.
Each subdirectory contains the same set of result files. 
This tool scans those subdirectories and merges files of the same type into a single output, 
writing one shared header followed by all data rows.

## Installation

Install from PyPI:

```bash
pip install alex123-unifier
```

## Usage

Point the tool at the directory produced by an ALEX123 search:

```bash
alex123-unifier <search_directory>
```

Or run it as a module:

```bash
python -m alex123_unifier <search_directory>
```

If no directory is given, the current working directory is used. The unified files are written back into the search directory itself.

### Input

The search directory holds one subdirectory per MS range, each containing the same set of result files:

```
search_results/                          <-- pass this directory to the tool
    neg_101extract_195-400/
        results_alex123_ms1.tab
        lockmasses.tab
        maxgap.tab
        targetlist_ms1.txt
    neg_101extract_350-675/
        results_alex123_ms1.tab
        lockmasses.tab
        maxgap.tab
        targetlist_ms1.txt
    ...
```

### Output

Files of the same type are merged into a single unified file:

| Input file pattern   | Output file              |
|----------------------|--------------------------|
| `results_alex123_*`  | `Results_unified.tab`    |
| `lockmasses*`        | `Lockmass_unified.tab`   |
| `maxgap*`            | `Maxgap_unified.tab`     |
| `targetlist*`        | `Targetlist_unified.txt` |

Each output file contains the header from the first matched file, followed by the data rows from all matched files. 
Column headers are validated across files. The unifier raises an error if the columns don't match.

## License

alex123-unifier 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.
