Metadata-Version: 2.5
Name: peaxart
Version: 0.1.1
Summary: Peak extraction in the retention time / m/z domain of GC-TOF-MS data (from alpinac)
Project-URL: Repository, https://github.com/lionel42/peaxart
Project-URL: Issues, https://github.com/lionel42/peaxart/issues
Author: Myriam Guillevic
Author-email: Lionel Constantin <lionel.constantin@empa.ch>
License-Expression: LGPL-3.0-or-later
License-File: LICENCE
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Requires-Dist: numba>=0.58
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: notebook
Requires-Dist: jupyter; extra == 'notebook'
Requires-Dist: matplotlib; extra == 'notebook'
Requires-Dist: nbclient; extra == 'notebook'
Requires-Dist: nbformat; extra == 'notebook'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# peaxart

Peak extraction in the retention time / m/z domain of GC-TOF-MS data.

This is a rewrite of the peak extraction of the legacy alpinac
(`halosearch/alpinac/mode_extraction`), independent of the HDF5 files: the
input is plain numpy arrays, the output a table of peaks. With the default
settings it reproduces the legacy extraction (bit for bit on most data).
The output can be written in the peak-file format read by the alpinac
identification.

## Method

For each domain (typically one unit mass +-0.5 m/z and ~10 s of rt):

1. **Mass domain, each spectrum**: peaks are detected with a slope method and
   fitted together with pseudo-Voigt functions of fixed shape (sigma from a
   model of the instrument, fixed Lorentzian fraction) plus a constant
   baseline: position, area and baseline are fitted. Weak peaks are removed and
   the fit redone.
2. **Grouping by m/z**: the per-scan peaks are grouped with a histogram of their
   m/z (bin width depending on the mean area) and assigned to the nearest centre.
3. **Retention time**: for each m/z group, the per-scan areas versus rt are
   fitted with chromatographic peaks (Pap and Papai 2001) and a baseline;
   insignificant peaks (Student t test) are removed, and the fit is rejected if
   it is not better than a straight line. The m/z of a peak is the mean of the
   per-scan positions weighted by the fitted chromatographic peak.

## Install

```bash
pip install peaxart   # numpy, scipy, pandas, numba
```

or, from a clone, `pip install -e .`

## Use

```python
import numpy as np
import peaxart

# intensity: (n_scans, n_points), keep float32 for TOF data
# rt:        (n_scans,) seconds
# mz:        m/z of each point: (n_points,), (n_scans, n_points), or a function mz(rt, x)
# x:         axis of the spectra used for the mass-domain fits (e.g. the tof index)
# sigma:     mass peak width in x units (number or function of x), alpha: Lorentzian fraction
peaks = peaxart.extract(intensity, rt, mz, sigma=lambda x: 0.4 + 2e-5 * x, alpha=0.49,
                        x=tofidx, masses=range(20, 300), rt_range=(1612, 1621), n_jobs=8)

peaks["compound"] = peaxart.group_compounds(peaks, dt=rt[1] - rt[0])

# input of the alpinac identification
peaxart.to_alpinac(peaks, "sample.frag.txt", mass_cal_u=5.0, metadata={"sample": "tank 5"})

# one domain only
df = peaxart.extract_domain(intensity_domain, rt_domain, mz_domain, sigma, alpha, x=x_domain)
```

Parameters (all with the legacy defaults) are in `peaxart.ExtractionConfig`,
e.g. `ExtractionConfig(rt_sigma=1.5)` for another chromatography.

### Output columns

| column | meaning |
|---|---|
| `mass` | unit mass of the domain (`extract` only) |
| `rt`, `rt_u` | retention time (s) and its standard error |
| `mz`, `mz_u`, `mz_u_ppm` | m/z and the spread of the per-scan positions |
| `area`, `area_u` | area (intensity x x-units x s) and its uncertainty |
| `height`, `height_u` | height of the chromatographic peak |
| `rt_sigma`, `rt_tailing` | width (s) and tailing of the chromatographic peak |
| `mz_sigma`, `mz_alpha` | mass peak shape (sigma in m/z, Lorentzian fraction) |
| `lod`, `sn` | limit of detection (area) and signal to noise |
| `x`, `x_u` | position on the x axis |
| `n_points`, `baseline` | per-scan peaks used, baseline of the rt fit |

### One chromatogram: integration methods

`peaxart.chromatogram` integrates the peaks of a single chromatogram (signal vs rt, e.g. a
unit mass chromatogram), with several methods. Each returns its own columns; all have
`rt`, `height` and `area` (signal x s).

```python
peaks = peaxart.integrate(t, y, method="trapezoid")              # detected peaks
peaks = peaxart.Fit().integrate(t, y, rt=[1823.2, 1826.1])        # start at given rts

# coelution: shapes fitted on an ion of each compound alone, heights fitted on a shared ion
shapes = pd.concat([peaxart.Fit().integrate(t, y85), peaxart.Fit().integrate(t, y70)])
peaks = peaxart.FixedShapes.from_peaks(shapes).integrate(t, y43)
```

