diff --git a/GLOSSARY.md b/GLOSSARY.md index 00ac68f..6043bc0 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -7,7 +7,7 @@ The words this repository uses, each in one line. [SPEC.md](SPEC.md) says the re - **Reference unit**: the unit an item's result is per (kg, MJ, machine hour). Floors are kept apart per unit. - **State**: one set of results. The first may be the published results; the others are builds. - **Step**: from one state to the next, with its kind, claim, tolerance and noise. -- **Step 0**: the reproduction of the published results. The start, never the target. +- **Step 0**: the reproduction of the published results. The start, never the target. A chain that does not start from the published results has no step 0: its steps are numbered from 1. - **Chain**: the states in order and the steps between them. - **Pair**: one item in one indicator, before and after a step. - **Class**: what a pair is, by one rule: agrees, within noise, differs, beyond 10x, zero reference, zero result, sign change, near zero, missing. @@ -25,3 +25,7 @@ The words this repository uses, each in one line. [SPEC.md](SPEC.md) says the re - **Breakdown**: what one item's result is made of, before and after one step. - **Tier**: whether a file lists items (`items`) or holds counts only (`counts`). - **Audience**: whether a file's writer says it may be published (`public`) or not (`local`). +- **Listed items**: the items a file holds, the worst first, up to `listed`. +- **Matrix**: every item of a local file, listed or not, in a second file the page loads after it has drawn. +- **Body**: the page as one element a site holds in its own page; its style stays inside it. +- **Drawer**: the panel of one item, at the right of the page, opened from a row. diff --git a/README.md b/README.md index 3f940e8..e08f4da 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,10 @@ sentier-agribalyse and others): - a chain of steps from the published results to the current build, each held against what it claimed to move, with the whole difference split between the steps (exactly, up to the rounding the page shows) and what nothing explains named; -- a static page that shows it, with no build step, no server and no network. +- a page that shows it: a frameless body a site holds in its own page, with a style + scoped to it that takes the site's tokens, or a page of its own with no build step, no + server and no network; a local file can carry a matrix of every item, which the page + loads after it has drawn. The published results are checked once, at the start (step 0). Every later step is compared with the step before it. @@ -26,7 +29,17 @@ database. Scoring and the readers of each database stay in the projects that use PYTHONPATH=src python3 -m sentier_diagnostics example --out build/example ``` -Then open `build/example/page/index.html`. The example is made up. +Then open `build/example/page/index.html`, or `build/example/local/page/index.html` for a +local file whose page loads the matrix of every item. The example is made up. + +In a site's own page: + +```python +from sentier_diagnostics import page + +html = page.body(data, title=False) # one
, the file inside +assets = page.assets() # diagnostics.js and diagnostics.css, to copy +``` Install it in a project, pinned to a tag: diff --git a/SPEC.md b/SPEC.md index fbe6969..20d5d03 100644 --- a/SPEC.md +++ b/SPEC.md @@ -119,6 +119,7 @@ control characters, bounded lengths. | `audience` | `"local"` (the default) or `"public"`: whether its writer says it may be published. The tool checks only that it is one of the two; a site's own check decides what it accepts. A page of a local file says so at its top | | `title`, `about` | Short text; `about` may be null | | `item` | `{"one": "product", "many": "products"}`: the word for an item | +| `indicator` | Optional. `{"one": "impact category", "many": "impact categories"}`: the word for an indicator, which the page and the summary use; null or absent for "indicator" | | `indicators` | `[{id, name, short, unit}]`. An indicator is matched by its exact id, never by a prefix | | `rule` | The floors and the tolerance of the whole way (section 5) | | `states` | `[{id, label, about, kind, identity, join}]` in order. `identity` is a short table of texts (commit, release, machine); `join` is what the reader counted when it matched its rows to items: `{compared, unmatched, ambiguous, note}`, or null | @@ -130,6 +131,7 @@ control characters, bounded lengths. | `explanations` | Section 8 | | `notes` | Up to 20 texts | | `made_by` | `"sentier-diagnostics 0.1.0"` | +| `matrix` | Optional. `{"file": name, "items": n}`: the full matrix of every item, a second file beside this one (section 4.5); null or absent for none. Only a local file of items names one, and `items` is `items_count.all` | A **block** counts one indicator in one step, or over the whole way: @@ -189,6 +191,42 @@ many items as a file may (5,000); a state's identity has up to 12 entries. Ids a 100 characters, labels 80, texts 600 and an explanation's text 2,000. The limits are in `fileformat.py`, and a refusal names the limit it met. +### 4.5 The matrix of every item + +A file lists the items worth a look, up to `listed`. A project looking at its own build +wants every item: `chain.build_with_matrix` writes them in a second file of format +`sentier-diagnostics-matrix/1`, which the page loads after it has drawn. Only a local file +of items has one; a public file keeps its listed items only. A reader that writes CSV tables +names it in its description (`"matrix": "matrix.json"`), and `sentier-diagnostics build` +writes it beside the file. + +```json +{"format": "sentier-diagnostics-matrix/1", + "of": {"title": "...", "states": ["a", "b", "c"], "indicators": ["x:climate", "x:water"], "steps": ["s0", "s1"]}, + "items": [["p01", "Wheat", "FR", "crops", "kg"], ...], + "values": [[0.52, 0.53, 0.47, 1.2, 1.2, null], ...], + "classes": ["=Dd===", ...], + "verdicts": ["a.==", ...]} +``` + +One row per item, in the order of the listed items (worst first): `[id, name, place, +group, unit]`; the results per indicator and state, indicator after indicator; per +indicator one code per step and one for the whole way; and, where a step has a claim, per +indicator one verdict code per step (`.` for a step without a claim; `verdicts` is null when +no step has one). The class codes are `=` agrees, `~` within noise, `0` near zero, `-` +missing, and for a pair that moved its class in upper case up and lower case down: `D` +differs, `B` beyond 10x, `R` zero reference, `T` zero result, `S` sign change. The verdict +codes are `a` as claimed, `o` off claim, `n` not claimed, `c` claimed, not moved, `~` within +noise, `=` unchanged, `?` not judged. A matrix holds no band: it follows from the results. + +`matrix.errors(m)` checks the shape and never raises. `matrix.against(m, data)` works every +code out again with the file's floors, tolerances and noise (and every verdict where the +claim's lists are in the file), and holds the file to it: with every item at hand, its +counts, attribution, `items_count.all` and `qualifying` must be what the matrix holds, +exactly, and every listed item must be in the matrix with the same name and results. +`sentier-diagnostics check` does both when the matrix lies beside its file. A matrix holds +up to 200,000 items and 64 MB. + ## 5. The counting rule ### 5.1 One class per pair @@ -405,34 +443,115 @@ sentier-agribalyse's sums over ecoinvent processes and may not be published. ## 10. Views -A static page: `index.html`, `diagnostics.js`, `diagnostics.css`. No build step, no -server, no network, no font or script from elsewhere. `sentier-diagnostics page FILE --out -FOLDER` writes it with the file beside it as `data.js`, so it opens from disk; served over -HTTP it can also read `?file=...`, and it 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 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. Whatever the file says, only an `https://` address becomes a link. +**One body for a site and for a page of its own.** `page.body(data)` is the diagnostics as +one element, `
`, with the file +(and its breakdowns) inside it as JSON: no ``, `` or ``, and no id, so a +site may hold it anywhere, even twice. The site loads `diagnostics.js` and +`diagnostics.css` from `page.assets()`; the script mounts into every such element (a site +that draws it later marks it `="manual"` and calls `SentierDiagnostics.mount(element, +{data})`). `data-sd-base` names where the files it loads lie, and `title=False` leaves the +heading to the site. The script sets the document's title only on a page of its own. + +**The style is scoped.** Every rule of `diagnostics.css` is under `.sentier-diagnostics`; +it sets no font, nothing on `:root`, `html` or `body`, and resets inside its root what a +site does to bare tables (borders, phone layouts that turn rows into blocks). Its colours +are `--sd-*` properties that take the site's tokens where the site sets them +(`--sd-ink: var(--ink, #1d232a)`, and so on for `--muted`, `--surface`, `--paper-deep`, +`--line`, `--line-strong`, `--index`, `--fail`, `--radius`, `--t-*`, `--s*`); up, down and +noise keep colours of their own (amber up, teal down), so that a direction never takes a +site's accent. A test reads the sheet and holds this. + +**A host lets the body be wide.** The matrix needs the page's width, and a site that caps +the children of an article at a reading measure (`.prose > * { max-width: 44rem }`) caps +the body with them, which leaves a 25-indicator grid a few columns wide. A host lifts that +cap for the body, as sentier-bafu does: +`.prose > .sentier-diagnostics { max-width: none }` (and the same for any wrapper of the +page that holds a measure). + +`sentier-diagnostics page FILE --out FOLDER` writes a page of its own: `index.html` with +the body in it, the two assets, and `standalone.css`, which sets the tokens and font a site +would. It opens from disk; no build step, no server, no network, no font or script from +elsewhere. Where the file names a matrix that lies beside it, the page writes it as +`matrix.js`, which loads from disk too; a site serving `matrix.json` needs nothing else, as +the page fetches it over HTTP. Served over HTTP the page can also read `?file=...`, and it +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. 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 +items, the length of every row) before a row of it is drawn; its codes are checked by +`sentier-diagnostics check`, not again in the browser. Whatever the file says, only an +`https://` address becomes a link. The text a page renders comes from the file or from words chosen to be neutral: it avoids stage, triage, ledger, layer, upstream, provider and candidate (a test holds this). +**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 +(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=&item=`), 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 -Title, the states in order (with their identity and join counts), the file's tier, how many -items it holds of how many worth a look, and a banner for a local file. +The title, the file's `about`, and one quiet line: how many items and indicators, how many +it holds of how many worth a look, and, for a local file, that its writer has not said it +may be published (a quiet part of the line, as a site's own notice, not a box). The states +in order, with their identity and join counts, head the steps (10.2). ### 10.2 Steps and the whole way +Steps are numbered from 0 where the first state is `published`: step 0 is then the +reproduction (rule 1 of section 1). A chain that starts from a build of its own has no +reproduction, and its steps are numbered from 1. + One row per step: kind, explained or not, the claim and its origin, moved, up, down, the verdicts, missing before and after, tolerance and noise. Then the whole way per indicator: every class, up, down, the step that carries most of the difference (section 7), spread 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 @@ -441,16 +560,44 @@ sizes lie apart (`|log10(after/before)|`, or the relative difference where there ratio). The page always says how many it shows of how many, and how many items worth a look the file does not hold. -### 10.5 Grid -Items by indicator for one comparison, filtered by text, class, verdict and group, paged by -100 with "show more". The reader's **size filter** ("size at least ×1.1 ... ×10") hides -smaller changes here and in the worst list; zeros, sign changes and missing values always -show, and the page says the filter changes no count. +### 10.5 Matrix +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 +and a mark, never in place of the number: an agreeing cell has no tint, one within noise +is marked `~`, one beyond 10x `»`. A `1.00` with a tint is a pair that moved by less than +the rounding shows; its title holds both results exactly. The cell's colour is its +direction's and its strength the band's; for a matrix row, which holds no band, the +band is named from the results as the rule names it (a test holds the two equal). The ratio +and the shading are a display: they change no class. The listed items, or every item once +the matrix is loaded, a dot marking the listed ones; the page says which it holds and why +(none named, loading, loaded, or the reason it was not loaded). **The grid opens with the +items furthest apart**: by the largest factor between the two results over every +indicator, among the values that moved and have a ratio; then the items whose moves have +none (from or to zero, a sign change), by their worst value in the order of 10.4; then +those that did not move. A heading sorts by how far the two lie apart in that indicator, +the furthest first (the order of 10.4), or by name, and a second click goes back; +filters by text, group, class and verdict; 300 rows at a time with "show more". The +reader's **size filter** ("size at least ×1.1 ... ×10") hides smaller changes here and in +the worst list; zeros, sign changes and missing values always show, and the page says the +filter changes no count. ### 10.6 Item -Both sides in every state, the class, verdict and signed share of each step, the share -nothing explains and the sum of the shares (or why there are none: section 7), its -explanations, and its breakdowns where they are in the file and fit the item and step. +A drawer at the right (the whole window on a phone), opened from a row of the matrix or the +worst list, closed with Close or Escape. First **why it differs**: the explanations about +the item, then those about a step or an indicator in which it moved (said to be so, as they +may not be about it), or "none given" when the file holds neither; the file holds every +explanation, so this "none" is never said over a part of a list. Then per indicator, the +one whose whole way lies furthest apart first: both sides in every state, the class, +verdict and signed share of each step, the share nothing explains and the sum of the shares +(or why there are none: section 7). Then its breakdowns where they are in the file and fit +the item and step. ### 10.7 Explanations and rule Every explanation with its origin badge; the rule with its tolerances, noise, floors and @@ -487,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` | @@ -508,7 +655,14 @@ line on ordinary mistakes, never a traceback; the summary escapes the file's tex Markdown; noise is taken beyond the floor, and a scope entry read from tables without `expect` may move; the page draws the example whole under Node with a small stand-in for the DOM (`tests/js/dom.js`), loads nothing from elsewhere and writes no markup from data; -the committed example is what the code makes, holds every class and every verdict, and no +the page takes the matrix the Python writes and refuses one of another file, loads it as a +script or over HTTP after it has drawn, draws 300 rows at a time, sorts by a heading, and +opens the drawer with "why it differs" first (node tests); `matrix.against` finds a changed +code, direction, result, verdict or count (`tests/test_matrix_page.py`); `page.body` is one +root with no frame and no id, and its data cannot end the element that holds it; every +selector of the style is inside the root, with no font and nothing on `:root` or `body`; +the committed examples (the public file, and the local file with its matrix in +`examples/local/`) are what the code makes, the public one holds every class and every verdict, and no tracked file carries an identifier-shaped string (`tests/test_repository.py`). ## 12. Out of scope @@ -568,7 +722,8 @@ sentier-bafu-agribalyse wrote their requirements. What became of each: | Closer and further not at the head of a later step | bafu, ADR 0009 | yes: counted, never shown as better | | A chain of more than two states, each step's share | all three | yes | | `listed` named and counted apart from what moved | bafu | yes: `items_count` | -| The page fetches its data as a file | bafu | yes: `data.js` beside the page, or `?file=` | +| The page fetches its data as a file | bafu | yes: the data inside the body, or `window.SENTIER_DIAGNOSTICS` from a site's own `data.js` (`page.as_script`), or `?file=` | +| Every item, not only the listed ones, on a local page | bafu | yes: the matrix (section 4.5), loaded after the page is drawn | | Noise per item | bafu | no: later | | The number of digits written | bafu | values are written unrounded; a rounded source is a tolerance basis | | Symmetric bands, floor of 1 % of the median per indicator | bafu | yes, and per unit | @@ -576,7 +731,9 @@ sentier-bafu-agribalyse wrote their requirements. What became of each: | A test that the script agrees with the Python rule | bafu | yes: shared cases | | A formatter target at the lowest Python | bafu | yes: `py310`, CI runs 3.10 to 3.14 | | Standard library only; assets as package data with their paths | bafu, bafu-agribalyse | yes: `page.assets()` | -| A page without a frame, with a list of tokens for a site's frame | bafu, bafu-agribalyse | no: later (the page has its own tokens) | +| A page without a frame, with a list of tokens for a site's frame | bafu, bafu-agribalyse | yes: `page.body`, a scoped style whose `--sd-*` take the site's tokens (section 10) | +| The grid as the trial dashboard reads: a ratio in every cell, a strong tint, the furthest apart first, compact columns | bafu (from Manuel, 17 November 2026) | yes (section 10.5); 25 indicators still scroll sideways at a laptop's width | +| The look of the trial dashboard: a sortable grid, a drawer for an item | bafu-agribalyse | yes: its look and structure; none of its values, and not its two definitions of agreement, its hand-written labels or a "none" over a top-N list (section 10) | | Reading version 1 and 2 files, or a converter | bafu | no: see section 13 and the migration plan | | A tier a site check can refuse on | bafu, bafu-agribalyse | yes: `tier` (items or counts) and `audience` (public or local) | | Join accounting per reference | bafu-agribalyse | yes: `join` per state | @@ -589,6 +746,8 @@ sentier-bafu-agribalyse wrote their requirements. What became of each: | Per-product table of all categories, distributions, drill-down, written reasons | agribalyse (from the backtest) | yes: grid, distributions, item view, explanations | | Run identity on the page | agribalyse | yes: each state's `identity` | | Indicators not hardcoded | agribalyse | yes: from the file | +| The file's own word for an indicator ("impact category") | bafu | yes: the optional `indicator` | +| No step 0 in a chain that does not start from the published results | bafu | yes: its steps are numbered from 1 (section 10.2) | | Readable without JavaScript for the counts; 375 px wide | bafu-agribalyse | 375 px: yes, no sideways scroll of the page (tables scroll inside their frame; checked in a browser). Without JavaScript: the summary is Markdown; a no-script page is later | ## 15. Open questions diff --git a/examples/local/diagnostics.json b/examples/local/diagnostics.json new file mode 100644 index 0000000..def56d0 --- /dev/null +++ b/examples/local/diagnostics.json @@ -0,0 +1,1112 @@ +{ + "format": "sentier-diagnostics/1", + "tier": "items", + "audience": "local", + "title": "A made-up chain: published results to the current build", + "about": "Made-up results of ten items in three indicators. Nobody's data.", + "item": { + "one": "product", + "many": "products" + }, + "indicators": [ + { + "id": "x:climate", + "name": "Climate change", + "short": "Climate", + "unit": "kg CO2 eq" + }, + { + "id": "x:water", + "name": "Water use", + "short": "Water", + "unit": "m3" + }, + { + "id": "x:tox", + "name": "Human toxicity", + "short": "Toxicity", + "unit": "CTUh" + } + ], + "rule": { + "floor_factor": 0.01, + "floors_from": "published", + "beyond": 10.0, + "total_tolerance": 0.0005, + "floors": [ + { + "indicator": "x:climate", + "unit": "MJ", + "value": 0.0003, + "basis": "median", + "n": 1 + }, + { + "indicator": "x:climate", + "unit": "h", + "value": 0.42, + "basis": "median", + "n": 1 + }, + { + "indicator": "x:climate", + "unit": "kg", + "value": 0.0049, + "basis": "median", + "n": 8 + }, + { + "indicator": "x:water", + "unit": "MJ", + "value": 4.000000000000001e-06, + "basis": "median", + "n": 1 + }, + { + "indicator": "x:water", + "unit": "h", + "value": 0.009000000000000001, + "basis": "median", + "n": 1 + }, + { + "indicator": "x:water", + "unit": "kg", + "value": 0.011000000000000001, + "basis": "median", + "n": 7 + }, + { + "indicator": "x:tox", + "unit": "MJ", + "value": 3e-11, + "basis": "median", + "n": 1 + }, + { + "indicator": "x:tox", + "unit": "h", + "value": 0.0, + "basis": "none", + "n": 0 + }, + { + "indicator": "x:tox", + "unit": "kg", + "value": 1.95e-09, + "basis": "median", + "n": 8 + } + ] + }, + "states": [ + { + "id": "published", + "label": "Published", + "about": "What the publisher released.", + "kind": "published", + "identity": { + "release": "1.0" + }, + "join": { + "compared": 10, + "unmatched": 1, + "ambiguous": 0, + "note": "One published row names no item of the build." + } + }, + { + "id": "repro", + "label": "Recomputed", + "about": null, + "kind": "build", + "identity": { + "commit": "0000001" + }, + "join": null + }, + { + "id": "fix-1", + "label": "With fix 1", + "about": null, + "kind": "build", + "identity": { + "commit": "0000002" + }, + "join": null + }, + { + "id": "rebuilt", + "label": "Rebuilt", + "about": null, + "kind": "build", + "identity": { + "commit": "0000002", + "machine": "second" + }, + "join": null + }, + { + "id": "mapping-2", + "label": "With mapping 2", + "about": null, + "kind": "build", + "identity": { + "commit": "0000003" + }, + "join": null + } + ], + "steps": [ + { + "id": "step-0", + "from": "published", + "to": "repro", + "label": "Reproduction", + "about": "The released data computed again with the same method.", + "kind": "reproduction", + "explained": true, + "link": null, + "claim": { + "text": "Nothing moves beyond the rounding of the published results.", + "by": { + "kind": "code", + "name": "reproduction rule", + "model": null, + "run_by": null + }, + "reach": null, + "scope": [] + }, + "tolerance": { + "value": 0.0005, + "basis": "published rounding", + "note": "four significant digits" + }, + "noise": { + "measured": false, + "between": null, + "by": null, + "note": null + } + }, + { + "id": "fix-1", + "from": "repro", + "to": "fix-1", + "label": "Fertiliser amounts of two cereals", + "about": "The nitrogen amounts of wheat and rice were per hectare, not per kilogram.", + "kind": "fix", + "explained": true, + "link": "https://example.org/findings/fix-1", + "claim": { + "text": "Wheat and rice go down in climate change, by 30 % at most. Nothing else moves.", + "by": { + "kind": "person", + "name": "A. Author", + "model": null, + "run_by": null + }, + "reach": 2, + "scope": [ + { + "indicators": [ + "x:climate" + ], + "items": [ + "p01", + "p05" + ], + "direction": "down", + "largest": 0.3, + "expect": "must" + } + ] + }, + "tolerance": { + "value": 1e-05, + "basis": "default", + "note": "one order of magnitude above the solver noise of two builds" + }, + "noise": { + "measured": false, + "between": null, + "by": null, + "note": null + } + }, + { + "id": "rebuilt", + "from": "fix-1", + "to": "rebuilt", + "label": "Built again on another machine", + "about": "The same state, built on a second machine.", + "kind": "rebuild", + "explained": false, + "link": null, + "claim": null, + "tolerance": { + "value": 1e-05, + "basis": "default", + "note": "one order of magnitude above the solver noise of two builds" + }, + "noise": { + "measured": false, + "between": null, + "by": null, + "note": null + } + }, + { + "id": "mapping-2", + "from": "rebuilt", + "to": "mapping-2", + "label": "Mapping change 2", + "about": "Five items take another background dataset.", + "kind": "mapping", + "explained": true, + "link": null, + "claim": { + "text": "Items whose supply chain reaches the changed links may move in water use; maize must.", + "by": { + "kind": "code", + "name": "reach of the changed links", + "model": null, + "run_by": null + }, + "reach": 4, + "scope": [ + { + "indicators": [ + "x:water" + ], + "items": [ + "p02", + "p04", + "p07", + "p10" + ], + "direction": "any", + "largest": null, + "expect": "may" + }, + { + "indicators": [ + "x:water" + ], + "items": [ + "p02" + ], + "direction": "up", + "largest": 0.5, + "expect": "must" + } + ] + }, + "tolerance": { + "value": 1e-05, + "basis": "default", + "note": "one order of magnitude above the solver noise of two builds" + }, + "noise": { + "measured": true, + "between": [ + "fix-1", + "rebuilt" + ], + "by": { + "x:climate": 0.0, + "x:water": 0.02439024390243894, + "x:tox": 0.0 + }, + "note": "One pair of builds of one state." + } + } + ], + "counts": { + "steps": { + "step-0": { + "x:climate": { + "pairs": 10, + "classes": { + "agrees": 10, + "within noise": 0, + "differs": 0, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 0, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 0, + "off claim": 0, + "not claimed": 0, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 10, + "not judged": 0 + }, + "closer": null, + "further": null + }, + "x:water": { + "pairs": 10, + "classes": { + "agrees": 9, + "within noise": 0, + "differs": 0, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 1 + }, + "missing": { + "before": 1, + "after": 0, + "both": 0 + }, + "directions": { + "up": 0, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 0, + "off claim": 0, + "not claimed": 0, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 9, + "not judged": 1 + }, + "closer": null, + "further": null + }, + "x:tox": { + "pairs": 10, + "classes": { + "agrees": 7, + "within noise": 0, + "differs": 1, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 2, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 1, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 1, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 0, + "off claim": 0, + "not claimed": 1, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 7, + "not judged": 2 + }, + "closer": null, + "further": null + } + }, + "fix-1": { + "x:climate": { + "pairs": 10, + "classes": { + "agrees": 7, + "within noise": 0, + "differs": 3, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 1, + "down": 2 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 1, + "down, factor 1.1-1.25": 1, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 1, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 1, + "off claim": 1, + "not claimed": 1, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 7, + "not judged": 0 + }, + "closer": 0, + "further": 3 + }, + "x:water": { + "pairs": 10, + "classes": { + "agrees": 10, + "within noise": 0, + "differs": 0, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 0, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 0, + "off claim": 0, + "not claimed": 0, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 10, + "not judged": 0 + }, + "closer": 0, + "further": 0 + }, + "x:tox": { + "pairs": 10, + "classes": { + "agrees": 8, + "within noise": 0, + "differs": 0, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 2, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 0, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 0, + "off claim": 0, + "not claimed": 0, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 8, + "not judged": 2 + }, + "closer": 0, + "further": 0 + } + }, + "rebuilt": { + "x:climate": { + "pairs": 10, + "classes": { + "agrees": 10, + "within noise": 0, + "differs": 0, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 0, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": null, + "closer": 0, + "further": 0 + }, + "x:water": { + "pairs": 10, + "classes": { + "agrees": 8, + "within noise": 0, + "differs": 1, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 1 + }, + "missing": { + "before": 0, + "after": 1, + "both": 0 + }, + "directions": { + "up": 1, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 1, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": null, + "closer": 0, + "further": 1 + }, + "x:tox": { + "pairs": 10, + "classes": { + "agrees": 8, + "within noise": 0, + "differs": 0, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 2, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 0, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": null, + "closer": 0, + "further": 0 + } + }, + "mapping-2": { + "x:climate": { + "pairs": 10, + "classes": { + "agrees": 7, + "within noise": 0, + "differs": 0, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 1, + "sign change": 1, + "near zero": 0, + "missing": 1 + }, + "missing": { + "before": 0, + "after": 1, + "both": 0 + }, + "directions": { + "up": 1, + "down": 1 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 0, + "off claim": 0, + "not claimed": 2, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 7, + "not judged": 1 + }, + "closer": 0, + "further": 2 + }, + "x:water": { + "pairs": 10, + "classes": { + "agrees": 7, + "within noise": 1, + "differs": 0, + "beyond 10x": 1, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 1 + }, + "missing": { + "before": 1, + "after": 0, + "both": 0 + }, + "directions": { + "up": 1, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 1 + }, + "verdicts": { + "as claimed": 1, + "off claim": 0, + "not claimed": 0, + "claimed, not moved": 1, + "within noise": 1, + "unchanged": 6, + "not judged": 1 + }, + "closer": 0, + "further": 1 + }, + "x:tox": { + "pairs": 10, + "classes": { + "agrees": 7, + "within noise": 0, + "differs": 1, + "beyond 10x": 0, + "zero reference": 1, + "zero result": 0, + "sign change": 0, + "near zero": 1, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 1, + "down": 1 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 1, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": { + "as claimed": 0, + "off claim": 0, + "not claimed": 2, + "claimed, not moved": 0, + "within noise": 0, + "unchanged": 7, + "not judged": 1 + }, + "closer": 0, + "further": 2 + } + } + }, + "total": { + "x:climate": { + "pairs": 10, + "classes": { + "agrees": 4, + "within noise": 0, + "differs": 3, + "beyond 10x": 0, + "zero reference": 0, + "zero result": 1, + "sign change": 1, + "near zero": 0, + "missing": 1 + }, + "missing": { + "before": 0, + "after": 1, + "both": 0 + }, + "directions": { + "up": 2, + "down": 3 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 1, + "down, factor 1.1-1.25": 1, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 0, + "up, factor 1.1-1.25": 1, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": null, + "closer": null, + "further": null + }, + "x:water": { + "pairs": 10, + "classes": { + "agrees": 6, + "within noise": 0, + "differs": 2, + "beyond 10x": 1, + "zero reference": 0, + "zero result": 0, + "sign change": 0, + "near zero": 0, + "missing": 1 + }, + "missing": { + "before": 1, + "after": 0, + "both": 0 + }, + "directions": { + "up": 3, + "down": 0 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 0, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 1, + "up, factor 1.1-1.25": 1, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 1 + }, + "verdicts": null, + "closer": null, + "further": null + }, + "x:tox": { + "pairs": 10, + "classes": { + "agrees": 6, + "within noise": 0, + "differs": 2, + "beyond 10x": 0, + "zero reference": 1, + "zero result": 0, + "sign change": 0, + "near zero": 1, + "missing": 0 + }, + "missing": { + "before": 0, + "after": 0, + "both": 0 + }, + "directions": { + "up": 2, + "down": 1 + }, + "bands": { + "down, factor over 10": 0, + "down, factor 2-10": 0, + "down, factor 1.25-2": 1, + "down, factor 1.1-1.25": 0, + "down, factor 1-1.1": 0, + "up, factor 1-1.1": 1, + "up, factor 1.1-1.25": 0, + "up, factor 1.25-2": 0, + "up, factor 2-10": 0, + "up, factor over 10": 0 + }, + "verdicts": null, + "closer": null, + "further": null + } + } + }, + "attribution": { + "x:climate": { + "dominant": { + "step-0": 0, + "fix-1": 3, + "rebuilt": 0, + "mapping-2": 2 + }, + "not_attributable": 0, + "spread": 0, + "unexplained_moved": 0 + }, + "x:water": { + "dominant": { + "step-0": 0, + "fix-1": 0, + "rebuilt": 1, + "mapping-2": 1 + }, + "not_attributable": 1, + "spread": 0, + "unexplained_moved": 1 + }, + "x:tox": { + "dominant": { + "step-0": 1, + "fix-1": 0, + "rebuilt": 0, + "mapping-2": 2 + }, + "not_attributable": 0, + "spread": 0, + "unexplained_moved": 0 + } + }, + "items": [ + {"id": "p08", "name": "Compost, used as fertiliser", "place": "CH", "group": "waste", "unit": "kg", "values": {"x:climate": [-0.5, -0.5, -0.5, -0.5, 0.2], "x:water": [0.05, 0.05, 0.05, 0.05, 0.05], "x:tox": [-2e-06, -2e-06, -2e-06, -2e-06, -4e-06]}, "classes": {"x:climate": ["agrees", "agrees", "agrees", "sign change", "sign change"], "x:water": ["agrees", "agrees", "agrees", "agrees", "agrees"], "x:tox": ["agrees", "agrees", "agrees", "differs", "differs"]}, "directions": {"x:climate": [null, null, null, "up", "up"], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, "down", "down"]}, "bands": {"x:climate": [null, null, null, null, null], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, "down, factor 1.25-2", "down, factor 1.25-2"]}, "verdicts": {"x:climate": ["unchanged", "unchanged", null, "not claimed"], "x:water": ["unchanged", "unchanged", null, "unchanged"], "x:tox": ["unchanged", "unchanged", null, "not claimed"]}, "breakdowns": null}, + {"id": "p09", "name": "Machine hour, harvesting", "place": "CH", "group": "services", "unit": "h", "values": {"x:climate": [42.0, 42.00042, 42.00042, 42.00042, 42.00042], "x:water": [0.9, 0.9, 0.9, 0.9, 0.9], "x:tox": [0.0, 0.0, 0.0, 0.0, 4e-07]}, "classes": {"x:climate": ["agrees", "agrees", "agrees", "agrees", "agrees"], "x:water": ["agrees", "agrees", "agrees", "agrees", "agrees"], "x:tox": ["near zero", "near zero", "near zero", "zero reference", "zero reference"]}, "directions": {"x:climate": [null, null, null, null, null], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, "up", "up"]}, "bands": {"x:climate": [null, null, null, null, null], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, null, null]}, "verdicts": {"x:climate": ["unchanged", "unchanged", null, "unchanged"], "x:water": ["unchanged", "unchanged", null, "unchanged"], "x:tox": ["not judged", "not judged", null, "not claimed"]}, "breakdowns": null}, + {"id": "p07", "name": "Heat from wood chips", "place": "CH", "group": "energy", "unit": "MJ", "values": {"x:climate": [0.03, 0.03, 0.03, 0.03, 0.0], "x:water": [0.0004, 0.0004, 0.0004, 0.0004, 0.0004], "x:tox": [3e-09, 3e-09, 3e-09, 3e-09, 3e-09]}, "classes": {"x:climate": ["agrees", "agrees", "agrees", "zero result", "zero result"], "x:water": ["agrees", "agrees", "agrees", "agrees", "agrees"], "x:tox": ["agrees", "agrees", "agrees", "agrees", "agrees"]}, "directions": {"x:climate": [null, null, null, "down", "down"], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, null, null]}, "bands": {"x:climate": [null, null, null, null, null], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, null, null]}, "verdicts": {"x:climate": ["unchanged", "unchanged", null, "not claimed"], "x:water": ["unchanged", "unchanged", null, "unchanged"], "x:tox": ["unchanged", "unchanged", null, "unchanged"]}, "breakdowns": null}, + {"id": "p10", "name": "Tomato, greenhouse", "place": "NL", "group": "crops", "unit": "kg", "values": {"x:climate": [1.3, 1.3, 1.3, 1.3, 1.3], "x:water": [0.02, 0.02, 0.02, 0.02, 0.5], "x:tox": [2.1e-07, 2.3e-07, 2.3e-07, 2.3e-07, 2.3e-07]}, "classes": {"x:climate": ["agrees", "agrees", "agrees", "agrees", "agrees"], "x:water": ["agrees", "agrees", "agrees", "beyond 10x", "beyond 10x"], "x:tox": ["differs", "agrees", "agrees", "agrees", "differs"]}, "directions": {"x:climate": [null, null, null, null, null], "x:water": [null, null, null, "up", "up"], "x:tox": ["up", null, null, null, "up"]}, "bands": {"x:climate": [null, null, null, null, null], "x:water": [null, null, null, "up, factor over 10", "up, factor over 10"], "x:tox": ["up, factor 1-1.1", null, null, null, "up, factor 1-1.1"]}, "verdicts": {"x:climate": ["unchanged", "unchanged", null, "unchanged"], "x:water": ["unchanged", "unchanged", null, "as claimed"], "x:tox": ["not claimed", "unchanged", null, "unchanged"]}, "breakdowns": null}, + {"id": "p05", "name": "Rice", "place": "IT", "group": "crops", "unit": "kg", "values": {"x:climate": [1.9, 1.9, 0.95, 0.95, 0.95], "x:water": [3.4, 3.4, 3.4, 3.4, 3.4], "x:tox": [1e-12, 1e-12, 1e-12, 1e-12, 3e-12]}, "classes": {"x:climate": ["agrees", "differs", "agrees", "agrees", "differs"], "x:water": ["agrees", "agrees", "agrees", "agrees", "agrees"], "x:tox": ["near zero", "near zero", "near zero", "near zero", "near zero"]}, "directions": {"x:climate": [null, "down", null, null, "down"], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, null, null]}, "bands": {"x:climate": [null, "down, factor 1.25-2", null, null, "down, factor 1.25-2"], "x:water": [null, null, null, null, null], "x:tox": [null, null, null, null, null]}, "verdicts": {"x:climate": ["unchanged", "off claim", null, "unchanged"], "x:water": ["unchanged", "unchanged", null, "unchanged"], "x:tox": ["not judged", "not judged", null, "not judged"]}, "breakdowns": null}, + {"id": "p03", "name": "Barley", "place": "DE", "group": "crops", "unit": "kg", "values": {"x:climate": [0.48, 0.47999, 0.575988, 0.575988, 0.575988], "x:water": [1.1, 1.1, 1.1, null, 1.3], "x:tox": [1.9e-07, 1.9e-07, 1.9e-07, 1.9e-07, 1.9e-07]}, "classes": {"x:climate": ["agrees", "differs", "agrees", "agrees", "differs"], "x:water": ["agrees", "agrees", "missing", "missing", "differs"], "x:tox": ["agrees", "agrees", "agrees", "agrees", "agrees"]}, "directions": {"x:climate": [null, "up", null, null, "up"], "x:water": [null, null, null, null, "up"], "x:tox": [null, null, null, null, null]}, "bands": {"x:climate": [null, "up, factor 1.1-1.25", null, null, "up, factor 1.1-1.25"], "x:water": [null, null, null, null, "up, factor 1.1-1.25"], "x:tox": [null, null, null, null, null]}, "verdicts": {"x:climate": ["unchanged", "not claimed", null, "unchanged"], "x:water": ["unchanged", "unchanged", null, "not judged"], "x:tox": ["unchanged", "unchanged", null, "unchanged"]}, "breakdowns": null} + ], + "items_count": { + "all": 10, + "qualifying": 10, + "listed": 6, + "not_listed": 4 + }, + "explanations": [ + { + "about": { + "step": "fix-1", + "indicator": "x:climate", + "item": null + }, + "finding": "reason", + "text": "The fertiliser amounts were per hectare; divided by the yield they are per kilogram, which lowers the nitrogen field emissions of both cereals.", + "by": { + "kind": "person", + "name": "A. Author", + "model": null, + "run_by": null + }, + "source": { + "link": null, + "doc": "docs/findings/fix-1.md" + }, + "not_checked": null + }, + { + "about": { + "step": null, + "indicator": "x:tox", + "item": "p05" + }, + "finding": "reason", + "text": "The toxicity results of rice lie far below one hundredth of the median result of the items measured per kilogram: they are counted as near zero.", + "by": { + "kind": "code", + "name": "floor rule", + "model": null, + "run_by": null + }, + "source": null, + "not_checked": null + }, + { + "about": { + "step": "mapping-2", + "indicator": "x:water", + "item": "p10" + }, + "finding": "reason", + "text": "The new mapping links tomatoes to a greenhouse heated with fresh water from a well, which multiplies the water use.", + "by": { + "kind": "model", + "name": null, + "model": "example-model-1", + "run_by": "example maintainers (agent-run)" + }, + "source": null, + "not_checked": "Nobody compared the greenhouse's water balance with a second source." + }, + { + "about": { + "step": "step-0", + "indicator": "x:tox", + "item": "p08" + }, + "finding": "none found", + "text": "Compost's toxicity result fell to almost nothing in the reproduction. The recipe, the background datasets and the method were compared; none of them explains it.", + "by": { + "kind": "person", + "name": "B. Reviewer", + "model": null, + "run_by": null + }, + "source": null, + "not_checked": null + } + ], + "notes": [ + "A made-up example: nobody's data." + ], + "made_by": "sentier-diagnostics 0.1.0", + "matrix": { + "file": "matrix.json", + "items": 10 + } +} diff --git a/examples/local/matrix.json b/examples/local/matrix.json new file mode 100644 index 0000000..7945f66 --- /dev/null +++ b/examples/local/matrix.json @@ -0,0 +1,50 @@ +{"format": "sentier-diagnostics-matrix/1", "of": {"title": "A made-up chain: published results to the current build", "states": ["published", "repro", "fix-1", "rebuilt", "mapping-2"], "indicators": ["x:climate", "x:water", "x:tox"], "steps": ["step-0", "fix-1", "rebuilt", "mapping-2"]}, + "items": [ + ["p08","Compost, used as fertiliser","CH","waste","kg"], + ["p09","Machine hour, harvesting","CH","services","h"], + ["p07","Heat from wood chips","CH","energy","MJ"], + ["p10","Tomato, greenhouse","NL","crops","kg"], + ["p05","Rice","IT","crops","kg"], + ["p03","Barley","DE","crops","kg"], + ["p01","Wheat","FR","crops","kg"], + ["p04","Oats","DE","crops","kg"], + ["p06","Rye","PL","crops","kg"], + ["p02","Maize","FR","crops","kg"] + ], + "values": [ + [-0.5,-0.5,-0.5,-0.5,0.2,0.05,0.05,0.05,0.05,0.05,-2e-06,-2e-06,-2e-06,-2e-06,-4e-06], + [42.0,42.00042,42.00042,42.00042,42.00042,0.9,0.9,0.9,0.9,0.9,0.0,0.0,0.0,0.0,4e-07], + [0.03,0.03,0.03,0.03,0.0,0.0004,0.0004,0.0004,0.0004,0.0004,3e-09,3e-09,3e-09,3e-09,3e-09], + [1.3,1.3,1.3,1.3,1.3,0.02,0.02,0.02,0.02,0.5,2.1e-07,2.3e-07,2.3e-07,2.3e-07,2.3e-07], + [1.9,1.9,0.95,0.95,0.95,3.4,3.4,3.4,3.4,3.4,1e-12,1e-12,1e-12,1e-12,3e-12], + [0.48,0.47999,0.575988,0.575988,0.575988,1.1,1.1,1.1,null,1.3,1.9e-07,1.9e-07,1.9e-07,1.9e-07,1.9e-07], + [0.52,0.520013,0.468012,0.468012,0.468012,1.2,1.2,1.2,1.2000001,1.2000001,2e-07,2.0000002e-07,2.0000002e-07,2.0000002e-07,2.0000002e-07], + [0.45,0.45,0.45,0.45,0.45,1.0,1.0,1.0,1.025,1.0455,1.7e-07,1.7e-07,1.7e-07,1.7e-07,1.7e-07], + [0.43,0.43,0.43,0.43,null,null,1.15,1.15,1.15,1.15,2.1e-07,2.1e-07,2.1e-07,2.1e-07,2.1e-07], + [0.41,0.41,0.41,0.41,0.41,2.5,2.500025,2.500025,2.500025,2.500025,1.8e-07,1.8e-07,1.8e-07,1.8e-07,1.8e-07] + ], + "classes": [ + "===SS========dd", + "==========000RR", + "===tt==========", + "========BBD===D", + "=d==d=====00000", + "=D==D==--D=====", + "=d==d==========", + "=======D~D=====", + "===---===-=====", + "===============" + ], + "verdicts": [ + "==.n==.===.n", + "==.===.=??.n", + "==.n==.===.=", + "==.===.an=.=", + "=o.===.=??.?", + "=n.===.?==.=", + "=a.===.===.=", + "==.===.~==.=", + "==.??=.===.=", + "==.===.c==.=" + ] +} diff --git a/src/sentier_diagnostics/chain.py b/src/sentier_diagnostics/chain.py index b207c86..905b12a 100644 --- a/src/sentier_diagnostics/chain.py +++ b/src/sentier_diagnostics/chain.py @@ -26,7 +26,7 @@ from collections.abc import Iterable, Mapping from pathlib import Path -from . import __version__, claims, fileformat, rule +from . import __version__, claims, fileformat, matrix, rule FILE = "diagnostics.json" @@ -103,17 +103,23 @@ def step(id: str, label: str, *, kind: str, explained: bool = True, about: str | def state(id: str, label: str, *, kind: str = "build", about: str | None = None, - identity: Mapping[str, str] | None = None, join: Mapping | None = None) -> dict: # fmt: skip + identity: Mapping[str, str | None] | None = None, join: Mapping | None = None) -> dict: # fmt: skip """One state: a set of results. `kind` is "published" for the results its publisher released. + `identity` is a short table of texts (commit, release, machine); an entry whose value is + None is left out, so that a writer can pass what it may not know. + `join` is what the reader that made the state counted when it matched its rows to items: `{"compared": n, "unmatched": n, "ambiguous": n, "note": text or None}`. + + >>> state("b", "Build", identity={"commit": "0e1f5be", "machine": None})["identity"] + {'commit': '0e1f5be'} """ if join is not None: join = {"compared": join["compared"], "unmatched": join.get("unmatched", 0), "ambiguous": join.get("ambiguous", 0), "note": join.get("note")} # fmt: skip return {"id": id, "label": label, "about": about, "kind": kind, - "identity": dict(identity or {}), "join": join} # fmt: skip + "identity": {k: v for k, v in (identity or {}).items() if v is not None}, "join": join} # fmt: skip def explanation(text: str, by: dict, *, step: str | None = None, indicator: str | None = None, @@ -170,7 +176,21 @@ def _values(values, states, indicators) -> dict: return found -def build( +def build(title: str, **given) -> dict: + """A whole chain, counted, judged, attributed and checked: the file, without a matrix. + The keywords are those of `_build`, whose docstring says what each one holds.""" + return _build(title, **given)[0] + + +def build_with_matrix(title: str, *, matrix_file: str = "matrix.json", **given) -> tuple[dict, dict]: + """The file and its full matrix (`sentier_diagnostics.matrix`): every item with its + results and codes, the worst first, in a second file named `matrix_file` that the file + names. Only a local file of items has one.""" + data, found = _build(title, matrix_file=matrix_file, **given) + return data, found + + +def _build( title: str, *, indicators: Iterable, @@ -180,6 +200,7 @@ def build( units: Mapping[str, str | None] | None = None, names: Mapping[str, Mapping] | None = None, item_word: tuple[str, str] = ("item", "items"), + indicator_word: tuple[str, str] | None = None, about: str | None = None, floors: Mapping[tuple[str, str | None], float] | None = None, floor_factor: float = rule.FLOOR_FACTOR, @@ -190,8 +211,10 @@ def build( explanations: Iterable[dict] = (), notes: Iterable[str] = (), breakdowns: Mapping[str, Mapping[str, str]] | None = None, -) -> dict: - """A whole chain, counted, judged, attributed and checked. + matrix_file: str | None = None, +) -> tuple[dict, dict | None]: + """A whole chain, counted, judged, attributed and checked, and its matrix where + `matrix_file` names one. - `indicators`: `(id, name, short, unit)` or dicts with those keys. - `states`: `state(...)`, in order; `steps`: `step(...)`, one fewer than the states. @@ -209,7 +232,10 @@ def build( - `audience`: "local" (the default: for the people who made it) or "public" (its writer says it may be published). The tool checks only that it is one of the two. - `breakdowns`: `{item id: {step id or "total": file name}}`. + - `matrix_file`: the name of the full matrix, for a local file of items; None for none. """ + if matrix_file is not None and (tier != "items" or audience != "local"): + raise ValueError("only a local file of items has a matrix: a public file keeps the listed items only") meta = [_indicator(i) for i in indicators] ids = [i["id"] for i in meta] if len(steps) != len(states) - 1: @@ -371,8 +397,8 @@ def worst(item): shown = qualifying[: max(0, listed)] if tier == "items" else [] breakdowns = breakdowns or {} any_claim = any(s.get("claim") for s in steps) - out_items = [] - for item in shown: + + def record_of(item): about_item = names.get(item) or {} record = { "id": item, @@ -394,7 +420,9 @@ def worst(item): record["bands"][indicator] = [r[4] for r in row] if any_claim: record["verdicts"][indicator] = [r[5] for r in row[:-1]] - out_items.append(record) + return record + + out_items = [record_of(item) for item in shown] data = { "format": fileformat.FORMAT, @@ -403,6 +431,7 @@ def worst(item): "title": title, "about": about, "item": {"one": item_word[0], "many": item_word[1]}, + **({"indicator": {"one": indicator_word[0], "many": indicator_word[1]}} if indicator_word else {}), "indicators": meta, "rule": { "floor_factor": floor_factor, @@ -431,10 +460,18 @@ def worst(item): "notes": list(notes), "made_by": f"sentier-diagnostics {__version__}", } + if matrix_file is not None: + data["matrix"] = {"file": matrix_file, "items": len(items)} errors = fileformat.errors(data) if errors: raise ValueError("not a diagnostics file: " + "; ".join(errors[:10])) - return data + if matrix_file is None: + return data, None + full = matrix.make(data, [record_of(item) for item in sorted(items, key=worst)]) + errors = matrix.errors(full) or matrix.against(full, data) + if errors: + raise ValueError("not a matrix of this file: " + "; ".join(errors[:10])) + return data, full #: Stands in for the list of items while the rest of a file is written. A file's texts hold diff --git a/src/sentier_diagnostics/cli.py b/src/sentier_diagnostics/cli.py index 465b62e..9c732aa 100644 --- a/src/sentier_diagnostics/cli.py +++ b/src/sentier_diagnostics/cli.py @@ -1,10 +1,11 @@ """The command `sentier-diagnostics`: check, build, summarise and show diagnostics files. - sentier-diagnostics check FILE [FILE ...] exit 1 if any file is not one a page shows - sentier-diagnostics build DESCRIPTION --out FILE - sentier-diagnostics summary FILE - sentier-diagnostics page FILE --out FOLDER - sentier-diagnostics example --out FOLDER +sentier-diagnostics check FILE [FILE ...] exit 1 if any file is not one a page shows + (a matrix beside a file is checked against it) +sentier-diagnostics build DESCRIPTION --out FILE +sentier-diagnostics summary FILE +sentier-diagnostics page FILE --out FOLDER +sentier-diagnostics example --out FOLDER """ from __future__ import annotations @@ -13,7 +14,7 @@ import sys from pathlib import Path -from . import __version__, breakdown, chain, example, fileformat, from_tables, page, summary +from . import __version__, breakdown, chain, example, fileformat, from_tables, matrix, page, summary def check(paths) -> int: @@ -27,11 +28,15 @@ def check(paths) -> int: continue if isinstance(data, dict) and data.get("format") == breakdown.FORMAT: errors = breakdown.errors(data) + elif isinstance(data, dict) and str(data.get("format", "")).startswith(matrix.FAMILY): + errors = matrix.errors(data) # against its file when the file is checked else: errors = fileformat.errors(data) size = Path(path).stat().st_size if size > fileformat.MAX_BYTES: - errors.append(f"{size} bytes, and a page holds {fileformat.MAX_BYTES} at most: list fewer items") + errors.append( + f"{size} bytes, and a page holds {fileformat.MAX_BYTES} at most: list fewer items" + ) if not errors: try: found, absent = page.named_breakdowns(data, Path(path).parent) @@ -41,6 +46,14 @@ def check(paths) -> int: errors += page.breakdown_errors(data, found) for name in absent: print(f"note {path}: names the breakdown {name}, which is not beside it (not checked)") + if data.get("matrix"): + try: + if page.named_matrix(data, Path(path).parent) is None: + print( + f"note {path}: names the matrix {data['matrix']['file']}, which is not beside it (not checked)" + ) + except ValueError as error: + errors.append(str(error)) if errors: failed += 1 print(f"FAIL {path}") @@ -73,8 +86,13 @@ def main(argv=None) -> int: if args.command == "check": return check(args.files) if args.command == "build": - chain.write(from_tables.build(args.description), args.out) - print(f"wrote {args.out}") + data, full = from_tables.build_with_matrix(args.description) + chain.write(data, args.out) + if full is None: + print(f"wrote {args.out}") + return 0 + beside = matrix.write(full, Path(args.out).parent / data["matrix"]["file"]) + print(f"wrote {args.out} and its matrix {beside}") return 0 if args.command == "summary": print(summary.text(chain.read(args.file)), end="") @@ -82,9 +100,14 @@ def main(argv=None) -> int: if args.command == "page": data = chain.read(args.file) found, absent = page.named_breakdowns(data, args.file.parent) - where = page.write(data, args.out, found) + full = page.named_matrix(data, args.file.parent) + where = page.write(data, args.out, found, full) for name in absent: print(f"note: the breakdown {name} is not beside the file; the page says so") + if data.get("matrix") and full is None: + print( + f"note: the matrix {data['matrix']['file']} is not beside the file; the page shows the listed items and says so" + ) print(f"wrote {where}") return 0 if args.command == "example": @@ -93,7 +116,13 @@ def main(argv=None) -> int: one = example.wheat_breakdown() breakdown.write(one, args.out / "p01-fix-1.json") where = page.write(data, args.out / "page", {"p01-fix-1.json": one}) - print(f"wrote {args.out / chain.FILE} and {where}") + local, full = example.build_local() + chain.write(local, args.out / "local" / chain.FILE) + matrix.write(full, args.out / "local" / local["matrix"]["file"]) + local_page = page.write(local, args.out / "local" / "page", None, full) + print( + f"wrote {args.out / chain.FILE} and {where}; the local example and its matrix: {local_page}" + ) return 0 except (ValueError, OSError) as error: print(f"error: {error}", file=sys.stderr) diff --git a/src/sentier_diagnostics/example.py b/src/sentier_diagnostics/example.py index cde40e3..e6719bf 100644 --- a/src/sentier_diagnostics/example.py +++ b/src/sentier_diagnostics/example.py @@ -202,7 +202,17 @@ def explanations() -> list[dict]: def build(**more) -> dict: """The made-up chain, counted and checked.""" - return chain.build( + return _made(chain.build, **more) + + +def build_local() -> tuple[dict, dict]: + """The same chain as a local file that lists the six worst products, and its full matrix + of all ten: what a project keeps on its own machine.""" + return _made(chain.build_with_matrix, audience="local", listed=6) + + +def _made(builder, **more): + return builder( "A made-up chain: published results to the current build", about="Made-up results of ten items in three indicators. Nobody's data.", indicators=INDICATORS, diff --git a/src/sentier_diagnostics/fileformat.py b/src/sentier_diagnostics/fileformat.py index 43a886a..e00b03d 100644 --- a/src/sentier_diagnostics/fileformat.py +++ b/src/sentier_diagnostics/fileformat.py @@ -39,6 +39,8 @@ FLOOR_BASES = ("median", "declared", "none") ORIGIN_KINDS = ("person", "code", "model") TOTAL = "total" +#: Keys a file may leave out; each is null where it says nothing. +OPTIONAL_KEYS = {"matrix", "indicator"} #: The largest file a page reads: it holds the whole file. MAX_BYTES = 12 * 1024 * 1024 @@ -152,6 +154,27 @@ def is_share(value) -> bool: return rule.is_value(value) and value >= 0 +def indicator_word(data: Mapping) -> dict: + """What the file calls an indicator, {one, many}: its own word, or "indicator". + + >>> indicator_word({"indicator": {"one": "impact category", "many": "impact categories"}})["many"] + 'impact categories' + >>> indicator_word({})["one"] + 'indicator' + """ + return data.get("indicator") or {"one": "indicator", "many": "indicators"} + + +def first_step(data: Mapping) -> int: + """The number of the first step: 0 where the chain starts from the published results (that + step checks they are reproduced), 1 otherwise. + + >>> first_step({"states": [{"kind": "published"}]}), first_step({"states": [{"kind": "build"}]}) + (0, 1) + """ + return 0 if data["states"][0]["kind"] == "published" else 1 + + def is_link(value) -> bool: return value is None or (is_text(value, 500) and value.startswith("https://")) @@ -795,7 +818,7 @@ def _errors(data, found: list[str]) -> list[str]: if isinstance(said, str) and said.startswith(FAMILY): return [f"format {said!r}: this reader knows {FORMAT} only"] return [f"not a diagnostics file of format {FORMAT}"] - found += [f"a key this format does not know: {key}" for key in sorted(set(data) - KEYS)] + found += [f"a key this format does not know: {key}" for key in sorted(set(data) - KEYS - OPTIONAL_KEYS)] found += [f"a key this format requires: {key}" for key in sorted(KEYS - set(data))] if found: return found @@ -810,6 +833,10 @@ def _errors(data, found: list[str]) -> list[str]: if not (isinstance(item, dict) and set(item) == {"one", "many"} and all(is_text(w, 30) for w in item.values())): # fmt: skip found.append("`item` is not {one, many}") + word = data.get("indicator") + if word is not None and not (isinstance(word, dict) and set(word) == {"one", "many"} + and all(is_text(w, 30) for w in word.values())): # fmt: skip + found.append("`indicator` is not {one, many}, or null") if not is_text(data["made_by"], 60): found.append("`made_by` is not a short text") notes = data["notes"] @@ -831,4 +858,21 @@ def _errors(data, found: list[str]) -> list[str]: _attribution(data, found, indicators, steps, blocks) items = _items(data, found, indicators, states, steps, floors, tier, blocks) _explanations(data, found, indicators, steps, set(items), tier) + _matrix(data, found) return found + + +def _matrix(data, found) -> None: + """A matrix holds every item with its results: only a local file of items may name one.""" + named = data.get("matrix") + if named is None: + return + if not (isinstance(named, dict) and set(named) == {"file", "items"} and isinstance(named["file"], str) + and FILE_NAME.fullmatch(named["file"]) and is_count(named["items"])): # fmt: skip + found.append("`matrix` is not {file, items} with a file name, or null") + return + if data["tier"] != "items" or data["audience"] != "local": + found.append("only a local file of items names a matrix: a public file keeps the listed items only") + count = data["items_count"] + if isinstance(count, dict) and named["items"] != count.get("all"): + found.append(f"`matrix` says {named['items']} items, the file counts {count.get('all')}") diff --git a/src/sentier_diagnostics/from_tables.py b/src/sentier_diagnostics/from_tables.py index 1c05c23..538dd0a 100644 --- a/src/sentier_diagnostics/from_tables.py +++ b/src/sentier_diagnostics/from_tables.py @@ -3,6 +3,7 @@ { "title": "Our database, from the published results to main", "item": {"one": "dataset", "many": "datasets"}, + "indicator": {"one": "impact category", "many": "impact categories"}, "indicators": [{"id": "ef31:climate", "name": "Climate change", "short": "Climate", "unit": "kg CO2 eq"}], "items": "items.csv", @@ -19,6 +20,10 @@ "tier": "items" } +A local file of items may also name its matrix of every item (`"matrix": "matrix.json"`, +with `"audience": "local"`): `build_with_matrix` then gives it, and `sentier-diagnostics +build` writes it beside the file. + Paths are relative to the description. A step's `noise` is `{"states": ["a", "b"]}` (two states of this chain that are builds of one state) or `{"tables": [{"label": "...", "results": "a.csv"}, {"label": "...", "results": "b.csv"}]}`. @@ -32,8 +37,8 @@ from . import chain, claims, fileformat, tables -KEYS = {"title", "about", "item", "indicators", "items", "states", "steps", "listed", "tier", "audience", "claim_lists", - "explanations", "notes", "floor_factor"} # fmt: skip +KEYS = {"title", "about", "item", "indicator", "indicators", "items", "states", "steps", "listed", "tier", "audience", + "claim_lists", "explanations", "notes", "floor_factor", "matrix"} # fmt: skip def _origin(said): @@ -71,13 +76,29 @@ def description_errors(spec) -> list[str]: ("listed", lambda v: isinstance(v, int) and not isinstance(v, bool) and v >= 0, "a whole number"), ("claim_lists", lambda v: isinstance(v, bool), "true or false"), ("floor_factor", _number, "a number"), - ("item", lambda v: _table(v, ("one", "many")) and all(map(_text, v.values())), "{one, many} in words"), + ( + "item", + lambda v: _table(v, ("one", "many")) and all(map(_text, v.values())), + "{one, many} in words", + ), + ( + "indicator", + lambda v: _table(v, ("one", "many")) and all(map(_text, v.values())), + "{one, many} in words", + ), ("notes", lambda v: isinstance(v, list) and all(map(_text, v)), "a list of texts"), + ( + "matrix", + lambda v: isinstance(v, str) and fileformat.FILE_NAME.fullmatch(v) is not None, + "the plain name of a .json file", + ), ): if key in spec and spec[key] is not None and not check(spec[key]): found.append(f"`{key}` is {says}") indicators = spec.get("indicators") - if not (isinstance(indicators, list) and indicators and all(_table(i, ("id", "name")) for i in indicators)): + if not ( + isinstance(indicators, list) and indicators and all(_table(i, ("id", "name")) for i in indicators) + ): found.append("`indicators` is a list of {id, name, short, unit}") states = spec.get("states") if not (isinstance(states, list) and len(states) >= 2 @@ -94,7 +115,10 @@ def description_errors(spec) -> list[str]: if said is not None: if not (_table(said, ("text",)) and _text(said["text"])): found.append(f"{where}: a claim says what it claims (`text`)") - elif not (isinstance(said.get("scope", []), list) and all(isinstance(e, dict) for e in said.get("scope", []))): + elif not ( + isinstance(said.get("scope", []), list) + and all(isinstance(e, dict) for e in said.get("scope", [])) + ): found.append(f"{where}: a claim's `scope` is a list of entries") elif said.get("by") is not None and not isinstance(said["by"], dict): found.append(f"{where}: a claim's `by` is {{kind, name}}") @@ -106,11 +130,17 @@ def description_errors(spec) -> list[str]: pair = said.get("states") if isinstance(said, dict) else None tables_ = said.get("tables") if isinstance(said, dict) else None if pair is not None: - if not (isinstance(pair, list) and len(pair) == 2 and all(isinstance(s, str) and s in known for s in pair)): + if not ( + isinstance(pair, list) + and len(pair) == 2 + and all(isinstance(s, str) and s in known for s in pair) + ): found.append(f"{where}: a noise's `states` names two states of this chain") elif not (isinstance(tables_, list) and len(tables_) == 2 and all(_table(t, ("label", "results")) and _text(t["results"]) for t in tables_)): # fmt: skip - found.append(f"{where}: a noise is {{states: [a, b]}} or {{tables: [{{label, results}}, {{label, results}}]}}") + found.append( + f"{where}: a noise is {{states: [a, b]}} or {{tables: [{{label, results}}, {{label, results}}]}}" + ) explanations = spec.get("explanations", []) if not (isinstance(explanations, list) and all(_table(e, ("text",)) for e in explanations)): found.append("`explanations` is a list of {text, by, ...}") @@ -120,6 +150,12 @@ def description_errors(spec) -> list[str]: def build(path: Path) -> dict: """The diagnostics file a description and its tables give, checked. Every mistake is a ValueError that says what is wrong (`tables.TableError` for a table).""" + return build_with_matrix(path)[0] + + +def build_with_matrix(path: Path) -> tuple[dict, dict | None]: + """The diagnostics file, and its matrix of every item where the description names one + (None where it does not). Only a local file of items may name one.""" path = Path(path) spec = fileformat.load_json(path) errors = description_errors(spec) @@ -160,8 +196,13 @@ def floor_by_item(indicator): found_claim = claims.claim( said_claim["text"], [ - claims.scope(e.get("indicators", "*"), e.get("items", "*"), e.get("direction", "any"), - e.get("largest"), e.get("expect", claims.MAY)) + claims.scope( + e.get("indicators", "*"), + e.get("items", "*"), + e.get("direction", "any"), + e.get("largest"), + e.get("expect", claims.MAY), + ) for e in said_claim.get("scope", []) ], # fmt: skip by=_origin(said_claim.get("by")), @@ -186,29 +227,53 @@ def floor_by_item(indicator): said_tol = one.get("tolerance") steps.append( chain.step( - one["id"], one["label"], kind=one["kind"], explained=one.get("explained", True), - about=one.get("about"), link=one.get("link"), claim=found_claim, + one["id"], + one["label"], + kind=one["kind"], + explained=one.get("explained", True), + about=one.get("about"), + link=one.get("link"), + claim=found_claim, tolerance=chain.tolerance(said_tol["value"], said_tol.get("basis"), said_tol.get("note")) - if said_tol else None, + if said_tol + else None, noise=found_noise, ) # fmt: skip ) explanations = [ chain.explanation( - e["text"], _origin(e.get("by")), step=e.get("step"), indicator=e.get("indicator"), - item=e.get("item"), link=e.get("link"), doc=e.get("doc"), not_checked=e.get("not_checked"), + e["text"], + _origin(e.get("by")), + step=e.get("step"), + indicator=e.get("indicator"), + item=e.get("item"), + link=e.get("link"), + doc=e.get("doc"), + not_checked=e.get("not_checked"), finding=e.get("finding", "reason"), ) # fmt: skip for e in spec.get("explanations", []) ] word = spec.get("item", {"one": "item", "many": "items"}) - return chain.build( - spec["title"], + named = spec.get("matrix") + if named is not None and ( + spec.get("audience", "local") != "local" or spec.get("tier", "items") != "items" + ): + raise ValueError( + f"{path}: only a local file of items names a matrix; a public file keeps the listed items only" + ) + given = dict( about=spec.get("about"), indicators=indicators, states=[ - chain.state(s["id"], s["label"], kind=s.get("kind", "build"), about=s.get("about"), - identity=s.get("identity"), join=s.get("join")) # fmt: skip + chain.state( + s["id"], + s["label"], + kind=s.get("kind", "build"), + about=s.get("about"), + identity=s.get("identity"), + join=s.get("join"), + ) # fmt: skip for s in spec["states"] ], steps=steps, @@ -216,6 +281,7 @@ def floor_by_item(indicator): units=units, names=items, item_word=(word["one"], word["many"]), + indicator_word=(spec["indicator"]["one"], spec["indicator"]["many"]) if spec.get("indicator") else None, listed=spec.get("listed", 200), tier=spec.get("tier", "items"), audience=spec.get("audience", "local"), @@ -224,3 +290,6 @@ def floor_by_item(indicator): explanations=explanations, notes=spec.get("notes", []), ) + if named is None: + return chain.build(spec["title"], **given), None + return chain.build_with_matrix(spec["title"], matrix_file=named, **given) diff --git a/src/sentier_diagnostics/matrix.py b/src/sentier_diagnostics/matrix.py new file mode 100644 index 0000000..f7c3e0d --- /dev/null +++ b/src/sentier_diagnostics/matrix.py @@ -0,0 +1,413 @@ +"""The full matrix of a local file, `sentier-diagnostics-matrix/1`: every item, not only the +listed ones. + +A diagnostics file lists the items worth a look, the worst first, up to `listed` (200 by +default), so that it stays small enough for a page to hold. A project looking at its own +build wants every item: the matrix is that, in a second file the page loads after it has +drawn. It is compact (one row per item, the indicators and states named once) and it holds +only what the rule gives: the results, and one code per pair for its class and direction, +and per step with a claim one code for its verdict. + +Only a local file may name a matrix (`"matrix": {"file": ..., "items": n}`); a public file +keeps the listed items only. `errors(m)` checks the shape; `against(m, data)` works every +code out again from the results and the diagnostics file's own rule, and holds the file's +counts, attribution and `items_count` to what the matrix holds: with every item at hand, +they must match exactly. +""" + +from __future__ import annotations + +import json +from collections.abc import Mapping +from pathlib import Path + +from . import claims, fileformat, rule + +FORMAT = "sentier-diagnostics-matrix/1" +FAMILY = "sentier-diagnostics-matrix/" +KEYS = {"format", "of", "items", "values", "classes", "verdicts"} +OF_KEYS = {"title", "states", "indicators", "steps"} + +#: A matrix is loaded after the page is drawn, not held inside it: it may be larger. +MAX_BYTES = 64 * 1024 * 1024 +MAX_ITEMS = 200_000 + +#: One character per pair: its class, and for a pair that moved its direction (upper case +#: up, lower case down). +CODES = { + (rule.AGREES, None): "=", + (rule.WITHIN_NOISE, None): "~", + (rule.NEAR_ZERO, None): "0", + (rule.MISSING, None): "-", + (rule.DIFFERS, rule.UP): "D", + (rule.DIFFERS, rule.DOWN): "d", + (rule.BEYOND, rule.UP): "B", + (rule.BEYOND, rule.DOWN): "b", + (rule.ZERO_REFERENCE, rule.UP): "R", + (rule.ZERO_REFERENCE, rule.DOWN): "r", + (rule.ZERO_RESULT, rule.UP): "T", + (rule.ZERO_RESULT, rule.DOWN): "t", + (rule.SIGN_CHANGE, rule.UP): "S", + (rule.SIGN_CHANGE, rule.DOWN): "s", +} +DECODE = {code: pair for pair, code in CODES.items()} + +#: One character per pair and step with a claim: its verdict. "." for a step without one. +VERDICT_CODES = { + claims.AS_CLAIMED: "a", + claims.OFF_CLAIM: "o", + claims.NOT_CLAIMED: "n", + claims.NOT_MOVED: "c", + claims.NOISE: "~", + claims.UNCHANGED: "=", + claims.NOT_JUDGED: "?", +} +NO_CLAIM = "." +VERDICT_DECODE = {code: verdict for verdict, code in VERDICT_CODES.items()} + + +def code_of(kind: str, way: str | None) -> str: + """The code of a class and direction. + + >>> code_of("differs", "up"), code_of("agrees", None), code_of("sign change", "down") + ('D', '=', 's') + """ + return CODES[(kind, way)] + + +def make(data: Mapping, rows: list[dict]) -> dict: + """A matrix of a diagnostics file from its rows, as `chain.build_with_matrix` gives them: + `{id, name, place, group, unit, values: {indicator: [per state]}, classes, directions, + verdicts}` with classes, directions and verdicts per indicator as the file lists them.""" + ids = [i["id"] for i in data["indicators"]] + steps = data["steps"] + out = { + "format": FORMAT, + "of": { + "title": data["title"], + "states": [s["id"] for s in data["states"]], + "indicators": ids, + "steps": [s["id"] for s in steps], + }, + "items": [], + "values": [], + "classes": [], + "verdicts": [] if any(s["claim"] for s in steps) else None, + } + for row in rows: + out["items"].append([row["id"], row["name"], row["place"], row["group"], row["unit"]]) + out["values"].append([v for i in ids for v in row["values"][i]]) + out["classes"].append( + "".join( + code_of(kind, way) for i in ids for kind, way in zip(row["classes"][i], row["directions"][i]) + ) + ) + if out["verdicts"] is not None: + out["verdicts"].append( + "".join( + NO_CLAIM if said is None else VERDICT_CODES[said] + for i in ids + for said in row["verdicts"][i] + ) + ) + return out + + +def dumps(m: Mapping) -> str: + """The text of a matrix: one line per item, so that a diff names the items.""" + head = {k: v for k, v in m.items() if k not in ("items", "values", "classes", "verdicts")} + lines = [json.dumps(head, ensure_ascii=False, allow_nan=False)[:-1] + ","] + for key in ("items", "values", "classes", "verdicts"): + rows = m[key] + if rows is None: + lines.append(f' "{key}": null' + ("," if key != "verdicts" else "")) + continue + body = ",\n".join( + " " + json.dumps(r, ensure_ascii=False, allow_nan=False, separators=(",", ":")) for r in rows + ) + lines.append(f' "{key}": [\n{body}\n ]' + ("," if key != "verdicts" else "")) + return "\n".join(lines) + "\n}\n" + + +def write(m: Mapping, path) -> Path: + """Write a matrix, its shape checked first; refuse one larger than a page loads.""" + found = errors(m) + if found: + raise ValueError("not a matrix: " + "; ".join(found[:10])) + text = dumps(m) + size = len(text.encode("utf-8")) + if size > MAX_BYTES: + raise ValueError(f"the matrix would be {size} bytes, and a page loads {MAX_BYTES} at most") + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + return path + + +def read(path, data: Mapping) -> dict: + """A matrix, read and checked against its checked diagnostics file; raises ValueError + with every error found.""" + path = Path(path) + if path.stat().st_size > MAX_BYTES: + raise ValueError(f"{path}: larger than {MAX_BYTES} bytes") + m = fileformat.load_json(path) + found = errors(m) or against(m, data) + if found: + raise ValueError(f"{path}: " + "; ".join(found[:10])) + return m + + +def _is_row(row) -> bool: + return ( + isinstance(row, list) + and len(row) == 5 + and fileformat.is_text(row[0], fileformat.MAX_ID) + and fileformat.is_text(row[1], 300) + and fileformat.is_optional(row[2], 60) + and fileformat.is_optional(row[3], fileformat.MAX_LABEL) + and fileformat.is_optional(row[4], fileformat.MAX_WORD) + ) + + +def errors(m) -> list[str]: + """Everything wrong with the shape of a matrix; nothing for one a page can load. It never + raises: a value it cannot read is a fault like any other.""" + try: + return _errors(m) + except Exception: # noqa: BLE001 - a backstop: the checks above it name the faults they know + return [fileformat.STOPPED] + + +def _errors(m) -> list[str]: + if not isinstance(m, Mapping): + return ["not a matrix: not an object"] + said = m.get("format") + if said != FORMAT: + if isinstance(said, str) and said.startswith(FAMILY): + return [f"format {said!r}: this reader knows {FORMAT} only"] + return [f"not a matrix of format {FORMAT}"] + found = [f"a key this format does not know: {k}" for k in sorted(set(m) - KEYS)] + found += [f"a key this format requires: {k}" for k in sorted(KEYS - set(m))] + if found: + return found + of = m["of"] + if not ( + isinstance(of, dict) + and set(of) == OF_KEYS + and fileformat.is_text(of["title"], 120) + and all(isinstance(of[k], list) and all(fileformat.is_text(x, fileformat.MAX_ID) for x in of[k]) + for k in ("states", "indicators", "steps")) + ): # fmt: skip + return ["`of` is not {title, states, indicators, steps}"] + nstates, nind, nsteps = len(of["states"]), len(of["indicators"]), len(of["steps"]) + if nsteps != nstates - 1 or not nind: + return ["`of`: one step fewer than states, and at least one indicator"] + items = m["items"] + if not isinstance(items, list) or len(items) > MAX_ITEMS: + return [f"`items` is not a list of at most {MAX_ITEMS} items"] + n = len(items) + for key in ("values", "classes"): + if not isinstance(m[key], list) or len(m[key]) != n: + found.append(f"`{key}` is not one row per item") + has_claims = m["verdicts"] is not None + if has_claims and (not isinstance(m["verdicts"], list) or len(m["verdicts"]) != n): + found.append("`verdicts` is not one row per item, or null") + if found: + return found + seen = set() + for at, row in enumerate(items): + if not _is_row(row): + return [f"item {at}: not [id, name, place, group, unit]"] + if row[0] in seen: + found.append(f"item {row[0]!r} is in the matrix twice") + seen.add(row[0]) + values = m["values"][at] + if not (isinstance(values, list) and len(values) == nind * nstates + and all(v is None or rule.is_value(v) for v in values)): # fmt: skip + return [f"item {row[0]!r}: not one finite number or null per indicator and state"] + codes = m["classes"][at] + if not ( + isinstance(codes, str) and len(codes) == nind * (nsteps + 1) and all(c in DECODE for c in codes) + ): + return [f"item {row[0]!r}: not one class code per indicator, step and the whole way"] + if has_claims: + said = m["verdicts"][at] + if not (isinstance(said, str) and len(said) == nind * nsteps + and all(c in VERDICT_DECODE or c == NO_CLAIM for c in said)): # fmt: skip + return [f"item {row[0]!r}: not one verdict code per indicator and step"] + return found + + +def against(m: Mapping, data: Mapping) -> list[str]: + """Everything a checked matrix and its checked diagnostics file disagree on. Every code + is worked out again with the file's floors, tolerances and noise, and, where a claim's + lists are in the file, every verdict; the file's counts, attribution and `items_count` + must be what the matrix holds, exactly.""" + try: + return _against(m, data) + except Exception: # noqa: BLE001 - a backstop, as in `errors` + return [fileformat.STOPPED] + + +def _against(m: Mapping, data: Mapping) -> list[str]: + found = [] + named = data.get("matrix") + if not named: + return ["the diagnostics file names no matrix"] + ids = [i["id"] for i in data["indicators"]] + order = [s["id"] for s in data["states"]] + steps = data["steps"] + of = {"title": data["title"], "states": order, "indicators": ids, "steps": [s["id"] for s in steps]} + if m["of"] != of: + return ["it is the matrix of another file: its title, states, indicators or steps differ"] + n = len(m["items"]) + if named["items"] != n: + found.append(f"the diagnostics file says {named['items']} items, the matrix holds {n}") + if data["items_count"]["all"] != n: + found.append(f"the diagnostics file counts {data['items_count']['all']} items, the matrix holds {n}") + nstates, nsteps = len(order), len(steps) + floors = {(f["indicator"], f["unit"]): f["value"] for f in data["rule"]["floors"]} + published_first = data["states"][0]["kind"] == "published" + listed = {item["id"]: item for item in data["items"]} + + # what the counts and attribution must be, counted from every item + def empty(k): + return { + "pairs": 0, + "classes": dict.fromkeys(rule.CLASSES, 0), + "missing": dict.fromkeys(fileformat.MISSING_SIDES, 0), + "directions": dict.fromkeys(rule.DIRECTIONS, 0), + "bands": dict.fromkeys(rule.BANDS, 0), + "verdicts": dict.fromkeys(claims.VERDICTS, 0) if k is not None and steps[k]["claim"] else None, + "closer": 0 if published_first and k not in (None, 0) else None, + "further": 0 if published_first and k not in (None, 0) else None, + } + + counted = {(k, i): empty(k) for k in [*range(nsteps), None] for i in ids} + attributed = { + i: { + "dominant": {s["id"]: 0 for s in steps}, + "not_attributable": 0, + "spread": 0, + "unexplained_moved": 0, + } + for i in ids + } + qualifying = 0 + for at, (item_id, name, place, group, unit) in enumerate(m["items"]): + where = f"item {item_id!r}" + flat, codes = m["values"][at], m["classes"][at] + said_verdicts = m["verdicts"][at] if m["verdicts"] is not None else None + worth = False + values_of = {} + for x, indicator in enumerate(ids): + values = flat[x * nstates : (x + 1) * nstates] + values_of[indicator] = values + floor = floors.get((indicator, unit)) + if floor is None: + return [f"{where}, {indicator}: the file holds no floor for unit {unit!r}"] + kinds = [] + for k in [*range(nsteps), None]: + at_k = nsteps if k is None else k + before, after = (values[0], values[-1]) if k is None else (values[k], values[k + 1]) + if k is None: + tol, level = data["rule"]["total_tolerance"], None + else: + tol = steps[k]["tolerance"]["value"] + noise = steps[k]["noise"] + level = (noise["by"] or {}).get(indicator) if noise["measured"] else None + kind, way, band = rule.judge(before, after, floor=floor, tolerance=tol, noise=level) + code = codes[x * (nsteps + 1) + at_k] + if code != code_of(kind, way): + step_name = "the whole way" if k is None else steps[k]["id"] + return [ + f"{where}, {indicator}, {step_name}: written as {DECODE[code]}, the rule gives {kind}/{way}" + ] + kinds.append(kind) + block = counted[(k, indicator)] + block["pairs"] += 1 + block["classes"][kind] += 1 + if kind == rule.MISSING: + side = ( + "both" + if before is None and after is None + else "before" + if before is None + else "after" + ) + block["missing"][side] += 1 + if way: + block["directions"][way] += 1 + if band: + block["bands"][band] += 1 + if block["closer"] is not None and kind in rule.MOVES and values[0] is not None: + was, now = abs(before - values[0]), abs(after - values[0]) + block["closer"] += now < was + block["further"] += now > was + worth = worth or kind not in rule.QUIET + if k is None: + continue + step_claim = steps[k]["claim"] + vcode = said_verdicts[x * nsteps + k] if said_verdicts is not None else NO_CLAIM + if step_claim is None: + if vcode != NO_CLAIM: + return [f"{where}, {indicator}, {steps[k]['id']}: a verdict without a claim"] + continue + said = VERDICT_DECODE.get(vcode) + if said is None or said not in fileformat.ALLOWED_VERDICTS[kind]: + return [f"{where}, {indicator}, {steps[k]['id']}: {kind!r} cannot be {said!r}"] + if claims.judgeable(step_claim): + covering = [ + e + for e in claims.entries_for(step_claim, indicator) + if claims.covers(e, item_id, indicator) + ] + again = claims.verdict(kind, before, after, way, covering) + if again != said: + return [ + f"{where}, {indicator}, {steps[k]['id']}: written {said!r}, the claim gives {again!r}" + ] + block["verdicts"][said] += 1 + worth = worth or said == claims.NOT_MOVED + # attribution, as `chain.build` makes it + one = attributed[indicator] + if any(not s["explained"] and kinds[j] in rule.MOVES for j, s in enumerate(steps)): + one["unexplained_moved"] += 1 + if kinds[nsteps] in rule.MOVES: + if any(v is None for v in values): + one["not_attributable"] += 1 + else: + carrier = rule.largest_step(values, kinds[:nsteps]) + if carrier is None: + one["spread"] += 1 + else: + one["dominant"][steps[carrier]["id"]] += 1 + qualifying += worth + if item_id in listed: + item = listed[item_id] + if [item["name"], item["place"], item["group"], item["unit"]] != [name, place, group, unit]: + found.append(f"{where}: its name, place, group or unit differ from the diagnostics file") + if item["values"] != values_of: + found.append(f"{where}: its results differ from the diagnostics file") + missing_listed = set(listed) - {row[0] for row in m["items"]} + if missing_listed: + found.append(f"{len(missing_listed)} listed items are not in the matrix") + if data["items_count"]["qualifying"] != qualifying: + found.append( + f"the diagnostics file counts {data['items_count']['qualifying']} items worth a look, " + f"the matrix holds {qualifying}" + ) + for (k, indicator), block in counted.items(): + name = fileformat.TOTAL if k is None else steps[k]["id"] + written = ( + data["counts"][fileformat.TOTAL][indicator] + if k is None + else data["counts"]["steps"][name][indicator] + ) + for key in block: + if block[key] != written[key]: + found.append(f"counts of {name!r} in {indicator!r}: `{key}` is not what the matrix holds") + for indicator in ids: + if attributed[indicator] != data["attribution"][indicator]: + found.append(f"attribution in {indicator!r} is not what the matrix holds") + return found diff --git a/src/sentier_diagnostics/page.py b/src/sentier_diagnostics/page.py index 3318695..25acf45 100644 --- a/src/sentier_diagnostics/page.py +++ b/src/sentier_diagnostics/page.py @@ -1,69 +1,166 @@ -"""The static page: three files that need no build step, no server and no network. +"""The page: a frameless body a site holds in its own page, or a page of its own. -`write(data, folder)` copies `index.html`, `diagnostics.js` and `diagnostics.css` into a -folder and writes the file beside them as `data.js`, so that the page opens from disk by -a double click (a browser does not let a page read a JSON file from disk by itself). The -breakdowns the file names go into `breakdowns.js` the same way. Served over HTTP, the -page can also read a JSON file named in its address (`index.html?file=diagnostics.json`), -and it can open a file a reader chooses. +`body(data)` is the diagnostics as one element, `
`, with the +file inside it as JSON: no ``, no ``, no id. A site puts it where it wants and +loads `diagnostics.js` and `diagnostics.css` from `assets()`. The style is scoped to that +element and sets no font and nothing on `:root` or `body`; its colours take the site's tokens +(`--ink`, `--line`, `--surface` ...) where the site sets them. + +`write(data, folder)` writes a page of its own: `index.html` with the body in it, the two +assets and `standalone.css`, which sets the tokens and font a site would. It opens from disk +by a double click and needs no server and no network. A local file may name its matrix of +every item (`chain.build_with_matrix`); given it, `write` puts it beside the page as +`matrix.js`, which the page loads after it has drawn. The page shows what the file says. It works out no class, no direction and no count of its own: it only adds the file's counts up (the classes that moved into "moved", a step's -counts over its indicators), and splits one item's difference into the steps' shares. +counts over its indicators), divides an item's result after by its result before to show +their ratio, and splits one item's difference into the steps' shares. """ from __future__ import annotations +import html import json +import re import shutil from collections.abc import Mapping from importlib import resources from pathlib import Path from . import breakdown, fileformat +from . import matrix as matrix_format -ASSETS = ("index.html", "diagnostics.js", "diagnostics.css") +#: What a site copies into its assets to hold the body. +ASSETS = ("diagnostics.js", "diagnostics.css") +#: What a page of its own adds: its frame and the template of the body. +STANDALONE = ("index.html", "standalone.css") +TEMPLATE = "body.html" +MATRIX_SCRIPT = "matrix.js" +_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._/-]*") +_ROOT = '
' -def as_script(name: str, value) -> str: - """A value as a script that assigns it: ASCII only, and no ` str: + """A value as JSON that no HTML parser reads as markup: ASCII only, and every `<` escaped, + so that no text of a file can end the element that holds it or open a comment.""" text = json.dumps(value, ensure_ascii=True, allow_nan=False, separators=(",", ":")) - text = text.replace(" str: + """A value as a script that assigns it (`window.NAME = ...;`), for a site that keeps the + data in a file of its own; the page reads `SENTIER_DIAGNOSTICS`, + `SENTIER_DIAGNOSTICS_BREAKDOWNS` and `SENTIER_DIAGNOSTICS_MATRIX`.""" + return f"window.{name} = {_json(value)};\n" + + +def _read(name: str) -> str: + return (resources.files(__package__) / "page" / name).read_text(encoding="utf-8") -def assets() -> dict[str, Path]: - """The page's own files by name, for a site that copies them into its assets and - writes `data.js` itself (`as_script("SENTIER_DIAGNOSTICS", data)`). The paths are those - of the installed package.""" +def assets(standalone: bool = False) -> dict[str, Path]: + """The page's own files by name, as paths of the installed package: the script and the + style a site copies, and with `standalone` also the frame of a page of its own and the + template of the body.""" source = resources.files(__package__) / "page" - return {name: Path(str(source / name)) for name in ASSETS} + names = ASSETS + ((*STANDALONE, TEMPLATE) if standalone else ()) + return {name: Path(str(source / name)) for name in names} -def write(data: Mapping, folder: Path, breakdowns: Mapping[str, Mapping] | None = None) -> Path: - """The page and its data in `folder`; returns the path of `index.html`.""" +def _checked(data: Mapping, breakdowns: Mapping[str, Mapping]) -> None: found = fileformat.errors(data) if found: raise ValueError("not a diagnostics file: " + "; ".join(found[:10])) - errors = breakdown_errors(data, breakdowns or {}) + errors = breakdown_errors(data, breakdowns) if errors: raise ValueError("; ".join(errors)) - script = as_script("SENTIER_DIAGNOSTICS", data) - if len(script) > fileformat.MAX_BYTES: # ASCII: one byte per character + + +def body( + data: Mapping, + *, + breakdowns: Mapping[str, Mapping] | None = None, + base: str = "", + title: bool = True, + matrix: str | None = None, +) -> str: + """The diagnostics as one element for a site's page, the file and its breakdowns inside. + + `base` is put before the names of the files the page loads (breakdowns, the matrix), for + a site that keeps them elsewhere than the page. `title=False` leaves the heading to the + site. `matrix` names the file of the matrix the page loads after it has drawn, where it + is not the one the file names (a site that serves `matrix.json` needs none). + """ + return _body(data, breakdowns=breakdowns, base=base, title=title, matrix=matrix, standalone=False) + + +def _body(data, *, breakdowns, base, title, matrix, standalone) -> str: + breakdowns = dict(breakdowns or {}) + _checked(data, breakdowns) + if matrix is not None and not (_NAME.fullmatch(matrix) and ".." not in matrix): + raise ValueError(f"the matrix {matrix!r} is not a plain file name") + scripts = f'\n' + if breakdowns: + scripts += f'\n' + if len(scripts) > fileformat.MAX_BYTES: # ASCII: one byte per character raise ValueError( - f"data.js would be {len(script)} bytes, and a page holds {fileformat.MAX_BYTES} at most: list fewer items" + f"the page would hold {len(scripts)} bytes of data, and holds {fileformat.MAX_BYTES} at most: " + "list fewer items, and keep every item in the matrix" ) + attributes = "" + if base: + attributes += f' data-sd-base="{html.escape(base, quote=True)}"' + if matrix: + attributes += f' data-sd-matrix="{html.escape(matrix, quote=True)}"' + if standalone: + attributes += " data-sd-standalone" + text = _read(TEMPLATE) + if _ROOT not in text or "" not in text: + raise RuntimeError("the template of the body has lost its root or its place for the data") + text = text.replace(_ROOT, _ROOT[:-1] + attributes + ">", 1) + if not title: + text = text.replace( + '

', '

{name}

\n{inner}", 1) folder = Path(folder) folder.mkdir(parents=True, exist_ok=True) source = resources.files(__package__) / "page" - for name in ASSETS: - with resources.as_file(source / name) as path: - shutil.copyfile(path, folder / name) - (folder / "data.js").write_text(script, encoding="utf-8") - (folder / "breakdowns.js").write_text( - as_script("SENTIER_DIAGNOSTICS_BREAKDOWNS", dict(breakdowns or {})), encoding="utf-8" - ) + for one in (*ASSETS, "standalone.css"): + with resources.as_file(source / one) as path: + shutil.copyfile(path, folder / one) + (folder / "index.html").write_text(page, encoding="utf-8") + stale = folder / MATRIX_SCRIPT + if script is not None: + stale.write_text(script, encoding="utf-8") + elif stale.exists(): + stale.unlink() # the matrix of an earlier page: this one names none return folder / "index.html" @@ -100,3 +197,16 @@ def named_breakdowns(data: Mapping, beside: Path) -> tuple[dict, list[str]]: continue found[name] = fileformat.load_json(path) return found, absent + + +def named_matrix(data: Mapping, beside: Path) -> dict | None: + """The matrix a file names, read from beside it and checked against the file; None where + it names none or where the matrix is not there (a page then shows the listed items and + says so). A matrix that is there and not the file's is refused.""" + named = data.get("matrix") + if not named: + return None + path = Path(beside) / named["file"] + if not path.is_file(): + return None + return matrix_format.read(path, data) diff --git a/src/sentier_diagnostics/page/body.html b/src/sentier_diagnostics/page/body.html new file mode 100644 index 0000000..0c8b053 --- /dev/null +++ b/src/sentier_diagnostics/page/body.html @@ -0,0 +1,110 @@ +
+
+

Diagnostics

+

+

+ +
+ + + + + +

+ +
diff --git a/src/sentier_diagnostics/page/diagnostics.css b/src/sentier_diagnostics/page/diagnostics.css index 241041c..53d0361 100644 --- a/src/sentier_diagnostics/page/diagnostics.css +++ b/src/sentier_diagnostics/page/diagnostics.css @@ -1,110 +1,243 @@ -/* sentier-diagnostics page. No font, script or image is loaded from anywhere else. */ -:root { - --ink: #1d232a; - --muted: #5b6672; - --paper: #ffffff; - --paper-deep: #f3f5f7; - --line: #d9dee3; - --up: #1f6fb2; /* went up: blue */ - --down: #b4560f; /* went down: orange; the pair reads for colour-blind readers */ - --noise: #8a939c; - --error: #a3262a; - --radius: 6px; - --gutter: 16px; - font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; - color: var(--ink); - background: var(--paper); +/* sentier-diagnostics: the style of the diagnostics, inside a host's page or on their own. + Every rule is scoped to .sentier-diagnostics: nothing here touches the host's :root, body, + headings or tables outside it, and no font is set (the host's is inherited). Colours and + sizes are custom properties that take the host's tokens where it sets them (the shared + tokens of the Sentier sites) and fall back otherwise. Up, down and noise keep colours of + their own, so that a direction never takes a site's accent. No font, script or image is + loaded from anywhere else. */ +.sentier-diagnostics { + --sd-ink: var(--ink, #1d232a); + --sd-muted: var(--muted, #5b6672); + --sd-surface: var(--surface, #ffffff); + --sd-paper-deep: var(--paper-deep, #f3f5f7); + --sd-line: var(--line, #d9dee3); + --sd-line-strong: var(--line-strong, #b6bfc8); + --sd-accent: var(--index, #1d625e); + --sd-on-accent: var(--on-index, #ffffff); + --sd-fail: var(--fail, #a3262a); + --sd-radius: var(--radius, 6px); + --sd-gutter: var(--gutter, 16px); + --sd-t-xs: var(--t-xs, 0.75rem); + --sd-t-sm: var(--t-sm, 0.875rem); + --sd-t-md: var(--t-md, 1rem); + --sd-t-lg: var(--t-lg, 1.2rem); + --sd-s2: var(--s2, 0.5rem); + --sd-s3: var(--s3, 0.75rem); + --sd-s4: var(--s4, 1rem); + --sd-s5: var(--s5, 1.5rem); + --sd-s6: var(--s6, 2rem); + --sd-up: #b07a1b; /* went up: amber */ + --sd-down: #1d625e; /* went down: teal; the pair reads for colour-blind readers */ + --sd-noise: #8a939c; + --sd-drawer: clamp(22rem, 42vw, 52rem); + color: var(--sd-ink); + font-size: var(--sd-t-md); + line-height: 1.45; } @media (prefers-color-scheme: dark) { - :root { - --ink: #e6eaee; - --muted: #9aa5b0; - --paper: #15191d; - --paper-deep: #1f252b; - --line: #36404a; - --up: #6fb0ec; - --down: #f0a065; - --noise: #77818b; - --error: #ff8a8e; - } + .sentier-diagnostics { --sd-up: #d9a441; --sd-down: #5fa29d; --sd-noise: #77818b; } } -body { margin: 0; background: var(--paper); line-height: 1.45; } -header.top, main, footer { max-width: 1200px; margin: 0 auto; padding: 0 var(--gutter); } -h1 { font-size: 1.6rem; margin: 0.2rem 0; } -h2 { font-size: 1.25rem; margin: 2rem 0 0.5rem; border-bottom: 1px solid var(--line); padding-bottom: 0.25rem; } -h3 { font-size: 1.05rem; margin: 1.25rem 0 0.4rem; } -.eyebrow { text-transform: uppercase; letter-spacing: 0.06em; font-size: 0.75rem; color: var(--muted); margin: 1rem 0 0; } -.lead { margin: 0.3rem 0; } -.quiet { color: var(--muted); font-size: 0.9rem; } -.error { color: var(--error); } -.plain { list-style: none; padding: 0; } -.plain li { margin: 0.5rem 0; } + /* a class that sets `display` would otherwise show an element marked hidden */ -[hidden] { display: none !important; } -.visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); } -code { font-size: 0.9em; } +.sentier-diagnostics [hidden] { display: none !important; } +.sentier-diagnostics .sd-visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); } + +/* the head */ +.sentier-diagnostics .sd-head { margin: 0 0 var(--sd-s4); } +.sentier-diagnostics .sd-title { margin: 0.2rem 0; } +.sentier-diagnostics .sd-lead { margin: 0.3rem 0; max-width: 60rem; } +.sentier-diagnostics .sd-lead:empty { display: none; } +.sentier-diagnostics .sd-tier { margin: 0.2rem 0; } +/* a local file says so as a quiet part of the line, as a site's own notice would */ +.sentier-diagnostics .sd-local { font-weight: 700; color: var(--sd-ink); } +.sentier-diagnostics .sd-local::before { content: "· "; font-weight: 400; color: var(--sd-muted); } +.sentier-diagnostics .sd-quiet { color: var(--sd-muted); font-size: var(--sd-t-sm); } +.sentier-diagnostics .sd-note { max-width: 70rem; color: var(--sd-muted); font-size: var(--sd-t-sm); line-height: 1.5; } +.sentier-diagnostics .sd-error { color: var(--sd-fail); } +.sentier-diagnostics .sd-plain { list-style: none; padding: 0; } +.sentier-diagnostics .sd-plain > li { margin: var(--sd-s2) 0; } +.sentier-diagnostics .sd-states { display: flex; flex-wrap: wrap; gap: 0.25rem 0.5rem; margin: 0.6rem 0; padding: 0; list-style: none; } +.sentier-diagnostics .sd-states > li { padding: 0.15rem 0.5rem; border: 1px solid var(--sd-line); border-radius: var(--sd-radius); background: var(--sd-paper-deep); font-size: var(--sd-t-sm); } +.sentier-diagnostics .sd-states > li + li::before { content: "→ "; color: var(--sd-muted); } +.sentier-diagnostics .sd-banner { display: inline-block; margin: var(--sd-s2) 0; padding: 0.3rem 0.6rem; border: 1px solid var(--sd-fail); border-radius: var(--sd-radius); color: var(--sd-fail); } +.sentier-diagnostics .sd-made-by { margin-top: var(--sd-s6); } + +/* the comparison: a row of chips, the whole way first, then each step */ +.sentier-diagnostics .sd-chips { display: flex; flex-wrap: wrap; align-items: center; gap: var(--sd-s2) var(--sd-s3); margin: var(--sd-s3) 0 var(--sd-s2); } +.sentier-diagnostics .sd-chips-label { font-size: var(--sd-t-xs); font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; color: var(--sd-muted); } +.sentier-diagnostics .sd-chip-row { display: flex; flex-wrap: wrap; gap: 0.35rem; min-width: 0; } +.sentier-diagnostics .sd-chip { display: inline-flex; align-items: baseline; gap: 0.4rem; max-width: 24rem; min-width: 0; padding: 0.3rem 0.75rem; border: 1px solid var(--sd-line-strong); + border-radius: 999px; background: var(--sd-surface); color: var(--sd-ink); font: inherit; font-size: var(--sd-t-sm); line-height: 1.3; cursor: pointer; } +.sentier-diagnostics .sd-chip:hover { border-color: var(--sd-accent); } +.sentier-diagnostics .sd-chip:focus-visible { outline: 2px solid var(--sd-accent); outline-offset: 2px; } +.sentier-diagnostics .sd-chip[aria-pressed="true"] { border-color: var(--sd-accent); background: var(--sd-accent); color: var(--sd-on-accent); } +.sentier-diagnostics .sd-chip-no { font-weight: 800; } +.sentier-diagnostics .sd-chip-label { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 600; } +.sentier-diagnostics .sd-chip-count { font-size: var(--sd-t-xs); font-variant-numeric: tabular-nums; white-space: nowrap; opacity: 0.75; } +.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; } -.states { display: flex; flex-wrap: wrap; gap: 0.25rem 0.5rem; padding: 0; margin: 0.6rem 0; list-style: none; } -.states li { background: var(--paper-deep); border: 1px solid var(--line); border-radius: var(--radius); padding: 0.15rem 0.5rem; font-size: 0.9rem; } -.states li + li::before { content: "→ "; color: var(--muted); } +/* below the matrix: the rest of the file, each part closed until a reader opens it */ +.sentier-diagnostics .sd-section { margin-top: var(--sd-s4); border-top: 1px solid var(--sd-line); } +.sentier-diagnostics .sd-section:last-of-type { border-bottom: 1px solid var(--sd-line); } +.sentier-diagnostics .sd-section > summary { padding: var(--sd-s2) 0; cursor: pointer; } +.sentier-diagnostics .sd-section > summary > h3 { display: inline; margin: 0; font-size: var(--sd-t-lg); } +.sentier-diagnostics .sd-section[open] > summary { margin-bottom: var(--sd-s2); } +.sentier-diagnostics .sd-section + .sd-section { margin-top: 0; border-top: 0; } +.sentier-diagnostics .sd-section + .sd-section > summary { border-top: 1px solid var(--sd-line); } +/* the steps: the label and the claim have room, the numbers stay narrow */ +.sentier-diagnostics .sd-steps td:nth-child(2) { min-width: 15rem; } +.sentier-diagnostics .sd-steps td:nth-child(5) { min-width: 18rem; } +.sentier-diagnostics .sd-table td.sd-wide { min-width: 16rem; } +.sentier-diagnostics h4 { margin: var(--sd-s5) 0 var(--sd-s2); } -.toc { position: sticky; top: 0; z-index: 2; background: var(--paper); border-bottom: 1px solid var(--line); - display: flex; flex-wrap: wrap; gap: 0.4rem 1rem; align-items: center; padding: 0.4rem var(--gutter); - max-width: 1200px; margin: 0 auto; } -.toc a { color: var(--ink); } -.compare { margin-left: auto; font-size: 0.9rem; } -.compare-size { font-size: 0.9rem; } -.banner { border: 1px solid var(--error); color: var(--error); border-radius: var(--radius); padding: 0.3rem 0.6rem; display: inline-block; } -select, input, button { font: inherit; color: inherit; background: var(--paper); border: 1px solid var(--line); border-radius: var(--radius); padding: 0.15rem 0.35rem; } -button { cursor: pointer; } -.controls { display: flex; flex-wrap: wrap; gap: 0.5rem 1rem; margin: 0.5rem 0; font-size: 0.9rem; } +/* fields, buttons */ +.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: 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; } +.sentier-diagnostics .sd-filters select { min-width: 7rem; } +.sentier-diagnostics select, .sentier-diagnostics input, .sentier-diagnostics .sd-button { + min-height: 2.25rem; padding: 0.25rem 0.5rem; border: 1px solid var(--sd-line-strong); border-radius: var(--sd-radius); + background: var(--sd-surface); color: var(--sd-ink); font: inherit; } +.sentier-diagnostics input[type="search"] { width: 100%; } +.sentier-diagnostics .sd-button { cursor: pointer; font-weight: 700; } +.sentier-diagnostics .sd-button:hover { border-color: var(--sd-accent); color: var(--sd-accent); } +.sentier-diagnostics select:focus-visible, .sentier-diagnostics input:focus-visible, .sentier-diagnostics .sd-button:focus-visible { outline: 2px solid var(--sd-accent); outline-offset: 1px; } -.table-wrap { overflow-x: auto; max-width: 100%; } -table { border-collapse: collapse; font-size: 0.88rem; } -th, td { border-bottom: 1px solid var(--line); padding: 0.25rem 0.5rem; text-align: left; vertical-align: top; } -th { font-weight: 600; background: var(--paper-deep); } -td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; } -tr.clickable { cursor: pointer; } -tr.clickable:hover td, tr.clickable:focus td { background: var(--paper-deep); } -.zero { color: var(--muted); } +/* tables: tables at every width, whatever the host does with bare ones */ +.sentier-diagnostics .sd-wrap { max-width: 100%; overflow-x: auto; } +.sentier-diagnostics table { display: table; width: auto; margin: 0; border: 0; border-collapse: collapse; background: none; font-size: var(--sd-t-sm); } +.sentier-diagnostics thead { display: table-header-group; position: static; width: auto; height: auto; overflow: visible; clip-path: none; } +.sentier-diagnostics tbody { display: table-row-group; } +.sentier-diagnostics tr { display: table-row; padding: 0; border: 0; } +.sentier-diagnostics th, .sentier-diagnostics td { display: table-cell; padding: 0.25rem 0.5rem; border: 0; border-bottom: 1px solid var(--sd-line); border-radius: 0; + text-align: left; vertical-align: top; letter-spacing: 0; text-transform: none; } +.sentier-diagnostics td + td::before { content: none; } +.sentier-diagnostics th { font-weight: 700; background: var(--sd-paper-deep); } +.sentier-diagnostics td.num, .sentier-diagnostics th.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; } +.sentier-diagnostics tr.sd-row { cursor: pointer; } +.sentier-diagnostics tr.sd-row:hover > *, .sentier-diagnostics tr.sd-row:focus-visible > * { background: var(--sd-paper-deep); } +.sentier-diagnostics tr.sd-row:focus { outline: none; } +.sentier-diagnostics tr.sd-row:focus-visible > th { box-shadow: inset 3px 0 0 var(--sd-accent); } +.sentier-diagnostics .zero { color: var(--sd-muted); } -/* a value: colour from its direction only, strength from its band */ -.cell { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; } -.tone-up { background: color-mix(in srgb, var(--up) calc(var(--s, 0.5) * 55%), transparent); } -.tone-down { background: color-mix(in srgb, var(--down) calc(var(--s, 0.5) * 55%), transparent); } -.tone-up.no-ratio, .tone-down.no-ratio { background-image: repeating-linear-gradient(135deg, transparent 0 4px, rgba(127,127,127,0.35) 4px 6px); } -.tone-noise { color: var(--noise); background-image: repeating-linear-gradient(135deg, transparent 0 5px, rgba(127,127,127,0.18) 5px 7px); } -.tone-near { color: var(--muted); } -.tone-missing { color: var(--error); font-style: italic; } -.tone-none { color: var(--muted); } -.mark { font-size: 0.75em; margin-left: 0.2em; } +/* the matrix: its own frame, scrolling both ways; the names stay on the left, the headings on top */ +.sentier-diagnostics .sd-status { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: 0.2rem var(--sd-s5); font-size: var(--sd-t-sm); } +.sentier-diagnostics .sd-count { margin: 0; font-weight: 700; font-variant-numeric: tabular-nums; } +.sentier-diagnostics .sd-grid-wrap { position: relative; max-height: max(24rem, calc(100vh - 6rem)); overflow: auto; border: 1px solid var(--sd-line); border-radius: var(--sd-radius); } +.sentier-diagnostics table.sd-grid { border-collapse: separate; border-spacing: 0; font-size: var(--sd-t-xs); line-height: 1.35; } +.sentier-diagnostics .sd-grid th, .sentier-diagnostics .sd-grid td { padding: 0.28rem 0.35rem; vertical-align: middle; } +.sentier-diagnostics .sd-grid thead th { position: sticky; top: 0; z-index: 2; vertical-align: bottom; border-bottom-color: var(--sd-line-strong); white-space: normal; min-width: 3.4rem; max-width: 6.5rem; overflow-wrap: break-word; hyphens: auto; font-size: 0.75rem; line-height: 1.2; } +.sentier-diagnostics .sd-grid thead th.sd-name { left: 0; z-index: 3; min-width: 12rem; } +.sentier-diagnostics .sd-grid thead th.sd-name, .sentier-diagnostics .sd-grid thead th.sd-group { max-width: none; overflow-wrap: normal; } +.sentier-diagnostics .sd-grid tbody th { position: sticky; left: 0; z-index: 1; max-width: 18rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; background: var(--sd-surface); font-weight: 600; } +.sentier-diagnostics .sd-grid tbody th .sd-listed { display: inline-block; width: 0.45rem; height: 0.45rem; margin-right: 0.35rem; border-radius: 50%; background: var(--sd-accent); vertical-align: 0.1em; } +.sentier-diagnostics .sd-grid td.sd-group { max-width: 8rem; overflow: hidden; text-overflow: ellipsis; color: var(--sd-muted); white-space: nowrap; } +.sentier-diagnostics .sd-sort { display: block; width: 100%; padding: 0; border: 0; background: none; color: inherit; font: inherit; font-weight: 700; text-align: right; cursor: pointer; } +.sentier-diagnostics .sd-name .sd-sort { text-align: left; } +.sentier-diagnostics .sd-sort:hover { color: var(--sd-accent); } +.sentier-diagnostics th[aria-sort] { box-shadow: inset 0 -3px 0 var(--sd-accent); } +.sentier-diagnostics tr[aria-current="true"] > th { box-shadow: inset 4px 0 0 var(--sd-accent); } +.sentier-diagnostics .sd-more { position: sticky; left: 0; margin: 0; padding: var(--sd-s3) var(--sd-s4); } -.legend { display: flex; flex-wrap: wrap; gap: 0.3rem 0.9rem; font-size: 0.82rem; margin: 0.4rem 0; } -.legend span.key { display: inline-block; min-width: 2.8em; text-align: center; padding: 0 0.3em; border: 1px solid var(--line); border-radius: 3px; margin-right: 0.3em; } +/* a value: colour from its direction only, strength from how far the two lie apart */ +.sentier-diagnostics .cell { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; } +.sentier-diagnostics .tone-up { background: color-mix(in srgb, var(--sd-up) calc(var(--s, 0.5) * 55%), var(--sd-surface)); } +.sentier-diagnostics .tone-down { background: color-mix(in srgb, var(--sd-down) calc(var(--s, 0.5) * 55%), var(--sd-surface)); } +.sentier-diagnostics .tone-up.no-ratio, .sentier-diagnostics .tone-down.no-ratio { background-image: repeating-linear-gradient(135deg, transparent 0 4px, rgba(127, 127, 127, 0.35) 4px 6px); font-weight: 700; } +.sentier-diagnostics .tone-noise { color: var(--sd-noise); background-image: repeating-linear-gradient(135deg, transparent 0 5px, rgba(127, 127, 127, 0.18) 5px 7px); } +.sentier-diagnostics .tone-near { color: var(--sd-muted); } +.sentier-diagnostics .tone-missing { color: var(--sd-fail); font-style: italic; } +.sentier-diagnostics .tone-none { color: var(--sd-muted); } +.sentier-diagnostics .mark { margin-left: 0.2em; font-size: 0.75em; } +.sentier-diagnostics .verdict-look { font-weight: 700; } -.bar-cell { min-width: 2.6rem; } -.bar { height: 2.2rem; display: flex; align-items: flex-end; } -.bar span { display: block; width: 100%; background: var(--muted); min-height: 0; } -.bar.up span { background: var(--up); } -.bar.down span { background: var(--down); } -.bar-n { font-size: 0.75rem; text-align: center; color: var(--muted); } +.sentier-diagnostics .sd-legend { display: flex; flex-wrap: wrap; gap: 0.2rem 0.9rem; margin: 0.4rem 0; font-size: var(--sd-t-xs); color: var(--sd-muted); } +.sentier-diagnostics .sd-status > * { min-width: 0; } +.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); } -.badge { display: inline-block; font-size: 0.75rem; border: 1px solid var(--line); border-radius: 999px; padding: 0 0.5em; margin-right: 0.4em; } -.badge.model { border-color: var(--down); } -.badge.person { border-color: var(--up); } -.verdict-look { font-weight: 600; } +/* 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); } -.steps-chart { display: grid; grid-template-columns: minmax(8rem, 14rem) 1fr; gap: 0.15rem 0.6rem; align-items: center; font-size: 0.85rem; margin: 0.4rem 0 1rem; } -.track { position: relative; height: 0.9rem; background: var(--paper-deep); border-radius: 2px; } -.track .seg { position: absolute; top: 0; bottom: 0; } -.track .seg.up { background: var(--up); } -.track .seg.down { background: var(--down); } -.track .axis { position: absolute; top: -2px; bottom: -2px; width: 1px; background: var(--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); } +.sentier-diagnostics .badge.model { border-color: var(--sd-down); } +.sentier-diagnostics .badge.person { border-color: var(--sd-up); } +.sentier-diagnostics .sd-scope { display: inline-block; margin-right: 0.3em; padding: 0 0.4em; border: 1px solid var(--sd-line-strong); border-radius: 3px; background: var(--sd-paper-deep); font-size: var(--sd-t-xs); font-weight: 700; } -#item-close { float: right; margin-top: -2.4rem; } -#item { border: 1px solid var(--line); border-radius: var(--radius); padding: 0 var(--gutter) var(--gutter); margin-top: 1.5rem; } +/* the item: a drawer on the right, the whole window on a phone */ +.sentier-diagnostics .sd-drawer { position: fixed; top: 0; right: 0; bottom: 0; z-index: 20; display: flex; flex-direction: column; width: var(--sd-drawer); max-width: 100%; + border-left: 1px solid var(--sd-line-strong); background: var(--sd-surface); box-shadow: -0.5rem 0 2rem color-mix(in srgb, var(--sd-ink) 16%, transparent); } +.sentier-diagnostics .sd-drawer-head { flex: none; display: grid; grid-template-columns: minmax(0, 1fr) auto; column-gap: var(--sd-s4); align-items: start; + padding: var(--sd-s4) var(--sd-s5); border-bottom: 1px solid var(--sd-line); background: var(--sd-paper-deep); } +.sentier-diagnostics .sd-drawer-head > .sd-label { grid-column: 1; margin: 0; font-size: var(--sd-t-xs); font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; color: var(--sd-muted); } +.sentier-diagnostics .sd-drawer-head > h3 { grid-column: 1; margin: 0.2rem 0 0; font-size: var(--sd-t-lg); line-height: 1.3; overflow-wrap: anywhere; } +.sentier-diagnostics .sd-drawer-head > h3:focus { outline: none; } +.sentier-diagnostics .sd-drawer-head > .sd-button { grid-column: 2; grid-row: 1 / span 2; align-self: center; } +.sentier-diagnostics .sd-drawer-body { flex: 1 1 auto; min-height: 0; overflow: auto; overscroll-behavior: contain; padding: var(--sd-s4) var(--sd-s5) var(--sd-s6); } +.sentier-diagnostics .sd-drawer-body > h4:first-child { margin-top: 0; } +.sentier-diagnostics .sd-why { padding: 0; list-style: none; } +.sentier-diagnostics .sd-why > li { margin: var(--sd-s2) 0; padding: var(--sd-s2) var(--sd-s3); border-left: 3px solid var(--sd-line-strong); border-radius: 0 4px 4px 0; background: var(--sd-paper-deep); font-size: var(--sd-t-sm); } +.sentier-diagnostics .sd-why > li.sd-none { border-left-color: var(--sd-line); background: none; color: var(--sd-muted); } -@media (max-width: 640px) { - .compare { margin-left: 0; } - h1 { font-size: 1.3rem; } +@media (max-width: 47.99rem) { + .sentier-diagnostics { --sd-drawer: 100vw; } + .sentier-diagnostics .sd-drawer { border-left: 0; box-shadow: none; } + .sentier-diagnostics .sd-drawer-head { padding: var(--sd-s3) var(--sd-s4); } + .sentier-diagnostics .sd-drawer-body { padding: var(--sd-s3) var(--sd-s4) var(--sd-s6); } + .sentier-diagnostics .sd-grid tbody th { max-width: 11rem; } + .sentier-diagnostics .sd-grid .sd-group { display: none; } } diff --git a/src/sentier_diagnostics/page/diagnostics.js b/src/sentier_diagnostics/page/diagnostics.js index 6dd36e3..0c7bdb9 100644 --- a/src/sentier_diagnostics/page/diagnostics.js +++ b/src/sentier_diagnostics/page/diagnostics.js @@ -1,14 +1,25 @@ /* sentier-diagnostics page: shows a diagnostics file (sentier-diagnostics/1) as it is. * - * Plain JavaScript, no library, no network but the file itself. The page works out no - * class, direction, band, verdict or count: they are in the file, checked by the - * validator. It only orders and filters, formats numbers, and subtracts consecutive - * results to show each step's share. Every text of the file is set as text, never as markup. + * Plain JavaScript, no library, no network but the files the page names. The script mounts + * into every element marked `data-sentier-diagnostics` (the body `page.body` writes), on a + * page of its own or inside a host's page; it looks nothing up outside that element but the + * address and the globals named below. A host that draws the element later calls + * `SentierDiagnostics.mount(element, {data})`, and marks it `data-sentier-diagnostics="manual"` + * so that it is not mounted before. + * + * The page works out no class, direction, verdict or count: they are in the file, checked by + * the validator. It only orders and filters, formats numbers, divides the result after by the + * result before to show their ratio, and subtracts consecutive results to show each step's + * share. Every text of a file is set as text, never as markup. */ -(function (root) { +(function (global) { 'use strict'; var FORMAT = 'sentier-diagnostics/1'; + var MATRIX_FORMAT = 'sentier-diagnostics-matrix/1'; + var MATRIX_MAX_ITEMS = 200000; // matrix.MAX_ITEMS + var MATRIX_MAX_BYTES = 64 * 1024 * 1024; // matrix.MAX_BYTES + var PAGE = 300; // rows of the grid drawn at a time var MOVES = ['differs', 'beyond 10x', 'zero reference', 'zero result', 'sign change']; var QUIET = ['agrees', 'within noise', 'near zero']; // the order of the classes from the worst: the same as the Python rule (rule.RANK) @@ -16,8 +27,11 @@ 'sign change': 0, 'zero reference': 1, 'zero result': 2, 'beyond 10x': 3, 'differs': 4, 'missing': 5, 'within noise': 6, 'agrees': 7, 'near zero': 8 }; - var STRENGTH = { '1-1.1': 0.3, '1.1-1.25': 0.5, '1.25-2': 0.7, '2-10': 0.85, 'over 10': 1 }; + var STRENGTH = { '1-1.1': 0.25, '1.1-1.25': 0.45, '1.25-2': 0.65, '2-10': 0.85, 'over 10': 1 }; + // the ends of the bands, as rule.SIZE_STEPS: the distance (|log10| of the factor) at which each ends + var SIZE_STEPS = [[Math.log10(1.1), '1-1.1'], [Math.log10(1.25), '1.1-1.25'], [Math.log10(2), '1.25-2'], [1, '2-10']]; var LOOK = ['off claim', 'not claimed', 'claimed, not moved']; + var LOOK_MARK = { 'off claim': '◐', 'not claimed': '■', 'claimed, not moved': '○' }; var SAID = { 'agrees': 'the two results differ by no more than the tolerance', 'within noise': 'they differ by no more than two builds of one state do', @@ -26,17 +40,29 @@ 'zero reference': 'the result before is zero or within the floor; the result after is not', 'zero result': 'the result after is zero or within the floor; the result before is not', 'sign change': 'the two results have different signs', - 'near zero': 'both results are within the floor of their indicator and unit: their ratio says nothing', + 'near zero': 'both results are within their floor: their ratio says nothing', 'missing': 'a side has no result; it is not read as zero' }; var SHORT = { 'agrees': '=', 'within noise': '~', 'near zero': '≈ 0', 'missing': '∅', 'zero reference': '0 →', 'zero result': '→ 0', 'sign change': '±' }; + // the codes of a matrix (matrix.CODES, matrix.VERDICT_CODES) + var CODES = { + '=': ['agrees', null], '~': ['within noise', null], '0': ['near zero', null], '-': ['missing', null], + 'D': ['differs', 'up'], 'd': ['differs', 'down'], 'B': ['beyond 10x', 'up'], 'b': ['beyond 10x', 'down'], + 'R': ['zero reference', 'up'], 'r': ['zero reference', 'down'], 'T': ['zero result', 'up'], 't': ['zero result', 'down'], + 'S': ['sign change', 'up'], 's': ['sign change', 'down'] + }; + var VERDICT_CODES = { + 'a': 'as claimed', 'o': 'off claim', 'n': 'not claimed', 'c': 'claimed, not moved', + '~': 'within noise', '=': 'unchanged', '?': 'not judged' + }; + var NO_CLAIM = '.'; // ------------------------------------------------------------------ pure helpers - function groupThousands(n) { return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ' '); } + function groupThousands(n) { return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ' '); } // a result as a reader reads it: four significant digits; never "0" for a value that is not 0 function formatNumber(v) { @@ -45,7 +71,7 @@ var a = Math.abs(v); // one style from 1e4 on: toPrecision(4) would write 12345 as "1.235e+4" itself if (a >= 1e4 || a < 1e-3) { - return v.toExponential(3).replace(/\.?0+e/, 'e').replace('e+', 'e').replace(/-/g, '\u2212'); + return v.toExponential(3).replace(/\.?0+e/, 'e').replace('e+', 'e').replace(/-/g, '−'); } var s = v.toPrecision(4); if (s.indexOf('.') >= 0) s = s.replace(/0+$/, '').replace(/\.$/, ''); @@ -68,7 +94,63 @@ function shareText(part) { var v = part * 100, size = Math.abs(v); var text = size === 0 ? '0' : size < 0.1 ? size.toExponential(1) : size.toFixed(1); - return (v > 0 ? '' : v < 0 ? '\u2212' : '') + text + ' %'; + return (v > 0 ? '' : v < 0 ? '−' : '') + text + ' %'; + } + + // the result after divided by the result before, of two results of one sign; never "1" for + // a ratio that is not 1, and never "Infinity" where the quotient leaves the floats + function ratioText(before, after) { + var r = after / before; + if (!isFinite(r) || r === 0) { + var orders = Math.log10(Math.abs(after)) - Math.log10(Math.abs(before)); + return '1e' + String(Math.round(orders)).replace('-', '−'); + } + var d = r - 1; + if (d !== 0 && Math.abs(d) < 1e-3) return '1 ' + (d > 0 ? '+ ' : '− ') + formatNumber(Math.abs(d)); + return formatNumber(r); + } + + // a ratio as the grid shows it, compact enough for a column: three significant digits + // ("1.00", "0.984", "2.27"), a power of ten below 0.01 and from 1000 on, and "1e600" where + // the quotient leaves the floats. "1.00" is a rounding, not a claim of agreement: the + // class says whether the two agree, and the cell's title holds both results exactly. + function ratioShort(before, after) { + var r = after / before; + if (!isFinite(r) || r === 0) return ratioText(before, after); + var s = r.toPrecision(3); + if (r < 0.01 || s.indexOf('e') >= 0) s = r.toExponential(2).replace(/\.?0+e/, 'e').replace('e+', 'e'); + return s.replace(/-/g, '−'); + } + + // the 10th, 50th and 90th percentile in one precision: the smallest (three digits at + // least, six at most) at which every two that differ read differently. "1.00, 1.00, 1.00" + // over values that moved would hide the spread a reader looks for, and one line in mixed + // precisions reads a rounded number as exact. Where six digits still read a percentile + // as the median, the line says how it lies, and the numbers left take the digits they need. + function quantileTexts(qs) { + var values = [qs.p10, qs.median, qs.p90]; + var one = function (v, digits) { + if (v !== 0 && (Math.abs(v) < 0.01 || Math.abs(v) >= 1e4)) return v.toExponential(digits - 1).replace(/\.?0+e/, 'e').replace('e+', 'e').replace(/-/g, '−'); + return v.toPrecision(digits).replace(/-/g, '−'); + }; + var pairs = [[0, 1], [1, 2], [0, 2]]; + var digitsFor = function (kept) { + for (var d = 3; d <= 6; d++) { + var apart = pairs.every(function (p) { + return kept.indexOf(p[0]) < 0 || kept.indexOf(p[1]) < 0 || values[p[0]] === values[p[1]] || one(values[p[0]], d) !== one(values[p[1]], d); + }); + if (apart) return d; + } + return null; + }; + var words = {}; + var d = digitsFor([0, 1, 2]); + if (d === null) { + if (values[0] !== values[1] && one(values[0], 6) === one(values[1], 6)) words[0] = 'just under the median'; + if (values[2] !== values[1] && one(values[2], 6) === one(values[1], 6)) words[2] = 'just over the median'; + d = digitsFor([0, 1, 2].filter(function (i) { return !(i in words); })) || 6; + } + return [0, 1, 2].map(function (i) { return i in words ? words[i] : one(values[i], d); }); } // Steps whose differences add up to more than this many times the whole difference @@ -115,8 +197,8 @@ // what a step's noise says: measured and identical, measured, or not measured. Two // identical builds are a finding, and never read as "not measured"; an indicator the noise // holds no size for was not measured, and is never read as identical. `ids` are the - // file's indicators. - function noiseText(noise, ids) { + // file's indicators, and `many` what the file calls them. + function noiseText(noise, ids, many) { if (!noise || !noise.measured) return 'not measured'; var by = noise.by || {}; var between = ' between ' + noise.between.join(' and '); @@ -124,7 +206,7 @@ var all = ids || keys; var absent = all.filter(function (k) { return !(k in by); }).length; if (!keys.length) return 'not measured: no result beyond the floor in both builds' + between; - var part = absent ? ', for ' + keys.length + ' of ' + all.length + ' indicators' : ''; + var part = absent ? ', for ' + keys.length + ' of ' + all.length + ' ' + (many || 'indicators') : ''; var largest = Math.max.apply(null, keys.map(function (k) { return by[k]; })); if (largest === 0) return 'identical' + between + part; return 'measured' + between + part + (largest > LARGE_NOISE ? '; large: up to ' + formatNumber(largest * 100) + ' %' : ''); @@ -136,12 +218,37 @@ return typeof value === 'string' && /^https:\/\/[^\s]+$/.test(value) ? value : null; } + // a file a page may load beside itself: a plain relative name, never an address or a way up + function safeName(value) { + return typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._\/-]*$/.test(value) && value.indexOf('..') < 0; + } + function bandStep(band) { if (!band) return null; var at = band.indexOf('factor '); return at < 0 ? null : band.slice(at + 7); } + // how far the sizes of two results of one sign lie apart, as rule.distance: the |log10| + // of their factor, or, where the factor is too large or too small for a float, the + // difference of their logarithms, which cannot overflow + var SMALLEST_NORMAL = 2.2250738585072014e-308; + function distance(before, after) { + var factor = Math.abs(after) / Math.abs(before); + if (isFinite(factor) && factor >= SMALLEST_NORMAL) return Math.abs(Math.log10(factor)); + return Math.abs(Math.log10(Math.abs(after)) - Math.log10(Math.abs(before))); + } + + // the band of a pair, as rule.band, for a matrix, which holds no bands: the class and + // direction are the file's, the band only names how far apart the two lie + function bandOf(before, after, cls, dir) { + if (cls === 'beyond 10x') return dir + ', factor over 10'; + if (cls !== 'differs') return null; + var found = distance(before, after); + for (var i = 0; i < SIZE_STEPS.length; i++) if (found <= SIZE_STEPS[i][0]) return dir + ', factor ' + SIZE_STEPS[i][1]; + return dir + ', factor ' + SIZE_STEPS[SIZE_STEPS.length - 1][1]; + } + // the reader's own size filter: it hides values, it changes no class and no count. // A value without a ratio (a zero or a sign change) and a missing one always pass. function sizeAtLeast(cls, band, threshold) { @@ -191,14 +298,21 @@ return view; } - // how far the sizes of two results of one sign lie apart, as rule.distance: the |log10| - // of their factor, or, where the factor is too large or too small for a float, the - // difference of their logarithms, which cannot overflow - var SMALLEST_NORMAL = 2.2250738585072014e-308; - function distance(before, after) { - var factor = Math.abs(after) / Math.abs(before); - if (isFinite(factor) && factor >= SMALLEST_NORMAL) return Math.abs(Math.log10(factor)); - return Math.abs(Math.log10(Math.abs(after)) - Math.log10(Math.abs(before))); + // a value of the matrix grid: the ratio after ÷ before in every cell that has one, agreeing + // pairs included ("1.00"), so that a column reads as numbers; else what cellView says + // ("≈ 0", "from 0", "− → +", "missing"). The class shows as the tint and a mark, never in + // place of the number: the colour is the direction's, its strength the band's. The ratio is + // a display; the class stays the file's. + var RATIO_CLASSES = ['agrees', 'within noise', 'differs', 'beyond 10x']; + function ratioView(before, after, cls, dir, band) { + var view = cellView(before, after, cls, dir, band); + var ratio = before !== null && after !== null && before !== 0 && after !== 0 && (before > 0) === (after > 0); + if (ratio && RATIO_CLASSES.indexOf(cls) >= 0) { + view.text = ratioShort(before, after); + if (cls === 'within noise') view.mark = '~'; + view.title += ' After ÷ before: ' + String(after / before) + '.'; + } + return view; } // the key that orders values from the worst: the same as the Python rule (rule.severity) @@ -245,424 +359,863 @@ if (!d[tables[k]] || typeof d[tables[k]] !== 'object' || Array.isArray(d[tables[k]])) return 'the ' + tables[k] + ' of the file is not a table'; } if (!d.indicators.length) return 'the file has no indicator'; + if (d.indicator !== undefined && d.indicator !== null && !(d.indicator && typeof d.indicator.one === 'string' && + typeof d.indicator.many === 'string')) return 'the indicator word of the file is not {one, many}'; if (d.steps.length !== d.states.length - 1) return 'the file has not one step fewer than states'; if (!d.counts.steps || !d.counts.total) return 'the counts of the file are not {steps, total}'; return null; } - // ------------------------------------------------------------------ the page - - var D = null, B = {}; - var view = { comp: null, worstN: 20, worstIndicator: '', find: '', cls: '', verdict: '', group: '', limit: 100, size: 0 }; - - function el(tag, props, children) { - var node = document.createElement(tag); - if (props) { - Object.keys(props).forEach(function (key) { - var value = props[key]; - if (value === null || value === undefined || value === false) return; - if (key === 'text') node.textContent = value; - else if (key === 'cls') node.className = value; - else if (key === 'style') node.setAttribute('style', value); - else node.setAttribute(key, value === true ? '' : value); - }); - } - (children || []).forEach(function (child) { - if (child === null || child === undefined) return; - node.appendChild(typeof child === 'string' ? document.createTextNode(child) : child); - }); - return node; + function sameList(a, b) { + if (!Array.isArray(a) || a.length !== b.length) return false; + for (var i = 0; i < a.length; i++) if (a[i] !== b[i]) return false; + return true; } - function q(id) { return document.getElementById(id); } - function clear(node) { while (node.firstChild) node.removeChild(node.firstChild); return node; } - function n(x) { return x === null || x === undefined ? '—' : groupThousands(x); } - function indicatorName(id) { - for (var i = 0; i < D.indicators.length; i++) { - if (D.indicators[i].id === id) return D.indicators[i].short || D.indicators[i].name; + // what a page needs of a matrix before it draws a row of it: that it is of the file the + // page shows, and that every row has the shape the format gives. Its codes are not worked + // out again here: `sentier-diagnostics check` does that. + function checkMatrix(m, d) { + if (!m || typeof m !== 'object') return 'not a matrix'; + if (m.format !== MATRIX_FORMAT) return 'not a matrix of format ' + MATRIX_FORMAT; + var of = m.of || {}; + var ids = d.indicators.map(function (i) { return i.id; }); + if (of.title !== d.title || !sameList(of.states, d.states.map(function (s) { return s.id; })) || + !sameList(of.indicators, ids) || !sameList(of.steps, d.steps.map(function (s) { return s.id; }))) { + return 'it is the matrix of another file: its title, states, indicators or steps differ'; } - return id; - } - function stepIndex(comp) { // the position of a comparison in an item's lists of classes - if (comp === 'total') return D.steps.length; - for (var i = 0; i < D.steps.length; i++) if (D.steps[i].id === comp) return i; - return D.steps.length; - } - function compLabel(comp) { - if (comp === 'total') return 'The whole way: ' + D.states[0].label + ' → ' + D.states[D.states.length - 1].label; - var k = stepIndex(comp); - return 'Step ' + k + ': ' + D.steps[k].label; - } - function pairOf(item, indicator, k) { - var values = item.values[indicator]; - return k === D.steps.length ? [values[0], values[values.length - 1]] : [values[k], values[k + 1]]; - } - function verdictOf(item, indicator, k) { - if (!item.verdicts || k >= D.steps.length) return null; - return item.verdicts[indicator][k]; + if (!Array.isArray(m.items) || m.items.length > MATRIX_MAX_ITEMS) return 'its items are not a list of at most ' + groupThousands(MATRIX_MAX_ITEMS); + var n = m.items.length; + if (d.matrix && d.matrix.items !== n) return 'the file says ' + d.matrix.items + ' items, the matrix holds ' + n; + var claimed = d.steps.some(function (s) { return !!s.claim; }); + if (!Array.isArray(m.values) || m.values.length !== n || !Array.isArray(m.classes) || m.classes.length !== n) return 'its values or classes are not one row per item'; + if (claimed ? !Array.isArray(m.verdicts) || m.verdicts.length !== n : m.verdicts !== null) return 'its verdicts are not one row per item, or null where no step has a claim'; + var ns = d.states.length, nk = d.steps.length, ni = ids.length; + for (var at = 0; at < n; at++) { + var row = m.items[at]; + if (!Array.isArray(row) || row.length !== 5 || typeof row[0] !== 'string' || typeof row[1] !== 'string') return 'item ' + at + ' is not [id, name, place, group, unit]'; + var values = m.values[at]; + if (!Array.isArray(values) || values.length !== ni * ns) return 'item ' + row[0] + ': not one result per indicator and state'; + for (var v = 0; v < values.length; v++) if (values[v] !== null && (typeof values[v] !== 'number' || !isFinite(values[v]))) return 'item ' + row[0] + ': a result that is not a number'; + var codes = m.classes[at]; + if (typeof codes !== 'string' || codes.length !== ni * (nk + 1)) return 'item ' + row[0] + ': not one class code per indicator and comparison'; + for (var c = 0; c < codes.length; c++) if (!CODES.hasOwnProperty(codes[c])) return 'item ' + row[0] + ': an unknown class code'; + if (claimed) { + var said = m.verdicts[at]; + if (typeof said !== 'string' || said.length !== ni * nk) return 'item ' + row[0] + ': not one verdict code per indicator and step'; + for (var s = 0; s < said.length; s++) if (said[s] !== NO_CLAIM && !VERDICT_CODES.hasOwnProperty(said[s])) return 'item ' + row[0] + ': an unknown verdict code'; + } + } + return listedDiffer(matrixRows(m, d), d); } - function cell(item, indicator, k) { - var pair = pairOf(item, indicator, k); - var cls = item.classes[indicator][k]; - var v = cellView(pair[0], pair[1], cls, item.directions[indicator][k], item.bands[indicator][k]); - var verdict = verdictOf(item, indicator, k); - var title = v.title + (verdict ? ' Verdict: ' + verdict + '.' : ''); - var classes = 'cell tone-' + v.tone + (v.noRatio ? ' no-ratio' : ''); - var td = el('td', { cls: classes, title: title, style: v.strength ? '--s:' + v.strength : null, 'data-class': cls }, - [v.text, v.mark ? el('span', { cls: 'mark', text: v.mark, 'aria-hidden': 'true' }) : null]); - if (verdict && LOOK.indexOf(verdict) >= 0) td.appendChild(el('span', { cls: 'mark verdict-look', text: verdict === 'claimed, not moved' ? '○' : verdict === 'off claim' ? '◐' : '■', title: verdict })); - return td; + // A matrix says of every item this file lists what the file says: its name, place, group and + // unit, its results, classes, directions and verdicts. A matrix left over from another run of + // the same chain has the same title, states, steps and count, and other numbers; the page + // would draw them in place of the file's. + function listedDiffer(rows, d) { + var ids = d.indicators.map(function (i) { return i.id; }); + var found = 0; + for (var r = 0; r < rows.length; r++) { + var row = rows[r], item = row.item; + if (!item) continue; + found++; + if (row.name !== item.name || row.place !== item.place || row.group !== item.group || row.unit !== item.unit) { + return 'item ' + row.id + ': its name, place, group or unit differ from what this file lists'; + } + for (var x = 0; x < ids.length; x++) { + var id = ids[x]; + var verdicts = row.verdicts && item.verdicts ? sameList(row.verdicts[id], item.verdicts[id] || []) : !row.verdicts === !item.verdicts; + if (!sameList(row.values[id], item.values[id] || []) || !sameList(row.classes[id], item.classes[id] || []) || + !sameList(row.directions[id], item.directions[id] || []) || !verdicts) { + return 'item ' + row.id + ', ' + id + ': its results or classes differ from what this file lists for it'; + } + } + } + return found === d.items.length ? null : (d.items.length - found) + ' of the items this file lists are not in it'; } - function legend(node) { - clear(node); - var keys = [ - ['tone-up', 'up', 'went up (as signed numbers)'], - ['tone-down', 'down', 'went down: two results below zero that go further below zero went down'], - ['tone-up no-ratio', '0 →', 'from zero, to zero or across zero: no ratio'], - ['tone-none', '=', 'agrees within the tolerance'], - ['tone-noise', '~', 'within the measured noise'], - ['tone-near', '≈ 0', 'near zero on both sides'], - ['tone-missing', 'missing', 'a side has no result'] - ]; - keys.forEach(function (k) { - node.appendChild(el('span', null, [el('span', { cls: 'key ' + k[0], style: '--s:0.7', text: k[1] }), k[2]])); + // the rows of a checked matrix, in the shape of a listed item: values, classes, directions + // and verdicts per indicator. A listed item keeps its own record beside the row. + function matrixRows(m, d) { + var ids = d.indicators.map(function (i) { return i.id; }); + var ns = d.states.length, nk = d.steps.length; + var listed = {}; + d.items.forEach(function (item) { listed[item.id] = item; }); + return m.items.map(function (row, at) { + var out = { id: row[0], name: row[1], place: row[2], group: row[3], unit: row[4], values: {}, classes: {}, directions: {}, + bands: null, verdicts: m.verdicts ? {} : null, item: listed[row[0]] || null }; + ids.forEach(function (id, x) { + out.values[id] = m.values[at].slice(x * ns, (x + 1) * ns); + var codes = m.classes[at].slice(x * (nk + 1), (x + 1) * (nk + 1)).split(''); + out.classes[id] = codes.map(function (c) { return CODES[c][0]; }); + out.directions[id] = codes.map(function (c) { return CODES[c][1]; }); + if (m.verdicts) { + out.verdicts[id] = m.verdicts[at].slice(x * nk, (x + 1) * nk).split('').map(function (c) { return c === NO_CLAIM ? null : VERDICT_CODES[c]; }); + } + }); + if (out.item) out.bands = out.item.bands; + return out; }); - node.appendChild(el('span', null, ['■ not claimed, ◐ off claim, ○ claimed, not moved'])); } - function renderHeader() { - document.title = D.title; - q('title').textContent = D.title; - q('about').textContent = D.about || ''; - var states = clear(q('states')); - D.states.forEach(function (s) { - var identity = Object.keys(s.identity).map(function (k) { return k + ': ' + s.identity[k]; }).join(', '); - var join = s.join ? n(s.join.compared) + ' compared, ' + n(s.join.unmatched) + ' unmatched, ' + n(s.join.ambiguous) + ' ambiguous' : ''; - states.appendChild(el('li', { title: (s.about || '') + (identity ? ' (' + identity + ')' : '') + (s.join && s.join.note ? ' ' + s.join.note : '') }, - [s.label + (s.kind === 'published' ? ' (published)' : ''), join ? el('span', { cls: 'quiet', text: ' · ' + join }) : null])); - }); - var c = D.items_count; - q('tier').textContent = groupThousands(c.all) + ' ' + D.item.many + ', ' + D.indicators.length + ' indicators. ' + - (D.tier === 'counts' ? 'This file holds counts only: no single ' + D.item.one + ' is shown.' - : groupThousands(c.listed) + ' of the ' + groupThousands(c.qualifying) + ' ' + D.item.many + ' worth a look are in this file' + - (c.not_listed ? '; ' + groupThousands(c.not_listed) + ' are not.' : '.')); - q('audience').textContent = D.audience === 'local' - ? 'Local file: its writer has not said that it may be published.' : ''; - q('audience').hidden = D.audience !== 'local'; - // only a chain that starts from the published results has a step 0 that reproduces them - q('steps-zero').hidden = D.states[0].kind !== 'published'; - q('made-by').textContent = 'Written by ' + D.made_by + '. ' + FORMAT + '.'; - var select = clear(q('comparison')); - select.appendChild(el('option', { value: 'total', text: 'The whole way' })); - D.steps.forEach(function (s, k) { select.appendChild(el('option', { value: s.id, text: 'Step ' + k + ': ' + s.label })); }); - select.value = view.comp; + function listedRow(item) { + return { id: item.id, name: item.name, place: item.place, group: item.group, unit: item.unit, values: item.values, + classes: item.classes, directions: item.directions, bands: item.bands, verdicts: item.verdicts, item: item }; } - function sumOver(comp, fn) { - var blocks = comp === 'total' ? D.counts.total : D.counts.steps[comp]; - return Object.keys(blocks).reduce(function (acc, key) { return acc + fn(blocks[key]); }, 0); - } - function moved(block) { return MOVES.reduce(function (a, k) { return a + block.classes[k]; }, 0); } - - function renderSteps() { - var table = clear(q('steps-table')); - var head = ['#', 'Step', 'Kind', 'Explained', 'Claim', 'Moved', 'Up', 'Down', 'As claimed', 'Off claim', 'Not claimed', 'Claimed, not moved', 'Within noise', 'Missing before', 'Missing after', 'Tolerance', 'Noise']; - table.appendChild(el('thead', null, [el('tr', null, head.map(function (h) { return el('th', { scope: 'col', text: h }); }))])); - var body = el('tbody'); - D.steps.forEach(function (s, k) { - var verdict = function (name) { return s.claim ? n(sumOver(s.id, function (b) { return b.verdicts[name]; })) : '—'; }; - var noise = noiseText(s.noise, D.indicators.map(function (i) { return i.id; })); - // the step from the published results: what moved there is the residual the chain - // starts from, not a regression, whatever its claim says - var unrepro = sumOver(s.id, moved); - var residual = k === 0 && D.states[0].kind === 'published' - ? (unrepro === 1 ? '1 value' : n(unrepro) + ' values') + ' not reproduced within the tolerance: the residual the chain starts from, not a regression.' : null; - body.appendChild(el('tr', null, [ - el('td', { cls: 'num', text: String(k) }), - el('td', null, [safeLink(s.link) ? el('a', { href: safeLink(s.link), text: s.label }) : s.label, s.about ? el('div', { cls: 'quiet', text: s.about }) : null, - residual ? el('div', { cls: 'quiet', text: residual }) : null]), - el('td', { text: s.kind }), - el('td', { text: s.explained ? 'yes' : 'no: nothing explains it', cls: s.explained ? null : 'error' }), - el('td', null, [s.claim ? s.claim.text : 'no claim', s.claim && s.claim.by ? el('div', null, [badge(s.claim.by)]) : null, - s.claim && s.claim.scope.some(function (e) { return e.items === null; }) - ? el('div', { cls: 'quiet', text: 'Its list of ' + D.item.many + ' is not in this file' + (s.claim.reach !== null ? ' (' + n(s.claim.reach) + ')' : '') + ': the verdicts were worked out by its writer and cannot be checked again here.' }) : null]), - el('td', { cls: 'num', text: n(sumOver(s.id, moved)) }), - el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.directions.up; })) }), - el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.directions.down; })) }), - el('td', { cls: 'num', text: verdict('as claimed') }), - el('td', { cls: 'num', text: verdict('off claim') }), - el('td', { cls: 'num', text: verdict('not claimed') }), - el('td', { cls: 'num', text: verdict('claimed, not moved') }), - el('td', { cls: 'num', text: verdict('within noise') }), - el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.missing.before + b.missing.both; })) }), - el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.missing.after + b.missing.both; })) }), - el('td', { cls: 'num', text: String(s.tolerance.value), title: s.tolerance.basis + (s.tolerance.note ? ': ' + s.tolerance.note : '') }), - el('td', { text: noise }) - ])); - }); - table.appendChild(body); - - var total = clear(q('total-table')); - q('total-heading').textContent = 'The whole way: ' + D.states[0].label + ' → ' + D.states[D.states.length - 1].label; - var classes = Object.keys(D.counts.total[D.indicators[0].id].classes); - var cols = ['Indicator'].concat(classes, ['Up', 'Down', 'Largest step', 'Spread over steps', 'Not attributable', 'Moved by what nothing explains']); - total.appendChild(el('thead', null, [el('tr', null, cols.map(function (h) { return el('th', { scope: 'col', text: h, title: SAID[h] || null }); }))])); - var tbody = el('tbody'); - D.indicators.forEach(function (ind) { - var block = D.counts.total[ind.id]; - var att = D.attribution[ind.id]; - var ranked = Object.keys(att.dominant).filter(function (k) { return att.dominant[k]; }) - .sort(function (a, b) { return att.dominant[b] - att.dominant[a]; }) - .map(function (k) { return D.steps[stepIndex(k)].label + ' (' + att.dominant[k] + ')'; }); - var row = [el('th', { scope: 'row', text: ind.name + (ind.unit ? ' (' + ind.unit + ')' : '') })]; - classes.forEach(function (c) { - var title = c === 'missing' ? 'missing before: ' + block.missing.before + ', after: ' + block.missing.after + ', on both sides: ' + block.missing.both : null; - row.push(el('td', { cls: 'num' + (block.classes[c] ? '' : ' zero'), text: n(block.classes[c]), title: title })); - }); - row.push(el('td', { cls: 'num', text: n(block.directions.up) }), el('td', { cls: 'num', text: n(block.directions.down) })); - row.push(el('td', { text: ranked.join(', ') || 'none' })); - row.push(el('td', { cls: 'num', text: n(att.spread), title: 'its total moved, and no single step moved it: small steps that add up' })); - row.push(el('td', { cls: 'num', text: n(att.not_attributable), title: 'its total moved, and it has no result in a state between: its difference cannot be split' })); - row.push(el('td', { cls: 'num', text: n(att.unexplained_moved), title: 'moved in a step that no cause explains' })); - tbody.appendChild(el('tr', null, row)); - }); - total.appendChild(tbody); - } + // ------------------------------------------------------------------ one mounted page - function renderDistributions() { - var comp = view.comp; - var blocks = comp === 'total' ? D.counts.total : D.counts.steps[comp]; - var first = blocks[D.indicators[0].id]; - var bands = Object.keys(first.bands); - var down = bands.filter(function (b) { return b.indexOf('down') === 0; }); - var up = bands.filter(function (b) { return b.indexOf('up') === 0; }); - var middle = ['agrees', 'within noise']; - var aside = ['zero reference', 'zero result', 'sign change', 'near zero', 'missing']; - var columns = down.map(function (b) { return ['band', b, 'down']; }) - .concat(middle.map(function (c) { return ['class', c, '']; })) - .concat(up.map(function (b) { return ['band', b, 'up']; })) - .concat(aside.map(function (c) { return ['class', c, '']; })); - var table = clear(q('dist-table')); - var head = [el('th', { scope: 'col', text: 'Indicator' })]; - columns.forEach(function (c) { - var label = c[0] === 'band' ? (c[2] === 'up' ? '↑ ' : '↓ ') + bandStep(c[1]) : (SHORT[c[1]] || c[1]); - head.push(el('th', { scope: 'col', cls: 'num', text: label, title: c[1] + (SAID[c[1]] ? ': ' + SAID[c[1]] : '') })); - }); - table.appendChild(el('thead', null, [el('tr', null, head)])); - var body = el('tbody'); - D.indicators.forEach(function (ind) { - var block = blocks[ind.id]; - var row = [el('th', { scope: 'row', text: indicatorName(ind.id) })]; - columns.forEach(function (c) { - var count = c[0] === 'band' ? block.bands[c[1]] : block.classes[c[1]]; - var share = block.pairs ? count / block.pairs : 0; - var bar = el('div', { cls: 'bar ' + c[2] }, [el('span', { style: 'height:' + (count ? Math.max(1, Math.round(share * 100)) : 0) + '%' })]); - row.push(el('td', { cls: 'bar-cell', title: c[1] + ': ' + count + ' of ' + block.pairs }, [bar, el('div', { cls: 'bar-n', text: groupThousands(count) })])); - }); - body.appendChild(el('tr', null, row)); - }); - table.appendChild(body); - } + function mount(root, given) { + if (!root || root.getAttribute('data-sd-mounted') !== null) return null; + root.setAttribute('data-sd-mounted', ''); + given = given || {}; + var doc = root.ownerDocument || global.document; + var win = global; + var standalone = root.getAttribute('data-sd-standalone') !== null; + var base = root.getAttribute('data-sd-base') || ''; - function renderWorst() { - var k = stepIndex(view.comp); - var rows = []; - D.items.forEach(function (item) { - D.indicators.forEach(function (ind) { - if (view.worstIndicator && ind.id !== view.worstIndicator) return; - var cls = item.classes[ind.id][k]; - if (QUIET.indexOf(cls) >= 0) return; - if (!sizeAtLeast(cls, item.bands[ind.id][k], view.size)) return; - var pair = pairOf(item, ind.id, k); - rows.push({ item: item, ind: ind.id, key: severityKey(pair[0], pair[1], cls).concat([item.id, ind.id]) }); + var D = null, B = {}, LISTED = [], M = null; + var matrix = { state: 'none', said: '' }; + var view = { comp: null, worstN: 20, worstIndicator: '', find: '', cls: '', verdict: '', group: '', limit: PAGE, size: 0, sort: 'worst', open: null, distScale: 'card' }; + var lastFocus = null; + + function q(name) { return root.querySelector('[data-sd="' + name + '"]'); } + function el(tag, props, children) { + var node = doc.createElement(tag); + if (props) { + Object.keys(props).forEach(function (key) { + var value = props[key]; + if (value === null || value === undefined || value === false) return; + if (key === 'text') node.textContent = value; + else if (key === 'cls') node.className = value; + else if (key === 'style') node.setAttribute('style', value); + else node.setAttribute(key, value === true ? '' : value); + }); + } + (children || []).forEach(function (child) { + if (child === null || child === undefined) return; + node.appendChild(typeof child === 'string' ? doc.createTextNode(child) : child); }); - }); - rows.sort(function (a, b) { return compareKeys(a.key, b.key); }); - var shown = rows.slice(0, view.worstN); - var c = D.items_count; - q('worst-said').textContent = D.tier === 'counts' - ? 'This file holds counts only: it names no ' + D.item.one + '.' - : 'Showing ' + shown.length + ' of the ' + rows.length + ' values that moved or are missing in ' + compLabel(view.comp) + - ', among the ' + groupThousands(c.listed) + ' ' + D.item.many + ' in this file' + - (c.not_listed ? '. ' + groupThousands(c.not_listed) + ' more ' + D.item.many + ' worth a look are not in this file.' : '.') + - ' Ordered by class (sign change, zero reference, zero result, beyond 10x, differs, missing), then by how far the two sizes lie apart.' + sizeSaid(); - var table = clear(q('worst-table')); - var head = ['#', D.item.one.charAt(0).toUpperCase() + D.item.one.slice(1), 'Indicator', 'Class', 'Before', 'After', 'Change', 'Verdict']; - table.appendChild(el('thead', null, [el('tr', null, head.map(function (h) { return el('th', { scope: 'col', text: h }); }))])); - var body = el('tbody'); - shown.forEach(function (row, i) { - var pair = pairOf(row.item, row.ind, k); - var tr = el('tr', { cls: 'clickable', tabindex: '0', 'data-item': row.item.id }, [ - el('td', { cls: 'num', text: String(i + 1) }), - el('td', { text: row.item.name + (row.item.place ? ' (' + row.item.place + ')' : '') }), - el('td', { text: indicatorName(row.ind) }), - el('td', { text: row.item.classes[row.ind][k] }), - el('td', { cls: 'num', text: formatNumber(pair[0]), title: String(pair[0]) }), - el('td', { cls: 'num', text: formatNumber(pair[1]), title: String(pair[1]) }), - cell(row.item, row.ind, k), - el('td', { text: verdictOf(row.item, row.ind, k) || '—' }) - ]); - body.appendChild(tr); - }); - table.appendChild(body); - } + return node; + } + function clear(node) { while (node.firstChild) node.removeChild(node.firstChild); return node; } + function n(x) { return x === null || x === undefined ? '—' : groupThousands(x); } + function many(count) { return count === 1 ? D.item.one : D.item.many; } + function capital(text) { return text.charAt(0).toUpperCase() + text.slice(1); } + function article(word) { return (/^[aeiou]/i.test(word) ? 'an ' : 'a ') + word; } - function gridRows() { - var k = stepIndex(view.comp); - var find = view.find.toLowerCase(); - return D.items.filter(function (item) { - if (find && (item.name + ' ' + (item.place || '') + ' ' + item.id).toLowerCase().indexOf(find) < 0) return false; - if (view.group && item.group !== view.group) return false; - var ids = D.indicators.map(function (i) { return i.id; }); - if (view.cls && !ids.some(function (id) { return item.classes[id][k] === view.cls; })) return false; - if (view.verdict && !ids.some(function (id) { return verdictOf(item, id, k) === view.verdict; })) return false; - if (view.size && !ids.some(function (id) { return QUIET.indexOf(item.classes[id][k]) < 0 && sizeAtLeast(item.classes[id][k], item.bands[id][k], view.size); })) return false; - return true; - }); - } + function indicatorName(id) { + for (var i = 0; i < D.indicators.length; i++) { + if (D.indicators[i].id === id) return D.indicators[i].short || D.indicators[i].name; + } + return id; + } + function indicatorIds() { return D.indicators.map(function (i) { return i.id; }); } + function stepIndex(comp) { // the position of a comparison in an item's lists of classes + if (comp === 'total') return D.steps.length; + for (var i = 0; i < D.steps.length; i++) if (D.steps[i].id === comp) return i; + return D.steps.length; + } + function stateIndex(stateId) { + for (var i = 0; i < D.states.length; i++) if (D.states[i].id === stateId) return i; + return 0; + } + function compLabel(comp) { + if (comp === 'total') return 'The whole way: ' + D.states[0].label + ' → ' + D.states[D.states.length - 1].label; + var k = stepIndex(comp); + return 'Step ' + stepNo(k) + ': ' + D.steps[k].label; + } + // a step's number: from 0 where the chain starts from the published results (step 0 + // checks they are reproduced), from 1 otherwise + function stepNo(k) { return k + (D.states[0].kind === 'published' ? 0 : 1); } + // what the file calls an indicator: its own word, or "indicator" + function indWord(many) { + var word = D.indicator || { one: 'indicator', many: 'indicators' }; + return many ? word.many : word.one; + } + function pairOf(row, indicator, k) { + var values = row.values[indicator]; + return k === D.steps.length ? [values[0], values[values.length - 1]] : [values[k], values[k + 1]]; + } + function verdictOf(row, indicator, k) { + if (!row.verdicts || k >= D.steps.length) return null; + return row.verdicts[indicator][k]; + } + function bandAt(row, indicator, k) { + if (row.bands) return row.bands[indicator][k]; + var pair = pairOf(row, indicator, k); + return bandOf(pair[0], pair[1], row.classes[indicator][k], row.directions[indicator][k]); + } - function renderGrid() { - var k = stepIndex(view.comp); - var rows = gridRows(); - var shown = rows.slice(0, view.limit); - var c = D.items_count; - q('grid-said').textContent = D.tier === 'counts' - ? 'This file holds counts only: it names no ' + D.item.one + '.' - : 'Showing ' + shown.length + ' of ' + rows.length + ' ' + D.item.many + ' (' + groupThousands(c.listed) + ' in this file' + - (c.not_listed ? '; ' + groupThousands(c.not_listed) + ' more worth a look are not in it' : '') + '). ' + compLabel(view.comp) + '.' + sizeSaid(); - var table = clear(q('grid-table')); - var head = [el('th', { scope: 'col', text: D.item.one.charAt(0).toUpperCase() + D.item.one.slice(1) }), el('th', { scope: 'col', text: 'Unit' })]; - D.indicators.forEach(function (ind) { head.push(el('th', { scope: 'col', cls: 'num', text: indicatorName(ind.id), title: ind.name + (ind.unit ? ' (' + ind.unit + ')' : '') })); }); - table.appendChild(el('thead', null, [el('tr', null, head)])); - var body = el('tbody'); - shown.forEach(function (item) { - var row = [el('th', { scope: 'row', text: item.name + (item.place ? ' (' + item.place + ')' : '') }), el('td', { text: item.unit || '?' })]; - D.indicators.forEach(function (ind) { row.push(cell(item, ind.id, k)); }); - body.appendChild(el('tr', { cls: 'clickable', tabindex: '0', 'data-item': item.id }, row)); - }); - table.appendChild(body); - var more = q('grid-more'); - more.hidden = rows.length <= shown.length; - more.textContent = 'Show ' + Math.min(100, rows.length - shown.length) + ' more'; - } + // the rows the grid and the worst list draw from: every item once the matrix is loaded, + // the listed items before + function rows() { return M || LISTED; } + function rowById(id) { + var all = rows(); + for (var i = 0; i < all.length; i++) if (all[i].id === id) return all[i]; + return null; + } + function heldSaid() { + var c = D.items_count; + if (M) return 'all ' + groupThousands(M.length) + ' ' + many(M.length) + ' (the matrix)'; + return 'the ' + groupThousands(c.listed) + ' ' + many(c.listed) + ' in this file' + + (c.not_listed ? '; ' + groupThousands(c.not_listed) + ' more worth a look are not in it' : ''); + } - function sizeSaid() { - return view.size ? ' Only changes by a factor of at least ' + view.size + ' are shown, with every zero, sign change and missing value: a filter of yours, which changes no count.' : ''; - } + function valueCell(row, indicator, k, ratio) { + var pair = pairOf(row, indicator, k); + var cls = row.classes[indicator][k]; + var v = (ratio ? ratioView : cellView)(pair[0], pair[1], cls, row.directions[indicator][k], bandAt(row, indicator, k)); + var verdict = verdictOf(row, indicator, k); + var title = v.title + (verdict ? ' Verdict: ' + verdict + '.' : ''); + var classes = 'cell tone-' + v.tone + (v.noRatio ? ' no-ratio' : ''); + var td = el('td', { cls: classes, title: title, style: v.strength ? '--s:' + v.strength : null, 'data-class': cls }, + [v.text, v.mark ? el('span', { cls: 'mark', text: v.mark, 'aria-hidden': 'true' }) : null]); + if (verdict && LOOK.indexOf(verdict) >= 0) td.appendChild(el('span', { cls: 'mark verdict-look', text: LOOK_MARK[verdict], title: verdict })); + return td; + } - function fillSelect(select, options, chosen) { - clear(select); - options.forEach(function (o) { select.appendChild(el('option', { value: o[0], text: o[1] })); }); - select.value = chosen; - } + function legend(node, ratio) { + clear(node); + // short words beside each key, the whole sentence in its title + var keys = [ + ['tone-up', ratio ? '1.3' : 'up', 'up', 'went up (as signed numbers)'], + ['tone-down', ratio ? '0.77' : 'down', 'down', 'went down (as signed numbers): two results below zero that go further below zero went down'], + ['tone-up no-ratio', '0 →', 'no ratio', 'from zero, to zero or across zero: no ratio'], + ['tone-none', ratio ? '1.00' : '=', 'agrees', 'agrees within the tolerance' + (ratio ? ': no tint' : '')], + ['tone-noise', ratio ? '1.00~' : '~', 'noise', 'within the measured noise'], + ['tone-near', '≈ 0', 'near zero', 'near zero on both sides'], + ['tone-missing', 'missing', '', 'a side has no result'] + ]; + keys.forEach(function (k) { + node.appendChild(el('span', { title: k[3] }, [el('span', { cls: 'key ' + k[0], style: '--s:0.7', text: k[1] }), k[2]])); + }); + node.appendChild(el('span', { title: 'verdicts worth a look' }, ['■ not claimed ◐ off claim ○ claimed, not moved'])); + } + + // the file's own word for an item, in the page's own sentences + function sayWords() { + var spans = root.querySelectorAll('[data-sd-word]'); + var words = { one: D.item.one, many: D.item.many, indicator: indWord(false), indicators: indWord(true), Indicator: capital(indWord(false)) }; + for (var i = 0; i < spans.length; i++) { + var said = words[spans[i].getAttribute('data-sd-word')]; + if (said !== undefined) spans[i].textContent = said; + } + q('grid-region').setAttribute('aria-label', 'After divided by before, per ' + D.item.one + ' and ' + indWord(false)); + q('item-close').setAttribute('aria-label', 'Close the ' + D.item.one); + } + + function renderHeader() { + sayWords(); + if (standalone) doc.title = D.title; + q('title').textContent = D.title; + q('about').textContent = D.about || ''; + var states = clear(q('states')); + D.states.forEach(function (s) { + var identity = Object.keys(s.identity).map(function (k) { return k + ': ' + s.identity[k]; }).join(', '); + var join = s.join ? n(s.join.compared) + ' compared, ' + n(s.join.unmatched) + ' unmatched, ' + n(s.join.ambiguous) + ' ambiguous' : ''; + states.appendChild(el('li', { title: (s.about || '') + (identity ? ' (' + identity + ')' : '') + (s.join && s.join.note ? ' ' + s.join.note : '') }, + [s.label + (s.kind === 'published' ? ' (published)' : ''), join ? el('span', { cls: 'sd-quiet', text: ' · ' + join }) : null])); + }); + tierSaid(); + q('audience').textContent = D.audience === 'local' + ? 'Local file: its writer has not said that it may be published.' : ''; + q('audience').hidden = D.audience !== 'local'; + // only a chain that starts from the published results has a step 0 that reproduces them + q('steps-zero').hidden = D.states[0].kind !== 'published'; + q('made-by').textContent = 'Written by ' + D.made_by + '. ' + FORMAT + '.'; + renderChips(); + renderStepSaid(); + } + + // the comparison is chosen from a row of chips: the whole way, then each step with its + // number, the values that moved in it and a mark for each verdict worth a look + function renderChips() { + var row = clear(q('comparison')); + var chip = function (value, parts, title) { + row.appendChild(el('button', { type: 'button', cls: 'sd-chip', 'data-comp': value, title: title, + 'aria-pressed': view.comp === value ? 'true' : 'false' }, parts)); + }; + var count = function (comp) { + var m = sumOver(comp, moved); + return el('span', { cls: 'sd-chip-count', text: n(m) + ' moved' }); + }; + chip('total', [el('span', { cls: 'sd-chip-label', text: 'The whole way' }), count('total')], compLabel('total')); + D.steps.forEach(function (s, k) { + var parts = [el('span', { cls: 'sd-chip-no', text: String(stepNo(k)) }), el('span', { cls: 'sd-chip-label', text: s.label }), count(s.id)]; + var said = [compLabel(s.id), n(sumOver(s.id, moved)) + ' values moved']; + if (!s.explained) { + parts.push(el('span', { cls: 'sd-chip-flag', text: '!' })); + said.push('nothing explains it'); + } + if (s.claim) LOOK.forEach(function (name) { + var found = sumOver(s.id, function (b) { return b.verdicts[name]; }); + if (!found) return; + parts.push(el('span', { cls: 'sd-chip-mark', text: LOOK_MARK[name] })); + said.push(n(found) + ' ' + name); + }); + chip(s.id, parts, said.join('. ') + '.'); + }); + } + + // under the chips: what the chosen comparison is, the claim of its step and who made it, + // and its rule, so that a reviewer reads what a step said beside what it did + function renderStepSaid() { + var node = q('step-said'); + if (!node) return; + clear(node); + if (view.comp === 'total') { + node.appendChild(el('p', null, [el('strong', { text: 'The whole way: ' }), D.states[0].label + ' → ' + D.states[D.states.length - 1].label + '. ', + el('span', { cls: 'sd-quiet', text: 'Each cell holds the last result divided by the first. Choose a step to see what one change did; "Steps and the whole way" below splits the whole difference between them.' })])); + return; + } + var k = stepIndex(view.comp); + var s = D.steps[k]; + var line = [el('strong', { text: 'Step ' + stepNo(k) + ': ' + s.label + '. ' }), el('span', { cls: 'sd-quiet', text: D.states[k].label + ' → ' + D.states[k + 1].label + '. ' })]; + if (s.about) line.push(el('span', { cls: 'sd-quiet', text: s.about })); + node.appendChild(el('p', null, line)); + if (k === 0 && D.states[0].kind === 'published') { + node.appendChild(el('p', { cls: 'sd-quiet', text: 'What moves here was not reproduced within the tolerance: the residual the chain starts from, not a regression.' })); + } + if (!s.explained) node.appendChild(el('p', { cls: 'sd-error', text: 'Nothing explains this step.' })); + var claim = [el('span', { cls: 'sd-claim-label', text: 'Claim' })]; + if (s.claim) { + claim.push(s.claim.text, ' ', badge(s.claim.by)); + // every verdict on a move, "as claimed" first, each with its count; the ones worth a + // look carry their mark, as on the chips. No colour: a verdict is not an approval. + var found = ['as claimed'].concat(LOOK).map(function (name) { return [name, sumOver(s.id, function (b) { return b.verdicts[name]; })]; }) + .filter(function (p) { return p[1]; }); + claim.push(el('span', { cls: 'sd-verdicts', text: found.length + ? ' ' + found.map(function (p) { return n(p[1]) + ' ' + (p[1] === 1 ? 'value' : 'values') + ' ' + (p[0] === 'as claimed' ? 'moved as claimed' : p[0]) + (LOOK_MARK[p[0]] ? ' ' + LOOK_MARK[p[0]] : ''); }).join(', ') + '.' + : ' Nothing moved, as claimed.' })); + if (s.claim.scope.some(function (e) { return e.items === null; })) { + claim.push(el('span', { cls: 'sd-quiet', text: ' Its list of ' + D.item.many + ' is not in this file' + (s.claim.reach !== null ? ' (' + n(s.claim.reach) + ')' : '') + ': its verdicts were worked out by its writer.' })); + } + } else { + claim.push(el('span', { cls: 'sd-quiet', text: 'none: what moves here is counted, not judged.' })); + } + node.appendChild(el('p', { cls: 'sd-claim' }, claim)); + node.appendChild(el('p', { cls: 'sd-quiet', text: 'Tolerance ' + s.tolerance.value + ' (' + s.tolerance.basis + '). Noise ' + noiseText(s.noise, indicatorIds(), indWord(true)) + '.' })); + } - function renderFilters() { - var k = stepIndex(view.comp); - var classes = {}, verdicts = {}, groups = {}; - D.items.forEach(function (item) { + function markChips() { + var chips = q('comparison').querySelectorAll('button[data-comp]'); + for (var i = 0; i < chips.length; i++) chips[i].setAttribute('aria-pressed', chips[i].getAttribute('data-comp') === view.comp ? 'true' : 'false'); + } + + // what the page holds of the items: the listed ones, or every one once the matrix is here + function tierSaid() { + var c = D.items_count; + var head = groupThousands(c.all) + ' ' + D.item.many + ', ' + D.indicators.length + ' ' + indWord(D.indicators.length !== 1) + '. '; + var said; + if (D.tier === 'counts') said = 'This file holds counts only: no single ' + D.item.one + ' is shown.'; + else if (M) said = 'All ' + groupThousands(M.length) + ' are loaded from the matrix; ' + groupThousands(c.listed) + ' of the ' + + groupThousands(c.qualifying) + ' worth a look are listed in this file.'; + else said = groupThousands(c.listed) + ' of the ' + groupThousands(c.qualifying) + ' ' + D.item.many + ' worth a look are in this file' + + (c.not_listed ? '; ' + groupThousands(c.not_listed) + ' are not.' : '.'); + q('tier').textContent = head + said; + } + + function sumOver(comp, fn) { + var blocks = comp === 'total' ? D.counts.total : D.counts.steps[comp]; + return Object.keys(blocks).reduce(function (acc, key) { return acc + fn(blocks[key]); }, 0); + } + function moved(block) { return MOVES.reduce(function (a, k) { return a + block.classes[k]; }, 0); } + + function renderSteps() { + var table = clear(q('steps-table')); + var head = ['#', 'Step', 'Kind', 'Explained', 'Claim', 'Moved', 'Up', 'Down', 'As claimed', 'Off claim', 'Not claimed', 'Claimed, not moved', 'Within noise', 'Missing before', 'Missing after', 'Tolerance', 'Noise']; + table.appendChild(el('thead', null, [el('tr', null, head.map(function (h) { return el('th', { scope: 'col', text: h }); }))])); + var body = el('tbody'); + D.steps.forEach(function (s, k) { + var verdict = function (name) { return s.claim ? n(sumOver(s.id, function (b) { return b.verdicts[name]; })) : '—'; }; + var noise = noiseText(s.noise, indicatorIds(), indWord(true)); + // the step from the published results: what moved there is the residual the chain + // starts from, not a regression, whatever its claim says + var unrepro = sumOver(s.id, moved); + var residual = k === 0 && D.states[0].kind === 'published' + ? (unrepro === 1 ? '1 value' : n(unrepro) + ' values') + ' not reproduced within the tolerance: the residual the chain starts from, not a regression.' : null; + body.appendChild(el('tr', null, [ + el('td', { cls: 'num', text: String(stepNo(k)) }), + el('td', null, [safeLink(s.link) ? el('a', { href: safeLink(s.link), text: s.label }) : s.label, s.about ? el('div', { cls: 'sd-quiet', text: s.about }) : null, + residual ? el('div', { cls: 'sd-quiet', text: residual }) : null]), + el('td', { text: s.kind }), + el('td', { text: s.explained ? 'yes' : 'no: nothing explains it', cls: s.explained ? null : 'sd-error' }), + el('td', null, [s.claim ? s.claim.text : 'no claim', s.claim && s.claim.by ? el('div', null, [badge(s.claim.by)]) : null, + s.claim && s.claim.scope.some(function (e) { return e.items === null; }) + ? el('div', { cls: 'sd-quiet', text: 'Its list of ' + D.item.many + ' is not in this file' + (s.claim.reach !== null ? ' (' + n(s.claim.reach) + ')' : '') + ': the verdicts were worked out by its writer and cannot be checked again here.' }) : null]), + el('td', { cls: 'num', text: n(sumOver(s.id, moved)) }), + el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.directions.up; })) }), + el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.directions.down; })) }), + el('td', { cls: 'num', text: verdict('as claimed') }), + el('td', { cls: 'num', text: verdict('off claim') }), + el('td', { cls: 'num', text: verdict('not claimed') }), + el('td', { cls: 'num', text: verdict('claimed, not moved') }), + el('td', { cls: 'num', text: verdict('within noise') }), + el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.missing.before + b.missing.both; })) }), + el('td', { cls: 'num', text: n(sumOver(s.id, function (b) { return b.missing.after + b.missing.both; })) }), + el('td', { cls: 'num', text: String(s.tolerance.value), title: s.tolerance.basis + (s.tolerance.note ? ': ' + s.tolerance.note : '') }), + el('td', { text: noise }) + ])); + }); + table.appendChild(body); + + var total = clear(q('total-table')); + q('total-heading').textContent = 'The whole way: ' + D.states[0].label + ' → ' + D.states[D.states.length - 1].label; + var classes = Object.keys(D.counts.total[D.indicators[0].id].classes); + var cols = [capital(indWord(false))].concat(classes, ['Up', 'Down', 'Largest step', 'Spread over steps', 'Not attributable', 'Moved by what nothing explains']); + total.appendChild(el('thead', null, [el('tr', null, cols.map(function (h) { return el('th', { scope: 'col', text: h, title: SAID[h] || null }); }))])); + var tbody = el('tbody'); D.indicators.forEach(function (ind) { - classes[item.classes[ind.id][k]] = 1; - var v = verdictOf(item, ind.id, k); - if (v) verdicts[v] = 1; + var block = D.counts.total[ind.id]; + var att = D.attribution[ind.id]; + var ranked = Object.keys(att.dominant).filter(function (k) { return att.dominant[k]; }) + .sort(function (a, b) { return att.dominant[b] - att.dominant[a]; }) + .map(function (k) { return D.steps[stepIndex(k)].label + ' (' + att.dominant[k] + ')'; }); + var row = [el('th', { scope: 'row', text: ind.name + (ind.unit ? ' (' + ind.unit + ')' : '') })]; + classes.forEach(function (c) { + var title = c === 'missing' ? 'missing before: ' + block.missing.before + ', after: ' + block.missing.after + ', on both sides: ' + block.missing.both : null; + row.push(el('td', { cls: 'num' + (block.classes[c] ? '' : ' zero'), text: n(block.classes[c]), title: title })); + }); + row.push(el('td', { cls: 'num', text: n(block.directions.up) }), el('td', { cls: 'num', text: n(block.directions.down) })); + row.push(el('td', { cls: 'sd-wide', text: ranked.join(', ') || 'none' })); + row.push(el('td', { cls: 'num', text: n(att.spread), title: 'its total moved, and no single step moved it: small steps that add up' })); + row.push(el('td', { cls: 'num', text: n(att.not_attributable), title: 'its total moved, and it has no result in a state between: its difference cannot be split' })); + row.push(el('td', { cls: 'num', text: n(att.unexplained_moved), title: 'moved in a step that no cause explains' })); + tbody.appendChild(el('tr', null, row)); }); - if (item.group) groups[item.group] = 1; - }); - fillSelect(q('grid-class'), [['', 'Any']].concat(Object.keys(classes).sort().map(function (c) { return [c, c]; })), view.cls); - fillSelect(q('grid-verdict'), [['', 'Any']].concat(Object.keys(verdicts).sort().map(function (c) { return [c, c]; })), view.verdict); - fillSelect(q('grid-group'), [['', 'Any']].concat(Object.keys(groups).sort().map(function (c) { return [c, c]; })), view.group); - q('grid-verdict').disabled = !Object.keys(verdicts).length; - fillSelect(q('worst-indicator'), [['', 'All']].concat(D.indicators.map(function (i) { return [i.id, indicatorName(i.id)]; })), view.worstIndicator); - } + total.appendChild(tbody); + } - function badge(by) { - if (!by) return el('span', { cls: 'badge', text: 'author not said' }); - if (by.kind === 'person') return el('span', { cls: 'badge person', text: 'Person: ' + by.name }); - if (by.kind === 'code') return el('span', { cls: 'badge', text: 'Code: ' + by.name }); - if (by.kind === 'model') return el('span', { cls: 'badge model', text: 'Model: ' + by.model + ', run by ' + by.run_by + '. A claim, not checked by a person' }); - return el('span', { cls: 'badge', text: String(by.kind) }); - } + // the bars of a distribution, left to right: across zero, down from far to near, the + // band around 1 (agrees, within noise), up from near to far, then the values with no + // ratio. [kind, key, tone] + function distBins(block) { + var bands = Object.keys(block.bands); + return [['class', 'sign change', 'aside']] + .concat(bands.filter(function (b) { return b.indexOf('down') === 0; }).map(function (b) { return ['band', b, 'down']; })) + .concat([['class', 'agrees', 'mid'], ['class', 'within noise', 'mid']]) + .concat(bands.filter(function (b) { return b.indexOf('up') === 0; }).map(function (b) { return ['band', b, 'up']; })) + .concat(['zero reference', 'zero result', 'near zero', 'missing'].map(function (c) { return ['class', c, 'aside']; })); + } + // the words under a histogram, each under its run of bars + function axis(bins) { + var runs = []; + bins.forEach(function (b, i) { + var last = runs[runs.length - 1]; + if (last && last.tone === b[2] && !(b[2] === 'aside' && i > 0 && bins[i - 1][2] !== 'aside')) last.n += 1; + else runs.push({ tone: b[2], n: 1, first: !runs.length }); + }); + var words = { down: '↓ ÷10', mid: '1', up: '×10 ↑' }; + return el('div', { cls: 'sd-axis', 'aria-hidden': 'true' }, runs.map(function (run) { + var word = run.tone === 'aside' ? (run.first ? '±' : '0 ∅') : words[run.tone]; + return el('span', { cls: 'sd-axis-' + run.tone, style: 'flex-grow:' + run.n, text: word }); + })); + } + function distLegend() { + var node = clear(q('dist-legend')); + [['down', 'went down'], ['mid', 'agrees or within noise (the band around 1)'], ['up', 'went up'], ['aside', 'across zero, from or to zero, near zero, missing: no ratio']].forEach(function (k) { + node.appendChild(el('span', null, [el('span', { cls: 'sd-bin-key ' + k[0] }), k[1]])); + }); + } + function binWords(bin) { + if (bin[0] === 'band') return bin[1]; + return bin[1] + (SAID[bin[1]] ? ' (' + SAID[bin[1]] + ')' : ''); + } - function explanationNode(one) { - var about = []; - if (one.about.step) about.push(one.about.step === 'total' ? 'the whole way' : 'step ' + D.steps[stepIndex(one.about.step)].label); - if (one.about.indicator) about.push(indicatorName(one.about.indicator)); - if (one.about.item) { - var item = D.items.filter(function (i) { return i.id === one.about.item; })[0]; - about.push(item ? item.name : one.about.item); - } - return el('li', null, [ - badge(one.by), el('span', { cls: 'quiet', text: 'About ' + about.join(', ') + '. ' }), - one.finding === 'none found' ? el('strong', { text: 'Looked, found no reason: ' }) : null, one.text, - one.not_checked ? el('div', { cls: 'quiet', text: 'Not checked: ' + one.not_checked }) : null, - one.source ? el('div', { cls: 'quiet' }, [safeLink(one.source.link) ? el('a', { href: safeLink(one.source.link), text: one.source.link }) : null, one.source.doc ? ' ' + one.source.doc : null]) : null - ]); - } + // after ÷ before at its 10th, 50th and 90th percentile, over the values of one indicator + // that have a ratio (the same sign on both sides, neither zero nor near it). Only from + // every item: the listed ones are the furthest apart, and would make a median of them + // say more than the whole holds. + function quantiles(indicator, k) { + var held = M || (D.items_count.listed === D.items_count.all && D.tier !== 'counts' ? LISTED : null); + if (!held) return null; + var found = []; + held.forEach(function (row) { + var cls = row.classes[indicator][k]; + if (RATIO_CLASSES.indexOf(cls) < 0) return; + var pair = pairOf(row, indicator, k); + if (pair[0] === null || pair[1] === null || pair[0] === 0 || pair[1] === 0 || (pair[0] > 0) !== (pair[1] > 0)) return; + var r = pair[1] / pair[0]; + if (isFinite(r)) found.push(r); + }); + if (!found.length) return { n: 0 }; + found.sort(function (a, b) { return a - b; }); + var at = function (p) { // linear between the two nearest ranks + var x = p * (found.length - 1), lo = Math.floor(x), hi = Math.ceil(x); + return found[lo] + (found[hi] - found[lo]) * (x - lo); + }; + return { n: found.length, p10: at(0.1), median: at(0.5), p90: at(0.9) }; + } - function renderExplanations() { - var list = clear(q('explanation-list')); - if (!D.explanations.length) list.appendChild(el('li', { cls: 'quiet', text: 'The file holds no explanation.' })); - D.explanations.forEach(function (one) { list.appendChild(explanationNode(one)); }); - } + // the card of the indicator the matrix is sorted by is marked, wherever the sort was chosen + function markChosenCard() { + var cards = q('dist-cards').childNodes; + for (var i = 0; i < cards.length; i++) { + var card = cards[i]; + var chosen = card.getAttribute('data-indicator') === view.sort; + card.className = card.className.replace(/ sd-chosen/g, '') + (chosen ? ' sd-chosen' : ''); + var button = card.childNodes[0].childNodes[0]; + button.setAttribute('aria-pressed', chosen ? 'true' : 'false'); + } + } - function renderRule() { - var body = clear(q('rule-body')); - body.appendChild(el('p', null, ['Every value is put into one class by one rule, in this order: missing, near zero, agrees, within noise (both only where the two share a sign), zero reference, zero result, sign change, beyond 10x, differs. ' + - 'Direction is up where the result after is larger as a signed number, down otherwise; colour follows the direction only. ' + - 'Beyond 10x: one size more than ' + D.rule.beyond + ' times the other. The whole way is counted with a tolerance of ' + D.rule.total_tolerance + ', the largest of the steps.'])); - var stepsTable = el('table', null, [el('thead', null, [el('tr', null, ['Step', 'Tolerance', 'Basis', 'Note', 'Noise'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); - var tb = el('tbody'); - D.steps.forEach(function (s) { - var noise = noiseText(s.noise, D.indicators.map(function (i) { return i.id; })) + (s.noise.measured ? ': ' + Object.keys(s.noise.by).map(function (k) { return indicatorName(k) + ' ' + formatNumber(s.noise.by[k]); }).join(', ') : ''); - tb.appendChild(el('tr', null, [el('td', { text: s.label }), el('td', { cls: 'num', text: String(s.tolerance.value) }), el('td', { text: s.tolerance.basis }), el('td', { text: s.tolerance.note || '' }), el('td', { text: noise })])); - }); - stepsTable.appendChild(tb); - body.appendChild(el('div', { cls: 'table-wrap' }, [stepsTable])); - body.appendChild(el('h3', { text: 'Floors' })); - body.appendChild(el('p', { cls: 'quiet', text: 'One floor per indicator and reference unit: ' + D.rule.floor_factor + ' times the median size of the results of ' + D.states[stepIndex2(D.rule.floors_from)].label + ' in that unit, unless declared. Units are never pooled.' })); - var floors = el('table', null, [el('thead', null, [el('tr', null, ['Indicator', 'Unit', 'Floor', 'Basis', 'From results'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); - var fb = el('tbody'); - D.rule.floors.forEach(function (f) { - fb.appendChild(el('tr', null, [el('td', { text: indicatorName(f.indicator) }), el('td', { text: f.unit || 'unknown' }), el('td', { cls: 'num', text: formatNumber(f.value), title: String(f.value) }), el('td', { text: f.basis }), el('td', { cls: 'num', text: n(f.n) })])); - }); - floors.appendChild(fb); - body.appendChild(el('div', { cls: 'table-wrap' }, [floors])); - var notes = clear(q('notes')); - D.notes.forEach(function (text) { notes.appendChild(el('li', { text: text })); }); - if (!D.notes.length) notes.appendChild(el('li', { cls: 'quiet', text: 'None.' })); - } - function stepIndex2(stateId) { - for (var i = 0; i < D.states.length; i++) if (D.states[i].id === stateId) return i; - return 0; - } + // one card per indicator, in the order of the matrix's columns: a histogram of the classes + // and bands of the comparison chosen above, each card on the scale of its own tallest bar + function renderDistributions() { + var comp = view.comp; + var k = stepIndex(comp); + var blocks = comp === 'total' ? D.counts.total : D.counts.steps[comp]; + var held = M || (D.items_count.listed === D.items_count.all && D.tier !== 'counts'); + q('dist-said').textContent = 'How many ' + D.item.many + ' fall in each band of after ÷ before, in the comparison chosen above, one card per ' + indWord(false) + + ' in the order of the matrix: from across zero, through down by more than ten times, the band around 1 (dark), to up by more than ten times; then the values with no ratio. ' + + (view.distScale === 'one' ? 'Every card is drawn on one scale, the share of all values, so that a bar of one height means as many in each; ' : + 'Each card is drawn on the scale of its own tallest bar, so that a few values that moved are seen beside many that agree; ') + 'a bar\'s title holds its count. ' + + (held ? 'The median and percentiles are of after ÷ before over every ' + D.item.one + ' with a ratio, in as many digits as keep apart the ones that differ. ' + : 'The median and percentiles need every ' + D.item.one + ', and this page holds the ' + groupThousands(D.items_count.listed) + ' listed, the furthest apart: it gives none. ') + + 'Choose a card to sort the matrix by that ' + indWord(false) + '.'; + var box = clear(q('dist-cards')); + var countsOf = function (block) { + return distBins(block).map(function (b) { return (b[0] === 'band' ? block.bands[b[1]] : block.classes[b[1]]) || 0; }); + }; + // on one scale: the largest share of any bar of any card is the full height + var topShare = 0; + D.indicators.forEach(function (ind) { + var block = blocks[ind.id]; + if (block.pairs) topShare = Math.max(topShare, Math.max.apply(null, countsOf(block)) / block.pairs); + }); + columns(comp).forEach(function (c) { + var ind = c.ind, block = blocks[ind.id]; + var bins = distBins(block); + var counts = countsOf(block); + var top = view.distScale === 'one' ? Math.max(1e-12, topShare) * block.pairs : Math.max.apply(null, counts.concat([1])); + var said = bins.map(function (b, i) { return b[1] + ': ' + groupThousands(counts[i]); }).join('; '); + var bars = bins.map(function (b, i) { + return el('span', { cls: 'sd-bin ' + b[2] + (i && bins[i - 1][2] !== b[2] && (b[2] === 'aside' || bins[i - 1][2] === 'aside') ? ' sd-gap' : ''), + style: 'height:' + (counts[i] ? Math.max(2, 100 * counts[i] / top).toFixed(1) : 0) + '%', + title: binWords(b) + ': ' + groupThousands(counts[i]) + ' of ' + groupThousands(block.pairs) }); + }); + var qs = quantiles(ind.id, k); + var meta = c.active ? capital(activeSaid(c)) + ', of ' + groupThousands(block.pairs) : 'Nothing moved'; + var said3 = qs && qs.n ? quantileTexts(qs) : null; + var left = qs ? block.pairs - qs.n : 0; + var stats = qs === null ? null : (said3 + ? 'Median of ' + groupThousands(qs.n) + ' ' + (qs.n === 1 ? 'ratio' : 'ratios') + ' ' + said3[1] + ', 10th percentile ' + said3[0] + ', 90th ' + said3[2] + + (left ? '; ' + groupThousands(left) + ' without a ratio' : '') + : 'No value with a ratio'); + var button = el('button', { type: 'button', cls: 'sd-dist-pick', 'aria-pressed': view.sort === ind.id ? 'true' : 'false', + title: 'Sort the matrix by ' + ind.name }, [ind.name]); + button.addEventListener('click', function () { + view.sort = view.sort === ind.id ? 'worst' : ind.id; + view.limit = PAGE; + renderGrid(); + markChosenCard(); + var region = q('grid-region'); + if (region && region.scrollIntoView) region.scrollIntoView({ block: 'start', behavior: 'smooth' }); + }); + box.appendChild(el('div', { cls: 'sd-dist' + (c.active ? '' : ' sd-still') + (view.sort === ind.id ? ' sd-chosen' : ''), 'data-indicator': ind.id }, [ + el('h4', null, [button]), + el('p', { cls: 'sd-top', 'aria-hidden': 'true', text: view.distScale === 'one' + ? 'full height: ' + groupThousands(Math.round(top)) + ' of ' + groupThousands(block.pairs) + : 'tallest bar: ' + groupThousands(Math.max.apply(null, counts)) }), + el('div', { cls: 'sd-hist', role: 'img', 'aria-label': said }, bars), + axis(bins), + el('p', { cls: 'sd-dist-meta' }, [el('strong', { text: meta }), stats ? el('br') : null, stats]) + ])); + }); + } + + function sizeSaid() { + return view.size ? ' Only changes by a factor of at least ' + view.size + ' are shown, with every zero, sign change and missing value: a filter of yours, which changes no count.' : ''; + } - function renderItem(id) { - var item = D.items.filter(function (i) { return i.id === id; })[0]; - var section = q('item'); - if (!item) { section.hidden = true; return; } - section.hidden = false; - q('item-title').textContent = item.name; - q('item-close').onclick = function () { section.hidden = true; history.replaceState(null, '', location.pathname + location.search + '#grid'); }; - q('item-meta').textContent = [item.id, item.place, item.group, item.unit ? 'per ' + item.unit : 'unit unknown'].filter(Boolean).join(' · '); - var body = clear(q('item-body')); - D.indicators.forEach(function (ind) { - var values = item.values[ind.id]; + function renderWorst() { + var k = stepIndex(view.comp); + var found = []; + rows().forEach(function (row) { + D.indicators.forEach(function (ind) { + if (view.worstIndicator && ind.id !== view.worstIndicator) return; + var cls = row.classes[ind.id][k]; + if (QUIET.indexOf(cls) >= 0) return; + if (!sizeAtLeast(cls, bandAt(row, ind.id, k), view.size)) return; + var pair = pairOf(row, ind.id, k); + found.push({ row: row, ind: ind.id, key: severityKey(pair[0], pair[1], cls).concat([row.id, ind.id]) }); + }); + }); + found.sort(function (a, b) { return compareKeys(a.key, b.key); }); + var shown = found.slice(0, view.worstN); + q('worst-said').textContent = D.tier === 'counts' + ? 'This file holds counts only: it names no ' + D.item.one + '.' + : 'Showing ' + shown.length + ' of the ' + groupThousands(found.length) + ' values that moved or are missing in ' + compLabel(view.comp) + + ', among ' + heldSaid() + '. Ordered by class (sign change, zero reference, zero result, beyond 10x, differs, missing), then by how far the two sizes lie apart.' + sizeSaid(); + var table = clear(q('worst-table')); + var head = ['#', capital(D.item.one), capital(indWord(false)), 'Class', 'Before', 'After', 'Change', 'Verdict']; + table.appendChild(el('thead', null, [el('tr', null, head.map(function (h) { return el('th', { scope: 'col', text: h }); }))])); + var body = el('tbody'); + shown.forEach(function (one, i) { + var pair = pairOf(one.row, one.ind, k); + body.appendChild(el('tr', { cls: 'sd-row', tabindex: '0', 'data-item': one.row.id }, [ + el('td', { cls: 'num', text: String(i + 1) }), + el('td', { text: one.row.name + (one.row.place ? ' (' + one.row.place + ')' : '') }), + el('td', { text: indicatorName(one.ind) }), + el('td', { text: one.row.classes[one.ind][k] }), + el('td', { cls: 'num', text: formatNumber(pair[0]), title: String(pair[0]) }), + el('td', { cls: 'num', text: formatNumber(pair[1]), title: String(pair[1]) }), + valueCell(one.row, one.ind, k, false), + el('td', { text: verdictOf(one.row, one.ind, k) || '—' }) + ])); + }); + table.appendChild(body); + } + + function gridRows() { + var k = stepIndex(view.comp); + var find = view.find.toLowerCase(); + var ids = indicatorIds(); + var found = rows().filter(function (row) { + if (find && (row.name + ' ' + (row.place || '') + ' ' + row.id).toLowerCase().indexOf(find) < 0) return false; + if (view.group && row.group !== view.group) return false; + if (view.cls && !ids.some(function (id) { return row.classes[id][k] === view.cls; })) return false; + if (view.verdict && !ids.some(function (id) { return verdictOf(row, id, k) === view.verdict; })) return false; + if (view.size && !ids.some(function (id) { return QUIET.indexOf(row.classes[id][k]) < 0 && sizeAtLeast(row.classes[id][k], bandAt(row, id, k), view.size); })) return false; + return true; + }); + var keyed = found.map(function (row, at) { + if (view.sort === 'name') return { row: row, key: [row.name.toLowerCase(), row.place || '', at] }; + if (view.sort === 'worst') return { row: row, key: worstKey(row, k, ids).concat([at]) }; + var pair = pairOf(row, view.sort, k); + return { row: row, key: severityKey(pair[0], pair[1], row.classes[view.sort][k]).concat([at]) }; + }); + keyed.sort(function (a, b) { return compareKeys(a.key, b.key); }); + return keyed.map(function (one) { return one.row; }); + } + + // where a row stands when the grid opens: the largest factor between its two results over + // every indicator, among the values that moved and have a ratio, the furthest from 1 + // first; a row whose moves have no ratio (from or to zero, a sign change) follows, by its + // worst value as severityKey orders values; a row that did not move comes last. Kept on + // the row per comparison. + function worstKey(row, k, ids) { + if (row.worst && row.worst.k === k) return row.worst.key; + var furthest = 0, worst = null; + ids.forEach(function (id) { + var pair = pairOf(row, id, k), cls = row.classes[id][k]; + if (cls === 'differs' || cls === 'beyond 10x') furthest = Math.max(furthest, distance(pair[0], pair[1])); + var one = severityKey(pair[0], pair[1], cls); + if (worst === null || compareKeys(one, worst) < 0) worst = one; + }); + var key = [-furthest].concat(worst); + row.worst = { k: k, key: key }; + return key; + } + + // a heading sorts by itself; a second click goes back to the furthest apart first + function sortButton(label, key, title) { + var button = el('button', { type: 'button', cls: 'sd-sort', text: label, title: title }); + button.addEventListener('click', function () { + view.sort = view.sort === key ? 'worst' : key; + view.limit = PAGE; + renderGrid(); + markChosenCard(); + }); + return button; + } + + // the columns of the matrix: the indicators in which the comparison moved most first, so + // that what a step did is in view without scrolling; the file's order among equals, and + // an indicator in which nothing moved last, quietened + function columns(comp) { + var blocks = comp === 'total' ? D.counts.total : D.counts.steps[comp]; + // a missing value is a finding, not stillness: it counts with what moved + return D.indicators.map(function (ind, at) { + var block = blocks[ind.id]; + return { ind: ind, moved: moved(block), missing: block.classes.missing || 0, at: at }; + }).map(function (c) { c.active = c.moved + c.missing; return c; }) + .sort(function (a, b) { return b.active - a.active || a.at - b.at; }); + } + + function activeSaid(c) { + if (!c.active) return 'nothing moved and nothing is missing'; + return [c.moved ? groupThousands(c.moved) + ' moved' : null, c.missing ? groupThousands(c.missing) + ' missing' : null].filter(Boolean).join(', '); + } + + function renderGrid() { + var k = stepIndex(view.comp); + var cols = columns(view.comp); + var found = gridRows(); + var shown = found.slice(0, view.limit); + q('grid-said').textContent = D.tier === 'counts' + ? 'This file holds counts only: it names no ' + D.item.one + '.' + : 'Showing ' + groupThousands(shown.length) + ' of ' + groupThousands(found.length) + ' ' + many(found.length) + + (M ? '' : ', among ' + heldSaid()) + '.' + sizeSaid(); + q('grid-region').setAttribute('aria-label', 'After divided by before, per ' + D.item.one + ' and ' + indWord(false) + ': ' + compLabel(view.comp) + + (view.sort === 'worst' ? ', the furthest apart first' : '')); + var table = clear(q('grid-table')); + var sorted = function (key) { return view.sort === key ? (key === 'name' ? 'ascending' : 'descending') : null; }; + var head = [ + el('th', { scope: 'col', cls: 'sd-name', 'aria-sort': sorted('name') }, [sortButton(capital(D.item.one), 'name', 'Sort by name')]), + el('th', { scope: 'col', cls: 'sd-group', text: 'Group' }) + ]; + cols.forEach(function (c) { + var ind = c.ind; + head.push(el('th', { scope: 'col', cls: 'num' + (c.active ? '' : ' sd-still'), 'aria-sort': sorted(ind.id), + title: ind.name + (ind.unit ? ' (' + ind.unit + ')' : '') + ': ' + activeSaid(c) + ' here' }, + [sortButton(indicatorName(ind.id), ind.id, 'Sort by how far the two lie apart, the furthest first')])); + }); + table.appendChild(el('thead', null, [el('tr', null, head)])); + var body = el('tbody'); + shown.forEach(function (row) { + var name = row.name + (row.place ? ' (' + row.place + ')' : ''); + var cells = [ + el('th', { scope: 'row', title: name + ', per ' + (row.unit || 'unknown unit') }, [M && row.item ? el('span', { cls: 'sd-listed', title: 'listed in this file' }) : null, name]), + el('td', { cls: 'sd-group', text: row.group || '' }) + ]; + cols.forEach(function (c) { + var td = valueCell(row, c.ind.id, k, true); + if (!c.active) td.className += ' sd-still'; + cells.push(td); + }); + body.appendChild(el('tr', { cls: 'sd-row', tabindex: '0', 'data-item': row.id, 'aria-current': view.open === row.id ? 'true' : null }, cells)); + }); + table.appendChild(body); + var more = q('grid-more'); + more.hidden = found.length <= shown.length; + more.textContent = 'Show ' + groupThousands(Math.min(PAGE, found.length - shown.length)) + ' more'; + } + + function fillSelect(select, options, chosen) { + clear(select); + options.forEach(function (o) { select.appendChild(el('option', { value: o[0], text: o[1] })); }); + select.value = chosen; + } + + function renderFilters() { + var k = stepIndex(view.comp); + var classes = {}, verdicts = {}, groups = {}; + var ids = indicatorIds(); + rows().forEach(function (row) { + ids.forEach(function (id) { + classes[row.classes[id][k]] = 1; + var v = verdictOf(row, id, k); + if (v) verdicts[v] = 1; + }); + if (row.group) groups[row.group] = 1; + }); + var any = [['', 'Any']]; + fillSelect(q('grid-class'), any.concat(Object.keys(classes).sort().map(function (c) { return [c, c]; })), view.cls); + fillSelect(q('grid-verdict'), any.concat(Object.keys(verdicts).sort().map(function (c) { return [c, c]; })), view.verdict); + fillSelect(q('grid-group'), any.concat(Object.keys(groups).sort().map(function (c) { return [c, c]; })), view.group); + q('grid-verdict').disabled = !Object.keys(verdicts).length; + fillSelect(q('worst-indicator'), [['', 'All']].concat(D.indicators.map(function (i) { return [i.id, indicatorName(i.id)]; })), view.worstIndicator); + } + + function badge(by) { + if (!by) return el('span', { cls: 'badge', text: 'author not said' }); + if (by.kind === 'person') return el('span', { cls: 'badge person', text: 'Person: ' + by.name }); + if (by.kind === 'code') return el('span', { cls: 'badge', text: 'Code: ' + by.name }); + if (by.kind === 'model') return el('span', { cls: 'badge model', text: 'Model: ' + by.model + ', run by ' + by.run_by + '. A claim, not checked by a person' }); + return el('span', { cls: 'badge', text: String(by.kind) }); + } + + function aboutText(about) { + var parts = []; + if (about.step) parts.push(about.step === 'total' ? 'the whole way' : 'step ' + stepNo(stepIndex(about.step)) + ': ' + D.steps[stepIndex(about.step)].label); + if (about.indicator) parts.push(indicatorName(about.indicator)); + if (about.item) { + var row = rowById(about.item); + parts.push(row ? row.name : about.item); + } + return parts.length ? 'About ' + parts.join(', ') + '. ' : 'About the whole file. '; + } + + function explanationNode(one, scope) { + return el('li', null, [ + scope ? el('span', { cls: 'sd-scope', text: scope }) : null, + badge(one.by), el('span', { cls: 'sd-quiet', text: aboutText(one.about) }), + one.finding === 'none found' ? el('strong', { text: 'Looked, found no reason: ' }) : null, one.text, + one.not_checked ? el('div', { cls: 'sd-quiet', text: 'Not checked: ' + one.not_checked }) : null, + one.source ? el('div', { cls: 'sd-quiet' }, [safeLink(one.source.link) ? el('a', { href: safeLink(one.source.link), text: one.source.link }) : null, one.source.doc ? ' ' + one.source.doc : null]) : null + ]); + } + + function renderExplanations() { + var list = clear(q('explanation-list')); + if (!D.explanations.length) list.appendChild(el('li', { cls: 'sd-quiet', text: 'The file holds no explanation.' })); + D.explanations.forEach(function (one) { list.appendChild(explanationNode(one)); }); + } + + function renderRule() { + var body = clear(q('rule-body')); + body.appendChild(el('p', null, ['Every value is put into one class by one rule, in this order: missing, near zero, agrees, within noise (both only where the two share a sign), zero reference, zero result, sign change, beyond 10x, differs. ' + + 'Direction is up where the result after is larger as a signed number, down otherwise; colour follows the direction only. ' + + 'Beyond 10x: one size more than ' + D.rule.beyond + ' times the other. The whole way is counted with a tolerance of ' + D.rule.total_tolerance + ', the largest of the steps. ' + + 'The matrix shows the result after divided by the result before; the ratio and the strength of its colour are a display, and change no class.'])); + var stepsTable = el('table', null, [el('thead', null, [el('tr', null, ['Step', 'Tolerance', 'Basis', 'Note', 'Noise'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); + var tb = el('tbody'); + D.steps.forEach(function (s) { + var noise = noiseText(s.noise, indicatorIds(), indWord(true)) + (s.noise.measured ? ': ' + Object.keys(s.noise.by).map(function (k) { return indicatorName(k) + ' ' + formatNumber(s.noise.by[k]); }).join(', ') : ''); + tb.appendChild(el('tr', null, [el('td', { text: s.label }), el('td', { cls: 'num', text: String(s.tolerance.value) }), el('td', { text: s.tolerance.basis }), el('td', { text: s.tolerance.note || '' }), el('td', { text: noise })])); + }); + stepsTable.appendChild(tb); + body.appendChild(el('div', { cls: 'sd-wrap' }, [stepsTable])); + body.appendChild(el('h4', { text: 'Floors' })); + body.appendChild(el('p', { cls: 'sd-quiet', text: 'One floor per ' + indWord(false) + ' and reference unit: ' + D.rule.floor_factor + ' times the median size of the results of ' + D.states[stateIndex(D.rule.floors_from)].label + ' in that unit, unless declared. Units are never pooled.' })); + var floors = el('table', null, [el('thead', null, [el('tr', null, [capital(indWord(false)), 'Unit', 'Floor', 'Basis', 'From results'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); + var fb = el('tbody'); + D.rule.floors.forEach(function (f) { + fb.appendChild(el('tr', null, [el('td', { text: indicatorName(f.indicator) }), el('td', { text: f.unit || 'unknown' }), el('td', { cls: 'num', text: formatNumber(f.value), title: String(f.value) }), el('td', { text: f.basis }), el('td', { cls: 'num', text: n(f.n) })])); + }); + floors.appendChild(fb); + body.appendChild(el('div', { cls: 'sd-wrap' }, [floors])); + var notes = clear(q('notes')); + D.notes.forEach(function (text) { notes.appendChild(el('li', { text: text })); }); + if (!D.notes.length) notes.appendChild(el('li', { cls: 'sd-quiet', text: 'None.' })); + } + + // ---------------------------------------------------------------- the item drawer + + // whether a row moved in a comparison and indicator an explanation is about; an + // explanation that names neither is about every one + function movedUnder(row, about) { + var ids = about.indicator ? [about.indicator] : indicatorIds(); + var ks = about.step ? [stepIndex(about.step)] : D.steps.map(function (s, k) { return k; }).concat([D.steps.length]); + return ids.some(function (id) { + return row.classes[id] && ks.some(function (k) { return MOVES.indexOf(row.classes[id][k]) >= 0; }); + }); + } + + function whyNode(row) { + var list = el('ul', { cls: 'sd-why' }); + var own = D.explanations.filter(function (e) { return e.about.item === row.id; }); + var wider = D.explanations.filter(function (e) { return !e.about.item && movedUnder(row, e.about); }); + own.forEach(function (e) { list.appendChild(explanationNode(e, 'This ' + D.item.one)); }); + wider.forEach(function (e) { list.appendChild(explanationNode(e, e.about.step && e.about.indicator ? 'Its step and ' + indWord(false) : e.about.step ? 'A step it moved in' : e.about.indicator ? capital(article(indWord(false))) + ' it moved in' : 'The whole file')); }); + if (!own.length && !wider.length) { + var any = movedUnder(row, {}); + list.appendChild(el('li', { cls: 'sd-none', text: any + ? 'None given: no explanation in this file is about this ' + D.item.one + ', or about a step or ' + indWord(false) + ' in which it moved.' + : 'It moved in no comparison, and no explanation in this file is about it.' })); + } + return list; + } + + function itemTable(row, ind) { + var values = row.values[ind.id]; var first = values[0], last = values[values.length - 1]; - var totalCls = item.classes[ind.id][D.steps.length]; - body.appendChild(el('h3', { text: ind.name + (ind.unit ? ' (' + ind.unit + ' per ' + (item.unit || 'unit') + ')' : '') })); - var table = el('table', null, [el('thead', null, [el('tr', null, ['Step', 'Before', 'After', 'Change', 'Verdict', 'Share of the whole difference'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); + var totalCls = row.classes[ind.id][D.steps.length]; + var table = el('table', { 'data-indicator': ind.id }, [el('thead', null, [el('tr', null, ['Step', 'Before', 'After', 'Change', 'Verdict', 'Share of the whole difference'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); var tb = el('tbody'); var split = splitOf(values, D.steps.map(function (s) { return s.explained; }), totalCls); D.steps.forEach(function (s, k) { var b = values[k], a = values[k + 1]; var share = split.state === 'split' ? shareText(split.shares[k]) : '—'; tb.appendChild(el('tr', null, [ - el('td', null, ['Step ' + k + ': ' + s.label, s.explained ? null : el('div', { cls: 'error', text: 'nothing explains it' })]), + el('td', null, ['Step ' + stepNo(k) + ': ' + s.label, s.explained ? null : el('div', { cls: 'sd-error', text: 'nothing explains it' })]), el('td', { cls: 'num', text: formatNumber(b), title: String(b) }), el('td', { cls: 'num', text: formatNumber(a), title: String(a) }), - cell(item, ind.id, k), - el('td', { text: verdictOf(item, ind.id, k) || '—' }), + valueCell(row, ind.id, k, false), + el('td', { text: verdictOf(row, ind.id, k) || '—' }), el('td', { cls: 'num', text: share }) ])); }); @@ -670,182 +1223,396 @@ el('th', { scope: 'row', text: 'The whole way' }), el('td', { cls: 'num', text: formatNumber(first), title: String(first) }), el('td', { cls: 'num', text: formatNumber(last), title: String(last) }), - cell(item, ind.id, D.steps.length), + valueCell(row, ind.id, D.steps.length, false), el('td', { text: '—' }), el('td', { cls: 'num', text: splitText(split) }) ])); table.appendChild(tb); - body.appendChild(el('div', { cls: 'table-wrap' }, [table])); - }); - var mine = D.explanations.filter(function (e) { return e.about.item === item.id; }); - if (mine.length) { - body.appendChild(el('h3', { text: 'Explanations' })); - body.appendChild(el('ul', { cls: 'plain' }, mine.map(explanationNode))); - } - Object.keys(item.breakdowns || {}).forEach(function (comp) { - var name = item.breakdowns[comp]; - var holder = el('div'); - body.appendChild(el('h3', { text: 'What it is made of: ' + compLabel(comp) })); - body.appendChild(holder); - var found = B[name]; - if (found) { - if (breakdownFits(found, item.id, comp)) breakdownInto(holder, found); - else holder.appendChild(el('p', { cls: 'error', text: 'The breakdown ' + name + ' is of another ' + D.item.one + ' or another step: not drawn.' })); + return el('div', { cls: 'sd-wrap' }, [table]); + } + + function renderItem(id) { + var row = rowById(id); + var drawer = q('item'); + if (!row) { closeItem(); return; } + if (drawer.hidden) lastFocus = doc.activeElement || null; + view.open = row.id; + drawer.hidden = false; + q('item-title').textContent = row.name; + q('item-meta').textContent = [row.id, row.place, row.group, row.unit ? 'per ' + row.unit : 'unit unknown', + row.item ? null : 'from the matrix: not listed in this file'].filter(Boolean).join(' · '); + var body = clear(q('item-body')); + body.appendChild(el('h4', { text: 'Why it differs' })); + body.appendChild(whyNode(row)); + body.appendChild(el('p', { cls: 'sd-quiet', text: 'The explanations about this ' + D.item.one + ' first, then those about a step or ' + indWord(false) + ' in which it moved: those may not be about it. An explanation is a claim; it changes no class.' })); + // the indicators, the one whose whole way lies furthest apart first + var last = D.steps.length; + var order = D.indicators.slice().sort(function (a, b) { + var pa = pairOf(row, a.id, last), pb = pairOf(row, b.id, last); + return compareKeys(severityKey(pa[0], pa[1], row.classes[a.id][last]), severityKey(pb[0], pb[1], row.classes[b.id][last])); + }); + order.forEach(function (ind) { + body.appendChild(el('h4', { text: ind.name + (ind.unit ? ' (' + ind.unit + ' per ' + (row.unit || 'unit') + ')' : '') })); + body.appendChild(itemTable(row, ind)); + }); + var named = row.item ? row.item.breakdowns || {} : {}; + Object.keys(named).forEach(function (comp) { + var name = named[comp]; + var holder = el('div'); + body.appendChild(el('h4', { text: 'What it is made of: ' + compLabel(comp) })); + body.appendChild(holder); + var found = B[name]; + if (found) { + if (breakdownFits(found, row.id, comp)) breakdownInto(holder, found); + else holder.appendChild(el('p', { cls: 'sd-error', text: 'The breakdown ' + name + ' is of another ' + D.item.one + ' or another step: not drawn.' })); + return; + } + holder.appendChild(el('p', { cls: 'sd-quiet', text: 'The breakdown ' + name + ' is not with this page.' })); + if (safeName(name) && /^https?:$/.test(win.location.protocol)) { + win.fetch(base + name).then(function (r) { if (!r.ok) throw new Error(); return r.json(); }) + .then(function (data) { if (!breakdownFits(data, row.id, comp)) throw new Error(); clear(holder); breakdownInto(holder, data); }) + .catch(function () { /* the sentence above stays */ }); + } + }); + markOpen(); + var title = q('item-title'); + if (title.focus) title.focus(); + } + + function markOpen() { + var table = q('grid-table'); + var trs = table.querySelectorAll ? table.querySelectorAll('tr[data-item]') : []; + for (var i = 0; i < trs.length; i++) { + if (trs[i].getAttribute('data-item') === view.open) trs[i].setAttribute('aria-current', 'true'); + else if (trs[i].removeAttribute) trs[i].removeAttribute('aria-current'); + } + } + + function closeItem() { + var drawer = q('item'); + if (!drawer || drawer.hidden) return; + drawer.hidden = true; + view.open = null; + markOpen(); + if (hashParts().item) setHash({ step: view.comp }); + if (lastFocus && lastFocus.focus && root.contains && root.contains(lastFocus)) lastFocus.focus(); + lastFocus = null; + } + + // a breakdown is drawn only under the item and the step that it breaks down + function breakdownFits(data, itemId, comp) { + if (!data || data.format !== 'sentier-diagnostics-breakdown/1' || data.item !== itemId) return false; + var k = stepIndex(comp); + var from = comp === 'total' ? D.states[0].id : D.steps[k].from; + var to = comp === 'total' ? D.states[D.states.length - 1].id : D.steps[k].to; + return data.from === from && data.to === to && !!data.indicators && typeof data.indicators === 'object'; + } + + function breakdownInto(holder, data) { + Object.keys(data.indicators).forEach(function (key) { + var entry = data.indicators[key]; + holder.appendChild(el('h4', { text: indicatorName(key) + (entry.unit ? ' (' + entry.unit + ')' : '') })); + var table = el('table', null, [el('thead', null, [el('tr', null, ['Part', 'Kind', 'Before', 'After', 'Change'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); + var tb = el('tbody'); + var line = function (label, kind, pair, strong) { + var d = pair[1] - pair[0]; + return el('tr', null, [el(strong ? 'th' : 'td', { text: label }), el('td', { text: kind || '' }), + el('td', { cls: 'num', text: formatNumber(pair[0]), title: String(pair[0]) }), + el('td', { cls: 'num', text: formatNumber(pair[1]), title: String(pair[1]) }), + el('td', { cls: 'num cell ' + (d > 0 ? 'tone-up' : d < 0 ? 'tone-down' : 'tone-none'), style: '--s:0.4', text: d === 0 ? '=' : (d > 0 ? '+' : '−') + formatNumber(Math.abs(d)) })]); + }; + entry.parts.forEach(function (p) { tb.appendChild(line(p.label, p.kind, p.values, false)); }); + tb.appendChild(line(entry.parts_not_listed ? 'The other ' + entry.parts_not_listed + ' parts' : 'No other part', '', entry.rest, false)); + tb.appendChild(line('Total', '', entry.total, true)); + table.appendChild(tb); + holder.appendChild(el('div', { cls: 'sd-wrap' }, [table])); + var cover = function (side) { + var listed = entry.parts.reduce(function (a, p) { return a + p.values[side]; }, 0); + return entry.total[side] ? shareText(listed / entry.total[side]) : 'none (the total is 0)'; + }; + holder.appendChild(el('p', { cls: 'sd-quiet', text: (entry.parts_not_listed + ? 'The first ' + entry.parts.length + ' parts make ' + cover(0) + ' of the total before and ' + cover(1) + ' after; the other ' + entry.parts_not_listed + ' are summed in one line. ' + : 'Every part is listed. ') + + 'Parts are listed by the larger of their two sizes, so that a part large on one side only is listed. The listed parts and the others add up to the total.' })); + }); + } + + // ---------------------------------------------------------------- the matrix + + function matrixSaid() { + var node = q('matrix-said'); + if (!node) return; + var c = D.items_count; + var text = { + none: D.tier === 'counts' ? '' : 'This file lists ' + groupThousands(c.listed) + ' of its ' + groupThousands(c.all) + ' ' + D.item.many + ' and names no matrix of every ' + D.item.one + ': the grid shows the listed ones.', + loading: 'Loading the matrix of every ' + D.item.one + ' (' + matrix.said + '); the grid shows the listed ones until it is here.', + loaded: 'The matrix of all ' + groupThousands(M ? M.length : 0) + ' ' + D.item.many + ' is loaded; a dot marks the ' + groupThousands(c.listed) + ' listed in this file.', + refused: 'The matrix was not loaded: ' + matrix.said + '. The grid shows the ' + groupThousands(c.listed) + ' ' + D.item.many + ' listed in this file.' + }[matrix.state]; + node.textContent = text; + } + + function takeMatrix(m) { + if (!D) return; + var problem = checkMatrix(m, D); + if (problem) { matrix.state = 'refused'; matrix.said = problem; matrixSaid(); return; } + M = matrixRows(m, D); + matrix.state = 'loaded'; + matrix.said = ''; + view.limit = PAGE; + tierSaid(); + renderComparison(); + matrixSaid(); + if (view.open) renderItem(view.open); + else route(); + } + + function refuseMatrix(said) { matrix.state = 'refused'; matrix.said = said; matrixSaid(); } + + // the matrix comes after the page is drawn: from a global, or from the file the root or + // the diagnostics file names, as a script beside the page (which opens from disk too) or + // as JSON over http + function loadMatrix() { + if (given.matrix) { takeMatrix(given.matrix); return; } + if (win.SENTIER_DIAGNOSTICS_MATRIX) { takeMatrix(win.SENTIER_DIAGNOSTICS_MATRIX); return; } + var name = root.getAttribute('data-sd-matrix') || (D.matrix ? D.matrix.file : null); + if (!name || D.tier === 'counts') { matrixSaid(); return; } + if (!safeName(name)) { refuseMatrix('its name is not a plain file name beside the page'); return; } + matrix.state = 'loading'; + matrix.said = name; + matrixSaid(); + if (/\.js$/.test(name)) { + var script = doc.createElement('script'); + script.setAttribute('src', base + name); + script.onload = function () { + if (win.SENTIER_DIAGNOSTICS_MATRIX) takeMatrix(win.SENTIER_DIAGNOSTICS_MATRIX); + else refuseMatrix(name + ' holds no matrix'); + }; + script.onerror = function () { refuseMatrix(name + ' is not beside the page'); }; + (doc.head || doc.body || root).appendChild(script); return; } - holder.appendChild(el('p', { cls: 'quiet', text: 'The breakdown ' + name + ' is not with this page.' })); - if (location.protocol === 'http:' || location.protocol === 'https:') { - fetch(name).then(function (r) { if (!r.ok) throw new Error(); return r.json(); }) - .then(function (data) { if (!breakdownFits(data, item.id, comp)) throw new Error(); clear(holder); breakdownInto(holder, data); }) - .catch(function () { /* the sentence above stays */ }); + if (!/^https?:$/.test(win.location.protocol)) { + refuseMatrix(name + ' is read over http only; `sentier-diagnostics page` writes it beside the page as a script, which opens from disk'); + return; } - }); - section.scrollIntoView({ block: 'start' }); - } + win.fetch(base + name).then(function (r) { + if (!r.ok) throw new Error(name + ' could not be read (' + r.status + ')'); + return r.text(); + }).then(function (text) { + if (text.length > MATRIX_MAX_BYTES) throw new Error(name + ' is larger than ' + groupThousands(MATRIX_MAX_BYTES) + ' bytes'); + var m; + try { m = JSON.parse(text); } catch (error) { throw new Error(name + ' is not JSON'); } + takeMatrix(m); + }).catch(function (error) { refuseMatrix(error.message || (name + ' could not be read')); }); + } - // a breakdown is drawn only under the item and the step that it breaks down - function breakdownFits(data, itemId, comp) { - if (!data || data.format !== 'sentier-diagnostics-breakdown/1' || data.item !== itemId) return false; - var k = stepIndex(comp); - var from = comp === 'total' ? D.states[0].id : D.steps[k].from; - var to = comp === 'total' ? D.states[D.states.length - 1].id : D.steps[k].to; - return data.from === from && data.to === to && !!data.indicators && typeof data.indicators === 'object'; - } + // ---------------------------------------------------------------- drawing a file - function breakdownInto(holder, data) { - Object.keys(data.indicators).forEach(function (key) { - var entry = data.indicators[key]; - holder.appendChild(el('h4', { text: indicatorName(key) + (entry.unit ? ' (' + entry.unit + ')' : '') })); - var table = el('table', null, [el('thead', null, [el('tr', null, ['Part', 'Kind', 'Before', 'After', 'Change'].map(function (h) { return el('th', { scope: 'col', text: h }); }))])]); - var tb = el('tbody'); - var line = function (label, kind, pair, strong) { - var d = pair[1] - pair[0]; - return el('tr', null, [el(strong ? 'th' : 'td', { text: label }), el('td', { text: kind || '' }), - el('td', { cls: 'num', text: formatNumber(pair[0]), title: String(pair[0]) }), - el('td', { cls: 'num', text: formatNumber(pair[1]), title: String(pair[1]) }), - el('td', { cls: 'num cell ' + (d > 0 ? 'tone-up' : d < 0 ? 'tone-down' : 'tone-none'), style: '--s:0.4', text: d === 0 ? '=' : (d > 0 ? '+' : '−') + formatNumber(Math.abs(d)) })]); - }; - entry.parts.forEach(function (p) { tb.appendChild(line(p.label, p.kind, p.values, false)); }); - tb.appendChild(line(entry.parts_not_listed ? 'The other ' + entry.parts_not_listed + ' parts' : 'No other part', '', entry.rest, false)); - tb.appendChild(line('Total', '', entry.total, true)); - table.appendChild(tb); - holder.appendChild(el('div', { cls: 'table-wrap' }, [table])); - var cover = function (side) { - var listed = entry.parts.reduce(function (a, p) { return a + p.values[side]; }, 0); - return entry.total[side] ? shareText(listed / entry.total[side]) : 'none (the total is 0)'; - }; - holder.appendChild(el('p', { cls: 'quiet', text: (entry.parts_not_listed - ? 'The first ' + entry.parts.length + ' parts make ' + cover(0) + ' of the total before and ' + cover(1) + ' after; the other ' + entry.parts_not_listed + ' are summed in one line. ' - : 'Every part is listed. ') + - 'Parts are listed by the larger of their two sizes, so that a part large on one side only is listed. The listed parts and the others add up to the total.' })); - }); - } + function renderComparison() { + renderFilters(); + renderDistributions(); + renderWorst(); + renderGrid(); + } - function renderComparison() { - renderFilters(); - renderDistributions(); - renderWorst(); - renderGrid(); - } + // a file the page cannot draw draws nothing: not even the part it drew before it failed + function refuse(problem) { + D = null; M = null; LISTED = []; + if (standalone) doc.title = 'Diagnostics'; + ['title', 'about', 'tier', 'audience', 'unchecked', 'matrix-said'].forEach(function (name) { + var node = q(name); + if (node) node.textContent = ''; + }); + ['audience', 'unchecked', 'item'].forEach(function (name) { if (q(name)) q(name).hidden = true; }); + if (q('states')) clear(q('states')); + showLoad(); + q('content').hidden = true; + q('load-error').textContent = problem; + } - // a file the page cannot draw draws nothing: not even the part it drew before it failed - function refuse(problem) { - D = null; - document.title = 'Diagnostics'; - ['title', 'about', 'tier', 'audience', 'unchecked'].forEach(function (id) { - var node = q(id); - if (node) node.textContent = ''; - }); - ['audience', 'unchecked'].forEach(function (id) { if (q(id)) q(id).hidden = true; }); - if (q('states')) clear(q('states')); - q('load').hidden = false; - q('content').hidden = true; - q('load-error').textContent = problem; - } + // `checked`: the file came with the page, which `sentier-diagnostics page` writes only + // after the validator passed it. A file chosen here or named in the address was not + // checked: the page checks its shape only, and says so above everything it draws. + function show(data, checked) { + var problem = checkShape(data); + if (problem) { refuse(problem); return; } + D = data; + M = null; + LISTED = D.items.map(listedRow); + matrix = { state: 'none', said: '' }; + view.comp = 'total'; + view.limit = PAGE; + q('load').hidden = true; + q('content').hidden = false; + var unchecked = q('unchecked'); + if (unchecked) { + unchecked.hidden = !!checked; + unchecked.textContent = checked ? '' : 'Opened in the browser: this page checked the shape of the file, not its counts. ' + + 'Run sentier-diagnostics check on it before relying on what it shows.'; + } + try { + renderHeader(); + renderSteps(); + renderExplanations(); + renderRule(); + legend(q('grid-legend'), true); + distLegend(); + renderComparison(); + matrixSaid(); + route(); + } catch (error) { + refuse('The file is JSON of the right format, but a part of it is missing or not what the format says (' + error.message + '). Run sentier-diagnostics check on it.'); + return; + } + if (checked) loadMatrix(); + } - // `checked`: the file came as data.js, which `sentier-diagnostics page` writes only after - // the validator passed it. A file chosen here or named in the address was not checked: the - // page checks its shape only, and says so above everything it draws. - function show(data, checked) { - var problem = checkShape(data); - if (problem) { refuse(problem); return; } - D = data; - view.comp = 'total'; - q('load').hidden = true; - q('content').hidden = false; - var unchecked = q('unchecked'); // a site's own frame may not have it; its data.js was checked - if (unchecked) { - unchecked.hidden = !!checked; - unchecked.textContent = checked ? '' : 'Opened in the browser: this page checked the shape of the file, not its counts. ' + - 'Run sentier-diagnostics check on it before relying on what it shows.'; - } - try { - renderHeader(); - renderSteps(); - renderExplanations(); - renderRule(); - legend(q('grid-legend')); - legend(q('dist-legend')); + // the address holds the chosen step and the open item, `#step=&item=`, each + // optional, so that a reviewer can send someone to exactly what they look at + function hashParts() { + var out = {}; + (win.location.hash || '').slice(1).split('&').forEach(function (part) { + var at = part.indexOf('='); + if (at > 0) out[part.slice(0, at)] = decodeURIComponent(part.slice(at + 1)); + }); + return out; + } + function setHash(parts) { + var said = []; + if (parts.step && parts.step !== 'total') said.push('step=' + encodeURIComponent(parts.step)); + if (parts.item) said.push('item=' + encodeURIComponent(parts.item)); + var wanted = said.join('&'); + if ((win.location.hash || '').replace(/^#/, '') === wanted) return false; + if (wanted) win.location.hash = wanted; + else if (win.history && win.history.replaceState) win.history.replaceState(null, '', win.location.pathname + win.location.search); + return true; + } + + function choose(comp) { + if (comp === view.comp) return; + view.comp = comp; view.cls = ''; view.verdict = ''; view.limit = PAGE; view.sort = 'worst'; + markChips(); + renderStepSaid(); renderComparison(); - route(); - } catch (error) { - refuse('The file is JSON of the right format, but a part of it is missing or not what the format says (' + error.message + '). Run sentier-diagnostics check on it.'); } - } - function route() { - var hash = decodeURIComponent(location.hash.slice(1)); - if (hash.indexOf('item=') === 0) renderItem(hash.slice(5)); - } + function route() { + if (!D) return; + var parts = hashParts(); + var step = parts.step && stepIndex(parts.step) < D.steps.length ? parts.step : 'total'; + choose(step); + if (parts.item) renderItem(parts.item); + else closeItem(); + } - function openFrom(event) { - var row = event.target.closest ? event.target.closest('tr[data-item]') : null; - if (row) location.hash = 'item=' + encodeURIComponent(row.getAttribute('data-item')); - } + function openFrom(event) { + var row = event.target.closest ? event.target.closest('tr[data-item]') : null; + if (!row) return; + var id = row.getAttribute('data-item'); + if (!setHash({ step: view.comp, item: id })) renderItem(id); + } - function start() { - B = root.SENTIER_DIAGNOSTICS_BREAKDOWNS || {}; - q('comparison').addEventListener('change', function (e) { view.comp = e.target.value; view.cls = ''; view.verdict = ''; view.limit = 100; renderComparison(); }); - q('size').addEventListener('change', function (e) { view.size = +e.target.value; view.limit = 100; renderWorst(); renderGrid(); }); - q('worst-n').addEventListener('change', function (e) { view.worstN = +e.target.value; renderWorst(); }); - q('worst-indicator').addEventListener('change', function (e) { view.worstIndicator = e.target.value; renderWorst(); }); - q('grid-find').addEventListener('input', function (e) { view.find = e.target.value; view.limit = 100; renderGrid(); }); - q('grid-class').addEventListener('change', function (e) { view.cls = e.target.value; view.limit = 100; renderGrid(); }); - q('grid-verdict').addEventListener('change', function (e) { view.verdict = e.target.value; view.limit = 100; renderGrid(); }); - q('grid-group').addEventListener('change', function (e) { view.group = e.target.value; view.limit = 100; renderGrid(); }); - q('grid-more').addEventListener('click', function () { view.limit += 100; renderGrid(); }); - ['grid-table', 'worst-table'].forEach(function (id) { - q(id).addEventListener('click', openFrom); - q(id).addEventListener('keydown', function (e) { if (e.key === 'Enter') openFrom(e); }); - }); - window.addEventListener('hashchange', route); - q('file').addEventListener('change', function (e) { - var file = e.target.files[0]; - if (!file) return; - var reader = new FileReader(); - reader.onload = function () { - var data; - try { data = JSON.parse(reader.result); } catch (error) { refuse('The file is not JSON: ' + error.message); return; } - show(data, false); - }; - reader.readAsText(file); - }); - if (root.SENTIER_DIAGNOSTICS) { show(root.SENTIER_DIAGNOSTICS, true); return; } - var wanted = new URLSearchParams(location.search).get('file'); - if (wanted && /^[A-Za-z0-9][A-Za-z0-9._\/-]*\.json$/.test(wanted) && wanted.indexOf('..') < 0 && location.protocol.indexOf('http') === 0) { - fetch(wanted).then(function (r) { return r.json(); }).then(function (data) { show(data, false); }, function () { - refuse('Could not read ' + wanted + ' as JSON.'); + function readScript(name) { + var node = q(name); + if (!node || !node.textContent || !/\S/.test(node.textContent)) return undefined; + return JSON.parse(node.textContent); + } + + function start() { + q('comparison').addEventListener('click', function (e) { + var chip = e.target.closest ? e.target.closest('button[data-comp]') : null; + if (!chip || chip.getAttribute('data-comp') === view.comp) return; + choose(chip.getAttribute('data-comp')); + setHash({ step: view.comp, item: view.open }); + }); + // the arrow keys move between the chips + q('comparison').addEventListener('keydown', function (e) { + if (!D || (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft')) return; + var comps = ['total'].concat(D.steps.map(function (s) { return s.id; })); + var at = comps.indexOf(view.comp) + (e.key === 'ArrowRight' ? 1 : -1); + if (at < 0 || at >= comps.length) return; + choose(comps[at]); + setHash({ step: view.comp, item: view.open }); + var next = q('comparison').querySelector('button[data-comp="' + comps[at] + '"]'); + if (next && next.focus) next.focus(); }); - return; + q('size').addEventListener('change', function (e) { view.size = +e.target.value; view.limit = PAGE; renderWorst(); renderGrid(); }); + q('worst-n').addEventListener('change', function (e) { view.worstN = +e.target.value; renderWorst(); }); + q('dist-scale').addEventListener('change', function (e) { view.distScale = e.target.value === 'one' ? 'one' : 'card'; renderDistributions(); }); + q('worst-indicator').addEventListener('change', function (e) { view.worstIndicator = e.target.value; renderWorst(); }); + q('grid-find').addEventListener('input', function (e) { view.find = e.target.value; view.limit = PAGE; renderGrid(); }); + q('grid-class').addEventListener('change', function (e) { view.cls = e.target.value; view.limit = PAGE; renderGrid(); }); + q('grid-verdict').addEventListener('change', function (e) { view.verdict = e.target.value; view.limit = PAGE; renderGrid(); }); + q('grid-group').addEventListener('change', function (e) { view.group = e.target.value; view.limit = PAGE; renderGrid(); }); + q('grid-more').addEventListener('click', function () { view.limit += PAGE; renderGrid(); }); + q('item-close').addEventListener('click', closeItem); + root.addEventListener('keydown', function (e) { if (e.key === 'Escape') closeItem(); }); + ['grid-table', 'worst-table'].forEach(function (name) { + q(name).addEventListener('click', openFrom); + q(name).addEventListener('keydown', function (e) { if (e.key === 'Enter') openFrom(e); }); + }); + win.addEventListener('hashchange', route); + q('file').addEventListener('change', function (e) { + var file = e.target.files[0]; + if (!file) return; + var reader = new win.FileReader(); + reader.onload = function () { + var data; + try { data = JSON.parse(reader.result); } catch (error) { refuse('The file is not JSON: ' + error.message); return; } + show(data, false); + }; + reader.readAsText(file); + }); + try { + var breakdowns = given.breakdowns || readScript('breakdowns'); + B = breakdowns || win.SENTIER_DIAGNOSTICS_BREAKDOWNS || {}; + var data = given.data || readScript('data'); + if (data === undefined) data = win.SENTIER_DIAGNOSTICS; + } catch (error) { + refuse('The data of this page is not JSON: ' + error.message); + return; + } + if (data) { show(data, true); return; } + var wanted = new win.URLSearchParams(win.location.search).get('file'); + if (wanted && safeName(wanted) && /\.json$/.test(wanted) && /^https?:$/.test(win.location.protocol)) { + win.fetch(base + wanted).then(function (r) { return r.json(); }).then(function (got) { show(got, false); }, function () { + refuse('Could not read ' + wanted + ' as JSON.'); + }); + return; + } + showLoad(); + } + + // the place for a file: a page of its own offers to open one; a host's page never does, + // and shows only why nothing is drawn + function showLoad() { + q('load').hidden = false; + q('load-choose').hidden = !standalone; + if (!standalone && !q('load-error').textContent) q('load-error').textContent = 'No diagnostics file came with this page.'; + } + + start(); + return { show: show, close: closeItem, open: renderItem }; + } + + // every root of the document not yet mounted, but those a host mounts itself + function mountAll(doc) { + var roots = (doc || global.document).querySelectorAll('[data-sentier-diagnostics]'); + for (var i = 0; i < roots.length; i++) { + if (roots[i].getAttribute('data-sentier-diagnostics') !== 'manual') mount(roots[i]); } - q('load').hidden = false; } - var api = { formatNumber: formatNumber, percentText: percentText, shareText: shareText, noiseText: noiseText, sizeAtLeast: sizeAtLeast, cellView: cellView, severityKey: severityKey, - compareKeys: compareKeys, bandStep: bandStep, checkShape: checkShape, safeLink: safeLink, splitOf: splitOf, splitText: splitText, distance: distance, RANK: RANK }; + var api = { formatNumber: formatNumber, percentText: percentText, shareText: shareText, ratioText: ratioText, ratioShort: ratioShort, noiseText: noiseText, + sizeAtLeast: sizeAtLeast, cellView: cellView, ratioView: ratioView, severityKey: severityKey, compareKeys: compareKeys, + bandStep: bandStep, bandOf: bandOf, checkShape: checkShape, checkMatrix: checkMatrix, matrixRows: matrixRows, + safeLink: safeLink, safeName: safeName, splitOf: splitOf, splitText: splitText, distance: distance, quantileTexts: quantileTexts, RANK: RANK, + mount: mount, mountAll: mountAll }; if (typeof module !== 'undefined' && module.exports) module.exports = api; - else if (typeof document !== 'undefined') { - if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start); - else start(); + else if (typeof global.document !== 'undefined') { + global.SentierDiagnostics = api; + if (global.document.readyState === 'loading') global.document.addEventListener('DOMContentLoaded', function () { mountAll(); }); + else mountAll(); } })(typeof window !== 'undefined' ? window : this); diff --git a/src/sentier_diagnostics/page/index.html b/src/sentier_diagnostics/page/index.html index a76214a..50960be 100644 --- a/src/sentier_diagnostics/page/index.html +++ b/src/sentier_diagnostics/page/index.html @@ -3,118 +3,14 @@ -Diagnostics +<!--title--> + - - - -
-

sentier-diagnostics

-

Diagnostics

-

-
    - - -

    -
    - - - -
    - - - +
    +
    - -

    diff --git a/src/sentier_diagnostics/page/standalone.css b/src/sentier_diagnostics/page/standalone.css new file mode 100644 index 0000000..75e0671 --- /dev/null +++ b/src/sentier_diagnostics/page/standalone.css @@ -0,0 +1,37 @@ +/* The frame of a page that stands on its own (`sentier-diagnostics page`). A site that holds + the diagnostics in its own page loads diagnostics.css only: this sheet sets the tokens a + site would set, the font and the ground, which diagnostics.css leaves to its host. */ +:root { + --ink: #1d232a; + --muted: #5b6672; + --surface: #ffffff; + --paper-deep: #f3f5f7; + --line: #d9dee3; + --line-strong: #b6bfc8; + --index: #1d625e; + --fail: #a3262a; + --radius: 6px; + --gutter: 16px; + color-scheme: light dark; +} +@media (prefers-color-scheme: dark) { + :root { + --ink: #e6eaee; + --muted: #9aa5b0; + --surface: #15191d; + --paper-deep: #1f252b; + --line: #36404a; + --line-strong: #56616c; + --index: #739e9b; + --fail: #ff8a8e; + } +} +body { + margin: 0; + font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; + line-height: 1.45; + color: var(--ink); + background: var(--surface); +} +.sd-standalone { max-width: 1400px; margin: 0 auto; padding: 0 var(--gutter) 2rem; } +.sd-standalone h1 { font-size: 1.6rem; margin: 1rem 0 0.2rem; } diff --git a/src/sentier_diagnostics/summary.py b/src/sentier_diagnostics/summary.py index 38fe1c7..cbd9e40 100644 --- a/src/sentier_diagnostics/summary.py +++ b/src/sentier_diagnostics/summary.py @@ -5,7 +5,7 @@ import re from collections.abc import Mapping -from . import chain, claims, rule +from . import chain, claims, fileformat, rule MOVES_ORDER = [k for k in rule.CLASSES if k in rule.MOVES] #: The characters that make Markdown of a text where it stands in a line (GitHub's flavour @@ -63,6 +63,8 @@ def text(data: Mapping) -> str: labels = {s["id"]: md(s["label"]) for s in data["steps"]} count = data["items_count"] many = md(data["item"]["many"]) + word = {k: md(v) for k, v in fileformat.indicator_word(data).items()} + indicators = word["one"] if len(data["indicators"]) == 1 else word["many"] out = [f"# {md(data['title'])}", ""] if data["audience"] == "local": out += ["**Local file: its writer has not said that it may be published.**", ""] @@ -77,7 +79,7 @@ def text(data: Mapping) -> str: f"unmatched, {_n(join['ambiguous'])} ambiguous." + (f" {md(join['note'])}" if join["note"] else "") ) out.append( - f"{_n(count['all'])} {many}, {len(data['indicators'])} indicators. " + f"{_n(count['all'])} {many}, {len(data['indicators'])} {indicators}. " + ( "This file holds counts only." if data["tier"] == "counts" @@ -88,7 +90,7 @@ def text(data: Mapping) -> str: out += ["", "## Steps", "", "| Step | Kind | Explained | Values moved | Missing before | Missing after | As claimed | Off claim | Not claimed | Claimed, not moved |", "|---|---|---|---:|---:|---:|---:|---:|---:|---:|"] # fmt: skip - for number, step in enumerate(data["steps"]): + for number, step in enumerate(data["steps"], fileformat.first_step(data)): blocks = data["counts"]["steps"][step["id"]].values() moved = sum(b["classes"][k] for b in blocks for k in rule.MOVES) # a result missing on both sides is missing before and missing after @@ -112,7 +114,7 @@ def text(data: Mapping) -> str: "residual the chain starts from, not a regression."] first, last = md(data["states"][0]["label"]), md(data["states"][-1]["label"]) out += ["", f"## The whole way: {first} → {last}", ""] - header = ["Indicator", *rule.CLASSES, "Largest step", "Spread over steps", "Not attributable", + header = [word["one"][:1].upper() + word["one"][1:], *rule.CLASSES, "Largest step", "Spread over steps", "Not attributable", "Moved by what nothing explains"] # fmt: skip out.append("| " + " | ".join(header) + " |") out.append("|---|" + "---:|" * (len(header) - 1)) @@ -132,7 +134,7 @@ def text(data: Mapping) -> str: out.append(f"- {labels[step['id']]}: tolerance {tol['value']:g} ({tol['basis']}); {noise_text(step['noise'], names)}") floors = data["rule"]["floors"] out.append( - f"- Floors: {len(floors)}, one per indicator and reference unit, " + f"- Floors: {len(floors)}, one per {word['one']} and reference unit, " f"{data['rule']['floor_factor']:g} of the median size in {md(states[data['rule']['floors_from']]['label'])}" f" ({sum(1 for f in floors if f['basis'] == 'declared')} declared, " f"{sum(1 for f in floors if f['basis'] == 'none')} without a result to take one from)." diff --git a/tests/helpers.py b/tests/helpers.py index 944f770..4c4a832 100644 --- a/tests/helpers.py +++ b/tests/helpers.py @@ -10,13 +10,13 @@ INDICATORS = [(A, "Indicator A", "A", "kg CO2 eq"), (B, "Indicator B", "B", "m3")] -def two_states(before: dict, after: dict, *, claim=None, units=None, **more) -> dict: +def two_states(before: dict, after: dict, *, claim=None, units=None, first_kind="published", **more) -> dict: """A chain of one step: `before` and `after` are `{indicator: {item: value}}`.""" items = {item for side in (before, after) for column in side.values() for item in column} return chain.build( "Two states", indicators=INDICATORS, - states=[chain.state("s0", "Before", kind="published"), chain.state("s1", "After")], + states=[chain.state("s0", "Before", kind=first_kind), chain.state("s1", "After")], steps=[chain.step("one", "One step", kind="fix", claim=claim)], values={"s0": before, "s1": after}, units=units or dict.fromkeys(items, "kg"), diff --git a/tests/js/dom.js b/tests/js/dom.js index d4c81e1..ee1e2d7 100644 --- a/tests/js/dom.js +++ b/tests/js/dom.js @@ -1,7 +1,7 @@ // A small stand-in for the part of the DOM the page script uses, so that the page can be // drawn under Node without a browser or a package. Elements hold children, attributes and -// listeners; text nodes hold text. `page(data, breakdowns)` runs diagnostics.js against -// the ids of index.html and returns what it drew. +// listeners; text nodes hold text. `page(data, breakdowns)` builds the elements of body.html +// that carry `data-sd`, runs diagnostics.js against them and returns what it drew. 'use strict'; const fs = require('node:fs'); @@ -10,6 +10,17 @@ const vm = require('node:vm'); const PAGE = path.join(__dirname, '..', '..', 'src', 'sentier_diagnostics', 'page'); +// the selectors the script asks for: [attr], [attr="value"], tag[attr], tag[attr="value"] +function matches(node, selector) { + const one = /^([a-z0-9]*)\[([a-z-]+)(?:="([^"]*)")?\]$/.exec(selector); + if (!one) throw new Error('the stand-in does not know the selector ' + selector); + const [, tag, key, value] = one; + if (node.text !== undefined) return false; + if (tag && node.tagName !== tag.toUpperCase()) return false; + if (!(key in node.attributes)) return false; + return value === undefined || node.attributes[key] === value; +} + class FakeNode { constructor(tag, text) { this.tagName = tag ? tag.toUpperCase() : null; @@ -22,7 +33,7 @@ class FakeNode { this.className = ''; this.value = ''; this.disabled = false; - this.onclick = null; + this.focused = false; } get firstChild() { return this.childNodes[0] || null; } @@ -60,23 +71,35 @@ class FakeNode { getAttribute(key) { return key in this.attributes ? this.attributes[key] : null; } + removeAttribute(key) { delete this.attributes[key]; } + addEventListener(type, listener) { (this.listeners[type] = this.listeners[type] || []).push(listener); } - dispatch(type, event) { (this.listeners[type] || []).forEach((listener) => listener({ target: this, ...event })); } + // an event on this node, passed up to its parents as a browser does + dispatch(type, event) { + const full = { target: this, ...event }; + for (let node = this; node; node = node.parentNode) (node.listeners[type] || []).forEach((listener) => listener(full)); + } closest(selector) { - if (selector !== 'tr[data-item]') throw new Error('the stand-in knows tr[data-item] only'); - for (let node = this; node; node = node.parentNode) { - if (node.tagName === 'TR' && node.getAttribute('data-item') !== null) return node; - } + for (let node = this; node; node = node.parentNode) if (matches(node, selector)) return node; return null; } + querySelectorAll(selector) { return this.all().slice(1).filter((n) => matches(n, selector)); } + + querySelector(selector) { return this.querySelectorAll(selector)[0] || null; } + + contains(other) { for (let n = other; n; n = n.parentNode) if (n === this) return true; return false; } + + focus() { this.focused = true; } + scrollIntoView() {} - // every text a reader sees: text nodes and tooltips, in order + // every text a reader sees: text nodes and tooltips, in order; nothing under a hidden node seen() { if (this.text !== undefined) return [this.text]; + if (this.hidden) return []; const own = this.attributes.title ? [this.attributes.title] : []; return own.concat(...this.childNodes.map((c) => c.seen())); } @@ -85,44 +108,80 @@ class FakeNode { all() { return this.text !== undefined ? [] : [this].concat(...this.childNodes.map((c) => c.all())); } } -function page(data, breakdowns) { - const html = fs.readFileSync(path.join(PAGE, 'index.html'), 'utf8'); - const byId = {}; +// the root of body.html and every element in it that carries `data-sd` or `data-sd-word`, each a child of the +// root; the data scripts as the Python writes them where `scripts` holds them +function body(scripts) { + const html = fs.readFileSync(path.join(PAGE, 'body.html'), 'utf8'); + const root = new FakeNode('div'); + root.setAttribute('class', 'sentier-diagnostics'); + root.setAttribute('data-sentier-diagnostics', ''); for (const [whole, tag] of html.matchAll(/<([a-z0-9]+)\b[^>]*>/g)) { - const id = /\sid="([^"]+)"/.exec(whole); - if (!id) continue; - byId[id[1]] = new FakeNode(tag); - byId[id[1]].attributes.id = id[1]; - byId[id[1]].hidden = /\shidden[\s>=]/.test(whole); + const word = /\sdata-sd-word="([^"]+)"/.exec(whole); + if (word) { const span = new FakeNode(tag); span.setAttribute('data-sd-word', word[1]); root.appendChild(span); continue; } + const name = /\sdata-sd="([^"]+)"/.exec(whole); + if (!name) continue; + const node = new FakeNode(tag); + node.setAttribute('data-sd', name[1]); + node.hidden = /\shidden[\s>=]/.test(whole); + root.appendChild(node); + } + for (const [name, value] of Object.entries(scripts || {})) { + const node = new FakeNode('script'); + node.setAttribute('type', 'application/json'); + node.setAttribute('data-sd', name); + node.textContent = JSON.stringify(value); + root.appendChild(node); } + return root; +} + +// `options`: {standalone, attributes, globals, fetch, protocol, scripts} +function page(data, breakdowns, options) { + options = options || {}; + const scripts = options.scripts || {}; + if (data !== undefined && !options.globals) scripts.data = data; + if (breakdowns && !options.globals) scripts.breakdowns = breakdowns; + const root = body(scripts); + if (options.standalone) root.setAttribute('data-sd-standalone', ''); + for (const [key, value] of Object.entries(options.attributes || {})) root.setAttribute(key, value); + const head = new FakeNode('head'); const listeners = {}; const document = { title: '', readyState: 'complete', + head, + activeElement: null, createElement: (tag) => new FakeNode(tag), createTextNode: (text) => new FakeNode(null, String(text)), - getElementById: (id) => byId[id] || null, + querySelectorAll: (selector) => (matches(root, selector) ? [root] : []), addEventListener: () => {}, }; + root.ownerDocument = document; const context = { document, - location: { hash: '', search: '', pathname: '/index.html', protocol: 'file:' }, - history: { replaceState: () => {} }, + location: { hash: '', search: '', pathname: '/index.html', protocol: options.protocol || 'file:' }, + history: { replaceState: () => { context.location.hash = ''; } }, addEventListener: (type, listener) => { (listeners[type] = listeners[type] || []).push(listener); }, URLSearchParams, FileReader: class {}, - fetch: () => Promise.reject(new Error('no network')), - SENTIER_DIAGNOSTICS: data, - SENTIER_DIAGNOSTICS_BREAKDOWNS: breakdowns || {}, + fetch: options.fetch || (() => Promise.reject(new Error('no network'))), + ...(options.globals || {}), }; + if (options.globals && data !== undefined) context.SENTIER_DIAGNOSTICS = data; + if (options.globals && breakdowns) context.SENTIER_DIAGNOSTICS_BREAKDOWNS = breakdowns; context.window = context; vm.createContext(context); vm.runInContext(fs.readFileSync(path.join(PAGE, 'diagnostics.js'), 'utf8'), context, { filename: 'diagnostics.js' }); + const byName = {}; + root.childNodes.forEach((n) => { if (n.getAttribute('data-sd')) byName[n.getAttribute('data-sd')] = n; }); return { - byId, + root, + byId: byName, // by the name in data-sd + head, document, - // the text of everything drawn, tooltips included - text: () => Object.values(byId).filter((n) => !n.hidden).map((n) => n.seen().join(' ')).join('\n'), + context, + // the text of everything drawn and not hidden, tooltips included + text: () => root.childNodes.filter((n) => !n.hidden && n.tagName !== 'SCRIPT').map((n) => n.seen().join(' ')).join('\n'), open: (hash) => { context.location.hash = '#' + hash; (listeners.hashchange || []).forEach((listener) => listener({})); @@ -130,4 +189,4 @@ function page(data, breakdowns) { }; } -module.exports = { FakeNode, page }; +module.exports = { FakeNode, page, body }; diff --git a/tests/js/page.test.js b/tests/js/page.test.js index b03832c..33254fb 100644 --- a/tests/js/page.test.js +++ b/tests/js/page.test.js @@ -1,5 +1,5 @@ // The page script against the acceptance cases the Python rule is tested on. -// Run with `node --test tests/js/`. Node's own test runner: no package, no install. +// Run with `node --test tests/js/page.test.js`. Node's own test runner: no package, no install. 'use strict'; const test = require('node:test'); @@ -140,7 +140,7 @@ const example = () => JSON.parse(fs.readFileSync(path.join(EXAMPLE, 'diagnostics const wheat = () => JSON.parse(fs.readFileSync(path.join(EXAMPLE, 'p01-fix-1.json'), 'utf8')); test('the example page is drawn whole', () => { - const drawn = dom.page(example(), { 'p01-fix-1.json': wheat() }); + const drawn = dom.page(example(), { 'p01-fix-1.json': wheat() }, { standalone: true }); assert.equal(drawn.byId.load.hidden, true, drawn.byId['load-error'].textContent); assert.equal(drawn.byId.content.hidden, false); assert.equal(drawn.byId.unchecked.hidden, true); @@ -202,7 +202,7 @@ test('a text by a model is drawn as a claim nobody checked (A9)', () => { test('nothing drawn calls a move better or worse (A22)', () => { const drawn = dom.page(example(), { 'p01-fix-1.json': wheat() }); drawn.open('item=p01'); - const html = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'sentier_diagnostics', 'page', 'index.html'), 'utf8') + const html = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'sentier_diagnostics', 'page', 'body.html'), 'utf8') .replace(/<[^>]*>/g, ' '); const text = (drawn.text() + '\n' + html).toLowerCase(); for (const word of ['better', 'worse', 'improve', 'closer']) assert.ok(!text.includes(word), word); @@ -217,7 +217,7 @@ test('the item view splits only what can be split and draws the breakdown of its assert.ok(/100\.0 %/.test(body), 'the sum of the shares'); drawn.open('item=p03'); // barley: no water use in the rebuilt state const barley = drawn.byId['item-body']; - const water = barley.all().filter((n) => n.tagName === 'TABLE')[1]; + const water = barley.querySelector('table[data-indicator="x:water"]'); const shares = water.all().filter((n) => n.tagName === 'TR').slice(1, -1).map((tr) => tr.childNodes[5].textContent); assert.deepEqual(shares, shares.map(() => '—')); assert.ok(water.seen().join(' ').includes('not split: missing in a state between')); @@ -233,6 +233,17 @@ test('a breakdown named by another item is not drawn under it (issue 5)', () => assert.ok(body.includes('is of another product or another step: not drawn'), body.slice(-300)); }); +test('a breakdown of the right step and another item is not drawn under it (issue 5)', () => { + const data = example(); + const step = Object.keys(data.items.find((i) => i.id === 'p01').breakdowns)[0]; + const rice = data.items.find((i) => i.id === 'p05'); + rice.breakdowns = { [step]: 'p01-fix-1.json' }; + const drawn = dom.page(data, { 'p01-fix-1.json': wheat() }); + drawn.open('item=p05'); + const body = drawn.byId['item-body'].seen().join(' '); + assert.ok(body.includes('is of another product or another step: not drawn'), body.slice(-300)); +}); + test('a file the page cannot draw draws nothing', () => { const data = example(); data.counts.total = null; @@ -241,3 +252,593 @@ test('a file the page cannot draw draws nothing', () => { assert.equal(drawn.byId.load.hidden, false); assert.equal(drawn.byId.title.textContent, ''); }); + +test('a host page never offers to open a file; a page of its own does', () => { + const host = dom.page(undefined); + assert.equal(host.byId.load.hidden, false); + assert.equal(host.byId['load-choose'].hidden, true); + assert.match(host.byId['load-error'].textContent, /No diagnostics file came with this page/); + const broken = example(); broken.counts.total = null; + assert.equal(dom.page(broken).byId['load-choose'].hidden, true); + const own = dom.page(undefined, undefined, { standalone: true }); + assert.equal(own.byId['load-choose'].hidden, false); + assert.equal(own.byId['load-error'].textContent, ''); +}); + +test('chips choose the comparison: the whole way first, then each step with what moved in it', () => { + const data = example(); + const drawn = dom.page(data); + const chips = () => drawn.byId.comparison.querySelectorAll('button[data-comp]'); + assert.deepEqual(chips().map((c) => c.getAttribute('data-comp')), ['total'].concat(data.steps.map((s) => s.id))); + assert.deepEqual(chips().map((c) => c.getAttribute('aria-pressed')), ['true'].concat(data.steps.map(() => 'false'))); + const moved = (comp) => Object.values(comp === 'total' ? data.counts.total : data.counts.steps[comp]) + .reduce((sum, b) => sum + ['differs', 'beyond 10x', 'zero reference', 'zero result', 'sign change'].reduce((a, k) => a + b.classes[k], 0), 0); + chips().forEach((chip) => assert.ok(chip.textContent.includes(moved(chip.getAttribute('data-comp')) + ' moved'), chip.textContent)); + // the unexplained step is flagged, the verdicts worth a look are marked + const rebuilt = data.steps.findIndex((s) => !s.explained); + assert.ok(rebuilt >= 0); + assert.ok(chips()[rebuilt + 1].textContent.includes('!')); + assert.match(chips()[rebuilt + 1].getAttribute('title'), /nothing explains it/); + const claimed = data.steps.findIndex((s) => s.claim && Object.values(data.counts.steps[s.id]).some((b) => b.verdicts['not claimed'])); + assert.ok(chips()[claimed + 1].textContent.includes('■'), chips()[claimed + 1].textContent); + // a click on a step's label chooses it, and the grid follows + const label = chips()[2].childNodes[1]; // the label inside the chip: the click reaches the chip + label.dispatch('click', {}); + assert.deepEqual(chips().map((c) => c.getAttribute('aria-pressed')), ['false', 'false', 'true'].concat(data.steps.slice(2).map(() => 'false'))); + assert.ok(drawn.byId['grid-region'].getAttribute('aria-label').endsWith(': Step 1: ' + data.steps[1].label + ', the furthest apart first'), + drawn.byId['grid-region'].getAttribute('aria-label')); +}); + +// ------------------------------------------------------------------ the matrix and the drawer + +const local = () => JSON.parse(fs.readFileSync(path.join(EXAMPLE, 'local', 'diagnostics.json'), 'utf8')); +const full = () => JSON.parse(fs.readFileSync(path.join(EXAMPLE, 'local', 'matrix.json'), 'utf8')); +const gridRows = (drawn) => drawn.byId['grid-table'].querySelectorAll('tr[data-item]'); + +test('the band the page names for a matrix row is the band of the Python rule', () => { + for (const c of cases) { + if (c.class !== 'differs' && c.class !== 'beyond 10x') continue; + assert.equal(page.bandOf(c.before, c.after, c.class, c.direction), c.band, c.id); + } +}); + +test('a ratio never reads 1 when it is not, nor Infinity', () => { + assert.equal(page.ratioText(2, 3), '1.5'); + assert.equal(page.ratioText(-2, -4), '2'); + assert.equal(page.ratioText(1, 1.0000003), '1 + 3e−7'); + assert.equal(page.ratioText(1, 0.9999), '1 − 1e−4'); + assert.equal(page.ratioText(1e-300, 1e300), '1e600'); + assert.equal(page.ratioText(1e300, 1e-300), '1e−600'); +}); + +test('the matrix the Python writes is one the page takes, and the rows are the file\'s', () => { + const data = local(); + assert.equal(page.checkMatrix(full(), data), null); + const rows = page.matrixRows(full(), data); + assert.equal(rows.length, data.items_count.all); + for (const item of data.items) { + const row = rows.find((r) => r.id === item.id); + assert.deepEqual(row.values, item.values, item.id); + assert.deepEqual(row.classes, item.classes, item.id); + assert.deepEqual(row.directions, item.directions, item.id); + assert.deepEqual(row.verdicts, item.verdicts, item.id); + } +}); + +test('a matrix of another file, or of another shape, is refused', () => { + const data = local(); + const other = full(); other.of.title = 'Another'; + assert.match(page.checkMatrix(other, data), /another file/); + const short = full(); short.classes[0] = short.classes[0].slice(1); + assert.match(page.checkMatrix(short, data), /class code/); + const wrong = full(); wrong.values[2][0] = 'x'; + assert.match(page.checkMatrix(wrong, data), /not a number/); + const fewer = full(); fewer.items.pop(); fewer.values.pop(); fewer.classes.pop(); fewer.verdicts.pop(); + assert.match(page.checkMatrix(fewer, data), /says 10 items/); +}); + +test('a matrix that says other numbers of a listed item than its file is refused', () => { + // a matrix left over from another run of the same chain: same title, states, steps and count + const data = local(); + const listed = data.items[0].id; + const at = full().items.findIndex((row) => row[0] === listed); + const tripled = full(); tripled.values[at] = tripled.values[at].map((v) => (typeof v === 'number' ? v * 3 : v)); + assert.match(page.checkMatrix(tripled, data), new RegExp('item ' + listed + ', .*: its results or classes differ')); + const reclassed = full(); + const code = reclassed.classes[at][0]; + const other = [...reclassed.classes.join('')].find((c) => c !== code); // another class the matrix itself uses + reclassed.classes[at] = other + reclassed.classes[at].slice(1); + assert.match(page.checkMatrix(reclassed, data), /its results or classes differ/); + const renamed = full(); renamed.items[at][1] = 'Another name'; + assert.match(page.checkMatrix(renamed, data), /its name, place, group or unit differ/); + const swapped = full(); swapped.items[at][0] = 'not-listed'; + assert.match(page.checkMatrix(swapped, data), /1 of the items this file lists are not in it/); + // an item the file does not list has nothing to be held to + const unlisted = full(); + const free = unlisted.items.findIndex((row) => !data.items.some((item) => item.id === row[0])); + unlisted.values[free] = unlisted.values[free].map((v) => (typeof v === 'number' ? v * 3 : v)); + assert.equal(page.checkMatrix(unlisted, data), null); +}); + +test('the grid shows the listed items, says so, and every item once the matrix is here', () => { + const data = local(); + const before = dom.page(data); // over file: the matrix.json the file names cannot be read + assert.equal(gridRows(before).length, data.items.length); + assert.match(before.byId['matrix-said'].textContent, /not loaded: matrix\.json is read over http only/); + assert.match(before.byId['grid-said'].textContent, new RegExp('of ' + data.items.length + ' products, among the ' + data.items.length + ' products in this file; ' + data.items_count.not_listed + ' more')); + const after = dom.page(data, undefined, { globals: { SENTIER_DIAGNOSTICS_MATRIX: full() } }); + assert.equal(gridRows(after).length, data.items_count.all); + assert.match(after.byId['matrix-said'].textContent, /matrix of all 10 products is loaded/); + assert.match(before.byId.tier.textContent, /6 of the \d+ products worth a look are in this file; \d+ are not\./); + assert.match(after.byId.tier.textContent, /All 10 are loaded from the matrix; 6 of the \d+ worth a look are listed in this file\./); + assert.equal(after.byId['grid-table'].all().filter((n) => n.className === 'sd-listed').length, data.items.length); +}); + +test('a matrix beside the page is loaded as a script after the page is drawn', () => { + const drawn = dom.page(local(), undefined, { attributes: { 'data-sd-matrix': 'matrix.js', 'data-sd-base': 'runs/1/' } }); + const script = drawn.head.querySelector('script[src]'); + assert.equal(script.getAttribute('src'), 'runs/1/matrix.js'); + assert.match(drawn.byId['matrix-said'].textContent, /^Loading/); + drawn.context.SENTIER_DIAGNOSTICS_MATRIX = full(); + script.onload(); + assert.equal(gridRows(drawn).length, 10); +}); + +test('a matrix is fetched as JSON over http, and one of another file is not drawn', async () => { + const served = (m) => () => Promise.resolve({ ok: true, status: 200, text: () => Promise.resolve(JSON.stringify(m)) }); + const drawn = dom.page(local(), undefined, { protocol: 'https:', fetch: served(full()) }); + await new Promise((done) => setImmediate(done)); + assert.equal(gridRows(drawn).length, 10); + const other = full(); other.of.steps = other.of.steps.slice().reverse(); + const refused = dom.page(local(), undefined, { protocol: 'https:', fetch: served(other) }); + await new Promise((done) => setImmediate(done)); + assert.equal(gridRows(refused).length, 6); + assert.match(refused.byId['matrix-said'].textContent, /not loaded: it is the matrix of another file/); +}); + +test('a grid cell is the ratio after ÷ before, coloured by its direction', () => { + const drawn = dom.page(example()); + const wheat = gridRows(drawn).find((tr) => tr.getAttribute('data-item') === 'p01'); + const item = example().items.find((i) => i.id === 'p01'); + const values = item.values['x:climate']; + const cell = wheat.childNodes[2]; // name, group, then the first indicator: no unit column + assert.equal(item.classes['x:climate'][4], 'differs'); + assert.equal(cell.textContent, page.ratioShort(values[0], values[values.length - 1])); + assert.match(cell.className, new RegExp('tone-' + item.directions['x:climate'][4])); + const heads = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]').map((th) => th.textContent); + assert.equal(heads.length, 2 + example().indicators.length); + assert.ok(!heads.includes('Unit')); +}); + +test('a ratio in the grid has three significant digits, and never "Infinity"', () => { + assert.equal(page.ratioShort(1, 1), '1.00'); + assert.equal(page.ratioShort(1, 1.0000003), '1.00'); + assert.equal(page.ratioShort(1, 0.984), '0.984'); + assert.equal(page.ratioShort(-2, -4.54), '2.27'); + assert.equal(page.ratioShort(1, 25), '25.0'); + assert.equal(page.ratioShort(1, 999.7), '1e3'); + assert.equal(page.ratioShort(1, 12345), '1.23e4'); + assert.equal(page.ratioShort(1, 0.004), '4e−3'); + assert.equal(page.ratioShort(1e-300, 1e300), '1e600'); + const noise = page.ratioView(1, 1.001, 'within noise', 'up', null); + assert.deepEqual([noise.text, noise.mark, noise.tone], ['1.00', '~', 'noise']); + const agrees = page.ratioView(2, 2, 'agrees', null, null); + assert.deepEqual([agrees.text, agrees.tone, agrees.strength], ['1.00', 'none', 0]); + assert.equal(page.ratioView(0, 0, 'agrees', null, null).text, '='); + assert.equal(page.ratioView(-1, 2, 'sign change', 'up', null).text, '− → +'); +}); + +test('every grid cell with a ratio shows it, agreeing ones too; the class is the tint and a mark', () => { + const data = example(); + const drawn = dom.page(data); + let agrees = 0, noise = 0; + for (const tr of gridRows(drawn)) { + const item = data.items.find((i) => i.id === tr.getAttribute('data-item')); + data.indicators.forEach((ind, at) => { + const cell = tr.childNodes[2 + at]; + const v = item.values[ind.id], before = v[0], after = v[v.length - 1], cls = item.classes[ind.id][4]; + const shared = before !== null && after !== null && before !== 0 && after !== 0 && (before > 0) === (after > 0); + if (shared && ['agrees', 'within noise', 'differs', 'beyond 10x'].includes(cls)) { + assert.ok(cell.textContent.startsWith(page.ratioShort(before, after)), item.id + ' ' + ind.id + ': ' + cell.textContent); + if (cls === 'agrees') { agrees += 1; assert.match(cell.className, /tone-none/); } + if (cls === 'within noise') { noise += 1; assert.match(cell.textContent, /~$/); } + } else { + assert.doesNotMatch(cell.textContent, /^\d/, item.id + ' ' + ind.id + ' (' + cls + '): ' + cell.textContent); + } + assert.notEqual(cell.textContent, '='); + }); + } + assert.ok(agrees > 5, 'agreeing cells were checked'); +}); + +test('the grid opens with the items that lie furthest apart, and a second click goes back to that', () => { + const data = example(); + data.items.reverse(); // the file lists them worst first already: the page must order them itself + const drawn = dom.page(data); + // the largest factor among the values that moved with a ratio first, then the worst value + const worst = (id) => { + const i = data.items.find((x) => x.id === id); + let furthest = 0; + const keys = data.indicators.map((ind) => { + const v = i.values[ind.id], cls = i.classes[ind.id][4]; + if (cls === 'differs' || cls === 'beyond 10x') furthest = Math.max(furthest, Math.abs(Math.log10(Math.abs(v[v.length - 1] / v[0])))); + return page.severityKey(v[0], v[v.length - 1], cls); + }); + return [-furthest].concat(keys.sort(page.compareKeys)[0]); + }; + const order = () => gridRows(drawn).map((tr) => tr.getAttribute('data-item')); + const first = order(); + for (let k = 1; k < first.length; k++) assert.ok(page.compareKeys(worst(first[k - 1]), worst(first[k])) <= 0, first.join()); + assert.notDeepEqual(first, data.items.map((i) => i.id), 'the example is not already in that order'); + assert.match(drawn.byId['grid-region'].getAttribute('aria-label'), /, the furthest apart first$/); + const button = () => drawn.byId['grid-table'].querySelectorAll('th[scope="col"]')[0].querySelector('button[type="button"]'); + button().dispatch('click', {}); + assert.doesNotMatch(drawn.byId['grid-region'].getAttribute('aria-label'), /furthest apart first/); + button().dispatch('click', {}); + assert.deepEqual(order(), first); +}); + +test('a heading sorts the grid by how far the two lie apart, the furthest first, and says so', () => { + const data = example(); + const drawn = dom.page(data); + const head = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]'); + const water = head.find((th) => th.getAttribute('title') && th.getAttribute('title').indexOf('Water') === 0); + water.querySelector('button[type="button"]').dispatch('click', {}); + const after = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]').find((th) => th.getAttribute('aria-sort')); + assert.equal(after.getAttribute('aria-sort'), 'descending'); + const order = gridRows(drawn).map((tr) => tr.getAttribute('data-item')); + const key = (id) => { const i = data.items.find((x) => x.id === id); const v = i.values['x:water']; return page.severityKey(v[0], v[v.length - 1], i.classes['x:water'][4]); }; + for (let k = 1; k < order.length; k++) assert.ok(page.compareKeys(key(order[k - 1]), key(order[k])) <= 0, order.join()); +}); + +test('the grid draws 300 rows at a time', () => { + const data = local(); + const m = full(); + const n = 650; + const grown = { ...m, items: [], values: [], classes: [], verdicts: [] }; + for (let i = 0; i < n; i++) { + const at = i % m.items.length; + grown.items.push(i < m.items.length ? m.items[at] : [m.items[at][0] + '-' + i].concat(m.items[at].slice(1))); + grown.values.push(m.values[at]); grown.classes.push(m.classes[at]); grown.verdicts.push(m.verdicts[at]); + } + data.matrix.items = n; + const drawn = dom.page(data, undefined, { globals: { SENTIER_DIAGNOSTICS_MATRIX: grown } }); + assert.equal(gridRows(drawn).length, 300); + assert.equal(drawn.byId['grid-more'].textContent, 'Show 300 more'); + drawn.byId['grid-more'].dispatch('click', {}); + drawn.byId['grid-more'].dispatch('click', {}); + assert.equal(gridRows(drawn).length, n); + assert.equal(drawn.byId['grid-more'].hidden, true); +}); + +test('the drawer opens on an item of the matrix, says why first, and closes with Escape', () => { + const data = local(); + const drawn = dom.page(data, undefined, { globals: { SENTIER_DIAGNOSTICS_MATRIX: full() } }); + const unlisted = full().items.map((r) => r[0]).find((id) => !data.items.some((i) => i.id === id)); + gridRows(drawn).find((tr) => tr.getAttribute('data-item') === unlisted).childNodes[0].dispatch('click', {}); + assert.equal(drawn.context.location.hash, 'item=' + unlisted); + drawn.open('item=' + unlisted); + assert.equal(drawn.byId.item.hidden, false); + assert.match(drawn.byId['item-meta'].textContent, /from the matrix: not listed in this file/); + assert.equal(drawn.byId['item-body'].childNodes[0].textContent, 'Why it differs'); + assert.equal(drawn.byId['item-title'].focused, true); + drawn.root.dispatch('keydown', { key: 'Escape' }); + assert.equal(drawn.byId.item.hidden, true); +}); + +test('why it differs: the item\'s own explanations, then those of a step or indicator it moved in, never a "none" over a part', () => { + const data = example(); + const drawn = dom.page(data); + for (const item of data.items) { + drawn.open('item=' + item.id); + const why = drawn.byId['item-body'].childNodes[1]; + const own = data.explanations.filter((e) => e.about.item === item.id).length; + const scopes = why.childNodes.map((li) => (li.childNodes[0].className === 'sd-scope' ? li.childNodes[0].textContent : 'none')); + assert.equal(scopes.filter((s) => s === 'This product').length, own, item.id); + assert.ok(scopes.indexOf('This product') <= 0 || scopes.slice(0, own).every((s) => s === 'This product'), item.id + ': its own first'); + if (scopes.includes('none')) assert.equal(why.childNodes.length, 1, item.id + ': "none" only where nothing is given'); + } +}); + +test('the page sets the title of a page of its own only, never a host\'s', () => { + assert.equal(dom.page(example()).document.title, ''); + assert.equal(dom.page(example(), undefined, { standalone: true }).document.title, example().title); +}); + +test('the data can come from a global, as a site\'s own data.js sets it', () => { + const drawn = dom.page(example(), { 'p01-fix-1.json': wheat() }, { globals: {} }); + assert.equal(drawn.byId.content.hidden, false); + assert.equal(drawn.byId.unchecked.hidden, true); +}); + +test('the page\'s own sentences say the file\'s word for an item', () => { + const data = example(); + data.item = { one: 'dataset', many: 'datasets' }; + const drawn = dom.page(data); + const words = drawn.root.querySelectorAll('[data-sd-word]'); + assert.ok(words.length >= 4); + const items = words.filter((span) => ['one', 'many'].includes(span.getAttribute('data-sd-word'))); + assert.ok(items.length >= 4); + for (const span of items) assert.equal(span.textContent, span.getAttribute('data-sd-word') === 'many' ? 'datasets' : 'dataset'); + assert.equal(drawn.byId['item-close'].getAttribute('aria-label'), 'Close the dataset'); + assert.ok(drawn.byId['grid-region'].getAttribute('aria-label').startsWith('After divided by before, per dataset and indicator: The whole way')); +}); + +test('the page says the file\'s word for an indicator, and "indicator" where it gives none', () => { + const plain = dom.page(example()); + const said = (drawn, value) => drawn.root.querySelectorAll('[data-sd-word]') + .filter((span) => span.getAttribute('data-sd-word') === value).map((span) => span.textContent); + assert.deepEqual([...new Set(said(plain, 'indicator'))], ['indicator']); + const data = example(); + data.indicator = { one: 'impact category', many: 'impact categories' }; + const drawn = dom.page(data); + assert.equal(drawn.byId.content.hidden, false); + assert.ok(said(drawn, 'indicator').length >= 3); + assert.deepEqual([...new Set(said(drawn, 'indicator'))], ['impact category']); + assert.deepEqual(said(drawn, 'Indicator'), ['Impact category']); + assert.ok(drawn.byId['grid-region'].getAttribute('aria-label').startsWith('After divided by before, per ' + data.item.one + ' and impact category: ')); + const text = drawn.text(); + assert.match(text, new RegExp(data.indicators.length + ' impact categories\\. ')); + assert.match(text, /One floor per impact category and reference unit/); + assert.doesNotMatch(text.replace(data.about, ''), /\bindicators?\b/i); +}); + +test('a page refuses an indicator word that is not {one, many}', () => { + const data = example(); + data.indicator = { one: 'impact category' }; + const drawn = dom.page(data); + assert.equal(drawn.byId.content.hidden, true); + assert.match(drawn.text(), /indicator word of the file is not \{one, many\}/); +}); + +test('steps count from 1 where the chain does not start from the published results', () => { + const published = example(); + assert.equal(published.states[0].kind, 'published'); + const first = dom.page(published); + assert.match(first.text(), /Step 0: /); + assert.equal(first.byId['steps-zero'].hidden, false); + const data = example(); + data.states[0].kind = 'build'; + const drawn = dom.page(data); + assert.equal(drawn.byId.content.hidden, false); + assert.equal(drawn.byId['steps-zero'].hidden, true); + const text = drawn.text(); + assert.doesNotMatch(text, /Step 0\b/); + data.steps.forEach((s, k) => assert.ok(text.includes('Step ' + (k + 1) + ': ' + s.label), s.label)); + const rows = drawn.byId['steps-table'].all().filter((n) => n.tagName === 'TR' && n.firstChild && n.firstChild.tagName === 'TD'); + assert.deepEqual(rows.map((row) => row.firstChild.textContent), data.steps.map((s, k) => String(k + 1))); + drawn.open('item=' + encodeURIComponent(data.items[0].id)); + const drawer = drawn.byId['item-body'].seen().join(' '); + assert.ok(drawer.includes('Step 1: ' + data.steps[0].label), drawer.slice(0, 200)); + assert.doesNotMatch(drawer, /Step 0\b/); +}); + + +// ------------------------------------------------------------------ reviewing one step + +const chips = (drawn) => drawn.byId.comparison.querySelectorAll('button[data-comp]'); + +test('choosing a step says its claim and what the claim found, under the chips, and the address keeps it', () => { + const data = example(); + const drawn = dom.page(data); + assert.match(drawn.byId['step-said'].textContent, /^The whole way: /); + const k = data.steps.findIndex((s) => s.claim && s.claim.scope.length); + const step = data.steps[k]; + chips(drawn)[k + 1].dispatch('click', {}); + const said = drawn.byId['step-said'].textContent; + assert.ok(said.includes(step.claim.text), said); + // what the claim found, from the file's own counts + const look = ['off claim', 'not claimed', 'claimed, not moved']; + const found = look.filter((v) => Object.values(data.counts.steps[step.id]).some((b) => b.verdicts[v])); + if (found.length) found.forEach((v) => assert.ok(said.includes(v), v)); + else assert.match(said, /as claimed/); + assert.equal(drawn.context.location.hash, 'step=' + encodeURIComponent(step.id)); + assert.equal(chips(drawn)[k + 1].getAttribute('aria-pressed'), 'true'); +}); + +test('the matrix shows first the indicators in which the chosen comparison moved most', () => { + const data = example(); + const drawn = dom.page(data); + const moves = ['differs', 'beyond 10x', 'zero reference', 'zero result', 'sign change']; + // what moved, and the missing values with it: missing is a finding, not stillness + const moved = (comp, id) => moves.concat(['missing']).reduce((m, c) => m + (comp === 'total' ? data.counts.total : data.counts.steps[comp])[id].classes[c], 0); + for (const comp of ['total'].concat(data.steps.map((s) => s.id))) { + drawn.byId.comparison.querySelectorAll('button[data-comp="' + comp + '"]')[0].dispatch('click', {}); + const heads = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]').slice(2); + const counts = heads.map((th) => moved(comp, data.indicators.find((i) => th.getAttribute('title').indexOf(i.name) === 0).id)); + for (let k = 1; k < counts.length; k++) assert.ok(counts[k - 1] >= counts[k], comp + ': ' + counts.join()); + heads.forEach((th, k) => assert.equal(/sd-still/.test(th.className), counts[k] === 0, comp)); + // the cells of a quiet column are quiet too + const row = gridRows(drawn)[0]; + const cells = row.childNodes.filter((n) => n.tagName === 'TD').slice(1); // after the group + cells.forEach((td, k) => assert.equal(/sd-still/.test(td.className), counts[k] === 0, comp + ' cell ' + k)); + } +}); + +test('an address with a step opens the page on that step, and with an item on that item', () => { + const data = example(); + const step = data.steps[2]; + const drawn = dom.page(data); + drawn.open('step=' + encodeURIComponent(step.id) + '&item=' + encodeURIComponent(data.items[0].id)); + assert.equal(chips(drawn).find((c) => c.getAttribute('aria-pressed') === 'true').getAttribute('data-comp'), step.id); + assert.equal(drawn.byId.item.hidden, false); + // closing the item keeps the step + drawn.byId['item-close'].dispatch('click', {}); + assert.equal(drawn.byId.item.hidden, true); + assert.equal(drawn.context.location.hash, 'step=' + encodeURIComponent(step.id)); + // an unknown step falls back to the whole way + drawn.open('step=nothing-of-the-kind'); + assert.equal(chips(drawn)[0].getAttribute('aria-pressed'), 'true'); +}); + +test('the arrow keys move between the chips', () => { + const data = example(); + const drawn = dom.page(data); + drawn.byId.comparison.dispatch('keydown', { key: 'ArrowRight' }); + assert.equal(chips(drawn)[1].getAttribute('aria-pressed'), 'true'); + drawn.byId.comparison.dispatch('keydown', { key: 'ArrowLeft' }); + assert.equal(chips(drawn)[0].getAttribute('aria-pressed'), 'true'); + drawn.byId.comparison.dispatch('keydown', { key: 'ArrowLeft' }); // nothing before the whole way + assert.equal(chips(drawn)[0].getAttribute('aria-pressed'), 'true'); +}); + +const cards = (drawn) => drawn.byId['dist-cards'].childNodes; + +test('a distribution card per indicator, in the order of the matrix, its bars the file\'s counts', () => { + const data = example(); + const drawn = dom.page(data); + for (const comp of ['total'].concat(data.steps.map((s) => s.id))) { + drawn.byId.comparison.querySelectorAll('button[data-comp="' + comp + '"]')[0].dispatch('click', {}); + const heads = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]').slice(2).map((th) => th.getAttribute('title')); + const ids = cards(drawn).map((card) => card.getAttribute('data-indicator')); + assert.equal(ids.length, data.indicators.length); + ids.forEach((id, k) => assert.ok(heads[k].indexOf(data.indicators.find((i) => i.id === id).name) === 0, comp + ' ' + k)); + for (const card of cards(drawn)) { + const block = (comp === 'total' ? data.counts.total : data.counts.steps[comp])[card.getAttribute('data-indicator')]; + const bars = card.childNodes[2].childNodes; + const sum = bars.reduce((s, bar) => s + Number(bar.getAttribute('title').match(/: ([\d,]+) of/)[1].replace(/,/g, '')), 0); + // every pair is in one bar: the bands split what moved and what agrees, the rest is a class + assert.equal(sum, block.pairs, comp + ' ' + card.getAttribute('data-indicator')); + } + } +}); + +test('a median of after ÷ before only from every item, never from the listed ones', () => { + const data = local(); + const listed = dom.page(data); + for (const card of cards(listed)) assert.doesNotMatch(card.textContent, /Median/); + assert.match(listed.byId['dist-said'].textContent, /need every product/); + const loaded = dom.page(data, undefined, { globals: { SENTIER_DIAGNOSTICS_MATRIX: full() } }); + const rows = page.matrixRows(full(), data); + const k = data.steps.length; // the whole way + const card = cards(loaded)[0]; + const id = card.getAttribute('data-indicator'); + const ratios = rows.filter((r) => ['agrees', 'within noise', 'differs', 'beyond 10x'].includes(r.classes[id][k])) + .map((r) => [r.values[id][0], r.values[id][r.values[id].length - 1]]) + .filter(([a, b]) => a && b && (a > 0) === (b > 0)).map(([a, b]) => b / a).sort((a, b) => a - b); + const x = 0.5 * (ratios.length - 1), lo = Math.floor(x), hi = Math.ceil(x); + const median = ratios[lo] + (ratios[hi] - ratios[lo]) * (x - lo); + assert.ok(ratios.length > 0); + const shown = Number(card.textContent.match(/Median of [\d ]+ ratios? ([\d.e−]+)/)[1].replace('−', '-')); + assert.ok(Math.abs(shown - median) <= 5e-3 * Math.abs(median), shown + ' vs ' + median); +}); + +test('percentiles share one precision: the fewest digits that keep apart the ones that differ', () => { + // a spread only the fifth digit shows + const text = page.quantileTexts({ p10: 0.99981, median: 1.0, p90: 1.00042 }); + assert.notEqual(text[0], text[2]); + assert.deepEqual(text, ['0.99981', '1.0000', '1.0004']); + // never mixed: a 10th percentile that reads as exactly 1 beside a six-digit median + assert.deepEqual(page.quantileTexts({ p10: 1.00004, median: 1.00005, p90: 1.00006 }), ['1.00004', '1.00005', '1.00006']); + assert.deepEqual(page.quantileTexts({ p10: 0.999, median: 1, p90: 1.0001 }), ['0.99900', '1.0000', '1.0001']); + assert.deepEqual(page.quantileTexts({ p10: 0.5, median: 1, p90: 2 }), ['0.500', '1.00', '2.00']); + assert.deepEqual(page.quantileTexts({ p10: 1, median: 1, p90: 1 }), ['1.00', '1.00', '1.00']); +}); + +test('a card sorts the matrix by its indicator, and a heading marks its card', () => { + const data = example(); + const drawn = dom.page(data); + const card = cards(drawn)[1]; + const id = card.getAttribute('data-indicator'); + card.childNodes[0].childNodes[0].dispatch('click', {}); + const sorted = drawn.byId['grid-table'].querySelectorAll('th[aria-sort]'); + assert.equal(sorted.length, 1); + assert.ok(sorted[0].getAttribute('title').indexOf(data.indicators.find((i) => i.id === id).name) === 0); + assert.equal(cards(drawn)[1].childNodes[0].childNodes[0].getAttribute('aria-pressed'), 'true'); + assert.match(cards(drawn)[1].className, /sd-chosen/); + // the heading of another indicator moves the mark to its card + const other = cards(drawn)[0].getAttribute('data-indicator'); + const head = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]').slice(2) + .find((th) => th.getAttribute('title').indexOf(data.indicators.find((i) => i.id === other).name) === 0); + head.childNodes[0].dispatch('click', {}); + assert.equal(cards(drawn)[0].childNodes[0].childNodes[0].getAttribute('aria-pressed'), 'true'); + assert.equal(cards(drawn)[1].childNodes[0].childNodes[0].getAttribute('aria-pressed'), 'false'); +}); + +test('the bars of every card can be put on one scale, the share of all values (A21)', () => { + const data = example(); + const drawn = dom.page(data); + const heights = () => cards(drawn).map((card) => card.childNodes[2].childNodes.map((bar) => parseFloat(/height:([\d.]+)%/.exec(bar.getAttribute('style'))[1]))); + // each card to its own tallest bar: every card that has values reaches the top + heights().forEach((h) => assert.equal(Math.max(...h), 100)); + const select = drawn.byId['dist-scale']; + select.value = 'one'; + select.dispatch('change', { target: select }); + const one = heights(); + assert.equal(Math.max(...one.flat()), 100); + // on one scale, a bar's height is its share of the values of its card, the same factor in every card + const shares = cards(drawn).map((card, i) => { + const block = data.counts.total[card.getAttribute('data-indicator')]; + // a bar is at least 2% high, so that one value is seen: those are left out + return card.childNodes[2].childNodes.map((bar, j) => { + const n = Number(bar.getAttribute('title').match(/: ([\d,]+) of/)[1].replace(/,/g, '')); + return n && one[i][j] > 2 ? one[i][j] / (n / block.pairs) : null; + }).filter((x) => x !== null); + }).flat(); + for (const f of shares) assert.ok(Math.abs(f - shares[0]) < 0.06 * shares[0], f + ' vs ' + shares[0]); + assert.match(drawn.byId['dist-said'].textContent, /one scale/); +}); + +test('the claim line names every verdict on a move, "as claimed" first, in words and without colour', () => { + const data = example(); + const drawn = dom.page(data); + const k = data.steps.findIndex((s) => s.claim && s.claim.scope.length); + const step = data.steps[k]; + chips(drawn)[k + 1].dispatch('click', {}); + const said = drawn.byId['step-said'].textContent; + const total = (v) => Object.values(data.counts.steps[step.id]).reduce((a, b) => a + b.verdicts[v], 0); + for (const v of ['as claimed', 'off claim', 'not claimed', 'claimed, not moved']) { + const word = v === 'as claimed' ? 'moved as claimed' : v; + if (total(v)) assert.ok(said.includes(total(v) + ' value' + (total(v) === 1 ? '' : 's') + ' ' + word), v + ': ' + said); + else assert.ok(!said.includes(word), v); + } + if (total('as claimed')) assert.ok(said.indexOf('moved as claimed') < Math.max(said.indexOf('off claim'), said.indexOf('not claimed')) || !/off claim|not claimed/.test(said)); + assert.doesNotMatch(said, /moves as claimed/); + const all = drawn.byId['step-said'].all(); + assert.ok(!all.some((node) => /sd-good|sd-look/.test(node.className || ''))); +}); + +test('a column whose only change is a missing value is not quietened as if nothing moved', () => { + const data = example(); + const step = data.steps[0].id; + const id = data.indicators[data.indicators.length - 1].id; + const block = data.counts.steps[step][id]; + // nothing moved in this indicator, two values went missing + for (const c of ['differs', 'beyond 10x', 'zero reference', 'zero result', 'sign change']) block.classes[c] = 0; + block.classes.missing = 2; + const drawn = dom.page(data); + drawn.byId.comparison.querySelectorAll('button[data-comp="' + step + '"]')[0].dispatch('click', {}); + const name = data.indicators.find((i) => i.id === id).name; + const head = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]').slice(2).find((th) => th.getAttribute('title').indexOf(name) === 0); + assert.doesNotMatch(head.className, /sd-still/); + assert.match(head.getAttribute('title'), /2 missing/); + const card = cards(drawn).find((c) => c.getAttribute('data-indicator') === id); + assert.doesNotMatch(card.className, /sd-still/); +}); + +test('two percentiles that six digits cannot part are said to lie just under or over the median', () => { + const t = page.quantileTexts({ p10: 1 - 1e-9, median: 1, p90: 5.94545 }); + assert.equal(t[0], 'just under the median'); + assert.notEqual(t[2], t[1]); + assert.equal(t[2], '5.95'); // the pair (median, 90th) never blurred + assert.equal(t[1], '1.00'); // the words took the place of the six digits: the rest go back to three + // only the pair that blurs is widened: 5.94545 needs no six digits beside 1 + assert.equal(page.quantileTexts({ p10: 0.5, median: 1, p90: 1 + 1e-9 })[0], '0.500'); + assert.equal(page.quantileTexts({ p10: 0.5, median: 1, p90: 1 + 1e-9 })[2], 'just over the median'); +}); + +test('a card says over how many ratios its median is, how many have none, and what full height is', () => { + const data = local(); + const loaded = dom.page(data, undefined, { globals: { SENTIER_DIAGNOSTICS_MATRIX: full() } }); + for (const card of cards(loaded)) { + const text = card.textContent; + const block = data.counts.total[card.getAttribute('data-indicator')]; + const m = text.match(/Median of ([\d ]+) ratios?/); + if (!m) { assert.match(text, /No value with a ratio/); continue; } + const n = Number(m[1].replace(/ /g, '')); + const left = block.pairs - n; + if (left) assert.ok(text.includes(left + ' without a ratio'), text); + else assert.doesNotMatch(text, /without a ratio/); + assert.match(card.childNodes[1].textContent, /^tallest bar: \d/); + } +}); diff --git a/tests/test_matrix_page.py b/tests/test_matrix_page.py new file mode 100644 index 0000000..bc59985 --- /dev/null +++ b/tests/test_matrix_page.py @@ -0,0 +1,357 @@ +"""The full matrix of a local file, and the page as a frameless body a site holds.""" + +from __future__ import annotations + +import contextlib +import io +import json +import re +import tempfile +import unittest +from html.parser import HTMLParser +from pathlib import Path + +from sentier_diagnostics import chain, cli, example, fileformat, from_tables, matrix, page + +from . import helpers + + +def local(): + return example.build_local() + + +class Matrix(unittest.TestCase): + def test_the_local_example_and_its_matrix_agree(self): + data, full = local() + self.assertEqual(fileformat.errors(data), []) + self.assertEqual(matrix.errors(full), []) + self.assertEqual(matrix.against(full, data), []) + self.assertEqual(data["matrix"], {"file": "matrix.json", "items": 10}) + self.assertEqual(len(data["items"]), 6) + + def test_the_matrix_is_ordered_as_the_listed_items_are(self): + data, full = local() + self.assertEqual( + [r[0] for r in full["items"]][: len(data["items"])], [i["id"] for i in data["items"]] + ) + + def test_a_matrix_survives_its_own_text(self): + _, full = local() + self.assertEqual(json.loads(matrix.dumps(full)), full) + + def test_every_changed_code_is_found(self): + data, full = local() + cases = { + "a class code": lambda m: m["classes"].__setitem__(0, ("=" if m["classes"][0][0] != "=" else "D") + m["classes"][0][1:]), + "a direction": lambda m: m["classes"].__setitem__(0, m["classes"][0].swapcase()), + "a result": lambda m: m["values"][7].__setitem__(0, (m["values"][7][0] or 1.0) * 3), + "a verdict": lambda m: m["verdicts"].__setitem__( + 6, "".join("o" if c == "a" else "a" if c == "o" else c for c in m["verdicts"][6])), + "a name of a listed item": lambda m: m["items"][0].__setitem__(1, "Another name"), + "one item fewer": lambda m: [m[k].pop() for k in ("items", "values", "classes", "verdicts")], + "the title": lambda m: m["of"].__setitem__("title", "Another"), + } # fmt: skip + for name, change in cases.items(): + with self.subTest(name): + changed = helpers.mutated(full, change) + self.assertNotEqual(changed, full) + found = matrix.errors(changed) or matrix.against(changed, data) + self.assertNotEqual(found, [], name) + + def test_counts_that_are_not_the_matrix_are_found(self): + data, full = local() + cases = { + "a count": lambda d: d["counts"]["total"]["x:climate"]["classes"].__setitem__( + "agrees", d["counts"]["total"]["x:climate"]["classes"]["agrees"] + 1), + "the attribution": lambda d: d["attribution"]["x:climate"].__setitem__( + "spread", d["attribution"]["x:climate"]["spread"] + 1), + "the items worth a look": lambda d: d["items_count"].__setitem__("qualifying", d["items_count"]["qualifying"] - 1), + "the items of the matrix": lambda d: d["matrix"].__setitem__("items", 11), + } # fmt: skip + for name, change in cases.items(): + with self.subTest(name): + self.assertNotEqual(matrix.against(full, helpers.mutated(data, change)), [], name) + + def test_shape_faults_never_raise(self): + _, full = local() + for bad in (None, [], {"format": "sentier-diagnostics-matrix/2"}, {**full, "extra": 1}, + {**full, "items": [[1, 2, 3, 4, 5]]}, {**full, "classes": ["?" * 15] * 10}): # fmt: skip + with self.subTest(repr(bad)[:60]): + self.assertNotEqual(matrix.errors(bad), []) + + def test_a_matrix_is_written_and_read_back_checked(self): + data, full = local() + with tempfile.TemporaryDirectory() as folder: + where = matrix.write(full, Path(folder) / "matrix.json") + self.assertEqual(matrix.read(where, data), full) + other = helpers.mutated(data, lambda d: d.update(title="Another")) + with self.assertRaises(ValueError): + matrix.read(where, other) + + +class NamesAMatrix(unittest.TestCase): + """The key `matrix` of a diagnostics file (SPEC 4.2).""" + + def test_only_a_local_file_of_items_names_a_matrix(self): + data, _ = local() + public = helpers.mutated(data, lambda d: d.update(audience="public")) + self.assertTrue(any("only a local file" in e for e in fileformat.errors(public))) + + def test_the_matrix_holds_every_item(self): + data, _ = local() + wrong = helpers.mutated(data, lambda d: d["matrix"].update(items=9)) + self.assertNotEqual(fileformat.errors(wrong), []) + + def test_a_matrix_is_named_by_a_plain_file_name(self): + data, _ = local() + for name in ("../matrix.json", "matrix.js", "/abs.json", "a b.json"): + with self.subTest(name): + self.assertNotEqual( + fileformat.errors(helpers.mutated(data, lambda d: d["matrix"].update(file=name))), [] + ) + + def test_no_matrix_is_no_key_or_null(self): + data, _ = local() + self.assertEqual(fileformat.errors(helpers.mutated(data, lambda d: d.update(matrix=None))), []) + self.assertEqual(fileformat.errors(helpers.mutated(data, lambda d: d.pop("matrix"))), []) + + def test_a_public_file_is_never_built_with_a_matrix(self): + with self.assertRaises(ValueError): + example._made(chain.build_with_matrix, audience="public") + + +class Elements(HTMLParser): + """Every start tag of a fragment, with its attributes.""" + + def __init__(self): + super().__init__() + self.tags = [] + + def handle_starttag(self, tag, attrs): + self.tags.append((tag, dict(attrs))) + + +def tags_of(text: str) -> list[tuple[str, dict]]: + parser = Elements() + parser.feed(text) + return parser.tags + + +class Body(unittest.TestCase): + def test_one_root_and_no_frame_no_id(self): + text = page.body(example.build(), breakdowns={"p01-fix-1.json": example.wheat_breakdown()}) + tags = tags_of(text) + self.assertEqual(tags[0][0], "div") + self.assertEqual(tags[0][1].get("class"), "sentier-diagnostics") + self.assertIn("data-sentier-diagnostics", tags[0][1]) + self.assertEqual([t for t, a in tags if "data-sentier-diagnostics" in a], ["div"]) + self.assertFalse({"html", "head", "body", "main", "link", "style", "h1"} & {t for t, _ in tags}) + self.assertFalse([t for t, a in tags if "id" in a], "no id a host's page could hold twice") + self.assertTrue(text.rstrip().endswith("
    ")) + + def test_the_data_inside_is_the_file_and_cannot_end_its_element(self): + data = helpers.mutated(example.build(), lambda d: d.update(about="