dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/comparison/snap.py

@@ -0,0 +1,62 @@
+"""The one snap rule (D149): a value the POINTER placed is written at a
+readable step.
+
+A drag released on the plot wrote where the pointer happened to stop, to 12
+significant digits — ``0.373778382112`` for a tolerance nobody would type.
+A value placed by the pointer (a drag's release, a click, and the preview
+of either) is rounded to a step of the axis it was placed on: the power of
+ten nearest to a thousandth of what that axis SHOWED, so a plot drawn about
+a thousand pixels wide snaps to about a pixel, and a zoom makes the step
+finer. A typed value is never snapped: this is called for a position, never
+for a field.
+"""
+
+from __future__ import annotations
+
+import math
+
+#: The smallest step, as its power of ten: what an axis showing nothing a
+#: thousandth of which is a number snaps to — so nothing is rounded away.
+_SMALLEST = -300
+
+
+def _exponent(span: object) -> int | None:
+    """The step's power of ten for an axis showing ``span``; None where
+    ``span`` is no number at all — a caller that is no pointer — and then
+    nothing is snapped. A span that is zero, negative, not finite or under
+    1e-300 has the smallest step: `log10` of a thousandth of it is no
+    number, or is one of an underflowed zero, which raised."""
+    if isinstance(span, bool) or not isinstance(span, (int, float)):
+        return None
+    if not math.isfinite(span) or span < 1e-300:
+        return _SMALLEST
+    return max(_SMALLEST, round(math.log10(span / 1000)))
+
+
+def snap_step(span: object) -> float | None:
+    """The step a value placed on an axis showing ``span`` is rounded to:
+    ``10 ** round(log10(span / 1000))`` — nearest in the exponent, so a span
+    of 3.1 snaps to 0.001 and one of 3.2 to 0.01. None for a span that is
+    no number; the smallest step, 1e-300, for one that shows nothing."""
+    exponent = _exponent(span)
+    return None if exponent is None else 10.0**exponent
+
+
+def snapped(value: float, span: object, *, fraction: bool = False) -> float:
+    """``value`` as a pointer on an axis showing ``span`` writes it.
+
+    A coordinate, and a tolerance side in the axis' own units, is rounded
+    to a multiple of :func:`snap_step` — as a decimal, so the result is the
+    float a person would type (``0.374``, never ``0.37400000000000005``);
+    a value exactly half way between two multiples goes to the even one.
+    A RELATIVE side (``fraction``: a fraction of its target, on no axis) is
+    rounded to 3 significant digits. A value that snaps to zero is ``0.0``,
+    never ``-0.0``. With no span — a caller that is no pointer — ``value``
+    comes back as it is.
+    """
+    exponent = _exponent(span)
+    if exponent is None or not math.isfinite(value):
+        return value
+    if fraction:
+        return float(f"{value:.3g}") + 0.0
+    return round(float(value), -exponent) + 0.0

dstf/comparison/strict_keys.py

