Study reproduction workflows

The xpectra-study command groups the analyses behind the published study. List them with xpectra-study --list; run one with xpectra-study <name>. Results are written to results/ and figures to figures/; intermediate artifacts are cached under .cache/xpectra/, so reruns are incremental.

Workflow catalog

Workflow	Description
`smoke`	Validate the stack on a cheap subsample
`calibrate`	Calibration metrics and reliability diagrams
`loso`	Random-split vs leave-one-study-out generalization
`ood`	OOD detection and risk–coverage sweeps
`ssl`	Semi-supervised learning experiment
`weathering`	Carbonyl index and unknown-pool composition
`batch-effect`	Study-probe and UMAP batch-effect diagnostics
`deep-ssl`	CNN / TabNet self-supervised LOSO
`resnet`	Deeper 1-D ResNet LOSO
`dann`	Domain-adversarial LOSO
`contrastive`	Contrastive encoder LOSO and cached embeddings
`degradation` / `cluster-robustness` / `degradation-validation`	Field-spectrum clustering
`openspecy-loso` / `data-scaling` / `simple-redundancy` / `awi-scaling` / `domain-distance`	External-data augmentation experiments
`nb2-corrected` / `nb2-figures`	Corrected nested deep-model reanalysis + figures
`nb3-analysis` / `nb3-figures`	Contrastive-transfer diagnostics + figures
`nb4-analysis` / `nb4-figures`	Degradation-structure diagnostics + figures
`report`	Collate result CSVs into `results/SUMMARY.md`

The nb2 / nb3 / nb4 analysis and figure steps are also exposed as standalone console scripts (xpectra-nb2-corrected, xpectra-nb3-analysis, …) for convenience.

Route selection

The deep-diagnostic and external-data workflows accept --route {norm,deriv1,deriv2} (default norm) and prefix every output with the route name, so runs on different routes coexist:

xpectra-study deep-ssl --route norm      # -> results/norm_deep_ssl_loso.csv
xpectra-study deep-ssl --route deriv1    # -> results/deriv1_deep_ssl_loso.csv

The classical sweeps (calibrate, loso, ood, ssl) evaluate all three routes at once and write a single file carrying a route column instead (see Preprocessing routes & the route-prefix convention).

Dependencies between workflows

Some workflows read another’s output:

contrastive trains the encoder and writes the cached embeddings that nb3-analysis, degradation, cluster-robustness, and nb4-analysis consume.
domain-distance reads the openspecy-loso, simple-redundancy, and awi-scaling results, so run those first.
nb2-figures / nb3-figures / nb4-figures read the corresponding *-analysis tables.

A typical full reproduction, in dependency order:

xpectra-process-raw
xpectra-study calibrate
xpectra-study loso
xpectra-study weathering
xpectra-study ood
xpectra-study ssl
xpectra-study batch-effect
xpectra-study openspecy-loso
xpectra-study data-scaling
xpectra-study simple-redundancy
xpectra-study awi-scaling
xpectra-study domain-distance
xpectra-study deep-ssl
xpectra-study dann
xpectra-study resnet
xpectra-nb2-corrected --force
xpectra-nb2-figures
xpectra-study contrastive
xpectra-nb3-analysis
xpectra-nb3-figures
xpectra-study cluster-robustness
xpectra-nb4-analysis
xpectra-nb4-figures
xpectra-study report

Reference datasets

The processed spectra combine four public core datasets plus three external reference libraries. Please cite the original sources if you use this data:

Core — Kedzierski et al. (2019); Jung et al. (2018); De Frond et al. (2021, SLoPP/SLoPP-E); Villegas-Camacho et al. (2024). External — Cowger et al. (2021, Open Specy); Primpke et al. (2018, siMPle); Primpke et al. (2024, AWI high-throughput).