coco_pipe.report.tables
=======================

.. py:module:: coco_pipe.report.tables

.. autoapi-nested-parse::

   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
---------

.. autoapisummary::

   coco_pipe.report.tables.primary_metric_column
   coco_pipe.report.tables.ensure_primary_metric
   coco_pipe.report.tables.make_cv_signature
   coco_pipe.report.tables.signature_compatibility
   coco_pipe.report.tables.split_by_status
   coco_pipe.report.tables.sort_by_metrics
   coco_pipe.report.tables.best_rows
   coco_pipe.report.tables.selector_columns
   coco_pipe.report.tables.relabel_columns
   coco_pipe.report.tables.display_frame


Module Contents
---------------

.. py:function:: 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 :func:`coco_pipe.decoding.stamp_primary_metric`.
   Returns ``None`` when the frame carries no scalar metric column.


.. py:function:: ensure_primary_metric(frame)

   Guarantee ``primary_metric``/``primary_metric_name`` columns exist.

   Records from the runner are already stamped by
   :func:`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.


.. py:function:: make_cv_signature(frame)

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


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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
   :func:`primary_metric_column` (falling back to ``"primary_metric"``); the
   resolved column name is returned alongside the rows.


.. py:function:: selector_columns(frame, candidates)

   Return interactive-table selector columns present in *frame*.


.. py:function:: 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 :func:`display_frame`.


.. py:function:: 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.