@@ -0,0 +1,246 @@
+"""A key nobody reads is an error that names it.
+
+``test_spec.json`` is written by hand as well as by the tool, and a key
+the scorer does not read used to be kept and ignored: a ``range`` leaf
+spelled ``"max_val": 0.5`` scored as if it had no upper bound and passed;
+an ``"agianst"`` scored against the primary baseline. This module is the
+ONE check every part of a spec entry goes through — a leaf, a flat
+override, the rows of a metric's tables, the keys inside a ``quantity``
+object and a tolerance pair, and (through :func:`unknown_field`) a window,
+a combinator, the entry's own blocks and the spec's root.
+
+What is known is never listed here. It is read from what already says it:
+a metric's config dataclass (its fields, and the ``columns`` metadata of
+its row tables — what the authoring tool's forms are built from) and the
+keys the parser and the evaluator read off every leaf. A metric a plug-in
+registers is therefore checked against ITS config with no change here.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Iterable, Mapping
+
+from .registry import metric, unnamed_metrics
+
+#: Params read off EVERY leaf and override, whatever its metric.
+#:
+#: ``tolerance`` — the evaluator resolves it for each leaf before it builds
+#: the mode (a leaf's own, else the test's), so it is a key of every metric
+#: even where the mode then has no use for the number.
+#:
+#: ``quantity`` — the evaluator looks at it on each leaf, and acts on it
+#: only for a metric that declares ``accepts_quantity``. On any other
+#: metric it is the one documented inert param (docs/extensibility.md,
+#: the Metric contract, item 6; ``MetricDescriptor``): "an unrecognized
+#: ``quantity`` stays an inert param — a trajectory metric keeps scoring
+#: trajectories". That promise is kept here, by name, and not by leniency.
+EVERY_METRIC = ("tolerance", "quantity")
+
+
+def _edits(a: str, b: str) -> int:
+    """How many single edits turn ``a`` into ``b``: a letter added, dropped
+    or replaced, or two neighbours swapped (the optimal-string-alignment
+    distance — ``agianst`` is ONE slip from ``against``)."""
+    previous2: list[int] = []
+    previous = list(range(len(b) + 1))
+    for i, ca in enumerate(a, start=1):
+        row = [i]
+        for j, cb in enumerate(b, start=1):
+            cost = 0 if ca == cb else 1
+            best = min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + cost)
+            if i > 1 and j > 1 and ca == b[j - 2] and a[i - 2] == cb:
+                best = min(best, previous2[j - 2] + 1)
+            row.append(best)
+        previous2, previous = previous, row
+    return previous[-1]
+
+
+def near_miss(key: str, names: Iterable[str]) -> str | None:
+    """The ONE of ``names`` that ``key`` is a slip of the hand from, or None.
+
+    A suggestion that is wrong sends the reader to the wrong field, so one
+    is made only for a near miss, and only when it is the only one:
+
+    - the same name in another case, always (``K`` for ``k``);
+    - else at most two edits (:func:`_edits`, case ignored) and at most one
+      per three letters typed — ``max_val`` → ``max_value``, ``tolerence``
+      → ``tolerance``, ``frq`` → ``freq``, ``agianst`` → ``against`` — with
+      no other name as near: ``m_value`` is as far from ``min_value`` as
+      from ``max_value``, and gets neither;
+    - else the start, three letters or more, of exactly one name that is
+      ONE word — itself (``tol`` for ``tolerance``) or less its last letter
+      (``childs`` for ``children``). Never the start of a name of several
+      words: ``time`` was offered ``time_tolerance``, ``tube_width``
+      ``tube_width_mode`` and ``baseline`` ``baseline_points``, each to a
+      person who had typed a whole word for another thing (a row's time, a
+      tube's width, ``against``). ``min`` for ``min_value`` goes with them:
+      nothing tells it from ``time``.
+
+    ``difflib``'s ratio, which this replaces, called these close:
+    ``start_time`` → ``stop_time`` (a different field), ``notes`` →
+    ``plots``, ``simulate_only`` → ``simulation``, ``tolerance_mode`` on a
+    leaf without one → ``tolerance``; the prefix rule offered ``tube_abs``
+    for ``tube`` with four names starting so. Each now lists the fields."""
+    names = sorted(set(names))
+    typed = key.casefold()
+    same = [name for name in names if name.casefold() == typed]
+    if same:
+        return same[0]
+    allowed = min(2, len(typed) // 3)
+    scored = sorted((_edits(typed, name.casefold()), name) for name in names)
+    if scored and 0 < scored[0][0] <= allowed:
+        if len(scored) == 1 or scored[1][0] > scored[0][0]:
+            return scored[0][1]
+        return None
+    for stem in (key, key[:-1]):
+        starts = [name for name in names if len(stem) >= 3 and name.startswith(stem)]
+        if starts:
+            return starts[0] if len(starts) == 1 and "_" not in starts[0] else None
+    return None
+
+
+def unknown_field(keys: Iterable[str], known: Iterable[str]) -> str | None:
+    """What to say about the first of ``keys`` that is not in ``known``, or
+    None when all are: ``unknown field "max_val" — did you mean
+    "max_value"?`` when ONE known key is a near miss (:func:`near_miss`),
+    else the keys there are to choose from."""
+    names = sorted(set(known))
+    for key in keys:
+        if key in names:
+            continue
+        close = near_miss(str(key), names)
+        if close is not None:
+            return f'unknown field "{key}" — did you mean "{close}"?'
+        return f'unknown field "{key}"; the fields here are: {", ".join(names)}'
+    return None
+
+
+def metric_fields(metric_name: str) -> frozenset[str] | None:
+    """The param keys a metric reads: its config dataclass's fields and
+    :data:`EVERY_METRIC`. None — NOT CHECKED — for a name no metric is
+    registered under (the parser and the flat path each say that
+    themselves) and for a metric whose ``config_cls`` is not a dataclass:
+    nothing says what such a metric reads, so nothing is refused for it.
+    """
+    desc = metric(metric_name)
+    if desc is None or not dataclasses.is_dataclass(desc.config_cls):
+        return None
+    return frozenset(f.name for f in dataclasses.fields(desc.config_cls)) | frozenset(
+        EVERY_METRIC
+    )
+
+
+def row_fields(metric_name: str) -> dict[str, frozenset[str]]:
+    """``{table field: the keys of one of its rows}`` for a metric's row
+    tables — ``points``, ``peaks``, ``events``, ``tube_points`` — from the
+    ``columns`` metadata on the config field, which names each row key as
+    the scorer reads it. A list field with no ``columns`` has no entry and
+    its rows are not checked."""
+    desc = metric(metric_name)
+    if desc is None or not dataclasses.is_dataclass(desc.config_cls):
+        return {}
+    return {
+        f.name: frozenset(column[0] for column in f.metadata["columns"])
+        for f in dataclasses.fields(desc.config_cls)
+        if f.metadata.get("columns")
+    }
+
+
+def unread_param(
+    metric_name: str, params: Mapping[str, object], *, beside: Iterable[str] = ()
+) -> str | None:
+    """What to say about the first key of ``params`` — a leaf's keys bar
+    its structural ones, or a flat override's bar ``mode`` — that
+    ``metric_name`` does not read, or None. A row of one of its tables is
+    checked too: ``points row 2: unknown field "tolerence" — did you mean
+    "tolerance"?`` (rows count from 1, as the tool's tables do).
+
+    ``beside`` names the keys written beside the params — a leaf's
+    ``metric`` / ``variable`` / ``against`` / ``window``, an override's
+    ``mode`` — which the caller reads itself: a misspelling of one of
+    THOSE lands among the params, and is offered its spelling (``agianst``
+    → ``against``)."""
+    known = metric_fields(metric_name)
+    if known is None:
+        return None
+    problem = unknown_field(params, (*known, *beside))
+    if problem is not None:
+        return problem
+    problem = _unread_inside(params, declares_quantity(metric_name))
+    if problem is not None:
+        return problem
+    for name, columns in row_fields(metric_name).items():
+        rows = params.get(name)
+        if not isinstance(rows, list):
+            continue
+        for i, row in enumerate(rows, start=1):
+            if not isinstance(row, dict):
+                continue  # the mode's own reader says what a row must be
+            problem = unknown_field(row, columns) or _unread_inside(row, False)
+            if problem is not None:
+                return f"{name} row {i}: {problem}"
+    return None
+
+
+def declares_quantity(metric_name: str) -> bool:
+    """Whether the metric's config has a ``quantity`` field of its own —
+    ``scalar`` — and so reads the object's keys. On any other metric
+    ``quantity`` is the inert param (:data:`EVERY_METRIC`): of any shape,
+    read by nothing, and not looked into."""
+    desc = metric(metric_name)
+    return (
+        desc is not None
+        and dataclasses.is_dataclass(desc.config_cls)
+        and any(f.name == "quantity" for f in dataclasses.fields(desc.config_cls))
+    )
+
+
+def _unread_inside(values: Mapping[str, object], quantity_is_read: bool) -> str | None:
+    """What to say about the first key INSIDE one of ``values`` — a leaf's
+    params, or the cells of a table row — that nothing reads, or None:
+    ``tolerance: unknown field "uper" — did you mean "upper"?``.
+
+    Two kinds of value are objects. A ``quantity`` holds ``reduce``
+    (``modes.QUANTITY_KEYS``): ``{"reduce": "max", "over": "x"}`` scored the
+    max and dropped ``over``. Every other object is a tolerance's
+    lower/upper pair, and ``sides.parse_sides`` — the one place a pair is
+    read — takes exactly those two keys: ``{"lower": 0.1, "uper": 0.2}`` was
+    found at compare, as a criterion that could not be configured. Both are
+    said here, where the spec is read."""
+    from .modes import QUANTITY_KEYS
+    from .sides import PAIR_KEYS
+
+    for name, value in values.items():
+        if not isinstance(value, dict):
+            continue
+        if name == "quantity":
+            if not quantity_is_read:
+                continue
+            problem = unknown_field(value, QUANTITY_KEYS)
+        else:
+            problem = unknown_field(value, PAIR_KEYS)
+        if problem is not None:
+            return f"{name}: {problem}"
+    return None
+
+
+def unread_override_key(override: Mapping[str, object]) -> tuple[str, str] | None:
+    """For a flat ``comparison.variable_overrides`` entry holding a key its
+    mode does not read: ``(that mode, what to say)``; else None.
+
+    The mode is the one ``modes.resolve_mode`` gives it. With no ``mode``
+    that is the default metric, or ``points`` under ``--default-points``
+    (:func:`~.registry.unnamed_metrics`) — the flag is not known where a
+    spec is read, so the entry may carry what EITHER reads, and is refused
+    only when neither reads all of it. A ``mode`` no metric is registered
+    under is not judged here: the comparison fails that variable loudly.
+    """
+    params = {k: v for k, v in override.items() if k != "mode"}
+    named = override.get("mode") or ""
+    modes = (str(named),) if named else unnamed_metrics()
+    problems = [unread_param(mode, params, beside=("mode",)) for mode in modes]
+    if any(problem is None for problem in problems):
+        return None
+    assert problems[0] is not None
+    return modes[0], problems[0]

dstf/comparison/summaries.py

@@ -0,0 +1,354 @@
+"""Per-mode :class:`~.types.ScoreSummary` builders.
+
+Each function turns one mode's ``VariableComparison`` into the pill text and
+criterion sentence the report and the terminal review loop show. They are
+attached to the mode's :class:`~.registry.MetricDescriptor` and dispatched
+by :func:`~.registry.summarize`; a third-party metric supplies its own or
+inherits :func:`summarize_default`. No mode name appears outside this file
+and the registrations in :mod:`.builtins`.
+"""
+
+from __future__ import annotations
+
+import math
+
+from .geometry import Box, VLine
+from .sides import Sides, parse_sides, sides_text, signed
+from .types import ScoreSummary, VariableComparison
+
+
+def _verdict(vc: VariableComparison) -> str:
+    return "PASS" if vc.passed else "FAIL"
+
+
+def _at(value: float, time: float) -> str:
+    return f"{value:.6e} at t={time:g}"
+
+
+def _deviation(value: float, sides: Sides) -> str:
+    """A reported row's deviation beside ITS sides: the magnitude under
+    equal ones, as a number always printed; signed under uneven ones, so
+    the reader sees which side applies."""
+    return f"{abs(value):.3e}" if sides.equal else signed(value)
+
+
+def _finals(vc: VariableComparison) -> tuple[str, str]:
+    return ("final", f"ref={vc.reference_final:.6e}  act={vc.actual_final:.6e}")
+
+
+def _trajectory_details(vc: VariableComparison) -> tuple[tuple[str, str], ...]:
+    """The pairs behind an NRMSE score: what the review loop printed for
+    every variable before summaries became mode-aware."""
+    if vc.is_constant:
+        spread: tuple[str, str] = ("RMSE", f"{vc.rmse:.6e} (constant signal)")
+    else:
+        spread = ("RMSE", f"{vc.rmse:.6e} (range {vc.signal_range:.4e})")
+    return (
+        spread,
+        ("max |err|", _at(vc.max_abs_error, vc.max_abs_error_time)),
+        _finals(vc),
+    )
+
+
+def summarize_default(vc: VariableComparison) -> ScoreSummary:
+    """NRMSE-shaped: the score is an error against a tolerance."""
+    return ScoreSummary(
+        display=f"NRMSE {vc.nrmse:.3e}",
+        criterion=(
+            f"NRMSE {vc.nrmse:.3e} vs tolerance {sides_text(vc.tolerance_used)} → "
+            f"{_verdict(vc)}"
+        ),
+        score=float(vc.nrmse),
+        score_label="NRMSE",
+        details=_trajectory_details(vc),
+    )
+
+
+summarize_nrmse = summarize_default
+
+
+def summarize_tube(vc: VariableComparison) -> ScoreSummary:
+    if vc.tube_points_inside is None:
+        return summarize_default(vc)
+    pct = vc.tube_points_inside * 100
+    details: list[tuple[str, str]] = []
+    if vc.tube_worst_violation is not None and vc.tube_worst_violation > 0:
+        details.append(
+            (
+                "worst violation",
+                _at(vc.tube_worst_violation, vc.tube_worst_violation_time or 0.0),
+            )
+        )
+    # The tube's own measures only. Its comparator also computes an NRMSE
+    # against the reference, which nothing scores: printed here, beside
+    # PASS, it read as the criterion's number (`2.82e-01` on a tube 100 %
+    # inside) — and the largest deviation says what it could.
+    details.append(("max |err|", _at(vc.max_abs_error, vc.max_abs_error_time)))
+    details.append(_finals(vc))
+    return ScoreSummary(
+        display=f"{pct:.1f}% in tube",
+        criterion=f"{pct:.1f}% inside tube → {_verdict(vc)} (requires 100%)",
+        score=float(vc.tube_points_inside),
+        score_label="in tube",
+        details=tuple(details),
+    )
+
+
+def summarize_range(vc: VariableComparison) -> ScoreSummary:
+    if vc.tube_worst_violation is None:
+        return summarize_default(vc)
+    diag = vc.diagnostics or {}
+    lo, hi = diag.get("min_value"), diag.get("max_value")
+    lo_s = "-inf" if lo is None else f"{lo:g}"
+    hi_s = "inf" if hi is None else f"{hi:g}"
+    details: list[tuple[str, str]] = [("bounds", f"[{lo_s}, {hi_s}]")]
+    if vc.tube_worst_violation > 0:
+        details.append(
+            (
+                "worst violation",
+                _at(vc.tube_worst_violation, vc.tube_worst_violation_time or 0.0),
+            )
+        )
+    if vc.tube_points_inside is not None:
+        details.append(("inside", f"{vc.tube_points_inside * 100:.1f}% of samples"))
+    return ScoreSummary(
+        display=f"max_viol {vc.tube_worst_violation:.3e}",
+        criterion=(
+            f"max violation {vc.tube_worst_violation:.3e} → {_verdict(vc)} (requires 0)"
+        ),
+        score=float(vc.tube_worst_violation),
+        score_label="max violation",
+        details=tuple(details),
+    )
+
+
+def summarize_points(vc: VariableComparison) -> ScoreSummary:
+    diag = vc.diagnostics or {}
+    details: list[tuple[str, str]] = []
+    if "scored_points" in diag:
+        # Of the DECLARED rows: `failed_points` counts a checkpoint that was
+        # never scored and `scored_points` does not — "3 of 2 failed".
+        n_unscored = diag.get("unscored_points", 0)
+        declared = diag["scored_points"] + n_unscored
+        said = f"{diag.get('failed_points', 0)} of {declared} failed"
+        if n_unscored:
+            said += f", {n_unscored} not scored"
+        details.append(("checkpoints", said))
+        if diag.get("worst_delta", 0.0) > 0:
+            details.append(
+                ("worst delta", _at(diag["worst_delta"], diag.get("worst_time", 0.0)))
+            )
+        for failure in diag.get("point_failures") or []:
+            details.append(
+                (f"t={failure.get('time'):g}", str(failure.get("reason", "")))
+            )
+    else:
+        details.append(_finals(vc))
+    # Equal sides: the magnitude, as a number always printed. Uneven ones:
+    # actual − target, signed, so the reader sees which side applies.
+    error = f"{vc.max_abs_error:.3e}"
+    if not vc.tolerance_used.equal:
+        if "scored_points" in diag:
+            error = signed(diag.get("worst_signed_delta", vc.max_abs_error))
+        else:
+            error = signed(vc.actual_final - vc.reference_final)
+    # What is scored: the final value where no row is declared, else the
+    # largest |Δ| of the declared ones — which was said of the final value
+    # too, though no row need be it. Where it is, is in the details (`worst
+    # delta`): its time is a sample's, inside a row's time box.
+    what = "Largest point" if "scored_points" in diag else "Final value"
+    criterion = (
+        f"{what} error {error} vs tolerance "
+        f"{sides_text(vc.tolerance_used)} → {_verdict(vc)}"
+    )
+    # Among declared points, the reported one's sides are not the leaf's
+    # (its own pair or number), or are relative, or its delta is not the
+    # largest, or the leaf's are a pair: the scorer recorded that point —
+    # the one furthest outside its band, or of the largest |Δ| when none
+    # is — with the sides IT was judged on.
+    if "worst_sides" in diag:
+        own = parse_sides(diag["worst_sides"], "worst_sides")
+        error = _deviation(diag["worst_signed_delta"], own)
+        relative = " (relative)" if diag["worst_sides_relative"] else ""
+        criterion = (
+            f"Point at t={diag['worst_point_time']:g}: error {error} vs tolerance "
+            f"{sides_text(own)}{relative} → {_verdict(vc)}"
+        )
+    # A checkpoint that was never scored (outside the reference, or the run
+    # never reached it) is the failure, whatever the scored rows did: the
+    # sentence named a row that passes beside FAIL. A scored row that fails
+    # as well is counted beside it: the one sentence hid that any did.
+    if "unscored_point" in diag:
+        unscored = diag["unscored_point"]
+        scored = diag["failed_points"] - diag["unscored_points"]
+        also = ""
+        if scored > 0:
+            also = (
+                f" (and {scored} scored point{'' if scored == 1 else 's'} "
+                f"fail{'s' if scored == 1 else ''})"
+            )
+        criterion = (
+            f"Point at t={unscored['time']:g}: not scored — {unscored['reason']}"
+            f"{also} → {_verdict(vc)}"
+        )
+    return ScoreSummary(
+        display=f"|err| {vc.max_abs_error:.3e}",
+        criterion=criterion,
+        score=float(vc.max_abs_error),
+        score_label="|err|",
+        details=tuple(details),
+    )
+
+
+def summarize_scalar(vc: VariableComparison) -> ScoreSummary:
+    diag = vc.diagnostics or {}
+    verdict = _verdict(vc)
+    if not math.isfinite(vc.actual_final):
+        # Hard-fail sentinel (unresolvable quantity, no samples, a reduction
+        # that came out non-finite): there is no scalar to show, so surface
+        # the reason instead of "nan vs nan". The sentinel keeps the
+        # variable's NAME, so the name is never the reason — every route that
+        # builds one stamps ``diagnostics["error"]``.
+        reason = diag.get("error") or "quantity could not be resolved"
+        return ScoreSummary(
+            display="not scored", criterion=f"Scalar leaf not scored — {reason}"
+        )
+    lo, hi = diag.get("min_value"), diag.get("max_value")
+    if lo is not None or hi is not None:
+        lo_s = "-inf" if lo is None else f"{lo:g}"
+        hi_s = "inf" if hi is None else f"{hi:g}"
+        return ScoreSummary(
+            display=f"value {vc.actual_final:.6g}",
+            criterion=f"Scalar {vc.actual_final:.6g} within [{lo_s}, {hi_s}] → {verdict}",
+            score=float(vc.actual_final),
+            score_label="value",
+            details=(("reduction", str(diag.get("reduction"))),),
+        )
+    fallback = bool(diag.get("abs_fallback"))
+    rel = diag.get("tolerance_mode") == "rel" and not fallback
+    criterion = "relative" if rel else "absolute"
+    note = " (|ref|=0 → absolute)" if fallback else ""
+    # Uneven sides: the signed score, as the scorer judged it (`d / |ref|`
+    # in rel) — the same two operations on the same two numbers.
+    deviation = f"{vc.nrmse:.3e}"
+    if not vc.tolerance_used.equal:
+        d = vc.actual_final - vc.reference_final
+        deviation = signed(d / abs(vc.reference_final) if rel else d)
+    return ScoreSummary(
+        display=(f"rel Δ {vc.nrmse:.3e}" if rel else f"|Δ| {vc.nrmse:.3e}"),
+        criterion=(
+            f"Scalar {vc.actual_final:.6g} vs baseline {vc.reference_final:.6g}: "
+            f"{criterion} deviation {deviation} vs "
+            f"tolerance {sides_text(vc.tolerance_used)}{note} → {verdict}"
+        ),
+        score=float(vc.nrmse),
+        score_label="rel Δ" if rel else "|Δ|",
+        details=(
+            ("reduction", str(diag.get("reduction"))),
+            ("scalar", f"ref={vc.reference_final:.6g}  act={vc.actual_final:.6g}"),
+        ),
+    )
+
+
+def _events_not_found(vc: VariableComparison) -> list[float]:
+    """The declared events that claimed no actual event, in declared order:
+    the scorer draws each declared event as a line and its window, and a
+    window nothing was found in is the one not ``passed``. The ids are read
+    by their tail — the evaluator stamps a leaf's path before them."""
+    times = {p.id: p.time for p in vc.geometry if isinstance(p, VLine)}
+    missing = []
+    for p in vc.geometry:
+        head, window, k = p.id.rpartition("events/window/")
+        if isinstance(p, Box) and window and p.passed is False:
+            missing.append(times[f"{head}events/ref/{k}"])
+    return missing
+
+
+def summarize_event_timing(vc: VariableComparison) -> ScoreSummary:
+    diag = vc.diagnostics or {}
+    ref_n = diag.get("ref_event_count", "?")
+    act_n = diag.get("act_event_count", "?")
+    sides = parse_sides(diag.get("time_tolerance", 0.0), "time_tolerance")
+    tol = sides_text(sides)
+    # Uneven sides: Δt signed (late positive) — of the pair furthest
+    # outside its window, or of the largest |Δt| when none is — recorded by
+    # the scorer.
+    delta = f"{vc.nrmse:.3e}"
+    if not sides.equal:
+        delta = signed(diag.get("max_time_delta_signed", vc.nrmse))
+    details: list[tuple[str, str]] = [
+        ("events", f"{act_n} actual / {ref_n} reference"),
+        ("max Δt", _at(vc.nrmse, vc.max_abs_error_time)),
+    ]
+    criterion = (
+        f"Max event Δt {delta} vs {tol} "
+        f"({act_n} actual events / {ref_n} reference) → {_verdict(vc)}"
+    )
+    # Among declared events, the reported one's window is not the leaf's
+    # (its own pair or number), or the leaf's is a pair: the window that Δt
+    # was held to is that event's (as `summarize_points`).
+    if "worst_sides" in diag:
+        own = parse_sides(diag["worst_sides"], "worst_sides")
+        criterion = (
+            f"Event at t={diag['worst_event_time']:g}: "
+            f"Δt {_deviation(diag['max_time_delta_signed'], own)} vs "
+            f"{sides_text(own)} "
+            f"({act_n} actual events / {ref_n} reference) → {_verdict(vc)}"
+        )
+    # A declared event that was never found is what failed, and the Δt
+    # above is not it: that is the matched events', inside the tolerance.
+    unmatched = diag.get("unmatched_events", 0)
+    if unmatched:
+        criterion = (
+            f"{unmatched} of {diag['declared_events']} declared events not found "
+            f"within tolerance {tol} ({act_n} actual events) → {_verdict(vc)}"
+        )
+        details.append(
+            ("not found", ", ".join(f"t={t:g}" for t in _events_not_found(vc)))
+        )
+    if "counts_match" in diag and not diag["counts_match"]:
+        details.append(("event count", "mismatch"))
+    return ScoreSummary(
+        display=f"Δt {vc.nrmse:.3e} ({act_n}/{ref_n} events)",
+        criterion=criterion,
+        score=float(vc.nrmse),
+        score_label="Δt",
+        details=tuple(details),
+    )
+
+
+def summarize_dominant_frequency(vc: VariableComparison) -> ScoreSummary:
+    diag = vc.diagnostics or {}
+    paired = diag.get("paired_peaks") or []
+    n_matched = sum(1 for p in paired if p.get("matched_hz") is not None)
+    n_declared = len(paired)
+    if n_declared == 0:
+        return ScoreSummary(
+            display="no peaks declared",
+            criterion=(
+                "No peaks declared — declare them in the leaf's `peaks` "
+                "list; the reference's detected peaks are in the "
+                "diagnostics as `detected_reference_peaks_hz`"
+            ),
+        )
+    details = tuple(
+        (
+            f"peak {p.get('declared_hz', '?')} Hz",
+            (
+                f"matched at {p['matched_hz']:.6g} Hz"
+                if p.get("matched_hz") is not None
+                else "not found"
+            ),
+        )
+        for p in paired
+    )
+    return ScoreSummary(
+        display=f"{n_matched}/{n_declared} peaks matched",
+        criterion=(
+            f"{n_matched} / {n_declared} declared peaks found in actual "
+            f"spectrum within tolerance → {_verdict(vc)}"
+        ),
+        score=float(n_matched),
+        score_label="peaks matched",
+        details=details,
+    )