bencher.scorecard.model
=======================

.. py:module:: bencher.scorecard.model

.. autoapi-nested-parse::

   Pure data-shaping for the scorecard: summary dicts -> table cells.

   No filesystem and no templating here — every function takes already-parsed
   summary records (the :func:`~bencher.report_export.result_to_dict` contract,
   with per-metric ``series``) and returns plain dicts the renderer turns into
   HTML. This keeps the column/verdict/formatting logic unit-testable in isolation.



Functions
---------

.. autoapisummary::

   bencher.scorecard.model.unify_metric_names
   bencher.scorecard.model.metric_columns
   bencher.scorecard.model.cell_verdict
   bencher.scorecard.model.fmt_value
   bencher.scorecard.model.fmt_change
   bencher.scorecard.model.build_cell


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

.. py:function:: unify_metric_names(metrics: dict[str, dict], regressions: dict[str, dict], aliases: dict[str, str]) -> tuple[dict[str, dict], dict[str, dict]]

   Apply *aliases* to one benchmark's metrics + regressions.

   Returns new dicts keyed by canonical column names, preserving metric order.
   A renamed metric records its original name under ``source_variable`` so a
   cell tooltip can surface it. Collisions (the canonical name already exists on
   this benchmark, or two of its metrics map to the same alias) keep the raw
   name to never drop or shadow data.


.. py:function:: metric_columns(records: list[dict]) -> list[str]

   Union of metric names, ordered by (shared-by-most, first-seen).


.. py:function:: cell_verdict(reg: dict | None) -> str

   4-way display verdict for a cell.

   ``None`` — no regression gate on this metric (or too little history) — maps
   to the uncolored ``"trend"`` fallback. Otherwise defer to bencher's 3-state
   core verdict and render its ``"unchanged"`` as ``"passed"`` (the gate ran and
   did not flag). A gate with no threshold can only have "passed".


.. py:function:: fmt_value(value: float | None, units: str | None, *, as_percent: bool = False) -> str

   Compact human label for a scalar value (``—`` when missing).


.. py:function:: fmt_change(change_percent: float | None) -> str

   Signed percent label for a Δ (empty when not computable).


.. py:function:: build_cell(rec: dict, var: str, config: bencher.scorecard.config.ScorecardConfig) -> dict | None

   Build one table cell for (benchmark, metric), or None when absent.