nirs4all.controllers.models.stacking.reconstructor module

Training Set Reconstructor for Meta-Model Stacking.

This module provides the TrainingSetReconstructor class that builds meta-model training features from out-of-fold (OOF) predictions of source models.

The key principle is that each training sample’s meta-feature comes from a fold where that sample was NOT used for training, preventing data leakage.

Classes:

TrainingSetReconstructor: Main class for OOF reconstruction. FoldAlignmentValidator: Validates fold structure consistency. ValidationResult: Container for validation errors and warnings. ReconstructionResult: Container for reconstructed data.

class nirs4all.controllers.models.stacking.reconstructor.FoldAlignmentValidator(prediction_store: Predictions, config: ReconstructorConfig | None = None)

Bases: object

Validates fold structure consistency across source models.

Ensures that all source models have compatible fold structures for proper out-of-fold reconstruction.

Checks performed: 1. All models have the same number of folds. 2. Fold indices are sequential (0, 1, 2, …, K-1). 3. No sample appears in multiple validation sets within a model. 4. Sample indices are consistent across folds.

Variables:

• prediction_store – Predictions storage for accessing fold data.

• config – Reconstructor configuration.

validate(source_model_names: list[str], context: ExecutionContext, branch_id_override: int | None = -1) → ValidationResult

Validate fold alignment across source models.

Parameters:

• source_model_names – List of source model names to validate.

• context – Execution context with branch info.

• branch_id_override – Optional branch_id override. If -1 (default), use context’s branch_id. If None, don’t filter by branch (for ALL_BRANCHES scope).

Returns:

ValidationResult with any errors or warnings.

class nirs4all.controllers.models.stacking.reconstructor.ValidationError(code: str, message: str, details: dict[str, Any] | None = None)

Bases: object

A single validation error.

code: str

details: dict[str, Any] | None = None

message: str

class nirs4all.controllers.models.stacking.reconstructor.ValidationResult(errors: list[ValidationError] = <factory>, warnings: list[ValidationWarning] = <factory>)

Bases: object

Container for validation errors and warnings.

Accumulates validation issues during fold alignment and coverage checks.

Variables:

• errors (list[nirs4all.controllers.models.stacking.reconstructor.ValidationError]) – List of validation errors (critical issues).

• warnings (list[nirs4all.controllers.models.stacking.reconstructor.ValidationWarning]) – List of validation warnings (non-critical issues).

• is_valid – True if no errors (warnings are allowed).

Example

>>> result = ValidationResult()
>>> result.add_error("FOLD_MISMATCH", "Folds don't align")
>>> result.add_warning("PARTIAL_COVERAGE", "80% coverage")
>>> if not result.is_valid:
...     raise ValueError(result.format_errors())

add_error(code: str, message: str, details: dict[str, Any] | None = None) → None

Add a validation error.

add_warning(code: str, message: str, details: dict[str, Any] | None = None) → None

Add a validation warning.

errors: list[ValidationError]

format_errors() → str

Format all errors as a human-readable string.

format_warnings() → str

Format all warnings as a human-readable string.

property is_valid: bool

Check if validation passed (no errors).

merge(other: ValidationResult) → None

Merge another validation result into this one.

warnings: list[ValidationWarning]

class nirs4all.controllers.models.stacking.reconstructor.ValidationWarning(code: str, message: str, details: dict[str, Any] | None = None)

Bases: object

A single validation warning.

code: str

details: dict[str, Any] | None = None

message: str