Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 52 additions & 11 deletions SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -477,7 +477,8 @@ the page fetches it over HTTP. Served over HTTP the page can also read `?file=..
opens a file a reader chooses (read in the browser, sent nowhere). **The page works out no
class, no direction and no count of its own.** It reads them from the file, which the
validator has checked, and only adds the file's counts up: the classes that moved into
"moved", and a step's counts over its indicators. A file read by `?file=` or chosen by a
"moved", and a step's counts over its indicators. The one number it works out itself is
the median and percentiles of a distribution (10.3), and only from every item. A file read by `?file=` or chosen by a
reader has not passed through the validator: the page checks its shape only, says so above
everything it draws, and refuses a file it cannot draw instead of drawing part of it. A
matrix is held to the file it says it is of (title, states, indicators, steps, number of
Expand All @@ -490,12 +491,22 @@ stage, triage, ledger, layer, upstream, provider and candidate (a test holds thi

**The page is a matrix page.** From the top: the header (10.1); a row of chips that
chooses the comparison, the whole way first and then each step with its number, the values
that moved in it, a `!` where nothing explains it and a mark for each verdict worth a look;
one row of controls (name, group, class, verdict, the size filter) with the count and the
legend on its right; then the matrix (10.5), which opens an item in a drawer (10.6). Below
it, each closed until a reader opens it: the steps and the whole way (10.2), the
distributions (10.3), the worst values (10.4), the explanations and the rule (10.7). A
host's page never offers to open a file; it says only why nothing is drawn.
that moved in it, a `!` where nothing explains it and a mark for each verdict worth a look
(the arrow keys move between them); under the chips one line for the chosen step: the
states it goes between, what it is, its claim with who made it, what the claim found, its
tolerance and its noise; one row of controls (name, group, class, verdict, the size
filter) with the count and the legend in the row under it; then the matrix (10.5), which
opens an item in a drawer (10.6); directly under it, always open, the distributions of the
chosen comparison (10.3). The address keeps the chosen step and an open item
(`#step=<id>&item=<id>`), so that a reviewer can send someone to exactly that view. Below
them, each closed until a reader opens it: the steps and the whole way (10.2), the worst
values (10.4), the explanations and the rule (10.7). A host's page never offers to open a
file; it says only why nothing is drawn.

The line of the chosen step names every verdict on a move with its count, "as claimed"
first ("40 values moved as claimed, 2 off claim ◐"), and "Nothing moved, as claimed" only
where every count is zero. It gives them weight, not colour: a verdict is not an approval
(ADR 0010, A20).

### 10.1 Header
The title, the file's `about`, and one quiet line: how many items and indicators, how many
Expand All @@ -514,8 +525,33 @@ every class, up, down, the step that carries most of the difference (section 7),
over steps, not attributable, and moved by what nothing explains.

### 10.3 Distributions
Per indicator, the share of values in each band and class, down on the left, up on the
right. **Every indicator on the same scale**, so a tall bar means the same in each.
One card per indicator, in the order of the matrix's columns (10.5), for the comparison the
chips have chosen: a histogram of the file's own counts, from left to right a sign change,
the bands down from far to near, agrees and within noise (two bars, the band around 1),
the bands up from near to far, then zero reference, zero result, near zero and missing.
Every count is in its bar's title.

