nirs4all.controllers.models.stacking.multilevel module

Multi-Level Stacking Validator (Phase 7).

This module provides validation and level detection for multi-level stacking, where meta-models can use predictions from other meta-models as sources.

The validator ensures: 1. No circular dependencies exist in the stacking hierarchy 2. Stacking levels don’t exceed configured maximum 3. Level detection works correctly for AUTO mode 4. Source models from appropriate levels are selected

Stacking Hierarchy:

Level 0: Base models (PLS, RF, XGBoost, Neural Networks, etc.) Level 1: First meta-models (stack on Level 0 only) Level 2: Second meta-models (stack on Level 0 + Level 1) Level 3: Third meta-models (stack on Level 0 + Level 1 + Level 2)

Example

>>> validator = MultiLevelValidator(prediction_store)
>>> result = validator.validate_sources(
...     meta_model_name="FinalMeta",
...     source_candidates=candidates,
...     context=context
... )
>>> if not result.is_valid:
...     raise CircularDependencyError(...)

class nirs4all.controllers.models.stacking.multilevel.LevelValidationResult(is_valid: bool = True, detected_level: int = 1, source_levels: Dict[str, int]=<factory>, circular_dependencies: List[List[str]] = <factory>, warnings: List[str] = <factory>, errors: List[str] = <factory>)

Bases: object

Result of multi-level stacking validation.

is_valid

Whether the validation passed.

Type:

bool

detected_level

The detected stacking level for the meta-model.

Type:

int

source_levels

Dict mapping source model names to their levels.

Type:

Dict[str, int]

circular_dependencies

List of detected circular dependencies.

Type:

List[List[str]]

warnings

List of warning messages.

Type:

List[str]

errors

List of error messages.

Type:

List[str]

add_error(message: str) → None

Add an error and mark as invalid.

add_warning(message: str) → None

Add a warning message.

circular_dependencies: List[List[str]]

detected_level: int = 1

errors: List[str]

is_valid: bool = True

source_levels: Dict[str, int]

warnings: List[str]

class nirs4all.controllers.models.stacking.multilevel.ModelLevelInfo(model_name: str, level: int, is_meta_model: bool, source_models: List[str] = <factory>, step_idx: int = 0)

Bases: object

Information about a model’s stacking level.

model_name

Name of the model.

Type:

str

level

Stacking level (0 for base models, 1+ for meta-models).

Type:

int

is_meta_model

Whether this is a meta-model.

Type:

bool

source_models

List of source model names (for meta-models).

Type:

List[str]

step_idx

Pipeline step index.

Type:

int

is_meta_model: bool

level: int

model_name: str

source_models: List[str]

step_idx: int = 0

class nirs4all.controllers.models.stacking.multilevel.MultiLevelValidator(prediction_store: Predictions, max_level: int = 3, log_warnings: bool = True)

Bases: object

Validates multi-level stacking configurations.

Ensures that stacking hierarchies are valid, detects circular dependencies, and computes appropriate stacking levels for meta-models.

prediction_store

Predictions storage for analyzing model metadata.

max_level

Maximum allowed stacking level.

log_warnings

Whether to emit Python warnings.

META_MODEL_PATTERNS = {'MetaModel', 'StackingClassifier', 'StackingRegressor'}

clear_cache() → None

Clear the level info cache.

detect_level(source_candidates: List[ModelCandidate], context: ExecutionContext) → int

Detect the appropriate stacking level based on source models.

Parameters:

• source_candidates – List of candidate source models.

• context – Execution context.

Returns:

Detected stacking level (1 if no meta-model sources, 2+ otherwise).

filter_by_level(candidates: List[ModelCandidate], context: ExecutionContext, max_source_level: int | None = None, exclude_meta_models: bool = False) → List[ModelCandidate]

Filter source candidates by stacking level.

Parameters:

• candidates – List of candidate source models.

• context – Execution context.

• max_source_level – Maximum allowed source level (None = no limit).

• exclude_meta_models – If True, exclude all meta-models from sources.

Returns:

Filtered list of candidates.

get_all_levels(context: ExecutionContext) → Dict[str, int]

Get levels for all models in the prediction store.

Parameters:

context – Execution context.

Returns:

Dict mapping model names to their stacking levels.

validate_sources(meta_model_name: str, source_candidates: List[ModelCandidate], context: ExecutionContext, allow_meta_sources: bool = True) → LevelValidationResult

Validate source models for a meta-model.

Checks for circular dependencies and computes the appropriate stacking level based on source model levels.

Parameters:

• meta_model_name – Name of the meta-model being validated.

• source_candidates – List of candidate source models.

• context – Execution context.

• allow_meta_sources – Whether to allow other meta-models as sources.

Returns:

LevelValidationResult with validation status and detected level.

nirs4all.controllers.models.stacking.multilevel.detect_stacking_level(prediction_store: Predictions, source_candidates: List[ModelCandidate], context: ExecutionContext) → int

Convenience function for detecting stacking level.

Parameters:

• prediction_store – Predictions storage.

• source_candidates – List of candidate source models.

• context – Execution context.

Returns:

Detected stacking level.

nirs4all.controllers.models.stacking.multilevel.validate_multi_level_stacking(prediction_store: Predictions, meta_model_name: str, source_candidates: List[ModelCandidate], context: ExecutionContext, max_level: int = 3, allow_meta_sources: bool = True) → LevelValidationResult

Convenience function for validating multi-level stacking.

Parameters:

• prediction_store – Predictions storage.

• meta_model_name – Name of the meta-model.

• source_candidates – List of candidate source models.

• context – Execution context.

• max_level – Maximum allowed stacking level.

• allow_meta_sources – Whether to allow meta-model sources.

Returns:

LevelValidationResult with validation status.