xpectra

Calibration, OOD abstention, semi-supervised learning, and weathering analysis for microplastic FTIR classification

Release 0.1.1 · maintained by Data Analysis Team at KaziLab.se · <xpectra@kazilab.se>

---

xpectra is a reusable pipeline and analysis toolkit for reliable polymer identification from FTIR spectra. It targets the failure mode that ordinary microplastic classifiers hide: models trained on pristine reference plastics and validated on a random split of a single dataset report high accuracy, then fail silently on weathered, environmental particles measured on a different instrument. xpectra quantifies that generalization gap and provides the tools that make predictions trustworthy in deployment:

• Honest validation — leave-one-study-out (LOSO), not random-split, so the score reflects transfer to an unseen instrument.

• Probability calibration — leakage-safe temperature / isotonic scaling with expected calibration error (ECE) and reliability diagrams.

• Out-of-distribution detection & abstention — max-softmax, entropy, energy, Mahalanobis, kNN-distance, and spectral-angle scorers with a calibrated abstention threshold.

• Semi-supervised learning — self-training and label spreading over unlabeled field spectra.

• Weathering analysis — the carbonyl index and its cross-instrument confounds.

• A reproducible study layer — the full published analyses (deep models, contrastive representations, external-data augmentation, degradation clustering) as one-command workflows.

Three preprocessing routes

Every workflow runs over one of three preprocessing routes, produced once by xpectra-process-raw:

Route	File	Content
norm	combined_norm_data.csv.xz	spectral_moments-normalized spectra
deriv1	combined_norm_deriv1_data.csv.xz	first Savitzky–Golay derivative
deriv2	combined_norm_deriv2_data.csv.xz	second Savitzky–Golay derivative

Getting started

Guide

• Installation
  • Requirements
  • From PyPI
  • Optional extras
  • From source (editable)
  • Verify the install
• Quickstart
  • 1. Build the processed data
  • 2. Load labeled and unlabeled spectra
  • 3. Calibrate a classifier (leakage-safe)
  • 4. Measure the generalization gap (LOSO)
  • 5. Detect out-of-distribution spectra and abstain
  • 6. Weathering indicator
• Preprocessing routes & the route-prefix convention
  • The three routes
  • Selecting a route
  • The route-prefix convention

Reference

• Command-line interface
  • xpectra-process-raw
  • xpectra-train
  • xpectra-predict
  • xpectra-study
• Study reproduction workflows
  • Workflow catalog
  • Route selection
  • Dependencies between workflows
  • Reference datasets
• API reference
  • Configuration & data
  • Metrics
  • Calibration
  • Out-of-distribution detection & abstention
  • Semi-supervised learning
  • Weathering analysis
  • Module index

Project

• Changelog

Citation & contact

If you use xpectra in academic work, please cite the package and the underlying reference datasets (see Study reproduction workflows). For questions, contact the Data Analysis Team at KaziLab.se at <xpectra@kazilab.se>.