nicetoolbox.evaluation.data.input_loader

Functions

align_arrays	Pair predictions with ground truth arrays and align their axes.
get_meta_type	Extract the shared NpzMeta type from a list of arrays.
get_npz_files	Resolve an InputBlock to the concrete NPZ file paths it refers to.
load_array	Load one NPZ entry, read axis labels from data_description, and apply filters.
load_experiment_config	Load the latest saved detector experiment config from an experiment folder.
load_input	Load and prepare all arrays for a given input block.
matches_filter	Match a discovered dimension value against an InputBlock filter.

Classes

AnnotationMeta
ArrayAxes
ExperimentMeta
LoadedArray
NpzMeta	Abstract base for all NPZ metadata types.
PathMeta
SubsequenceInfo

class nicetoolbox.evaluation.data.input_loader.AnnotationMeta(npz_path: pathlib.Path, npz_key: str, dataset: str, session: str, sequence: str, component: str)

align_key() → tuple

Return the key used to pair this array with its counterpart during alignment.

classmethod always_iterate() → frozenset[str]

Return columns that must always get their own row in summaries (never pooled).

static comparable_dim() → str | None

Return the dimension used to compare results side-by-side (e.g. as series/color in charts).

to_dict() → dict[str, Any]

Return user-facing metadata fields as a flat dict.

class nicetoolbox.evaluation.data.input_loader.ArrayAxes(subjects: list[str], cameras: list[str], frames: list[str], labels: list[str], data: list[str] = <factory>)

class nicetoolbox.evaluation.data.input_loader.ExperimentMeta(npz_path: pathlib.Path, npz_key: str, dataset: str, session: str, sequence: str, component: str, algorithm: str, fps: int, subsequence: nicetoolbox.evaluation.data.input_loader.SubsequenceInfo)

align_key() → tuple

Return the key used to pair this array with its counterpart during alignment.

classmethod always_iterate() → frozenset[str]

Return columns that must always get their own row in summaries (never pooled).

static comparable_dim() → str | None

Return the dimension used to compare results side-by-side (e.g. as series/color in charts).

to_dict() → dict[str, Any]

Return user-facing metadata fields as a flat dict.

class nicetoolbox.evaluation.data.input_loader.LoadedArray(meta: nicetoolbox.evaluation.data.input_loader.NpzMeta, data: numpy.ndarray, axes: nicetoolbox.evaluation.data.input_loader.ArrayAxes)

class nicetoolbox.evaluation.data.input_loader.NpzMeta(npz_path: Path, npz_key: str)

Abstract base for all NPZ metadata types.

align_key() → tuple | None

Return the key used to pair this array with its counterpart during alignment.

abstract static always_iterate() → frozenset[str]

Return columns that must always get their own row in summaries (never pooled).

abstract static comparable_dim() → str | None

Return the dimension used to compare results side-by-side (e.g. as series/color in charts).

abstract to_dict() → dict[str, Any]

Return user-facing metadata fields as a flat dict.

class nicetoolbox.evaluation.data.input_loader.PathMeta(npz_path: pathlib.Path, npz_key: str)

classmethod always_iterate() → frozenset[str]

Return columns that must always get their own row in summaries (never pooled).

static comparable_dim() → str | None

Return the dimension used to compare results side-by-side (e.g. as series/color in charts).

to_dict() → dict[str, Any]

Return user-facing metadata fields as a flat dict.

class nicetoolbox.evaluation.data.input_loader.SubsequenceInfo(subsequence_index: int, video_start: int | str, video_length: int | str)

nicetoolbox.evaluation.data.input_loader.align_arrays(predictions: list[nicetoolbox.evaluation.data.input_loader.LoadedArray], ground_truth: list[nicetoolbox.evaluation.data.input_loader.LoadedArray], broadcast_single: bool = False) → list[tuple[nicetoolbox.evaluation.data.input_loader.LoadedArray, nicetoolbox.evaluation.data.input_loader.LoadedArray]]

