nicetoolbox.evaluation.data.summary

Functions

aggregate_summary	Aggregate a summary DataFrame by always-iterate columns, averaging over agg_col.
arrays_to_dataframe	Convert a list of LoadedArrays into a single long-format DataFrame.
pair_arrays_to_df	Join paired prediction/ground-truth arrays into a single long-format DataFrame.
resolve_group_levels	Return the columns to group by for a categorical metric computation.
split_aligned_arrays	Split N-tuples of LoadedArrays into N separate lists, mirroring zip semantics.
summarize_with_group_by	Build a summary DataFrame from frame-level arrays, grouped by specified dimensions.

nicetoolbox.evaluation.data.summary.aggregate_summary(summary: DataFrame, agg_col: str, meta_type: type[nicetoolbox.evaluation.data.input_loader.NpzMeta]) → DataFrame

Aggregate a summary DataFrame by always-iterate columns, averaging over agg_col.

Parameters:

• summary – Summary DataFrame containing metric results per group.

• agg_col – Name of the column to average.

• meta_type – NpzMeta subclass whose always_iterate() defines the grouping keys.

Returns:

Aggregated DataFrame with one row per unique combination of grouping columns.

Raises:

ValueError – If none of the always-iterate columns are present in summary.

nicetoolbox.evaluation.data.summary.arrays_to_dataframe(arrays: list[nicetoolbox.evaluation.data.input_loader.LoadedArray]) → DataFrame

Convert a list of LoadedArrays into a single long-format DataFrame.

Each row represents one scalar value at a specific (meta…, subject, camera, frame, label) coordinate.

Parameters:

arrays – LoadedArray instances to convert. All arrays must share the same meta key structure.

Returns:

Long-format DataFrame with a single value column and a MultiIndex built from meta fields and axis labels.

nicetoolbox.evaluation.data.summary.pair_arrays_to_df(pairs: list[tuple[nicetoolbox.evaluation.data.input_loader.LoadedArray, nicetoolbox.evaluation.data.input_loader.LoadedArray]], value_names: tuple[str, str] = ('pred', 'gt')) → DataFrame

Join paired prediction/ground-truth arrays into a single long-format DataFrame.

Parameters:

• pairs (list) – List of (prediction, ground_truth) LoadedArray pairs as returned by align_arrays.

• value_names – Column names for the prediction and ground truth values respectively.

Returns:

Long-format DataFrame with one row per (meta…, subject, camera, frame, label) coordinate, or an empty DataFrame if pairs is empty.

Raises:

ValueError – If the axis merge loses rows, indicating a violated align_arrays invariant.

nicetoolbox.evaluation.data.summary.resolve_group_levels(df: DataFrame, meta_type: type[nicetoolbox.evaluation.data.input_loader.NpzMeta], group_by: GroupBySpec, exclude: frozenset[str] = frozenset({'frame'})) → list[str]

Return the columns to group by for a categorical metric computation.

Always includes always_iterate columns from meta_type that are present in df, then adds user-requested dimensions from group_by, minus anything in exclude.

Parameters:

• df – DataFrame containing the metric data to be grouped.

• meta_type – NpzMeta subclass whose always_iterate() defines mandatory grouping keys.

• group_by – User-specified grouping dimensions.

• exclude – Column names to never include in the result.

Returns:

Ordered list of column names to pass to a groupby call.

nicetoolbox.evaluation.data.summary.split_aligned_arrays(*pairs: tuple[nicetoolbox.evaluation.data.input_loader.LoadedArray, ...]) → list[list[nicetoolbox.evaluation.data.input_loader.LoadedArray]]

Split N-tuples of LoadedArrays into N separate lists, mirroring zip semantics.

nicetoolbox.evaluation.data.summary.summarize_with_group_by(arrays: list[nicetoolbox.evaluation.data.input_loader.LoadedArray], group_by: GroupBySpec, agg: AggSpec) → DataFrame

Build a summary DataFrame from frame-level arrays, grouped by specified dimensions.

Meta-level fields are always iterated; axes-level fields are iterated only when listed in group_by.

Parameters:

• arrays – Frame-level LoadedArray instances to summarize.

• group_by – User-specified grouping dimensions applied on top of mandatory always-iterate fields.

• agg – Aggregation specification mapping output column names to functions.

Returns:

Summary DataFrame with one row per group and one column per aggregation function, or an empty DataFrame if arrays is empty.