Metadata-Version: 2.4
Name: rgakit
Version: 0.1.1
Summary: RGA mass spectrum decomposition and library fitting
Author-email: roncofaber <fabrice.roncoroni@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/roncofaber/rgakit
Project-URL: Bug Tracker, https://github.com/roncofaber/rgakit/issues
Project-URL: Changelog, https://github.com/roncofaber/rgakit/releases
Keywords: rga,mass spectrometry,fitting,synchrotron,NIST
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: platformdirs>=2.5.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: nistchempy

# rgakit

Python toolkit for decomposing RGA (Residual Gas Analyzer) electron-ionisation
mass spectra into known compound contributions.

Developed for synchrotron beamline ALS BL12.0.1.2 to analyse gas desorption
from X-ray irradiated perovskite thin films.

## Features

- **NNLS fitting** — non-negative least-squares decomposition against a reference library
- **Similarity metrics** — cosine, Jaccard, Pearson, spectral entropy; pairwise matrix for clustering
- **Library search** — rank candidates by any similarity metric before NNLS fitting
- **NIST library access** — fetch and cache spectra from NIST WebBook by name or CAS
- **JDX & MSP I/O** — JCAMP-DX (round-trip with metadata) and NIST MSP (multi-entry files)
- **Background correction** — linear subtraction using beam-off windows (via `clabs`)
- **Interactive HTML report** — observed vs fitted, residual, contributions, stacked breakdown
- **Smart naming** — common trivial names (Water, Methane, …) with IUPAC fallback via NCI Cactus

## Install

```bash
pip install rgakit
```

## Quick start

```python
from rgakit import MassSpectrum, SpectraLibrary, pairwise

# Build library from a folder of .jdx or .msp files
lib = SpectraLibrary.from_dir("data/jdx/")

# Load an experimental spectrum
ms = MassSpectrum.from_jdx_file("sample.jdx")

# Candidate search (cosine, jaccard, pearson, or entropy)
print(lib.search(ms, top_n=5, method="entropy"))

# NNLS fit
result = lib.fit(ms)
result.summary()

# HTML report
from rgakit import generate_report
generate_report(result, library=lib, spectrum=ms, output_path="report.html")

# Pairwise similarity matrix (for clustering / classification)
mat, names = pairwise(lib, method="cosine")
# mat is a symmetric (N, N) ndarray; use with seaborn.heatmap or UMAP
```

### MSP format

```python
# Load all spectra from a single NIST MSP file (multi-entry)
lib = SpectraLibrary.from_msp("nist_library.msp")

# Load one entry by index
ms = MassSpectrum.from_msp_file("nist_library.msp", index=3)

# Save a spectrum as MSP
ms.save_msp("output/water.msp")
```

## Workflow with clabs

```python
# Background-correct the raw RGA measurement in clabs, then extract spectrum
rga.background_correct()
ms = MassSpectrum.from_rga(rga)
ms.save_jdx("sample.jdx")
```

## File structure

```
rgakit/
  spectrum.py     — MassSpectrum (JDX, MSP, txt I/O; compare; from_rga)
  library.py      — SpectraLibrary (NNLS fit, search, from_dir/from_msp)
  result.py       — FitResult (summary table, plot)
  similarity.py   — cosine / jaccard / pearson / entropy; pairwise matrix
  background.py   — standalone linear background correction
  nomenclature.py — name resolution (common names → Cactus IUPAC → NIST)
  report.py       — interactive HTML report generation
```

