nirs4all.controllers.models.stacking.exceptions module

Meta-Model Exceptions - Error classes for meta-model stacking.

This module provides specific exception classes for meta-model prediction and serialization errors.

Exception Hierarchy:

MetaModelError (base) ├── MetaModelPredictionError (prediction failures) │ ├── MissingSourceModelError (source model not found) │ ├── SourcePredictionError (source model prediction failed) │ ├── FeatureOrderMismatchError (column order doesn’t match) │ └── BranchMismatchError (branch context incompatible) └── MetaModelSerializationError (persistence failures)

└── MissingDependencyError (dependency not serialized)

exception nirs4all.controllers.models.stacking.exceptions.BranchFeatureAlignmentError(expected_features: int, branch_features: Dict[int, int], alignment_issues: List[str] | None = None)

Bases: CrossBranchStackingError

Raised when cross-branch features cannot be aligned.

This occurs when attempting to combine predictions from multiple branches but the feature matrices cannot be properly aligned due to different preprocessing or ordering.

expected_features

Expected number of features.

branch_features

Dict mapping branch_id to feature count.

alignment_issues

List of specific alignment problems.

exception nirs4all.controllers.models.stacking.exceptions.BranchMismatchError(training_branch: Dict[str, Any], prediction_branch: Dict[str, Any], meta_model_id: str)

Bases: MetaModelPredictionError

Raised when prediction branch doesn’t match training branch.

This occurs when attempting to use a meta-model trained in one branch for prediction in a different, incompatible branch context.

training_branch

Branch context during training.

prediction_branch

Branch context during prediction.

meta_model_id

The artifact ID of the meta-model.

exception nirs4all.controllers.models.stacking.exceptions.BranchingError(message: str, details: Dict[str, Any] | None = None)

Bases: MetaModelError

Base exception for branching-related errors in meta-model stacking.

exception nirs4all.controllers.models.stacking.exceptions.CircularDependencyError(source_model: str, meta_model: str, dependency_chain: List[str])

Bases: MultiLevelStackingError

Raised when circular dependencies are detected in multi-level stacking.

This occurs when a meta-model attempts to use itself or a model that depends on it as a source, creating a circular dependency.

source_model

Name of the source model causing the cycle.

meta_model

Name of the current meta-model.

dependency_chain

List of model names forming the cycle.

exception nirs4all.controllers.models.stacking.exceptions.CrossBranchStackingError(message: str, details: Dict[str, Any] | None = None)

Bases: BranchingError

Base exception for cross-branch stacking errors.

exception nirs4all.controllers.models.stacking.exceptions.CrossPartitionStackingError(partition_a: str, partition_b: str, n_samples_a: int, n_samples_b: int)

Bases: BranchingError

Raised when attempting cross-partition stacking with sample_partitioner.

Sample partitioner creates disjoint sample sets, making cross-partition stacking impossible without data leakage or sample misalignment.

partition_a

Name of first partition.

partition_b

Name of second partition.

n_samples_a

Number of samples in partition A.

n_samples_b

Number of samples in partition B.

exception nirs4all.controllers.models.stacking.exceptions.DisjointSampleSetsError(source_model: str, expected_samples: int, found_samples: int, overlap_ratio: float)

Bases: BranchingError

Raised when source models have disjoint sample sets.

This typically occurs with sample_partitioner where different branches have different samples, making OOF reconstruction impossible.

source_model

Name of the source model with disjoint samples.

expected_samples

Number of expected samples.

found_samples

Number of samples found in predictions.

overlap_ratio

Ratio of overlapping samples.

exception nirs4all.controllers.models.stacking.exceptions.FeatureOrderMismatchError(expected_columns: List[str], actual_columns: List[str], meta_model_id: str)

Bases: MetaModelPredictionError

Raised when feature columns don’t match expected order.

This occurs when the predictions from source models don’t align with the feature column order that was used during meta-model training.

expected_columns

Expected feature column names in order.

actual_columns

Actual feature column names found.

meta_model_id

The artifact ID of the meta-model.

exception nirs4all.controllers.models.stacking.exceptions.FoldMismatchAcrossBranchesError(fold_structures: Dict[int, int], affected_models: List[str])

Bases: BranchingError

Raised when source models from different branches have mismatched folds.

For stacking to work correctly, all source models must have compatible fold structures (same number of folds, same sample assignments per fold).

fold_structures

Dict mapping branch_id to fold count.

affected_models

List of affected model names.

exception nirs4all.controllers.models.stacking.exceptions.GeneratorSyntaxStackingWarning(generator_type: str, n_variants: int)

Bases: BranchingError

Raised as warning for generator syntax with stacking.

Generator syntax creates multiple model variants which may complicate stacking behavior. This is a warning, not a hard error.

generator_type

Type of generator used.

n_variants

Number of variants generated.

exception nirs4all.controllers.models.stacking.exceptions.IncompatibleBranchSamplesError(branches: Dict[int, int], overlap_matrix: Dict[tuple, float] | None = None)

Bases: CrossBranchStackingError

Raised when branches have incompatible sample sets for cross-branch stacking.

This occurs when attempting ALL_BRANCHES stacking with branches that have different sample indices (e.g., sample_partitioner branches).

branches

