nirs4all.synthesis.reconstruction.validation module

Validation and diagnostics for reconstruction quality.

Provides tools to evaluate: 1. Reconstruction quality (residual analysis) 2. Synthetic vs real data comparison (PCA, statistics) 3. Parameter plausibility checks

class nirs4all.synthesis.reconstruction.validation.ReconstructionValidator(r2_threshold: float = 0.9, residual_autocorr_threshold: float = 0.3, pca_distance_threshold: float = 3.0, concentration_max: float = 10.0, path_length_bounds: Tuple[float, float] = (0.3, 3.0))

Bases: object

Validate reconstruction quality and synthetic realism.

Checks: 1. Residuals should be structureless (no systematic patterns) 2. Synthetic should match real in PCA space 3. Per-wavelength statistics should be similar 4. Parameters should be physically plausible

r2_threshold

Minimum acceptable R² for reconstruction.

Type:

float

residual_autocorr_threshold

Max autocorrelation in residuals.

Type:

float

pca_distance_threshold

Max Mahalanobis distance in PCA space.

Type:

float

concentration_max

Max plausible concentration value.

Type:

float

concentration_max: float = 10.0

path_length_bounds: Tuple[float, float] = (0.3, 3.0)

pca_distance_threshold: float = 3.0

r2_threshold: float = 0.9

residual_autocorr_threshold: float = 0.3

validate(inversion_results: List['InversionResult'], X_real: np.ndarray, X_synth: np.ndarray) → ValidationResult

Run full validation.

Parameters:

• inversion_results – Inversion results.

• X_real – Real data.

• X_synth – Synthetic data.

Returns:

ValidationResult.

validate_parameters(inversion_results: List['InversionResult']) → Dict[str, Any]

Validate parameter plausibility.

Parameters:

inversion_results – List of inversion results.

Returns:

Dict of parameter metrics.

validate_reconstruction(inversion_results: List['InversionResult']) → Dict[str, Any]

Validate reconstruction quality.

Parameters:

inversion_results – List of inversion results.

Returns:

Dict of reconstruction metrics.

validate_synthetic(X_real: ndarray, X_synth: ndarray) → Dict[str, Any]

Validate synthetic vs real data.

Parameters:

• X_real – Real data matrix.

• X_synth – Synthetic data matrix.

Returns:

Dict of comparison metrics.

class nirs4all.synthesis.reconstruction.validation.ValidationResult(reconstruction_metrics: Dict[str, ~typing.Any]=<factory>, synthetic_metrics: Dict[str, ~typing.Any]=<factory>, parameter_metrics: Dict[str, ~typing.Any]=<factory>, overall_score: float = 0.0, passed: bool = False, warnings: List[str] = <factory>)

Bases: object

Result of reconstruction validation.

reconstruction_metrics

Per-sample reconstruction quality.

Type:

Dict[str, Any]

synthetic_metrics

Synthetic vs real comparison metrics.

Type:

Dict[str, Any]

parameter_metrics

Parameter plausibility metrics.

Type:

Dict[str, Any]

overall_score

Combined quality score (0-100).

Type:

float

passed

Whether all quality checks passed.

Type:

bool

warnings

List of warning messages.

Type:

List[str]

overall_score: float = 0.0

parameter_metrics: Dict[str, Any]

passed: bool = False

reconstruction_metrics: Dict[str, Any]

summary() → str

Generate human-readable summary.

synthetic_metrics: Dict[str, Any]

warnings: List[str]

nirs4all.synthesis.reconstruction.validation.compute_diagnostic_data(X_real: np.ndarray, X_synth: np.ndarray, inversion_results: List['InversionResult'] | None = None, wavelengths: np.ndarray | None = None) → Dict[str, Any]

Compute data for diagnostic plots.

Parameters:

• X_real – Real data.

• X_synth – Synthetic data.

• inversion_results – Optional inversion results for residuals.

• wavelengths – Wavelength grid.

Returns:

Dict of diagnostic data arrays.