nirs4all.controllers.splitters.split module

class nirs4all.controllers.splitters.split.CrossValidatorController

Bases: OperatorController

Controller for any sklearn‑compatible splitter (native or custom).

execute(step_info: ParsedStep, dataset: SpectroDataset, context: ExecutionContext, runtime_context: RuntimeContext, source: int = -1, mode: str = 'train', loaded_binaries: Any = None, prediction_store: Any = None)

Run operator.split and store the resulting folds on dataset.

• Smartly supplies y / groups only if required.

• Extracts groups from metadata if specified.

• Supports group_by parameter and dataset repetition for group-aware splitting.

• Maps local indices back to the global index space.

• Stores the list of folds into the dataset for subsequent steps.

Parameters:

• step_info (ParsedStep) – Parsed step containing the operator and original step configuration.

• dataset (SpectroDataset) – The dataset to split.

• context (ExecutionContext) – Current execution context.

• runtime_context (RuntimeContext) – Runtime context with global settings.

• source (int) – Source index (-1 for combined sources).

• mode (str) – Execution mode (“train”, “predict”, or “explain”).

• loaded_binaries (Any) – Pre-loaded binary data (not used).

• prediction_store (Any) – Store for predictions (not used).

classmethod matches(step: Any, operator: Any, keyword: str) → bool

Return True if operator behaves like a splitter.

Criteria – must expose a callable split whose first positional argument is named X. Optional presence of get_n_splits is a plus but not mandatory, so user‑defined simple splitters are still accepted.

Also matches on the ‘split’ keyword for group-aware splitting syntax.

priority: int = 10

classmethod supports_prediction_mode() → bool

Cross-validators should not execute during prediction mode.

classmethod use_multi_source() → bool

Cross‑validators themselves are single‑source operators.

class nirs4all.controllers.splitters.split.ResolvedSplitGroups(capability: 'SplitGroupingCapability', group_by: 'str | list[str] | None', effective_groups: 'np.ndarray | None', uses_repetition: 'bool', uses_group_by: 'bool', satisfied_by_repetition_only: 'bool')

Bases: object

capability: SplitGroupingCapability

effective_groups: ndarray | None

group_by: str | list[str] | None

property requires_wrapper: bool

satisfied_by_repetition_only: bool

uses_group_by: bool

uses_repetition: bool

class nirs4all.controllers.splitters.split.SplitGroupingCapability(group_required: 'bool', group_handling: 'SplitGroupHandling')

Bases: object

group_handling: Literal['native', 'wrapper']

group_required: bool

nirs4all.controllers.splitters.split.compute_effective_groups(dataset: SpectroDataset, group_by: str | list[str] | None = None, ignore_repetition: bool = False, context: Any | None = None, include_augmented: bool = False) → np.ndarray | None

Compute final group labels for splitting.

Applies repetition and explicit group_by columns as split constraints. When both are present, the effective groups are the connected components induced by: - same repetition value - same explicit group_by value (or tuple of values for multi-column

group_by)

This is stricter than a plain tuple of (repetition, group_by) because it guarantees that raw group_by values cannot leak across folds when the dataset repetition column is also enforced.

Parameters:

• dataset (SpectroDataset) – The dataset containing metadata columns for grouping.

• group_by (str or List[str], optional) – Additional column(s) to group by. Combined with repetition column if repetition is defined and not ignored.

• ignore_repetition (bool, default=False) – If True, ignore the dataset’s repetition column and only use group_by columns for grouping. Use for specific experiments where you want to split within repetitions.

• context (Any, optional) – Execution context for selecting samples (e.g., partition filter). If None, uses all samples.

• include_augmented (bool, default=False) – If True, include augmented samples. Typically False for splitting to avoid data leakage.

Returns:

Array of group labels (one per sample), or None if no grouping needed. - For single column: array of column values - For multi-column explicit group_by without repetition:

array of tuples (e.g., (Site, Year))

• For repetition + explicit group_by: connected-component labels enforcing both constraints

Return type:

np.ndarray or None

Examples

>>> # Repetition only (auto from dataset)
>>> groups = compute_effective_groups(dataset)
>>> # groups = ['S1', 'S1', 'S2', 'S2', ...]

>>> # Repetition + additional grouping
>>> groups = compute_effective_groups(dataset, group_by=['Year'])
>>> # groups = connected-component labels enforcing both sample_id and Year

>>> # Explicit grouping without repetition
>>> groups = compute_effective_groups(dataset, group_by='Batch', ignore_repetition=True)
>>> # groups = ['B1', 'B1', 'B2', 'B2', ...]

nirs4all.controllers.splitters.split.get_split_grouping_capability(splitter: Any) → SplitGroupingCapability

Return how a splitter consumes effective groups.