| method | columns besides `rt`, `height`, `area` |
|---|---|
| `Trapezoid`: straight baseline between bounds, drop lines between overlapping peaks | `start`, `stop`, `baseline_start`, `baseline_stop`, `fwhm`, `prominence` |
| `Fit`: Pap-Papai peaks and a constant baseline (the rt stage of the extraction) | `rt_u`, `height_u`, `area_u`, `rt_sigma`, `rt_tailing`, `lod`, `sn`, `linear_ratio`, `baseline` |
| `FixedShapes`: given rts and shapes, heights >= 0 and a linear baseline fitted | `height_u`, `area_u`, `rt_sigma`, `rt_tailing`, `baseline`, `baseline_slope`, `residual_std` |

`notebooks/chromatogram_methods.ipynb` compares them on 2- and 3-methylhexane (generated by
`notebooks/make_chromatogram_notebook.py --run`). A new method subclasses
`peaxart.chromatogram.Method` (`integrate`, `bands` for the plots, `columns`) and is added to `METHODS`.

### Data from TOFWERK h5 files

peaxart does not read h5 files: get the intensity, rt and the mass calibration
with your h5 reader (e.g. the legacy alpinac) and pass them as arrays.

## Example notebook

`notebooks/examples.ipynb` plots example domains (real data: `tests/data/domains`, and
`data/examples` for coelution, long and late peaks)
with the functions of `peaxart.plotting` (`analyse_domain`, `field_figure`, `plot_groups`):
the signal in the rt / m/z plane with the per-scan and the extracted peaks, and for
each peak the chromatographic fit and the mass fit at the apex.

```bash
pip install -e ".[notebook]"
jupyter lab notebooks/examples.ipynb
python notebooks/make_examples_notebook.py   # regenerate it (--run: also execute, slow)
```

## Numerics and speed

- `ExtractionConfig(legacy_numerics=True)` (default) reproduces the legacy fits
  (lmfit's algorithm and rounding). It is 2-10 times faster than the legacy
  code per domain, and `extract(..., n_jobs=N)` runs domains in parallel.
- `legacy_numerics=False` uses an analytic Jacobian: much faster for spectra
  with many peaks, same fit quality, but the rt fits of the legacy method are
  sensitive: a ~1 % change of a per-scan area can change the area of some peaks
  by tens of percent. Use it for exploration.
- `convention="legacy"` (default) keeps the legacy Gaussian
  `exp(-(x-mu)^2 / (2 sigma)^2)`, needed with sigma models fitted by the legacy
  mass calibration; `"standard"` is the usual Gaussian.

## Differences to the legacy extraction

With `ExtractionConfig.legacy()` the peaks are the same as the legacy ones.
By default, each chromatographic peak is also tested individually (the legacy
code only compared the whole rt window with a straight line, and fitted peaks
to noise and background elevations):

- `peak_linear_ratio = 0.9`: on the points it covers, the peak must explain the
  data better than a straight background (residual std, corrected for the
  number of parameters, below 0.9 x the one of the line) - column `linear_ratio`;
- `peak_min_coverage = 0.5`: at least half of the scans around the apex must
  have a per-scan mass peak (no "peak" interpolated across a gap) - column `coverage`.

`extract_domain(..., return_rejected=True)` also returns the rejected
candidates, with the reason and the straight background that explains their
data as well (`line_rt`, `line`), as plotted in the example notebook.

Coeluting compounds closer than the rt peak detection can separate (e.g. 2- and
3-methylhexane, 2.9 s apart) are split: after the rt fit, one more peak is tried where
the residual is largest (`rt_extra_peaks`, up to 2). It is kept only if the fit is
clearly better (`rt_extra_peak_ratio`), the new peak is not small (`rt_extra_peak_min_height`)
nor overlapping another one (`rt_extra_peak_min_separation`), and the data show a shoulder
or a dip between the two apexes (`rt_extra_peak_shoulder`): a single tailing peak is
otherwise fitted better with a second small peak in its tail.

A single outlier scan in the per-scan areas of an m/z group (`rt_outlier_k`: one point
deviating from its neighbours 20x more than typical and 3x more than any other point) is
left out of the rt fit, otherwise the fit puts a narrow peak on it, which is then
rejected. Seen on the ringing peaks of strong mass peaks, whose outlier is the apex scan
of the strong peak. The removed points are in `scans["outlier"]` (`return_scans=True`).

Mass peaks are also required to stand above the noise: apex >= noise median +
`mz_noise_k` (3) x a robust noise standard deviation. The legacy rule (1.3 x the
noise median) let dozens of noise bumps per spectrum through next to strong
peaks, which made the fits very slow. `max_iterations` (100) limits each mass fit; a fit
stopped by its limit keeps the best parameters found (`on_abort="best"`; lmfit and
`ExtractionConfig.legacy()`: the last ones, `"last"`).

The reported values also differ where the legacy output was wrong:

- `peak_width` in the alpinac file is the m/z sigma of the peaks (legacy:
  computed from the *rt* sigma, in seconds, used as a tof-index offset);
- `peak_alpha` is the Lorentzian fraction of the mass peaks (legacy: the rt tailing);
- `area_u` is the uncertainty of the area (legacy: of the height);
- a peak on the edge of two unit-mass domains is reported once;
- compound indices of different rt windows do not collide.

## Development

```bash
python -m pytest            # quick (~10 s)
python -m pytest -m slow    # end-to-end on data/examples (~30 s)
```
