Metadata-Version: 2.4
Name: xpectra
Version: 0.1.1
Summary: Calibration, OOD abstention, semi-supervised learning, and weathering analysis for microplastic FTIR classification
Author-email: Julhash Kazi <xpectra@kazilab.se>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kazilab/xpectra
Project-URL: Documentation, https://xpectra.readthedocs.io
Project-URL: Repository, https://github.com/kazilab/xpectra
Keywords: FTIR,microplastics,spectroscopy,machine-learning,calibration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: xgboost
Requires-Dist: joblib
Requires-Dist: matplotlib
Requires-Dist: xpectrass>=0.0.4
Provides-Extra: deep
Requires-Dist: torch; extra == "deep"
Provides-Extra: study
Requires-Dist: torch; extra == "study"
Requires-Dist: umap-learn; extra == "study"
Requires-Dist: pytorch-tabnet; extra == "study"
Requires-Dist: scikit-learn>=1.3; extra == "study"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Dynamic: license-file

# FTIR Model Training And Prediction Pipeline

`xpectra` is a reusable pipeline for microplastic FTIR classification, built around three preprocessing routes:

- `norm`: `combined_norm_data.csv.xz`
- `deriv1`: `combined_norm_deriv1_data.csv.xz`
- `deriv2`: `combined_norm_deriv2_data.csv.xz`

The preprocessing defaults, reproduced by `xpectra-process-raw`, are: wavelet denoising, `aspls` baseline correction, atmospheric interpolation with `zero`, `spectral_moments` normalization, and Savitzky-Golay derivatives with `window_length=15`, `polyorder=3`.

When installed from PyPI, the reusable workflows are available as command-line tools:

```bash
xpectra-process-raw --out-dir processed_data
xpectra-train --routes all
xpectra-predict path/to/raw_spectra.csv --output predictions.csv
xpectra-study --list
```

The notebook reproduction drivers are grouped under `xpectra-study`. Install the optional
study dependencies for the heavier workflows:

```bash
python -m pip install "xpectra[study]"
```

## Process Raw Data

Regenerate the three route files (`.csv.xz`) consumed by the study workflows. `--out-dir`
defaults to `processed_data/`; pass `--dry-run` to build and verify without writing:

```bash
xpectra-process-raw               # writes to processed_data/
xpectra-process-raw --out-dir some/other/dir
xpectra-process-raw --dry-run     # build + verify only, no files written
```

## Reproduce Notebook Results

List the available study workflows:

```bash
xpectra-study --list
```

Run one workflow:

```bash
xpectra-study loso
xpectra-study nb2-corrected
xpectra-study nb2-figures
xpectra-study contrastive
xpectra-study nb3-analysis
xpectra-study nb3-figures
xpectra-study nb4-analysis
xpectra-study nb4-figures
xpectra-study report
```

### Preprocessing route

The study workflows and the `nb2`/`nb3`/`nb4` analysis and figure commands accept
`--route {norm,deriv1,deriv2}` (default `norm`). Every result table, figure, and cached
embedding is written with the route as a filename prefix (for example
`norm_deep_ssl_loso.csv`, `deriv1_figure3_main_contrastive_transfer.png`), so runs on
different routes never overwrite one another:

```bash
xpectra-study deep-ssl --route norm
xpectra-study deep-ssl --route deriv1
```

The classical sweeps (`calibrate`, `loso`, `ood`, `ssl`) instead carry a `route` column and
cover all three routes in a single unprefixed file.

The corrected Notebook 2 workflow reuses current `nb2-corrected-v3` result tables by
default. To deliberately rerun the complete nested analysis, use
`xpectra-nb2-corrected --force`. Publication figures can be regenerated with
`xpectra-nb2-figures` (also `--route`-aware).

The Notebook 3 publication workflow uses the cached contrastive encoder and
embeddings from `xpectra-study contrastive`. Generate its canonical diagnostic
tables with `xpectra-nb3-analysis`, then build the main and supplementary figure
sets with `xpectra-nb3-figures`.

Notebook 4 validates robust field-spectrum clusters against polymer identity,
carbonyl index, environmental status, and source-study provenance. Generate its
canonical tables with `xpectra-nb4-analysis` and the publication figure sets
with `xpectra-nb4-figures`.

## Train And Save Models

Train all 41 Xpectrass models for all three routes:

```bash
xpectra-train --routes all
```

Train selected models only:

```bash
xpectra-train \
  --routes norm deriv1 deriv2 \
  --model "XGBoost (100)" \
  --model "Random Forest (100)"
```

Saved artifacts are written to:

```text
models/
  norm/<model>.joblib
  deriv1/<model>.joblib
  deriv2/<model>.joblib
  training_summary.csv
```

Each artifact contains the fitted estimator, `StandardScaler`, `LabelEncoder`, class names, preprocessing settings, and exact training wavenumber order.

## Predict From Raw CSV

Predict through all saved route artifacts:

```bash
xpectra-predict path/to/raw_spectra.csv \
  --routes all \
  --models-dir models \
  --output predictions.csv
```

Use only selected models:

```bash
xpectra-predict path/to/raw_spectra.csv \
  --routes norm deriv1 \
  --model "XGBoost (100)" \
  --output predictions.csv
```

If your CSV is already normalized, skip raw denoise/baseline/normalization and only interpolate/derive:

```bash
xpectra-predict path/to/normalized_spectra.csv \
  --input-stage normalized \
  --routes all \
  --output predictions.csv
```

If your CSV is already route-ready on the expected wavenumber grid:

```bash
xpectra-predict path/to/route_ready.csv \
  --input-stage route \
  --routes norm \
  --output predictions.csv
```

## Override Preprocessing

The prediction CLI lets you override the preprocessing defaults:

```bash
xpectra-predict path/to/raw_spectra.csv \
  --denoising-method wavelet \
  --baseline-method aspls \
  --normalization-method spectral_moments \
  --interpolate-method zero
```

For absorbance-like inputs that should skip Xpectrass auto-conversion:

```bash
xpectra-predict path/to/raw_spectra.csv \
  --force-absorbance
```

For spectra stored on a 0-100 absorbance-like scale:

```bash
xpectra-predict path/to/raw_spectra.csv \
  --force-absorbance \
  --absorbance-scale-factor 100
```
