Metadata-Version: 2.5
Name: tadamz_gui
Version: 1.0.0a15
Summary: A frontend for the targeted analysis of LC-MS(/MS) data using the tadamz package.
Project-URL: Homepage, https://gitlab.com/j.hemmann/tadamz_gui
Project-URL: Issues, https://gitlab.com/j.hemmann/tadamz_gui/issues
Author-email: Jethro Hemmann <jethro.hemmann@leibniz-hki.de>
License-Expression: GPL-3.0-only
License-File: LICENSE
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: emzed-gui>=3.2.0
Requires-Dist: emzed>=3.0.9
Requires-Dist: matplotlib>=3.11.2
Requires-Dist: mplcursors
Requires-Dist: psutil
Requires-Dist: pyqt5
Requires-Dist: tadamz==1.0.0a23
Description-Content-Type: text/markdown

# tadaMZ GUI

[![PyPI](https://img.shields.io/pypi/v/tadamz-gui)](https://pypi.org/project/tadamz-gui/)
[![Python](https://img.shields.io/pypi/pyversions/tadamz-gui)](https://pypi.org/project/tadamz-gui/)
[![Pipeline](https://gitlab.com/j.hemmann/tadamz_gui/badges/main/pipeline.svg)](https://gitlab.com/j.hemmann/tadamz_gui/-/pipelines)
[![License: GPL v3](https://img.shields.io/badge/license-GPL--3.0--only-blue.svg)](https://gitlab.com/j.hemmann/tadamz_gui/-/blob/main/LICENSE)

<img src="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/src/tadamz_gui/assets/AppIcon.png" alt="tadaMZ GUI logo" width="80">

tadaMZ GUI is a desktop application for targeted analysis of LC–MS and
LC–MS/MS data. It provides a graphical workflow around the
[`tadamz`](https://pypi.org/project/tadamz/) analysis package, from peak
extraction and quality assessment to calibration, quantification, result
inspection, and reporting.

See the [changelog](https://gitlab.com/j.hemmann/tadamz_gui/-/blob/main/CHANGELOG.md)
for the release history.

## Features

- Configure absolute and relative quantification workflows with several
  normalization and peak-integration methods.
- Process MS1 spectra or chromatogram-only MRM data, including optional peak
  classification, co-elution analysis, and qualifier checks.
- Fit and inspect calibration models for absolute quantification.
- Inspect result tables, chromatograms, and interactive report plots, then
  export results as CSV.
- Save complete workflows as `.tadamzproject` files for later inspection or
  reanalysis.

<table>
  <tr>
    <td><a href="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/workflow-processing.png"><img src="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/workflow-processing.png" alt="Processing an absolute-quantification workflow" height="200"></a></td>
    <td><a href="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/calibration-inspection.png"><img src="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/calibration-inspection.png" alt="Inspecting calibration models" height="200"></a></td>
    <td><a href="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/result-inspection.png"><img src="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/result-inspection.png" alt="Inspecting chromatograms and results in the Table Explorer" height="200"></a></td>
    <td><a href="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/interactive-report.png"><img src="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/interactive-report.png" alt="Viewing a compound-wise interactive report" height="200"></a></td>
  </tr>
</table>

## Installation

tadaMZ GUI requires Python 3.11 or newer. Installation with `pip` is available
on Windows, macOS, and Linux.

### Windows installer

A Windows installer will be available soon. Until then, install tadaMZ GUI
with `pip` as described below.

### Install with pip

Creating a virtual environment is recommended:

```bash
python -m venv .venv
```

Activate it on macOS or Linux:

```bash
source .venv/bin/activate
```

Or on Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
```

Then install the application:

```bash
python -m pip install --upgrade pip
python -m pip install tadamz_gui
```

To start the application, activate the virtual environment and run:

```bash
tadamz_gui
```

## Input data

A new workflow uses the following inputs:

| Input | Required | Purpose |
| --- | --- | --- |
| Target table (`.xlsx`) | Yes | Defines compounds, expected retention times, and target transitions or masses. |
| Sample table (`.xlsx`) | Yes | Describes the samples. It must contain a `filename` column. |
| Sample folder | Yes | Contains the raw-data files named in the sample table. |
| Calibrant table (`.xlsx`) | Absolute workflows only | Defines calibrant samples and amounts used to fit calibration models. |

<a href="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/workflow-setup.png">
  <img
    src="https://gitlab.com/j.hemmann/tadamz_gui/-/raw/main/docs/images/workflow-setup.png"
    alt="Setting up workflow inputs and output in tadaMZ GUI"
    height="200"
  />
</a>

## Project files

A `.tadamzproject` file is a ZIP-based archive that keeps the workflow
configuration and input tables together with any saved results, calibration
results, workflow log, and generated report cache.

Raw LC–MS files are **not** copied into the project. Keep the original sample
folder available if you intend to rerun processing or use functionality that
needs the source data.

## Support

Please report reproducible bugs and feature requests in the
[GitLab issue tracker](https://gitlab.com/j.hemmann/tadamz_gui/issues). Include
the version information shown in the application's start window, the workflow
log, and the steps needed to reproduce the problem when possible.

## Credits

tadaMZ GUI was created by Jethro Hemmann (Leibniz-HKI) and is built on the
`tadamz` package created by Patrick Kiefer (ETH Zurich), with contributions
from Johannes Hartl (BIH at Charité).

## License

This project is licensed under the
[GNU General Public License v3.0](https://gitlab.com/j.hemmann/tadamz_gui/-/blob/main/LICENSE).