Pair predictions with ground truth arrays and align their axes.

Matches pairs by shared meta fields (dataset, session, sequence, component). For each pair, all axes (subjects, cameras, frames, labels, data) are intersected so both arrays have identical labels in the same order. Pairs with an empty intersection on any required axis are skipped with a warning.

Parameters:

• predictions – Loaded prediction arrays to match against ground truth.

• ground_truth – Loaded ground truth arrays. A single PathMeta entry acts as a wildcard matched to any prediction without a structured match.

• broadcast_single – When True, axes where both sides have exactly one element are paired directly regardless of label mismatch, keeping the prediction label.

Returns:

List of (prediction, ground_truth) pairs with aligned axes.

Raises:

ValueError – If more than one path-based array is provided on either side.

nicetoolbox.evaluation.data.input_loader.get_meta_type(arrays: list[nicetoolbox.evaluation.data.input_loader.LoadedArray]) → type[nicetoolbox.evaluation.data.input_loader.NpzMeta]

Extract the shared NpzMeta type from a list of arrays.

Parameters:

arrays – Non-empty list of LoadedArray instances all sharing the same meta type.

Returns:

The common NpzMeta subclass used by all arrays in the list.

Raises:

ValueError – If arrays is empty or contains mixed meta types.

nicetoolbox.evaluation.data.input_loader.get_npz_files(input_block: BaseInputBlock) → list[nicetoolbox.evaluation.data.input_loader.NpzMeta]

Resolve an InputBlock to the concrete NPZ file paths it refers to.

Parameters:

input_block – Input configuration specifying source type and filters.

Returns:

List of NpzMeta instances sorted by file path.

Raises:

• ValueError – If the input block has no path set and no default experiment was resolved, or if the input block type is not recognized.

• FileNotFoundError – If a resolved NPZ path does not exist on disk.

nicetoolbox.evaluation.data.input_loader.load_array(meta: NpzMeta, filters: NpzAxis) → LoadedArray | None

Load one NPZ entry, read axis labels from data_description, and apply filters.

Parameters:

• meta – Metadata describing the NPZ file path and key to load.

• filters – Axis filter spec (subjects, cameras, labels, data) to apply after loading.

Returns:

LoadedArray with filtered data and axis labels, or None if any filtered axis has no overlap with the available labels.

Raises:

• KeyError – If data_description is missing from the NPZ file or the requested key is absent from data_description.

• ValueError – If the data array shape does not match data_description axis lengths.

nicetoolbox.evaluation.data.input_loader.load_experiment_config(experiment_folder: Path) → DetectorsExperimentConfig

Load the latest saved detector experiment config from an experiment folder.

Parameters:

experiment_folder – Path to the experiment output folder containing saved config files.

Returns:

Parsed DetectorsExperimentConfig from the most recently saved config file.

nicetoolbox.evaluation.data.input_loader.load_input(input_block: BaseInputBlock) → list[nicetoolbox.evaluation.data.input_loader.LoadedArray]

Load and prepare all arrays for a given input block.

Resolves the relevant NPZ files based on the input block’s source type (experiment/annotation/path), loads each one, and applies axis filters (subjects, cameras, labels, etc.).

Parameters:

input_block – Configuration describing what data to load and how to filter it.

Returns:

List of loaded arrays ready for metric iteration, sorted by source NPZ file.

Raises:

• RuntimeError – If all resolved NPZ files are filtered out or no data is found.

• FileNotFoundError – If a resolved NPZ path does not exist on disk.

nicetoolbox.evaluation.data.input_loader.matches_filter(value: str, filter_value: str | Any | list[Any]) → bool

Match a discovered dimension value against an InputBlock filter.

Parameters:

• value – The actual dimension value to test (e.g. dataset name, session ID).

• filter_value – Filter to match against. Accepts "*" to accept any value, a literal string for exact match, or a list of values for membership test.

Returns:

True if value satisfies the filter, False otherwise.