Mixtures

Module: spectralbridge.mixtures.

Experimental, exact small convex mixture models and audited library selection.

No operational abundance claim or stable top-level API. Model spectra and targets must share explicit support and one common scale; never normalize each separately.

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.

model_indices

model_indices(labels, max_components=3, maximum_models=20000)

Enumerate distinct-class candidate sets, including every simplex face.

Audience: advanced.

fit_models

fit_models(targets, labels, endmembers, *, max_components=3, tolerance=0.01, maximum_models=20000, chunk_models=128)

Exact active-face search, not unconstrained fractions clipped afterwards.

Interior affine least squares is admitted only inside its simplex. Every boundary face appears explicitly. Singular interiors are skipped; their convex hull remains covered by affinely independent lower-dimensional faces. Near-composition counts count distinct CLASS sets, not redundant candidates.

Audience: advanced.

fcls

fcls(targets, endmembers) -> dict

Exactly fit a small fixed library under nonnegative sum-one constraints.

Parameters:

Name	Type	Description	Default
targets	array - like	Finite spectra (N, B), B >= 2, in common units.	required
endmembers	array - like	Finite candidate spectra (M, B), 1 <= M <= 12.	required

Returns:

Name	Type	Description
dict	dict	Fractions (N, M), RMSE/reconstructions, angle and ambiguity details from fit_models. Fractions are dimensionless; RMSE retains input units.

Raises:

Type	Description
ValueError	Nonfinite/inconsistent matrices or oversized library.

Experimental numerical utility, not an ecological abundance validation. Every feasible face is considered at declared numerical rank tolerances; degenerate/near-collinear candidates can leave fractions nonidentifiable.

Audience: advanced.

shade_model_errors

shade_model_errors(targets, candidates)

RMSE(target, fcandidate+(1-f)0), 0<=f<=1; rows target, cols candidate.

Audience: advanced.

selection_scores

selection_scores(spectra, labels)

Published EAR and MASA within-class means excluding self.

Audience: advanced.

select_endmembers

select_endmembers(spectra, labels, method, count_per_class, *, seed=20261014, threshold=0.02)

Training-only selections. IES budget is global count_per_class x classes.

CoB may stop early once all training spectra are covered. Ranking EAR/MASA beyond their minimum and capped IES/hybrid are explicitly size adaptations.

Audience: advanced.

grouped_identity_split

grouped_identity_split(identities, test_rows)

Purge every held-out identity from training while preserving the supplied test-row mask.

Audience: advanced.

mixture_truth

mixture_truth(spectra, labels, *, pairs_per_composition=2, seed=20261014, include_triples=True)

Generate linear mixtures ONLY from a caller-provided held-out source set.

Audience: advanced.

validate_holdout

validate_holdout(identities, train, test, selected=None) -> None

Reject identity leakage or endmembers selected outside a training fold.

Parameters:

Name	Type	Description	Default
identities	array - like	Nonmissing identity vector, shape (N,).	required
train	array - like	Boolean training mask, shape (N,).	required
test	array - like	Boolean test mask, shape (N,). Unused rows are allowed.	required
selected	array - like	Integer candidate indices into these N rows.	None

Raises:

Type	Description
ValueError	Shapes/identities are invalid, identities cross folds, or a selected index is not a training row. Split by site/flight first; this guard then purges/checks the complete identity history.

Audience: advanced.

adequacy_status

adequacy_status(residuals, threshold) -> np.ndarray

Experimental residual adequacy labels; never certify material membership.

Parameters:

Name	Type	Description	Default
residuals	array - like	Finite nonnegative RMSE values in the same units as threshold; arbitrary shape.	required
threshold	float	Nonnegative training-only adequacy bound. NaN means unassessed; infinity and negative bounds are invalid.	required

Returns:

Type	Description
ndarray	numpy.ndarray: Same-shape string labels. Low residual is explicitly unvalidated membership, even when an unknown material fits exactly.

Raises:

Type	Description
ValueError	Invalid residuals or threshold. No data are clipped.

Audience: advanced.

detection_metrics

detection_metrics(truth, estimated, *, threshold=0.1) -> dict

Conditional fraction-detection counts; true presence means truth > 0.

Parameters:

Name	Type	Description	Default
truth	array - like	Finite fractions in [0, 1], shape (N,) or (N, C).	required
estimated	array - like	Same-shape finite fractions in [0, 1].	required
threshold	float	Detection cutoff in (0, 1], inclusive within 1e-10, matching the readiness workflow's detection-curve rule.	0.1

Returns:

Name	Type	Description
dict	dict	TP, FP, TN, FN, N and false-positive/negative rates across supplied entries. A rate with no eligible denominator is NaN. These conditional observations do not define population detection limits. Truth >= 0.1 class-set error in the readiness audit is a separate estimand.

Raises:

Type	Description
ValueError	Shape, range or nonfinite inputs are invalid.