From cc94c2980ee749db5b999bcb739a0771419ad7f6 Mon Sep 17 00:00:00 2001 From: Harenome Ranaivoarivony-Razanajato Date: Wed, 18 Nov 2026 15:53:32 +0100 Subject: [PATCH 1/2] feat(web): draw categorical charts as bars, dots or a scatter A backend module places a few named values, one per item, in SVG user units, and a template macro draws the marks and texts as given, with a table of every value for a screen reader. A missing value is a gap, a check is hollow and named, and nothing is ranked. Styles are a registry of drawing functions, so a new style is one function and one entry. An item's series gives it one colour in every chart, from eight --series-* tokens set for the light and the dark themes. --- AGENTS.md | 2 +- app/nullius/charts.py | 316 +++++++++++++++++++++++++++ app/static/style.css | 26 +++ app/templates/_charts.html | 19 ++ app/tests/field_contract.json | 53 +++++ app/tests/field_contract.py | 4 +- app/tests/test_categorical_charts.py | 171 +++++++++++++++ 7 files changed, 588 insertions(+), 3 deletions(-) create mode 100644 app/nullius/charts.py create mode 100644 app/templates/_charts.html create mode 100644 app/tests/test_categorical_charts.py diff --git a/AGENTS.md b/AGENTS.md index 365cd67e..9be3711f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,7 +78,7 @@ and its resources. The source layout stays under `app/`. `cli` and `__main__` (the unified `nullius` and `python -m nullius` commands), `paths` (user config, data and cache locations), `prices` (the user's model price list: fetched on request and before a capped run; what a cost is estimated from), `migrate` (explicit copying of legacy checkout storage), `settings`, `hosts`, `constraints` (what Nullius may use on each machine: one table, the container and systemd scope probes, the warnings), `execution`, `progress` (what a run is doing, one line per stage), `prerequisites` (what a recipe needs of each machine it runs on, asked before Run and again as it starts), `onboarding` (the Getting started checklist: what this machine says is done, and where each step is done), `gitrefs` (a repository's branches and tags, - by `git ls-remote`), `secrets` (a benchmark's licences, kept per benchmark outside the repository, and the Hugging Face token of Data providers), `sandbox` (Docker's state, and the Docker Hub login Data providers uses) and `redact` at the top. + by `git ls-remote`), `secrets` (a benchmark's licences, kept per benchmark outside the repository, and the Hugging Face token of Data providers), `sandbox` (Docker's state, and the Docker Hub login Data providers uses), `charts` (categorical charts, bars, dots and a scatter, and their style registry: Compare's Chart view) and `redact` at the top. - `app/templates/`, `app/static/` — the interface, grouped by the same capability names (`runs/`, `traces/`, `builder/`, …; `base.html`, `style.css` and the fonts at the top), including the command builder's JavaScript, which owns the generated recipes. `app/templates/_tables.html` and diff --git a/app/nullius/charts.py b/app/nullius/charts.py new file mode 100644 index 00000000..6790c630 --- /dev/null +++ b/app/nullius/charts.py @@ -0,0 +1,316 @@ +"""Categorical charts: a few named values, one per item (a run), drawn as bars, dots or a scatter. + +The trace distributions (:mod:`nullius.traces.charts`) bin nanosecond durations on a log axis; these place a +handful of plain values on a linear one, so the two share no scale and no code. They share the split: this module +computes the geometry, in SVG user units, and ``templates/_charts.html`` draws it without arithmetic. + +A caller passes :class:`Metric` objects, each a label, a tick formatter and one :class:`Value` per item, already +computed and formatted as the caller shows them elsewhere: nothing here recomputes a value. A value of ``None`` is a +gap, never a zero. A ``check`` item is drawn hollow and named so; nothing here ranks items. An item's ``series`` +gives its marks one colour in every chart, the class ``s1`` to ``s8`` (cycling), which the stylesheet maps to +``--series-1`` to ``--series-8``; the item's name always says which it is. + +Each chart is one :class:`Panel`, drawn by a style of :data:`STYLES` from as many metrics as its ``Style.axes`` name: +one for bars and dots, x then y for a scatter. A caller reads the registry to offer the styles and, for each, a choice +of each axis's metric. Adding a style is one drawing function, taking those metrics and returning a :class:`Panel` of +:class:`Mark` and :class:`Text` that the template draws as they come, and one :data:`STYLES` entry. A new mark shape +also needs its one element in the template. + +Stdlib only, and no Flask. +""" + +from __future__ import annotations + +import math +import textwrap +from dataclasses import dataclass +from typing import Callable + +WIDTH = 360.0 # every panel's viewBox width; the page scales it to the panel +_LINE = 15.0 # a text line's height +_CHARS = 46 # a label's line length, at the template's font size; longer labels wrap, never clip +_BAR = 10.0 # a bar's thickness +_ROW_GAP = 9.0 +_LEFT, _RIGHT = 8.0, 70.0 # room before the plot, and after it for the values +_AXIS = 20.0 # the tick labels under the rows +_DOT = 4.5 +SERIES = 8 # the series colours, --series-1 to --series-8 in style.css +_CHAR_W = 7.0 # a character's width, at the template's font size + + +@dataclass(frozen=True) +class Value: + """One item's value: ``value`` None for no measurement; ``text`` as the caller shows it, ``note`` beside it.""" + + label: str + value: float | None + text: str = "" + note: str = "" + check: bool = False + baseline: bool = False + tag: str = "" # a short name, where the full one does not fit (a scatter's dot) + series: int = 0 # its colour, 1 on, the same in every chart; 0 for none + + def cls(self, shape: str) -> str: + """A mark's classes: its shape, its series (``s1`` to ``s``, cycling) and whether it is a check.""" + return " ".join(filter(None, (shape, self.series and f"s{(self.series - 1) % SERIES + 1}", self.check and "check"))) + + @property + def name(self) -> str: + """The label with what sets the item apart.""" + tags = [t for t, on in (("baseline", self.baseline), ("check", self.check)) if on] + return f"{self.label} ({', '.join(tags)})" if tags else self.label + + @property + def reading(self) -> str: + return " ".join(filter(None, (self.text or "—", self.note))) + + +@dataclass(frozen=True) +class Metric: + label: str + values: tuple + fmt: Callable = str # a tick's label + + +@dataclass(frozen=True) +class Mark: + """One shape: a rect (x, y, w, h), a circle (x, y, r) or a line (x, y to x2, y2); ``title`` its reading.""" + + shape: str + x: float + y: float + w: float = 0.0 + h: float = 0.0 + r: float = 0.0 + x2: float = 0.0 + y2: float = 0.0 + cls: str = "" + title: str = "" + + +@dataclass(frozen=True) +class Text: + x: float + y: float # the first line's baseline + lines: tuple + anchor: str = "start" + cls: str = "" + leading: float = _LINE + + +@dataclass(frozen=True) +class Panel: + """One SVG: its ``title`` names it, ``table`` (head, rows) carries every value as text.""" + + title: str + height: float + marks: tuple = () + texts: tuple = () + table: tuple = ((), ()) + width: float = WIDTH + + @property + def viewbox(self) -> str: + return f"0 0 {self.width:g} {self.height:g}" + + +def nice_ticks(lo: float, hi: float, count: int = 4, step_min: float = 0.0) -> tuple: + """Round ticks enclosing ``[lo, hi]``, about ``count`` steps, none finer than ``step_min``; ints where whole.""" + if hi < lo: + lo, hi = hi, lo + if hi == lo: + pad = abs(lo) * 0.1 or 1.0 + lo, hi = lo - pad, hi + pad + raw = (hi - lo) / count + mag = 10 ** math.floor(math.log10(raw)) + step = max(next(m * mag for m in (1, 2, 2.5, 5, 10) if m * mag >= raw), step_min) + first, last = math.floor(lo / step + 1e-9), math.ceil(hi / step - 1e-9) + return tuple(_clean(k * step) for k in range(first, last + 1)) + + +def _clean(v: float): + v = round(v, 10) + return int(v) if v == int(v) else v + + +def _tick(fmt: Callable, v) -> str: + return "0" if v == 0 else str(fmt(v)) + + +class _Scale: + """A linear map of ``ticks``' span onto [a, b] user units.""" + + def __init__(self, ticks: tuple, a: float, b: float): + self.ticks, self.lo, self.hi, self.a, self.b = ticks, ticks[0], ticks[-1], a, b + + def __call__(self, v: float) -> float: + return round(self.a + (v - self.lo) / (self.hi - self.lo) * (self.b - self.a), 2) + + +def _ticks_for(values: list, with_zero: bool) -> tuple: + """A metric's ticks: around its present values, from zero when its marks grow from zero.""" + if with_zero: + values = values + [0] + lo, hi = (min(values), max(values)) if values else (0, 1) + if with_zero and lo == hi == 0: + hi = 1 + whole = values and all(isinstance(v, int) for v in values) + return nice_ticks(lo, hi, step_min=1 if whole else 0) + + +def _x_labels(scale: _Scale, fmt: Callable, y: float) -> list: + """The labels of an x axis's ticks at ``y``, the end ones inside the panel. A label that would touch the one + before it is left out, the last one never: the gridlines still mark every tick.""" + last = len(scale.ticks) - 1 + kept = [] + for i, t in enumerate(scale.ticks): + text = _tick(fmt, t) + anchor = "start" if i == 0 else "end" if i == last else "middle" + x, w = scale(t), len(text) * _CHAR_W + x0 = {"start": x, "end": x - w, "middle": x - w / 2}[anchor] + while kept and kept[-1][1] + 6 > x0 and i == last and len(kept) > 1: + kept.pop() + if not kept or kept[-1][1] + 6 <= x0 or i == last: + kept.append((Text(x, y, (text,), anchor, "tick"), x0 + w)) + return [t for t, _ in kept] + + +def _rows(metric: Metric, with_zero: bool, mark: Callable) -> Panel: + """A row per item, its name over its mark, on one x axis: what bars and dots share. ``mark(v, scale, y)`` + gives the marks of ``v`` at the row's centre ``y``, none for a gap, and the x its reading starts at. The + gridlines and the baseline's reference cross each row's band only, never a name.""" + present = [v.value for v in metric.values if v.value is not None] + scale = _Scale(_ticks_for(present, with_zero), _LEFT, WIDTH - _RIGHT) + base = next((v for v in metric.values if v.baseline and v.value is not None), None) + base = base if len(present) > 1 else None + marks, texts, y = [], [], 4.0 + for v in metric.values: + lines = tuple(textwrap.wrap(v.name, _CHARS)) or ("",) + texts.append(Text(_LEFT, y + _LINE - 3, lines, cls="label")) + y += _LINE * len(lines) + mid = y + 4 + _BAR / 2 + top, bottom = mid - _BAR / 2 - 3, mid + _BAR / 2 + 3 + marks += [Mark("line", scale(t), top, x2=scale(t), y2=bottom, cls="grid") for t in scale.ticks] + if base: + marks.append(Mark("line", scale(base.value), top, x2=scale(base.value), y2=bottom, cls="ref", title=_title(base))) + drawn, at = mark(v, scale, mid) + marks += drawn + texts.append(Text(at, mid + 4, (v.text or "—",), cls="value" if drawn else "value none")) + y += 4 + _BAR + _ROW_GAP + bottom = y - _ROW_GAP + 2 + return Panel(metric.label, round(bottom + _AXIS, 2), tuple(marks), tuple(texts + _x_labels(scale, metric.fmt, bottom + 14)), + (("Name", metric.label), tuple((v.name, v.reading) for v in metric.values))) + + +def _title(v: Value) -> str: + return f"{v.name}: {v.reading}" + + +def bars(metric: Metric) -> Panel: + """A bar per item from zero; a present value always shows a mark, however small.""" + def bar(v, scale, mid): + if v.value is None: + return [], scale(0) + 4 + a, b = sorted((scale(0), scale(v.value))) + w = max(b - a, 1.5) + return [Mark("rect", a, mid - _BAR / 2, w=round(w, 2), h=_BAR, cls=v.cls("bar"), title=_title(v))], max(a + w, scale(0)) + 4 + return _rows(metric, True, bar) + + +def dots(metric: Metric) -> Panel: + """A dot per item on a track, the axis around the values rather than from zero: close values stay apart.""" + def dot(v, scale, mid): + if v.value is None: + return [], scale.b + 10 + return [Mark("line", scale.a, mid, x2=scale.b, y2=mid, cls="track"), + Mark("circle", scale(v.value), mid, r=_DOT, cls=v.cls("dot"), title=_title(v))], scale.b + 10 + return _rows(metric, False, dot) + + +_S_HEIGHT, _S_LEFT, _S_TOP, _S_BOTTOM = 270.0, 48.0, 22.0, 38.0 +_TAG_W, _TAG_H = 7.5, 13.0 # a tag's width per character and its height, at the template's font size + + +def _tag_box(px: float, py: float, width: float, side: str) -> tuple: + """Where a tag ``width`` wide goes on ``side`` of a dot at (px, py): (x, baseline, anchor, box).""" + gap = _DOT + 3 + x, base, anchor = {"right": (px + gap, py + 4, "start"), "left": (px - gap, py + 4, "end"), + "above": (px, py - gap - 2, "middle"), "below": (px, py + gap + 10, "middle")}[side] + x0 = {"start": x, "end": x - width, "middle": x - width / 2}[anchor] + return x, base, anchor, (x0, base - _TAG_H + 3, x0 + width, base + 3) + + +def _overlaps(a: tuple, b: tuple) -> bool: + return a[0] < b[2] and b[0] < a[2] and a[1] < b[3] and b[1] < a[3] + + +def scatter(x: Metric, y: Metric) -> Panel: + """A dot per item at (x, y), and its tag (``Value.tag``, else its place in the order) beside it, spelled out in a + key under the plot. Every item keeps its own dot: items at one place are set in a ring around it, each tag outward + from its dot. Any other tag takes the first side of its dot inside the plot and clear of the dots and tags before + it.""" + pairs = list(zip(x.values, y.values)) + tags = [a.tag or str(i + 1) for i, (a, _) in enumerate(pairs)] + shown = [(t, a, b) for t, (a, b) in zip(tags, pairs) if a.value is not None and b.value is not None] + left, right, top, bottom = _S_LEFT, WIDTH - 8, _S_TOP, _S_HEIGHT - _S_BOTTOM + # the scales inset from the frame, so a dot on the last tick is whole + sx = _Scale(_ticks_for([a.value for _, a, _ in shown], False), left + 12, right - 12) + sy = _Scale(_ticks_for([b.value for _, _, b in shown], False), bottom - 12, top + 12) + marks = [Mark("line", sx(t), top, x2=sx(t), y2=bottom, cls="grid") for t in sx.ticks] + marks += [Mark("line", left, sy(t), x2=right, y2=sy(t), cls="grid") for t in sy.ticks] + texts = _x_labels(sx, x.fmt, bottom + 14) + texts += [Text(left - 4, sy(t) + 4, (_tick(y.fmt, t),), "end", "tick") for t in sy.ticks] + texts += [Text(left, 12, (y.label,), cls="axis-title"), Text(right, bottom + 30, (x.label,), "end", "axis-title")] + places: dict = {} + for item in shown: + places.setdefault((sx(item[1].value), sy(item[2].value)), []).append(item) + dots = [] # (x, y, the tag's place on its ring or None, tag, x value, y value) + for (px, py), group in places.items(): + ring = max(_DOT * 2, len(group) * (2 * _DOT + 4) / (2 * math.pi)) if len(group) > 1 else 0.0 + for k, item in enumerate(group): + turn = 2 * math.pi * k / len(group) - math.pi / 2 + at = (round(px + (ring + 11) * math.cos(turn), 2), round(py + (ring + 11) * math.sin(turn) + 4, 2)) if ring else None + dots.append((round(px + ring * math.cos(turn), 2), round(py + ring * math.sin(turn), 2), at, *item)) + taken = [(px - _DOT, py - _DOT, px + _DOT, py + _DOT) for px, py, *_ in dots] + taken += [(tx - _TAG_W, ty - _TAG_H + 3, tx + _TAG_W, ty + 3) for _, _, (tx, ty), *_ in (d for d in dots if d[2])] + for px, py, at, tag, a, b in dots: + marks.append(Mark("circle", px, py, r=_DOT, cls=a.cls("dot"), + title=f"{tag} {a.name}: {x.label} {a.reading}, {y.label} {b.reading}")) + if at: # on a ring, the tag sits outward from its dot + texts.append(Text(*at, (tag,), "middle", "tag")) + continue + width = _TAG_W * len(tag) + spots = [_tag_box(px, py, width, side) for side in ("right", "left", "above", "below")] + inside = [s for s in spots if s[3][0] >= left and s[3][2] <= right and s[3][1] >= top and s[3][3] <= bottom] + tx, base, anchor, box = next((s for s in inside if not any(_overlaps(s[3], t) for t in taken)), (inside or spots)[0]) + taken.append(box) + texts.append(Text(tx, base, (tag,), anchor, "tag")) + key_y = _S_HEIGHT + 8 + key = _LEFT + (12 if any(a.series for a, _ in pairs) else 0) + drawn = {id(d[4]) for d in dots} + for tag, (a, _) in zip(tags, pairs): + # a name the caller numbered already (two runs of one agent) is not numbered twice + lines = tuple(textwrap.wrap(a.name if a.name.startswith(f"{tag}. ") else f"{tag}. {a.name}", _CHARS)) + if a.series: # its colour beside its name; the name says which it is + marks.append(Mark("rect", _LEFT, key_y - 8, w=8, h=8, cls=a.cls("swatch"))) + texts.append(Text(key, key_y, lines, cls="label" if id(a) in drawn else "label none")) + key_y += _LINE * len(lines) + rows = tuple((a.name, a.reading, b.reading) for a, b in pairs) + return Panel(f"{y.label} by {x.label}", round(key_y, 2), tuple(marks), tuple(texts), (("Name", x.label, y.label), rows)) + + +@dataclass(frozen=True) +class Style: + """A way to draw: its ``label``, the function, and the names of the metrics it takes, in its arguments' order.""" + + label: str + draw: Callable + axes: tuple + + +STYLES = { + "bars": Style("Bars", bars, ("Metric",)), + "dots": Style("Dots", dots, ("Metric",)), + "scatter": Style("Scatter", scatter, ("X", "Y")), +} diff --git a/app/static/style.css b/app/static/style.css index 150136ff..923fefb8 100644 --- a/app/static/style.css +++ b/app/static/style.css @@ -53,6 +53,11 @@ --cat-edit: #f5c274; /* L* 81 */ --cat-execute: #758e63; /* L* 56 */ --cat-plan: #ca90a9; /* L* 66 */ + /* A series of runs, the colour of each in every chart: muted blues, teal, brown, plum, never an outcome's green, + red or amber. Checked with the data-viz validator on each dark --surface-2 (charcoal, graphite and midnight keep + these): adjacent CVD ΔE ≥ 10.1, the first five apart ≥ 8.1, normal vision ≥ 15.2, contrast ≥ 3:1. */ + --series-1: #3a75bf; --series-2: #16a8a8; --series-3: #ad6a44; --series-4: #748ee3; + --series-5: #aa5d83; --series-6: #3aa0d4; --series-7: #7768be; --series-8: #38a3ba; --ph-verify: #f09bb8; --ok: #a5c5a8; --bad: #f26a62; @@ -124,6 +129,9 @@ --cat-edit: #b96c08; /* L* 53 */ --cat-execute: #405428; /* L* 33 */ --cat-plan: #984873; /* L* 42 */ + /* adjacent CVD ΔE ≥ 10.7, the first five apart ≥ 9.4, normal vision ≥ 15.2, contrast ≥ 3.07:1 on --surface-2 */ + --series-1: #215da5; --series-2: #179696; --series-3: #7d3f17; --series-4: #657dd1; + --series-5: #7e2e59; --series-6: #1587ba; --series-7: #5e5197; --series-8: #2695ac; --ph-verify: #b83a72; --ok: #3f6e4f; --bad: #c62f26; @@ -1443,6 +1451,24 @@ a.chip { text-decoration: none; } .ch-seg { transition: none; } } +/* ---- categorical charts (templates/_charts.html) ---- + The SVG scales with its box, so its text is sized in its own units. One mark colour, since the names say which + item is which; a check is hollow. */ +.fig-svg { display: block; width: 100%; height: auto; overflow: visible; font-family: var(--sans); } +.fig-svg text { font-size: 13px; fill: var(--text); font-variant-numeric: tabular-nums; } +.fig-svg text.label, .fig-svg text.axis-title { fill: var(--text-dim); } +.fig-svg text.tick, .fig-svg text.none { fill: var(--text-faint); } +.fig-svg text.tag { font-weight: 600; font-size: 11px; } +.fig-svg text:is(.value, .tag) { paint-order: stroke; stroke: var(--surface-2); stroke-width: 3px; stroke-linejoin: round; } /* a reference line under a value leaves it legible */ +.fig-svg :is(.grid, .track) { stroke: var(--border-soft); stroke-width: 1; } +.fig-svg .ref { stroke: var(--text-dim); stroke-width: 1.5; stroke-dasharray: 3 3; } +.fig-svg :is(.bar, .dot, .swatch) { fill: var(--c, var(--accent)); } +.fig-svg .dot { stroke: var(--surface-2); stroke-width: 2; } +.fig-svg .check { fill: var(--surface-2); stroke: var(--c, var(--text-dim)); stroke-width: 1.5; } +.fig-svg .s1 { --c: var(--series-1); } .fig-svg .s2 { --c: var(--series-2); } .fig-svg .s3 { --c: var(--series-3); } +.fig-svg .s4 { --c: var(--series-4); } .fig-svg .s5 { --c: var(--series-5); } .fig-svg .s6 { --c: var(--series-6); } +.fig-svg .s7 { --c: var(--series-7); } .fig-svg .s8 { --c: var(--series-8); } + .topbar .btn.sm { padding: .38rem .8rem; font-size: .82rem; } /* ---- the shell: left rail + content ---- diff --git a/app/templates/_charts.html b/app/templates/_charts.html new file mode 100644 index 00000000..5459dca2 --- /dev/null +++ b/app/templates/_charts.html @@ -0,0 +1,19 @@ +{#- A categorical chart (nullius/charts.py): `p`, a Panel, as an SVG of the marks and texts it was given, already + placed, and a table of its values for a screen reader. `id` names its title. #} +{% macro panel(p, id) %} + + {{ p.title }} + {% for m in p.marks %}{% set tip %}{% if m.title %}{{ m.title }}{% endif %}{% endset %} + {%- if m.shape == 'rect' %}{{ tip }} + {%- elif m.shape == 'circle' %}{{ tip }} + {%- else %}{{ tip }}{% endif %} + {% endfor %} + {% for t in p.texts %}{% for line in t.lines %}{{ line }}{% endfor %} + {% endfor %} + +
+ + {% for h in p.table[0] %}{% endfor %} + {% for row in p.table[1] %}{% for cell in row %}{% if loop.first %}{% else %}{% endif %}{% endfor %}{% endfor %} +
{{ p.title }}
{{ h }}
{{ cell }}{{ cell }}
+{% endmacro %} diff --git a/app/tests/field_contract.json b/app/tests/field_contract.json index 36c6c419..9da9cce2 100644 --- a/app/tests/field_contract.json +++ b/app/tests/field_contract.json @@ -110,6 +110,59 @@ "usable" ] }, + "categorical": { + "Mark": [ + "cls", + "h", + "r", + "shape", + "title", + "w", + "x", + "x2", + "y", + "y2" + ], + "Metric": [ + "fmt", + "label", + "values" + ], + "Panel": [ + "height", + "marks", + "table", + "texts", + "title", + "viewbox", + "width" + ], + "Style": [ + "axes", + "draw", + "label" + ], + "Text": [ + "anchor", + "cls", + "leading", + "lines", + "x", + "y" + ], + "Value": [ + "baseline", + "check", + "label", + "name", + "note", + "reading", + "series", + "tag", + "text", + "value" + ] + }, "charts": { "Bar": [ "count", diff --git a/app/tests/field_contract.py b/app/tests/field_contract.py index 36fb0c6a..5422bbe1 100644 --- a/app/tests/field_contract.py +++ b/app/tests/field_contract.py @@ -50,10 +50,10 @@ "conversation": "nullius.traces", "behavior": "nullius.traces", "comparison": "nullius.compare", "catalog": "nullius.catalogue", "benchmarks": "nullius.runs", - "harnesses": "nullius", "workspace": "nullius", + "harnesses": "nullius", "workspace": "nullius", "categorical": "nullius", } # Manifest keys whose importable module names differ. -MODULE_NAME = {"harnesses": "importers", "benchmarks": "verifier"} +MODULE_NAME = {"harnesses": "importers", "benchmarks": "verifier", "categorical": "charts"} MODULES = tuple(PACKAGE_OF) diff --git a/app/tests/test_categorical_charts.py b/app/tests/test_categorical_charts.py new file mode 100644 index 00000000..c7422b37 --- /dev/null +++ b/app/tests/test_categorical_charts.py @@ -0,0 +1,171 @@ +"""The categorical charts (nullius/charts.py): scales, gaps, checks and the style registry.""" + +import unittest + +from nullius import charts as c + + +def metric(*values, label="Metric", fmt=str): + return c.Metric(label, tuple(c.Value(label=f"run {i}", value=v, text="—" if v is None else str(v)) + for i, v in enumerate(values)), fmt) + + +def shapes(panel, cls): + return [m for m in panel.marks if cls in m.cls.split()] + + +class Ticks(unittest.TestCase): + def test_round_steps_enclose_the_range(self): + self.assertEqual(c.nice_ticks(0, 1), (0, 0.25, 0.5, 0.75, 1)) + self.assertEqual(c.nice_ticks(-3, 5), (-4, -2, 0, 2, 4, 6)) + self.assertEqual(c.nice_ticks(0.0012, 0.0031)[0], 0.001) + + def test_whole_counts_never_step_below_one(self): + self.assertEqual(c.nice_ticks(0, 3, step_min=1), (0, 1, 2, 3)) + + def test_long_tick_labels_that_would_touch_leave_one_out_never_the_last(self): + p = c.bars(metric(0, 32, 85, 4, fmt=lambda v: f"${v:.2f}")) + labels = [t for t in p.texts if t.cls == "tick"] + self.assertEqual([t.lines[0] for t in labels], ["0", "$25.00", "$50.00", "$100.00"]) + self.assertEqual(len([m for m in p.marks if m.cls == "grid"]) // 4, 5) # every tick keeps its gridline + + def test_one_value_still_has_a_range(self): + ticks = c.nice_ticks(5, 5) + self.assertLess(ticks[0], 5); self.assertGreater(ticks[-1], 5) + + +class Bars(unittest.TestCase): + def test_a_bar_per_present_value_from_zero_on_the_metric_s_own_axis(self): + p = c.bars(metric(2, 4)) + bars = shapes(p, "bar") + self.assertEqual(len(bars), 2) + self.assertEqual(bars[0].x, bars[1].x) # both grow from zero + self.assertAlmostEqual(bars[1].w, 2 * bars[0].w, delta=0.1) + ticks = [t.lines[0] for t in p.texts if t.cls == "tick"] + self.assertEqual(ticks[0], "0") + + def test_a_missing_value_is_a_gap_with_no_mark_never_zero(self): + p = c.bars(metric(3, None)) + self.assertEqual(len(shapes(p, "bar")), 1) + self.assertIn(("run 1", "—"), p.table[1]) + self.assertIn(("—",), [t.lines for t in p.texts if "none" in t.cls.split()]) + + def test_zero_and_negative_values_show_a_mark_on_each_side_of_zero(self): + p = c.bars(metric(-2, 0, 3)) + neg, zero, pos = shapes(p, "bar") + self.assertGreater(zero.w, 0) # a real zero is still drawn + self.assertAlmostEqual(neg.x + neg.w, zero.x, delta=0.01) # the negative bar ends at zero + self.assertEqual(pos.x, zero.x) + self.assertIn("0", [t.lines[0] for t in p.texts if t.cls == "tick"]) + + def test_a_check_is_drawn_hollow_and_named(self): + m = c.Metric("M", (c.Value("agent", 1, "1"), c.Value("oracle", 2, "2", check=True))) + p = c.bars(m) + self.assertEqual([b.cls for b in shapes(p, "bar")], ["bar", "bar check"]) + self.assertEqual(p.table[1][1][0], "oracle (check)") + + def test_the_baseline_is_a_reference_mark_at_its_value_in_each_row(self): + m = c.Metric("M", (c.Value("a", 2, "2", baseline=True), c.Value("b", 4, "4", "+2"))) + p = c.bars(m) + refs = shapes(p, "ref") + a, b = shapes(p, "bar") + self.assertEqual(len(refs), 2) # across each row's band, never its name + self.assertEqual({r.x for r in refs}, {round(a.x + a.w, 2)}) + self.assertEqual(p.table[1], (("a (baseline)", "2"), ("b", "4 +2"))) + + def test_a_single_run_has_no_reference_line(self): + p = c.bars(c.Metric("M", (c.Value("a", 2, "2", baseline=True),))) + self.assertEqual((len(shapes(p, "bar")), shapes(p, "ref")), (1, [])) + + def test_a_long_name_wraps_never_clips(self): + name = "agent " * 30 + p = c.bars(c.Metric("M", (c.Value(name, 1, "1"),))) + label = next(t for t in p.texts if t.cls == "label") + self.assertGreater(len(label.lines), 1) + self.assertEqual(" ".join(label.lines), name.strip()) + + def test_very_different_magnitudes_get_their_own_panels_and_axes(self): + panels = [c.bars(metric(0.002, 0.003)), c.bars(metric(4000, 9000))] + small, large = ([t.lines[0] for t in p.texts if t.cls == "tick"] for p in panels) + self.assertNotEqual(small[-1], large[-1]) + self.assertEqual(large[-1], "10000") + + +class Dots(unittest.TestCase): + def test_the_axis_is_around_the_values_so_close_values_stay_apart(self): + p = c.dots(metric(0.81, 0.83)) + a, b = shapes(p, "dot") + self.assertGreater(b.x - a.x, 50) + self.assertNotEqual([t.lines[0] for t in p.texts if t.cls == "tick"][0], "0") + + def test_a_gap_has_no_dot_and_no_track(self): + p = c.dots(metric(1, None)) + self.assertEqual((len(shapes(p, "dot")), len(shapes(p, "track"))), (1, 1)) + + +class Scatter(unittest.TestCase): + def test_every_run_keeps_its_own_dot_and_tag_and_ties_sit_around_one_place(self): + x, y = metric(40, 40, 40, 40, label="Trials"), metric(0, 0, 0, 3, label="Broke") + p = c.scatter(x, y) + dots = shapes(p, "dot") + self.assertEqual(len(dots), 4) + self.assertEqual(len({(d.x, d.y) for d in dots}), 4) # three at one place, set apart + self.assertEqual(sorted(t.lines[0] for t in p.texts if t.cls == "tag"), ["1", "2", "3", "4"]) + self.assertEqual([t.lines[0] for t in p.texts if t.cls.startswith("label")], ["1. run 0", "2. run 1", "3. run 2", "4. run 3"]) + self.assertEqual(p.table[0], ("Name", "Trials", "Broke")) + self.assertTrue(dots[0].title.startswith("1 run 0: Trials 40, Broke 0")) + + def test_tags_stay_inside_the_plot_and_clear_of_each_other(self): + values = [(0.40 + k * 0.002, 1 + k * 0.01) for k in range(7)] # a tight cluster + p = c.scatter(metric(*[a for a, _ in values]), metric(*[b for _, b in values])) + boxes = [] + for t in (t for t in p.texts if t.cls == "tag"): + w = c._TAG_W * len(t.lines[0]) + x0 = {"start": t.x, "end": t.x - w, "middle": t.x - w / 2}[t.anchor] + boxes.append((x0, t.y - c._TAG_H + 3, x0 + w, t.y + 3)) + self.assertEqual(len(boxes), 7) + for box in boxes: + self.assertGreaterEqual(box[0], c._S_LEFT); self.assertLessEqual(box[2], c.WIDTH - 8) + clear = sum(not any(c._overlaps(a, b) for b in boxes if b is not a) for a in boxes) + self.assertGreaterEqual(clear, 5) + + def test_a_tag_is_the_caller_s_and_a_run_missing_either_value_has_no_dot(self): + x = c.Metric("X", (c.Value("a", 1, "1", tag="3"), c.Value("b", None, "—", tag="5"), c.Value("d", 2, "2", tag="6"))) + p = c.scatter(x, metric(1, 2, 3)) + self.assertEqual(len(shapes(p, "dot")), 2) + self.assertEqual(sorted(t.lines[0] for t in p.texts if t.cls == "tag"), ["3", "6"]) + self.assertIn("label none", [t.cls for t in p.texts if t.lines[0].startswith("5")]) + numbered = c.Metric("X", (c.Value("3. a", 1, "1", tag="3"), c.Value("b", 2, "2", tag="4"))) + self.assertEqual([t.lines[0] for t in c.scatter(numbered, numbered).texts if t.cls == "label"], ["3. a", "4. b"]) + + +class Series(unittest.TestCase): + def test_marks_carry_their_series_cycling_after_eight_and_a_check_stays_hollow(self): + values = tuple(c.Value(f"run {n}", n, str(n), series=n, check=n == 3) for n in range(1, 11)) + bars = shapes(c.bars(c.Metric("M", values)), "bar") + self.assertEqual([b.cls for b in bars][:3], ["bar s1", "bar s2", "bar s3 check"]) + self.assertEqual([b.cls.split()[1] for b in bars][7:], ["s8", "s1", "s2"]) + dots = shapes(c.dots(c.Metric("M", values)), "dot") + self.assertEqual([d.cls.split()[1] for d in dots], [b.cls.split()[1] for b in bars]) + self.assertEqual(c.bars(metric(1, 2)).marks[-1].cls, "bar") # no series: no colour class + + def test_a_scatter_s_dots_and_key_share_each_run_s_colour(self): + x = c.Metric("X", tuple(c.Value(f"run {n}", n, str(n), series=n, tag=str(n)) for n in (1, 2, 9))) + p = c.scatter(x, x) + self.assertEqual([m.cls for m in shapes(p, "dot")], ["dot s1", "dot s2", "dot s1"]) + self.assertEqual([m.cls for m in shapes(p, "swatch")], ["swatch s1", "swatch s2", "swatch s1"]) + self.assertEqual([t.lines[0] for t in p.texts if t.cls == "label"], ["1. run 1", "2. run 2", "9. run 9"]) # the name too + + +class Registry(unittest.TestCase): + def test_each_style_names_the_metrics_it_draws_one_panel_from(self): + self.assertEqual({k: s.axes for k, s in c.STYLES.items()}, {"bars": ("Metric",), "dots": ("Metric",), "scatter": ("X", "Y")}) + for key, s in c.STYLES.items(): + p = s.draw(*(metric(1, 2, label=a) for a in s.axes)) + self.assertIsInstance(p, c.Panel, key) + self.assertTrue(s.label) + self.assertEqual(c.STYLES["scatter"].draw(metric(1, label="A"), metric(2, label="B")).title, "B by A") + + +if __name__ == "__main__": + unittest.main() From f9e1841aea866d163f6aff85fe03d50768bfa441 Mon Sep 17 00:00:00 2001 From: Harenome Ranaivoarivony-Razanajato Date: Wed, 18 Nov 2026 15:53:32 +0100 Subject: [PATCH 2/2] feat(compare): add a Chart view of the summary rows Compare gains a third view beside Side by side and Task by task. Each chart is a card. Its header holds a Style menu (Bars, Dots or Scatter), a Data menu of one metric, or X and Y menus for a scatter, each button naming its metric, and a Remove button. Add chart adds a card. The charts live in the URL, one chart= value each, and every link keeps them. The values are the side table's own cells, and a run's colour is its column's place, the same in every chart. --- app/static/compare/columns.js | 7 +- app/static/compare/comparison.css | 16 +- app/static/style.css | 8 +- app/templates/base.html | 1 + app/templates/compare/compare.html | 60 +++++++- app/ui_tests/test_comparison_routes.py | 140 ++++++++++++++++- app/web/compare.py | 199 +++++++++++++++++++------ docs/results.md | 3 +- 8 files changed, 365 insertions(+), 69 deletions(-) diff --git a/app/static/compare/columns.js b/app/static/compare/columns.js index 54f09072..4fbc29d8 100644 --- a/app/static/compare/columns.js +++ b/app/static/compare/columns.js @@ -116,11 +116,10 @@ window.NulliusCompare = { if (mine) this.entry(btn.querySelector('[data-run-label]'), mine); }, - /* Every column of the page, its cells in the rows they share, and the Order menu. A list opens only on its - button. */ + /* Every column of the page, its cells in the rows they share, the Order menu and each chart card's menus. A list + opens only on its button. */ wire(cfg) { - const order = document.querySelector('[data-order-btn]'); - if (order) NulliusTable.menu(order, order.nextElementSibling); + document.querySelectorAll('[data-order-btn], [data-chart-btn]').forEach(b => NulliusTable.menu(b, b.nextElementSibling)); const cols = []; document.querySelectorAll('[data-column]').forEach(c => (cols[+c.dataset.column] ||= []).push(c)); cols.forEach(cells => this.column(cells, cfg)); diff --git a/app/static/compare/comparison.css b/app/static/compare/comparison.css index b7407dbd..884e4ccc 100644 --- a/app/static/compare/comparison.css +++ b/app/static/compare/comparison.css @@ -13,7 +13,7 @@ .col-head { display: flex; flex-direction: column; gap: .4rem; min-width: 0; } .col-tools { display: flex; align-items: center; gap: .15rem; } .col-id { display: flex; flex-wrap: wrap; gap: .2rem .8rem; } -.col-tools .icon-btn { width: 26px; height: 26px; font-size: .9rem; text-decoration: none; } +.col-tools .icon-btn, .fig-head .icon-btn { width: 26px; height: 26px; font-size: .9rem; text-decoration: none; } .compare-baseline { margin-right: auto; color: var(--accent); font-size: .7rem; letter-spacing: .07em; text-transform: uppercase; } .col-ws, .col-run { width: 100%; min-width: 0; padding: .45rem .6rem; border: 1px solid var(--border); border-radius: 7px; font: .82rem var(--sans); color: var(--text); background: var(--surface); text-align: left; } .col-run { cursor: pointer; } @@ -136,3 +136,17 @@ overflow-wrap: anywhere; } .compare-table-wrap .grid.compare tr.pass-k th.rowhead { text-transform: none; letter-spacing: 0; font-family: var(--mono); } +/* The chart cards: as many to a row as fit, one to a row on a phone; each its style, its metrics and Remove. */ +.compare-chart { margin-top: 1.2rem; } +.figs { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 27rem), 1fr)); gap: 1rem; } /* 27rem: a Scatter's Style, X, Y and Remove on one row */ +.fig { padding: .7rem .9rem .9rem; border: 1px solid var(--border-soft); border-radius: 10px; background: var(--surface-2); min-width: 0; } +.fig-head { display: flex; align-items: flex-start; gap: .5rem; margin-bottom: .7rem; } +.fig-tools { display: flex; flex-wrap: wrap; gap: .5rem; min-width: 0; } /* the buttons wrap; Remove stays at the first row's end */ +.fig-head .btn { white-space: nowrap; } /* a button wraps to the next row whole, its name never cut */ +.fig-head .menu { max-height: min(60vh, 26rem); overflow-y: auto; } +.fig-head .menu legend { float: none; } /* a group of links: its name above them */ +.fig-head .icon-btn { flex: none; margin: calc((var(--tool-h) - 26px) / 2) 0 0 auto; } /* centred on the first row */ +.ic-letter { display: inline-grid; place-items: center; font: 600 .8rem/1 var(--sans); } /* a letter in an icon's place */ +.fig-head .tools-menu a::before { content: ""; flex: 0 0 1em; text-align: center; color: var(--accent); } /* every item keeps the check's slot, so the names align */ +.fig-head .tools-menu a[aria-current="true"]::before { content: "✓"; } /* the card's style or metric */ +.fig-note { margin: 0; font-size: .84rem; color: var(--text-dim); } diff --git a/app/static/style.css b/app/static/style.css index 923fefb8..8509c3ab 100644 --- a/app/static/style.css +++ b/app/static/style.css @@ -384,7 +384,7 @@ button.seg:hover { filter: brightness(1.25); } .table-buttons, .table-slot { display: flex; flex-wrap: wrap; justify-content: flex-end; align-items: center; gap: .75rem; } .table-buttons { margin-left: auto; } .table-buttons .menu { left: auto; right: 0; } /* opens leftwards, inside the page */ -.table-controls :is(.btn, .seg-toggle, .filter-pill) { height: var(--tool-h); } +.table-controls :is(.btn, .seg-toggle, .filter-pill), .fig-head .btn { height: var(--tool-h); } .table-controls .filter-pill { min-height: 0; padding-block: 0; } /* a segmented toggle: a bordered group of links or buttons, the current one marked */ .seg-toggle { display: inline-flex; padding: 3px; gap: 3px; border: 1px solid var(--border-soft); border-radius: 8px; background: var(--surface); } @@ -405,11 +405,11 @@ button.seg:hover { filter: brightness(1.25); } padding: .5rem; min-width: 168px; box-shadow: 0 8px 24px rgba(0, 0, 0, .3); display: flex; flex-direction: column; gap: .1rem; } -.menu label, .tools-menu > a { +.menu label, .tools-menu > a, .tools-menu fieldset > a { display: flex; align-items: center; gap: .5rem; cursor: pointer; font-size: .84rem; color: var(--text-dim); padding: .3rem .45rem; border-radius: 6px; } -.menu label:hover, .tools-menu > a:hover { background: var(--surface-2); color: var(--text); text-decoration: none; } +.menu label:hover, .tools-menu > a:hover, .tools-menu fieldset > a:hover { background: var(--surface-2); color: var(--text); text-decoration: none; } .menu input { accent-color: var(--accent); } .table-note { color: var(--text-faint); font-size: .8rem; } .table-pager { margin-top: .6rem; } @@ -497,7 +497,7 @@ button.seg:hover { filter: brightness(1.25); } .filter-pill:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; } .filter-pills > .ic { align-self: center; color: var(--text-dim); } .dd-chev { margin-right: -.2rem; } -[data-dropdown][aria-expanded="true"] .dd-chev { transform: rotate(180deg); } +[aria-expanded="true"] > .dd-chev { transform: rotate(180deg); } @media (prefers-reduced-motion: no-preference) { .dd-chev { transition: transform .24s ease; } } .btn.ghost.narrowed { border-color: var(--accent); color: var(--text); } /* a filter button whose column shows not every value */ .tools-count { margin-left: .4rem; padding: 0 .4em; border-radius: 99px; background: var(--accent-soft); color: var(--text); font-size: .72rem; font-variant-numeric: tabular-nums; } diff --git a/app/templates/base.html b/app/templates/base.html index 21cda119..40ecbf6d 100644 --- a/app/templates/base.html +++ b/app/templates/base.html @@ -73,6 +73,7 @@ + diff --git a/app/templates/compare/compare.html b/app/templates/compare/compare.html index 0ececc2a..2794fd92 100644 --- a/app/templates/compare/compare.html +++ b/app/templates/compare/compare.html @@ -2,6 +2,7 @@ {% from 'traces/_attempts.html' import attempt_count %} {% from '_tables.html' import classes, controls %} {% from '_page.html' import page_head %} +{% from '_charts.html' import panel as draw_panel %} {% extends "base.html" %} {% block title %}Compare {{ jobs|length }} run{{ '' if jobs|length == 1 else 's' }} — Nullius{% endblock %} {% block head %} @@ -88,21 +89,22 @@ {#- The controls row: the cohort, the view and the columns' order, then Add a run. #} {% macro side_views() %} {% if n_agents > 1 %}{% endif %}{% endmacro %} -{% macro side_actions() %}Add a run{% endmacro %} +{% macro side_actions() %}{% if view == 'chart' %}Add chart{% endif %}Add a run{% endmacro %} {#- one block, so the controls row sticks only as far as the table #}
{{ controls(view or 'side', [], sort=false, views=side_views, actions=side_actions) }} @@ -110,7 +112,49 @@ {% if cohort == 'matched' and not n_shared %}

No shared cohort is available. Choose runs with overlapping coverage or return to whole runs.

{% endif %} {% if comparison.datasets_known and not comparison.datasets_match %}

The recorded datasets differ: pick runs of the baseline's dataset to compare the same tasks.

{% endif %} {% endif %} -{% if not view %} +{% if view == 'chart' %} +{#- the columns' controls, as the tables open with, then the chart of their runs #} +
+ + {{ comparison_columns() }} + {{ column_controls('Column') }} + +
+
+{% if jobs %}
+{% if cards %}
+ {% for card in cards %}{% set k = loop.index0 %} +
+
+
+ + {% set n = loop.index %} + {% for axis in card.axes %} + + {% endfor %} +
+ +
+ {% if card.panel %}{{ draw_panel(card.panel, 'chart-' ~ loop.index) }}{% else %}

Not in this comparison.

{% endif %} +
+ {% endfor %} +
+{% else %}

Add chart

{% endif %} +
{% endif %} +{% elif not view %}
{{ comparison_columns() }} diff --git a/app/ui_tests/test_comparison_routes.py b/app/ui_tests/test_comparison_routes.py index 75d9893b..fdf5240d 100644 --- a/app/ui_tests/test_comparison_routes.py +++ b/app/ui_tests/test_comparison_routes.py @@ -308,7 +308,7 @@ def test_the_controls_row_holds_the_cohort_the_order_and_add_a_run(self): row = body[body.index('
'):body.index('
([A-Z][\w ]+)', row), [("views", "", "", ""), ("", "Comparison cohort", "", ""), ("", "", "", "Whole runs"), ("", "", "", "Matched tasks"), - ("", "Comparison view", "", ""), ("", "", "", "Side by side"), ("", "", "", "Task by task"), + ("", "Comparison view", "", ""), ("", "", "", "Side by side"), ("", "", "", "Task by task"), ("", "", "", "Chart"), ("", "", "i-reorder", ""), ("", "", "", "Order"), ("", "", "", "Group by agent"), ("", "", "", "Alternate agents"), ("actions", "", "", ""), ("", "", "i-plus", ""), ("", "", "", "Add a run")]) # Order opens a menu of the two one-off reorders, links that keep the cohort @@ -404,7 +404,8 @@ def test_the_view_is_side_by_side_or_task_by_task_and_every_link_keeps_it(self): switch = re.search(r'aria-label="Comparison view">(.*?)', row, re.S).group(1) # the view switch keeps the cohort and the picks self.assertEqual([query(h) for h in re.findall(r'href="([^"]+)"', switch)], - [{"pick": picks, "cohort": ["matched"]}, {"pick": picks, "cohort": ["matched"], "view": ["tasks"]}]) + [{"pick": picks, "cohort": ["matched"]}, {"pick": picks, "cohort": ["matched"], "view": ["tasks"]}, + {"pick": picks, "cohort": ["matched"], "view": ["chart"]}]) # the cohort switch, Order and Add a run keep the view links = [query(h) for h in re.findall(r'href="([^"]+)"', row.replace(switch, "")) if not h.startswith("#")] self.assertEqual(len(links), 5) @@ -423,13 +424,146 @@ def test_the_view_is_side_by_side_or_task_by_task_and_every_link_keeps_it(self): self.assertEqual([q["view"] for q in back], [["tasks"]] * 2) self.assertIn("url.searchParams.set('view', \"tasks\")", page) self.assertNotIn("searchParams.set('view'", self.get("/compare/task/shared", pick=picks, cohort="matched", dataset=self.left.dataset)) - # anything but view=tasks is side by side + # anything but view=tasks or chart is side by side self.assertIn('id="side" style', self.get(pick=picks, view="other")) # the old picker keeps it response = self.client.get("/compare/pick", query_string={"pick": picks, "view": "tasks"}) self.addCleanup(response.close) self.assertEqual(query(response.location)["view"], ["tasks"]) + # ---- the chart: the side table's summary rows, drawn, a card a chart ---- + + @staticmethod + def chart_of(body): + return body[body.index('
'):body.index("