**Bar heights: each card to its own tallest bar by default**, with one scale for every card
(the share of all values) as a switch beside the legend. A step that moves a few values
of thousands moves them in most indicators by less than a pixel on one scale, and the
reviewer looks for exactly those; so each card says what its full height is ("tallest bar:
7", or on one scale "full height: 300 of 11 947"), and a bar of one value is never drawn as
large as a bar of thousands without that number beside it. An indicator in which nothing
moved and nothing is missing is quietened, as its column is.

Under each card, how many moved and are missing, and **the median, 10th and 90th
percentile of after ÷ before: the one statistic the page works out itself.** It is taken
only where the page holds every item (the matrix is loaded, or the file lists them all),
over the values with a ratio (both results neither zero nor missing, of one sign), and says
over how many ("Median of 11 893 ratios", and how many have none). From the listed items
alone it gives none and says why: they are the furthest apart, and their median would say
more than the whole holds. The three percentiles share one precision: the fewest digits
(three at least, six at most) at which every two that differ read differently, so that no
rounded number stands as exact beside a longer one. Where six still read a percentile as the
median, it says "just under the median" or "just over the median" instead of two equal
numbers, and the numbers left take the digits they need.

A card's title sorts the matrix by its indicator; a heading of the matrix marks its card.

### 10.4 Worst
The N worst values of one comparison (a step or the whole way), ordered by class (sign
Expand All @@ -525,7 +561,12 @@ ratio). The page always says how many it shows of how many, and how many items w
look the file does not hold.

### 10.5 Matrix
Items by indicator for one comparison: each cell with a ratio shows the result after
Items by indicator for the comparison the chips have chosen. **The indicators in which that
comparison moved most come first**, so that what a step did is in view without scrolling;
an indicator in which it moved nothing and nothing is missing comes last, quietened, and
keeps its column (a missing value counts with what moved: it is a finding, not stillness).
Choosing another comparison sorts the grid furthest-first again, since a new comparison
has a new order. In it: each cell with a ratio shows the result after
divided by the result before in three significant digits (`1.00`, `0.984`, `2.27`,
`1.01e−3`), agreeing pairs included, so that a column reads as numbers; a cell without one
says what the class says (from 0, to 0, + → −, missing, ≈ 0). The class shows as the tint
Expand Down Expand Up @@ -593,7 +634,7 @@ the page script (`tests/js/page.test.js`), so the two cannot drift apart unnotic
| A18 | The split is exact up to rounding, the page prints the sum it computed, and an item it cannot split is counted | rule, review of PR 2 | `test_a18`, node "A18" |
| A19 | Only `must` can be unmet, and it is unmet by a pair that stayed within the tolerance, the noise or the floor; empty scope means nothing moves; a zero reference is never within `largest`; a private claim list | sentier-bafu, sentier-agribalyse, review of PR 2 | `test_a19`, `test_a19b`, `Verdicts` |
| A20 | No status or acceptance field anywhere | sentier-bafu-agribalyse ADR 0010 | `test_a20` |
| A21 | Distributions are drawn on one scale | trial dashboard | checked by hand in a browser (not automated) |
| A21 | Distributions: each card says what its full height is; one scale for every card is a switch; percentiles only from every item, over the values with a ratio, with their number | trial dashboard, review of PR 21 | node "one scale", "a median of after ÷ before only from every item", "over how many ratios", "just under or over the median" |
| A22 | Coming closer to the reference is never called better | ADR 0009, sentier-bafu | `test_a22`, node "nothing drawn calls a move better or worse" |
| A23 | An indicator is matched by its exact id, not a prefix | backtest | `test_a23` |
| A24 | Results on one side only are counted, by side | sentier-bafu | `test_a24` |
Expand Down
19 changes: 12 additions & 7 deletions src/sentier_diagnostics/page/body.html
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ <h3>Open a file</h3>
<span class="sd-chips-label">Comparison</span>
<div class="sd-chip-row" data-sd="comparison"></div>
</div>
<div class="sd-step" data-sd="step-said" aria-live="polite"></div>
<p class="sd-note sd-grid-note">Each cell is the result after divided by the result before, for one <span data-sd-word="one">item</span> and <span data-sd-word="indicator">indicator</span>, in the comparison chosen above;
the grid opens with the <span data-sd-word="many">items</span> furthest apart. A heading sorts by that column. Choose a row (click it, or press Enter on it) to open the <span data-sd-word="one">item</span>.</p>
<div class="sd-controls">
Expand All @@ -45,6 +46,17 @@ <h3>Open a file</h3>
</div>
</div>

<section class="sd-dists-part" data-sd="distributions">
<h3>Distributions per <span data-sd-word="indicator">indicator</span></h3>
<p class="sd-note" data-sd="dist-said"></p>
<div class="sd-controls sd-dist-controls">
<label class="sd-field"><span>Bar heights</span>
<select data-sd="dist-scale"><option value="card">each card to its own tallest bar</option><option value="one">one scale for every card</option></select></label>
<p class="sd-legend" data-sd="dist-legend" aria-hidden="true"></p>
</div>
<div class="sd-dists" data-sd="dist-cards"></div>
</section>

<aside class="sd-drawer" data-sd="item" hidden>
<div class="sd-drawer-head">
<p class="sd-label" data-sd="item-meta"></p>
Expand All @@ -68,13 +80,6 @@ <h4 data-sd="total-heading">The whole way</h4>
<div class="sd-wrap"><table class="sd-table" data-sd="total-table"></table></div>
</details>

<details class="sd-section" data-sd="distributions">
<summary><h3>Distributions</h3></summary>
<p class="sd-note">Values per class and band, as a share of all values of the <span data-sd-word="indicator">indicator</span>, in the comparison chosen above. Every <span data-sd-word="indicator">indicator</span> is drawn on the same scale.</p>
<p class="sd-legend" data-sd="dist-legend"></p>
<div class="sd-wrap"><table class="sd-table" data-sd="dist-table"></table></div>
</details>

<details class="sd-section" data-sd="worst">
<summary><h3>Worst</h3></summary>
<div class="sd-controls">
Expand Down
56 changes: 47 additions & 9 deletions src/sentier_diagnostics/page/diagnostics.css
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,18 @@
.sentier-diagnostics .sd-chip-flag { font-weight: 800; color: var(--sd-fail); }
.sentier-diagnostics .sd-chip[aria-pressed="true"] .sd-chip-flag { color: inherit; }
.sentier-diagnostics .sd-chip-mark { font-size: var(--sd-t-xs); }

/* the line of the chosen step: what it compares, its claim and what the claim found, its rule */
.sentier-diagnostics .sd-step { margin: 0 0 var(--sd-s3); padding: var(--sd-s2) var(--sd-s4); border-left: 3px solid var(--sd-accent); border-radius: 0 var(--sd-radius) var(--sd-radius) 0; background: var(--sd-paper-deep); font-size: var(--sd-t-sm); }
.sentier-diagnostics .sd-step > p { margin: 0; }
.sentier-diagnostics .sd-step > p + p { margin-top: 0.25rem; }
.sentier-diagnostics .sd-claim-label { display: inline-block; margin-right: 0.5em; padding: 0 0.45em; border-radius: 3px; background: var(--sd-surface); font-size: var(--sd-t-xs); font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; color: var(--sd-muted); }
/* what a claim found: weight, not colour; a verdict is not an approval (ADR 0010) */
.sentier-diagnostics .sd-verdicts { font-weight: 700; }

/* an indicator in which the chosen comparison moved nothing: last, and quiet */
.sentier-diagnostics .sd-grid .sd-still { color: var(--sd-muted); opacity: 0.7; }
.sentier-diagnostics .sd-grid thead th.sd-still { font-weight: 400; }
.sentier-diagnostics .sd-grid-note { margin: 0 0 var(--sd-s2); }
.sentier-diagnostics .sd-matrix-said { margin: 0; font-size: var(--sd-t-xs); }
.sentier-diagnostics .sd-matrix-said:empty { display: none; }
Expand All @@ -99,8 +111,8 @@
.sentier-diagnostics .sd-controls { display: flex; flex-wrap: wrap; align-items: flex-end; gap: var(--sd-s2) var(--sd-s4); margin: var(--sd-s3) 0; }
.sentier-diagnostics .sd-filters { display: flex; flex: 1 1 auto; flex-wrap: wrap; align-items: flex-end; gap: var(--sd-s2) var(--sd-s3); min-width: 0; }
/* the count and the legend on the right of the filters, as in a dashboard's control row */
.sentier-diagnostics .sd-controls > .sd-status { flex: 0 1 34rem; gap: 0.15rem; flex-direction: column; align-items: flex-end; text-align: right; }
.sentier-diagnostics .sd-controls > .sd-status .sd-legend { justify-content: flex-end; margin: 0; }
.sentier-diagnostics .sd-controls > .sd-status { flex: 1 1 100%; gap: 0.15rem var(--sd-s4); flex-direction: row; flex-wrap: wrap; align-items: baseline; justify-content: space-between; text-align: left; }
.sentier-diagnostics .sd-controls > .sd-status .sd-legend { margin: 0; }
.sentier-diagnostics .sd-field { display: flex; flex-direction: column; gap: 0.2rem; font-size: var(--sd-t-sm); }
.sentier-diagnostics .sd-field > span { font-size: var(--sd-t-xs); font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; color: var(--sd-muted); }
.sentier-diagnostics .sd-grow { flex: 0 1 20rem; }
Expand Down Expand Up @@ -166,13 +178,39 @@
.sentier-diagnostics .sd-legend > span { min-width: 0; overflow-wrap: anywhere; }
.sentier-diagnostics .sd-legend .key { display: inline-block; white-space: nowrap; min-width: 2.6em; margin-right: 0.3em; padding: 0 0.3em; border: 1px solid var(--sd-line); border-radius: 3px; text-align: center; color: var(--sd-ink); }

/* distributions */
.sentier-diagnostics .bar-cell { min-width: 2.6rem; }
.sentier-diagnostics .bar { display: flex; align-items: flex-end; height: 2.2rem; }
.sentier-diagnostics .bar span { display: block; width: 100%; min-height: 0; background: var(--sd-muted); }
.sentier-diagnostics .bar.up span { background: var(--sd-up); }
.sentier-diagnostics .bar.down span { background: var(--sd-down); }
.sentier-diagnostics .bar-n { font-size: var(--sd-t-xs); text-align: center; color: var(--sd-muted); }
/* the distributions: one card per indicator, as many in a row as fit, under the matrix */
.sentier-diagnostics .sd-dists-part { margin: var(--sd-s6) 0 var(--sd-s5); }
.sentier-diagnostics .sd-dists-part > h3 { margin: 0 0 var(--sd-s2); font-size: var(--sd-t-lg); }
.sentier-diagnostics .sd-dist-controls { margin: var(--sd-s2) 0 0; align-items: center; }
.sentier-diagnostics .sd-dist-controls .sd-legend { margin: 0; }
.sentier-diagnostics .sd-dists { display: grid; grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr)); gap: var(--sd-s3); margin-top: var(--sd-s3); }
.sentier-diagnostics .sd-dist { position: relative; display: flex; flex-direction: column; min-width: 0; padding: var(--sd-s3) var(--sd-s4); border: 1px solid var(--sd-line); border-radius: var(--sd-radius); background: var(--sd-surface); }
.sentier-diagnostics .sd-dist:hover { border-color: var(--sd-accent); }
.sentier-diagnostics .sd-dist.sd-chosen { border-color: var(--sd-accent); box-shadow: inset 0 3px 0 var(--sd-accent); }
.sentier-diagnostics .sd-dist.sd-still { opacity: 0.6; }
.sentier-diagnostics .sd-dist > h4 { margin: 0 0 var(--sd-s2); min-height: 2.6em; font-size: var(--sd-t-sm); line-height: 1.3; }
/* the title is the button; it covers the card, so that the whole card is the target */
.sentier-diagnostics .sd-dist-pick { padding: 0; border: 0; background: none; color: inherit; font: inherit; font-weight: 700; text-align: left; cursor: pointer; }
.sentier-diagnostics .sd-dist-pick::after { content: ""; position: absolute; inset: 0; border-radius: var(--sd-radius); }
.sentier-diagnostics .sd-dist-pick:focus-visible { outline: none; }
.sentier-diagnostics .sd-dist-pick:focus-visible::after { outline: 2px solid var(--sd-accent); outline-offset: 2px; }
.sentier-diagnostics .sd-top { margin: 0 0 0.15rem; font-size: 0.7rem; line-height: 1.2; color: var(--sd-muted); text-align: right; font-variant-numeric: tabular-nums; }
.sentier-diagnostics .sd-hist { display: flex; align-items: flex-end; gap: 2px; height: 4.5rem; border-bottom: 1px solid var(--sd-line-strong); }
.sentier-diagnostics .sd-bin { flex: 1 1 0; min-width: 0; border-radius: 1px 1px 0 0; }
.sentier-diagnostics .sd-bin.sd-gap { margin-left: 5px; }
.sentier-diagnostics .sd-bin.down, .sentier-diagnostics .sd-bin-key.down { background: color-mix(in srgb, var(--sd-down) 70%, var(--sd-surface)); }
.sentier-diagnostics .sd-bin.up, .sentier-diagnostics .sd-bin-key.up { background: color-mix(in srgb, var(--sd-up) 80%, var(--sd-surface)); }
.sentier-diagnostics .sd-bin.mid, .sentier-diagnostics .sd-bin-key.mid { background: color-mix(in srgb, var(--sd-ink) 72%, var(--sd-surface)); }
.sentier-diagnostics .sd-bin.aside, .sentier-diagnostics .sd-bin-key.aside { background: var(--sd-noise); background-image: repeating-linear-gradient(135deg, transparent 0 3px, rgba(255, 255, 255, 0.35) 3px 5px); }
.sentier-diagnostics .sd-bin-key { display: inline-block; width: 0.8em; height: 0.8em; margin-right: 0.35em; border-radius: 2px; vertical-align: -0.05em; }
.sentier-diagnostics .sd-axis { display: flex; gap: 2px; margin-top: 0.2rem; font-size: 0.7rem; line-height: 1.2; color: var(--sd-muted); white-space: nowrap; }
.sentier-diagnostics .sd-axis > span { flex: 1 1 0; min-width: 0; overflow: hidden; text-overflow: clip; }
.sentier-diagnostics .sd-axis-mid { text-align: center; }
.sentier-diagnostics .sd-axis-up { text-align: right; }
.sentier-diagnostics .sd-axis-aside + .sd-axis-down, .sentier-diagnostics .sd-axis-up + .sd-axis-aside { margin-left: 5px; }
.sentier-diagnostics .sd-axis-up + .sd-axis-aside { text-align: right; }
.sentier-diagnostics .sd-dist-meta { margin: var(--sd-s2) 0 0; font-size: var(--sd-t-xs); line-height: 1.45; color: var(--sd-muted); font-variant-numeric: tabular-nums; }
.sentier-diagnostics .sd-dist-meta strong { color: var(--sd-ink); }

/* who wrote what */
.sentier-diagnostics .badge { display: inline-block; margin-right: 0.4em; padding: 0 0.5em; border: 1px solid var(--sd-line); border-radius: 999px; font-size: var(--sd-t-xs); }
Expand Down
Loading
Loading