Dict mapping branch_id to sample counts.

overlap_matrix

Optional matrix showing sample overlap between branches.

exception nirs4all.controllers.models.stacking.exceptions.IncompatibleBranchTypeError(branch_type: str, reason: str, suggestions: List[str] | None = None)

Bases: BranchingError

Raised when stacking is attempted with incompatible branch type.

This occurs when the branch context is not suitable for stacking, such as attempting cross-partition stacking with sample_partitioner.

branch_type

Type of branching detected.

reason

Explanation of why stacking is incompatible.

suggestions

List of possible solutions.

exception nirs4all.controllers.models.stacking.exceptions.InconsistentLevelError(expected_levels: List[int], found_levels: Dict[str, int], problematic_models: List[str])

Bases: MultiLevelStackingError

Raised when source models have inconsistent stacking levels.

This occurs when a meta-model tries to use source models from incompatible levels, which could indicate a pipeline configuration issue.

expected_levels

Expected level(s) for source models.

found_levels

Actual levels found in source models.

problematic_models

Models with unexpected levels.

exception nirs4all.controllers.models.stacking.exceptions.InvalidMetaModelArtifactError(artifact_id: str, validation_errors: List[str])

Bases: MetaModelSerializationError

Raised when a meta-model artifact is invalid or corrupted.

This occurs when loading a meta-model artifact that doesn’t contain the required fields or has inconsistent data.

artifact_id

The artifact ID being loaded.

validation_errors

List of validation errors found.

exception nirs4all.controllers.models.stacking.exceptions.MaxStackingLevelExceededError(current_level: int, max_level: int, source_models: List[str] | None = None)

Bases: MultiLevelStackingError

Raised when the maximum stacking level is exceeded.

This occurs when attempting to create more stacking levels than allowed, which could lead to overfitting or excessive computational cost.

current_level

The level that was attempted.

max_level

The maximum allowed level.

source_models

Source models that caused the level increase.

exception nirs4all.controllers.models.stacking.exceptions.MetaModelError(message: str, details: Dict[str, Any] | None = None)

Bases: Exception

Base exception for meta-model errors.

All meta-model specific exceptions inherit from this class, allowing catch-all handling of meta-model issues.

message

Human-readable error description.

details

Optional dictionary with additional context.

exception nirs4all.controllers.models.stacking.exceptions.MetaModelPredictionError(message: str, details: Dict[str, Any] | None = None)

Bases: MetaModelError

Base exception for meta-model prediction errors.

Raised when prediction mode fails for a meta-model.

exception nirs4all.controllers.models.stacking.exceptions.MetaModelSerializationError(message: str, details: Dict[str, Any] | None = None)

Bases: MetaModelError

Base exception for meta-model serialization errors.

Raised when persistence or loading of meta-model artifacts fails.

exception nirs4all.controllers.models.stacking.exceptions.MissingDependencyError(dependency_id: str, meta_model_id: str, dependency_name: str | None = None)

Bases: MetaModelSerializationError

Raised when a dependency is not serialized.

This occurs when attempting to serialize a meta-model but one of its source model dependencies hasn’t been persisted yet.

dependency_id

The artifact ID of the missing dependency.

meta_model_id

The artifact ID of the meta-model.

dependency_name

Optional name of the missing dependency.

exception nirs4all.controllers.models.stacking.exceptions.MissingSourceModelError(source_model_id: str, meta_model_id: str, all_missing: List[str] | None = None)

Bases: MetaModelPredictionError

Raised when a source model binary is not found.

This occurs when trying to load a meta-model for prediction but one or more of its source model dependencies cannot be found in the artifact store.

source_model_id

The artifact ID of the missing source model.

meta_model_id

The artifact ID of the meta-model.

all_missing

List of all missing source model IDs (if multiple).

exception nirs4all.controllers.models.stacking.exceptions.MultiLevelStackingError(message: str, details: Dict[str, Any] | None = None)

Bases: MetaModelError

Base exception for multi-level stacking errors.

exception nirs4all.controllers.models.stacking.exceptions.NestedBranchStackingError(branch_depth: int, branch_path: List[int], reason: str)

Bases: BranchingError

Raised when stacking is attempted with complex nested branching.

Complex nested branching scenarios may not be fully supported in meta-model stacking due to sample alignment challenges.

branch_depth

Depth of nesting.

branch_path

Full path of branch IDs.

reason

Explanation of the issue.

exception nirs4all.controllers.models.stacking.exceptions.NoSourcePredictionsError(expected_sources: List[str], meta_model_id: str)

Bases: MetaModelPredictionError

Raised when no source model predictions are available.

This occurs when the prediction store doesn’t contain any predictions from source models, making it impossible to construct meta-features.

expected_sources

List of expected source model names.

meta_model_id

The artifact ID of the meta-model.

exception nirs4all.controllers.models.stacking.exceptions.SourcePredictionError(source_model_id: str, source_model_name: str, original_error: Exception | None = None)

Bases: MetaModelPredictionError

Raised when a source model fails to produce predictions.

This occurs when a source model is loaded successfully but fails during prediction, preventing the meta-model from constructing its input features.

source_model_id

The artifact ID of the failing source model.

source_model_name

The name of the failing source model.

original_error

The underlying exception that caused the failure.