xpectra.ood

Out-of-distribution scoring and abstention.

Convention: every scorer returns a 1-D array where HIGHER = more OOD.

Functions

add_noise(X, sigma, rng)
baseline_drift(X, magnitude, rng)
block_scramble(X, n_blocks, rng)	Shuffle contiguous wavenumber blocks: destroys band structure, keeps the overall intensity distribution.

Classes

AbstainingClassifier(model, scorer)	Predict a class when the OOD score is below tau, otherwise abstain.
Energy()	Negative log-sum-exp of logits (log-proba fallback for CV-calibrated models).
Entropy()	Normalized Shannon entropy of the predictive distribution.
KNNDistance([k, n_components, random_state])	Distance to the k-th nearest training sample in PCA space.
Mahalanobis([n_components, random_state])	Min per-class Mahalanobis distance in PCA space (shared LW covariance).
MaxSoftmax()	1 - max predicted probability.
OODScorer()
SpectralAngleScorer()	Min spectral angle to the class-mean spectra (norm route only).

class xpectra.ood.OODScorer

Bases: ABC

name: str = 'ood'

abstractmethod fit(X, y=None, model=None)

Parameters:

• X (ndarray)

• y (ndarray | None)

Return type:

OODScorer

abstractmethod score(X, model=None)

Parameters:

X (ndarray)

Return type:

ndarray

class xpectra.ood.MaxSoftmax

Bases: OODScorer

1 - max predicted probability.

name: str = 'max_softmax'

fit(X, y=None, model=None)

score(X, model=None)

class xpectra.ood.Entropy

Bases: OODScorer

Normalized Shannon entropy of the predictive distribution.

name: str = 'entropy'

fit(X, y=None, model=None)

score(X, model=None)

class xpectra.ood.Energy

Bases: OODScorer

Negative log-sum-exp of logits (log-proba fallback for CV-calibrated models).

name: str = 'energy'

fit(X, y=None, model=None)

score(X, model=None)

class xpectra.ood.Mahalanobis(n_components=20, random_state=42)

Bases: OODScorer

Min per-class Mahalanobis distance in PCA space (shared LW covariance).

Parameters:

• n_components (int)

• random_state (int)

name: str = 'mahalanobis'

fit(X, y=None, model=None)

score(X, model=None)

class xpectra.ood.KNNDistance(k=5, n_components=20, random_state=42)

Bases: OODScorer

Distance to the k-th nearest training sample in PCA space.

Parameters:

• k (int)

• n_components (int)

• random_state (int)

name: str = 'knn'

fit(X, y=None, model=None)

score(X, model=None)

class xpectra.ood.SpectralAngleScorer

Bases: OODScorer

Min spectral angle to the class-mean spectra (norm route only).

name: str = 'spectral_angle'

fit(X, y=None, model=None)

score(X, model=None)

class xpectra.ood.AbstainingClassifier(model, scorer)

Bases: object

Predict a class when the OOD score is below tau, otherwise abstain.

Parameters:

scorer (OODScorer)

ABSTAIN = 'ABSTAIN'

tau_: float | None

fit_tau(X_val, target_coverage=0.9)

Set tau so that target_coverage of X_val falls below it.

X_val must be a HELD-OUT labeled set that neither the model nor the scorer was trained on — calibrating on in-sample data yields optimistic scores and a threshold too tight to hit the target coverage on new data.

Parameters:

• X_val (ndarray)

• target_coverage (float)

Return type:

AbstainingClassifier

achieved_coverage(X)

Fraction of X that would be classified (not abstained) at the current tau.

Parameters:

X (ndarray)

Return type:

float

predict(X, class_names)

Parameters:

• X (ndarray)

• class_names (list[str])

Return type:

tuple[ndarray, ndarray]

xpectra.ood.add_noise(X, sigma, rng)

Parameters:

• X (ndarray)

• sigma (float)

• rng (Generator)

Return type:

ndarray

xpectra.ood.baseline_drift(X, magnitude, rng)

Parameters:

• X (ndarray)

• magnitude (float)

• rng (Generator)

Return type:

ndarray

xpectra.ood.block_scramble(X, n_blocks, rng)

Shuffle contiguous wavenumber blocks: destroys band structure, keeps the overall intensity distribution.

Parameters:

• X (ndarray)

• n_blocks (int)

• rng (Generator)

Return type:

ndarray