nirs4all.synthesis.reconstruction.calibration module

Prototype-based global calibration for instrument parameters.

This module implements global parameter estimation using representative prototype spectra (median + quantiles + k-medoids).

class nirs4all.synthesis.reconstruction.calibration.CalibrationResult(wl_shift: float = 0.0, wl_stretch: float = 1.0, ils_sigma: float = 4.0, stray_light: float = 0.0, gain: float = 1.0, offset: float = 0.0, prototype_residuals: ndarray | None = None, prototype_r2: ndarray | None = None, total_loss: float = inf)[source]

Bases: object

Result of global calibration.

wl_shift

Calibrated wavelength shift.

Type:: float

wl_stretch

Calibrated wavelength stretch.

Type:: float

ils_sigma

Calibrated ILS width.

Type:: float

stray_light

Calibrated stray light fraction.

Type:: float

gain

Calibrated photometric gain.

Type:: float

offset

Calibrated photometric offset.

Type:: float

prototype_residuals

Residuals for each prototype.

Type:: numpy.ndarray | None

prototype_r2

R² for each prototype.

Type:: numpy.ndarray | None

total_loss

Total calibration loss.

Type:: float

classmethod from_array(params: ndarray) → CalibrationResult[source]: Create from parameter array [wl_shift, wl_stretch, ils_sigma].

gain: float = 1.0

ils_sigma: float = 4.0

offset: float = 0.0

prototype_r2: ndarray | None = None

prototype_residuals: ndarray | None = None

stray_light: float = 0.0

to_dict() → Dict[str, float][source]: Convert to parameter dictionary.

total_loss: float = inf

wl_shift: float = 0.0

wl_stretch: float = 1.0

class nirs4all.synthesis.reconstruction.calibration.GlobalCalibrator(wl_shift_bounds: Tuple[float, float] = (-10.0, 10.0), wl_stretch_bounds: Tuple[float, float] = (0.98, 1.02), ils_sigma_bounds: Tuple[float, float] = (2.0, 20.0), regularization: float = 1e-06, use_global_search: bool = False)[source]

Bases: object

Calibrate global instrument parameters using prototype spectra.

Optimizes θ_global = {wl_shift, wl_stretch, ils_sigma} to minimize total fitting loss across all prototypes, with per-prototype linear parameters solved via NNLS.

forward_chain: ForwardChain for computing model predictions.

wl_shift_bounds

Bounds for wavelength shift.

Type:: Tuple[float, float]

wl_stretch_bounds

Bounds for wavelength stretch.

Type:: Tuple[float, float]

ils_sigma_bounds

Bounds for ILS sigma.

Type:: Tuple[float, float]

regularization

L2 regularization strength.

Type:: float

use_global_search

Use differential evolution for global search.

Type:: bool

calibrate(prototypes: np.ndarray, forward_chain: ForwardChain, initial_guess: np.ndarray | None = None) → CalibrationResult[source]

Calibrate global parameters on prototype spectra.

Parameters:

prototypes – Prototype spectra (n_prototypes, n_wavelengths).
forward_chain – Forward chain for model evaluation.
initial_guess – Initial [wl_shift, wl_stretch, ils_sigma].

Returns:

CalibrationResult with optimized parameters.

ils_sigma_bounds: Tuple[float, float] = (2.0, 20.0)

refine(current_result: CalibrationResult, prototypes: np.ndarray, forward_chain: ForwardChain) → CalibrationResult[source]

Refine calibration with tighter bounds around current estimate.

Parameters:

current_result – Current calibration result.
prototypes – Prototype spectra.
forward_chain – Forward chain.

Returns:

Refined CalibrationResult.

regularization: float = 1e-06

use_global_search: bool = False

wl_shift_bounds: Tuple[float, float] = (-10.0, 10.0)

wl_stretch_bounds: Tuple[float, float] = (0.98, 1.02)

class nirs4all.synthesis.reconstruction.calibration.PrototypeSelector(n_prototypes: int = 5, include_median: bool = True, include_quantiles: bool = True, pca_components: int = 5)[source]

Bases: object

Select representative prototype spectra from a dataset.

Uses multiple strategies to ensure robust global calibration: 1. Median spectrum (robust central tendency) 2. Quantile spectra (25%, 75% in PC1) 3. K-medoids in PCA space (capture diversity)

n_prototypes

Number of prototypes to select.

Type:: int

include_median

Always include median spectrum.

Type:: bool

include_quantiles

Include quantile spectra.

Type:: bool

pca_components

Number of PCA components for clustering.

Type:: int

include_median: bool = True

include_quantiles: bool = True

n_prototypes: int = 5

pca_components: int = 5

select(X: ndarray) → Tuple[ndarray, ndarray][source]

Select prototype spectra.

Parameters:: X – Spectra matrix (n_samples, n_wavelengths).
Returns:: Tuple of (prototype_spectra, prototype_indices).

nirs4all.synthesis.reconstruction.calibration.multistage_calibration(X: np.ndarray, forward_chain: ForwardChain, n_prototypes: int = 5, stages: int = 2) → CalibrationResult[source]

Multi-stage calibration with progressive refinement.

Stage 1: Coarse calibration on smoothed prototypes Stage 2: Fine calibration on original prototypes

Parameters:

X – Full dataset (n_samples, n_wavelengths).
forward_chain – Forward chain for model evaluation.
n_prototypes – Number of prototypes to select.
stages – Number of refinement stages.

Returns:

Final CalibrationResult.