nirs4all.controllers.data.branch_utils module

Branch utilities for value mapping and condition parsing.

This module provides utilities for parsing user-friendly value conditions into callable predicates for branch separation logic.

Supported condition formats:

• Boolean: True, False

• List: [“a”, “b”, “c”] (value in list)

• Comparison strings: “> 0.8”, “>=10”, “< 50”, “<=100”, “== 5”, “!= 3”

• Range strings: “0..50”, “50..”, “..50” (inclusive on both ends)

• Lambda/callable: lambda x: x > 0.8

Example usage:

>>> from nirs4all.controllers.data.branch_utils import parse_value_condition
>>> pred = parse_value_condition("> 0.8")
>>> pred(0.9)  # True
>>> pred(0.5)  # False
>>> pred = parse_value_condition("0..50")
>>> pred(25)   # True
>>> pred(75)   # False

nirs4all.controllers.data.branch_utils.group_samples_by_value_mapping(values: List[Any], value_mapping: Dict[str, Any]) → Dict[str, List[int]]

Group sample indices by value mapping conditions.

Given a list of values and a mapping of branch names to conditions, returns a dict mapping branch names to lists of sample indices.

Parameters:

• values – List of values (one per sample).

• value_mapping – Dict mapping branch names to conditions. Each condition is parsed via parse_value_condition().

Returns:

Dict mapping branch names to lists of sample indices.

Raises:

ValueError – If samples appear in multiple branches (overlapping conditions).

Example

>>> values = [0.2, 0.5, 0.8, 0.9, 0.3]
>>> mapping = {"low": "< 0.5", "high": ">= 0.5"}
>>> group_samples_by_value_mapping(values, mapping)
{'low': [0, 4], 'high': [1, 2, 3]}

nirs4all.controllers.data.branch_utils.parse_value_condition(condition: Any) → Callable[[Any], bool]

Parse user-friendly value conditions into callable predicates.

Parameters:

condition – The condition to parse. Supported formats: - callable: Used directly - bool: Equality check (x == condition) - list/tuple/set: Membership check (x in condition) - str: Parsed as comparison or range (see _parse_string_condition) - int/float: Equality check (x == condition)

Returns:

A callable that takes a single value and returns bool.

Raises:

ValueError – If condition format is not recognized.

Examples

>>> parse_value_condition(True)(True)
True
>>> parse_value_condition([1, 2, 3])(2)
True
>>> parse_value_condition("> 0.5")(0.8)
True
>>> parse_value_condition("10..20")(15)
True

nirs4all.controllers.data.branch_utils.validate_disjoint_conditions(value_mapping: Dict[str, Any], sample_values: List[Any] | None = None) → bool

Validate that value mapping conditions are disjoint.

This is a best-effort check. For complex conditions (lambdas), it will only detect overlaps when sample_values is provided.

Parameters:

• value_mapping – Dict mapping branch names to conditions.

• sample_values – Optional sample values to test against.

Returns:

True if conditions appear disjoint, False if overlap detected.

Raises:

ValueError – If obvious overlap is detected.