coco_pipe.report.tables#

Generic result-table helpers shared by decoding/dim-reduction reports.

Pure DataFrame utilities — status splitting, metric-ranked sorting, best-row selection, display subsetting, and selector-column filtering — with no study-specific column knowledge. Study reports layer their own column labels and ordering on top of these.

Functions#

`primary_metric_column`(frame)	Return the scalar `<metric>_mean` column that ranks results.
`ensure_primary_metric`(frame)	Guarantee `primary_metric`/`primary_metric_name` columns exist.
`make_cv_signature`(frame)	Return a readable `cv_strategy \| folds \| seed` Series, or None.
`signature_compatibility`(frame, group_columns, *[, ...])	Per-group CV/cohort-signature compatibility for paired comparisons.
`split_by_status`(frame)	Split a dataframe into `(successful_rows, failed_rows)`.
`sort_by_metrics`(frame[, primary_metric, tie_breakers])	Sort descending by `primary_metric`, then by `tie_breakers`.
`best_rows`(frame, group_columns[, primary_metric, ...])	Return the best successful row per requested group.
`selector_columns`(frame, candidates)	Return interactive-table selector columns present in frame.
`relabel_columns`(columns, *[, labels])	Map raw column names to their display labels, leaving unmapped names as-is.
`display_frame`(frame, *[, order, labels, round_decimals])	Return a display-ready result frame: ordered, rounded, and relabeled.

Module Contents#

coco_pipe.report.tables.primary_metric_column(frame)#

Return the scalar <metric>_mean column that ranks results.

Prefers balanced_accuracy_mean (the group-robust default), matching the metric contract stamped by coco_pipe.decoding.stamp_primary_metric(). Returns None when the frame carries no scalar metric column.

Parameters:: frame (pandas.DataFrame)
Return type:: str | None

coco_pipe.report.tables.ensure_primary_metric(frame)#

Guarantee primary_metric/primary_metric_name columns exist.

Records from the runner are already stamped by coco_pipe.decoding.stamp_primary_metric(); this is the frame-level fallback for externally-supplied tables (legacy CSVs, tests) so every leaderboard and comparison keys off one metric contract.

Parameters:: frame (pandas.DataFrame)
Return type:: pandas.DataFrame

coco_pipe.report.tables.make_cv_signature(frame)#

Return a readable cv_strategy | folds | seed Series, or None.

Parameters:: frame (pandas.DataFrame)
Return type:: pandas.Series | None

coco_pipe.report.tables.signature_compatibility(frame, group_columns, *, signature_columns=CV_SIGNATURE_COLUMNS)#

Per-group CV/cohort-signature compatibility for paired comparisons.

A group is compatible only when every row records every signature field and all rows agree on each. A missing field, or a frame without the column, marks the group incompatible: an unknown design is never assumed to match.

Parameters:

frame (pandas.DataFrame)
group_columns (collections.abc.Sequence[str])
signature_columns (collections.abc.Sequence[str])

Return type:

pandas.DataFrame

coco_pipe.report.tables.split_by_status(frame)#

Split a dataframe into (successful_rows, failed_rows).

Rows are successful when a status column equals "success"; without a status column every row is treated as successful.

Parameters:: frame (pandas.DataFrame)
Return type:: tuple[pandas.DataFrame, pandas.DataFrame]

coco_pipe.report.tables.sort_by_metrics(frame, primary_metric='primary_metric', tie_breakers=())#

Sort descending by primary_metric, then by tie_breakers.

tie_breakers is a sequence of (column_name, ascending) tuples. Strings/objects are coerced to numeric for safe sorting. When the primary metric column is absent the frame is returned unsorted rather than raising.

Parameters:

frame (pandas.DataFrame)
primary_metric (str)
tie_breakers (collections.abc.Sequence[tuple[str, bool]])

Return type:

pandas.DataFrame

coco_pipe.report.tables.best_rows(frame, group_columns, primary_metric=None, tie_breakers=())#

Return the best successful row per requested group.

When primary_metric is None the ranking column is auto-detected via primary_metric_column() (falling back to "primary_metric"); the resolved column name is returned alongside the rows.

Parameters:

frame (pandas.DataFrame)
group_columns (collections.abc.Sequence[str])
primary_metric (str | None)
tie_breakers (collections.abc.Sequence[tuple[str, bool]])

Return type:

tuple[pandas.DataFrame, str | None]

coco_pipe.report.tables.selector_columns(frame, candidates)#

Return interactive-table selector columns present in frame.

Parameters:

frame (pandas.DataFrame)
candidates (collections.abc.Sequence[str])

Return type:

list[str]

coco_pipe.report.tables.relabel_columns(columns, *, labels=None)#

Map raw column names to their display labels, leaving unmapped names as-is.

Use this to translate selector/sort column names to match a frame that was already relabeled by display_frame().

Parameters:

columns (collections.abc.Sequence[str])
labels (collections.abc.Mapping[str, str] | None)

Return type:

list[str]

coco_pipe.report.tables.display_frame(frame, *, order=None, labels=None, round_decimals=4)#

Return a display-ready result frame: ordered, rounded, and relabeled.

Selects the non-empty columns from order (defaulting to DEFAULT_DECODING_RESULT_COLUMN_ORDER) in that order, rounds numeric columns to round_decimals (skipped when None), and relabels the columns via DEFAULT_DECODING_RESULT_COLUMN_LABELS merged with labels. This is the single display path for decoding sweep-result tables.

Parameters:

frame (pandas.DataFrame)
order (collections.abc.Sequence[str] | None)
labels (collections.abc.Mapping[str, str] | None)
round_decimals (int | None)

Return type:

pandas.DataFrame