Spectral Learning

Module: spectralbridge.spectral_learning.

Experimental leakage-safe learning primitives for the library analytics audit.

Requires the optional analytics extra. Nothing here is a stable top-level API or proof of ecological transfer. All model selection is confined to supplied proper training rows; outer/calibration memberships are explicit and testable.

API glossary · Workflow / scientific context

Signatures and documentation below are collected from the current source. Advanced objects are not newly declared stable by inclusion here.

Audience: advanced.

LearningConfig dataclass

LearningConfig(seed: int = 20261014, plant_folds: int = 3, minimum_train: int = 10, minimum_test: int = 3, calibration_fraction: float = 0.2, minimum_calibration: int = 25, bootstraps: int = 499, conformal_alpha: float = 0.1, inner_folds: int = 3)

Fixed experimental budgets; counts are identities, never source pixels.

Audience: advanced.

outer_folds

outer_folds(table, config=None)

Yield actual plant/site/year/flight masks with entire identities purged.

table requires label/site/year/GlobalID/flights. The existing readiness fold generator defines the seed/stratification. Unsupported folds are not omitted.

Audience: advanced.

calibration_split

calibration_split(identities, fraction=0.2, seed=20261014)

Uniformly reserve whole training identities, not stratified pixel rows.

Returns proper/calibration boolean masks. Caller checks class support before fitting. Labels never determine this split, and no outer-test data enter it.

Audience: advanced.

StableFSelector

StableFSelector(k='all')

Training-only F-rank coordinate selection with deterministic tie handling.

F is an exploratory ranking, not confirmatory wavelength significance. Selected coordinates retain their input spectral order. k='all' keeps all.

fit

fit(X, y)

transform

transform(X)

Audience: advanced.

PLSDA

PLSDA(n_components=4)

PLS regression on one-hot labels; argmax classification, raw softmax scores.

Raw score normalization is not assumed calibrated. No class reweighting is implicit in PLS. All preprocessing precedes this estimator in a fitted pipeline.

fit

fit(X, y)

predict_proba

predict_proba(X)

predict

predict(X)

Audience: advanced.

CentroidClassifier

Equal-class nearest mean baseline in its training-scaled input space.

fit

fit(X, y)

predict_proba

predict_proba(X)

predict

predict(X)

Audience: advanced.

model_pipeline

model_pipeline(name, *, k='all', seed=20261014)

Return an unfitted training-only pipeline and predeclared small inner grid.

Audience: advanced.

fit_training_model

fit_training_model(values, labels, identities, name, *, k='all', seed=20261014, inner_folds=3, tune=True, allow_repeated_identity_labels=False)

Fit only supplied proper-training data; inner splits use GlobalID groups.

Returns estimator plus choices/support/warnings. Caller separately validates that these rows exclude outer-test and calibration identities.

Audience: advanced.

probabilities

probabilities(model, X)

Model-order probabilities or explicitly uncalibrated normalized decisions.

SVM avoids its row-splitting internal probability calibration entirely.

Audience: advanced.

check_probabilities

check_probabilities(p)

Validate finite nonnegative (observations, classes) scores whose rows sum to one.

Audience: advanced.

temperature_probabilities

temperature_probabilities(p, temperature=1.0)

Apply a positive temperature to clipped log probabilities and renormalize with softmax.

Audience: advanced.

fit_temperature

fit_temperature(p, encoded_truth)

Fit one temperature using ONLY a separately reserved calibration sample.

Audience: advanced.

conformal_threshold

conformal_threshold(raw_calibration_p, encoded_truth, identities, alpha=0.1)

Finite-sample quantile of maximum RAW nonconformity per identity.

Scores must come from a predictor fitted independently of these labels. Do NOT pass temperature scores fitted on the same calibration labels. Geographic shift and nonexchangeable sampling do not gain a guarantee.

Audience: advanced.

conformal_metrics

conformal_metrics(raw_test_p, encoded_truth, identities, threshold)

Empirical row/whole-identity prediction-set coverage, not a shift guarantee.

Audience: advanced.

classification_metrics

classification_metrics(truth, p, classes, *, bins=10)

Balanced accuracy/macro F1 and calibration with explicit class order.

Brier = mean sum-class squared error (range 0–2). ECE is top-label, equal-width-bin absolute calibration error. No pixel independence assumed.

Audience: advanced.

cluster_bootstrap_accuracy

cluster_bootstrap_accuracy(truth, predicted, identities, classes, *, replicates=499, seed=20261014, stratify=True)

Stratified whole-identity balanced-accuracy draws for paired comparisons.

Identical ordered inputs/classes/seed give identical draws across sensors. Intervals condition on observed sites/classes, not a site superpopulation.

Audience: advanced.

class_prototypes

class_prototypes(values, labels, identities, *, method='medoid', count=1, seed=20261014)

Training-only empirical class representatives; never a purity certificate.

Supply one row per training identity in the chosen spectral metric. Mean and median are synthetic prototypes; medoid/diversity/cluster_medoid are observed rows. cluster_medoid is a KMeans-nearest-observation adaptation, not global PAM. Returns spectra, labels and source row positions (-1 for synthetic centers).

Audience: advanced.

fit_novelty_space

fit_novelty_space(training)

Training-only scaled PCA novelty scores; no Gaussian/outlier guarantee.

Audience: advanced.

novelty_scores

novelty_scores(values, training, space)

Nearest angle/distance and PCA radius/reconstruction residual.

All geometry comes from supplied proper training, not final/unknown targets. Distances are exploratory diagnostics calibrated on separate known identities.