diff --git a/CHANGELOG.md b/CHANGELOG.md index 841f926..cbb9893 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,12 @@ entry per wave, newest first; the first six waves (V1–V6, the MVP) predate the are recorded in PLAN.md §B and §J. Each entry carries the opening sentence of its row and the reason the wave was built. +## V66 — The glass box: one row, replayed through the model + +The third and last part of F8. + +_Why:_ Approved 13/11/2026. A learner who trains here should be able to carry the run to a notebook and see, in figures, what changed on the way. + ## V65 — An unlabelled file becomes a submission The second part of F8; the glass box stays proposed below. diff --git a/PLAN.md b/PLAN.md index fb35569..87eea96 100644 --- a/PLAN.md +++ b/PLAN.md @@ -680,7 +680,7 @@ defect that produces a wrong number comes first), then extends the lab past the export: uncertainty with a guarantee, governance, and monitoring after deployment, with nothing added on a server. -V53 to V65 are delivered. Every other row is a proposal with its launch +V53 to V66 are delivered. Every other row is a proposal with its launch condition, and none starts without an explicit launch command. | Wave | Content | Why | @@ -699,14 +699,15 @@ condition, and none starts without an explicit launch command. | **V63 — delivered** | **A data contract.** Listed as F5 below until it shipped. The quality report asks whether a file looks clean; a contract asks whether it is still the file that was agreed on. The proposal read « export the validity rules, the consistency rules and the profile as one contract »; reading the code showed what that sentence hid. The seven rules are not declarations: each decides whether it applies, from the column's name and from at least 80 % of its values being plausible (V40), which is right for an unknown file, where a column named `age` holding 20 000 is a duration. **The wave opened by measuring the price of that guard.** One column of a demo degraded by steps of impossible values: at 5, 10 and 15 % the rule flags every one of them; **at 20 % it stops applying and the report says nothing**, and nothing again at 25, 30 and 50 %. On titanic, 134 ages of 999 are reported and 178 are not; the same holds for negative quantities and prices on cafe-sales. Only the future-date rule, which has no plausibility guard, keeps speaking. A file that gets much worse goes quiet. **So a contract freezes what was found on a reference** (the columns, how much is missing, which rules applied and how often they failed, the bins and shares of each distribution) **and requires it of the next file, clause by clause**, applying each rule without its guard. Five kinds of clause, three outcomes: kept, warning, broken. Two rules: a fact is not an estimate, and moving is not breaking. **The second measurement refused two parts of the first design**, on a contract drawn from one half of a file and checked on the other half, where nothing changed (Fisher-Yates, no replacement, 200 checks per file). **(1) « A type that changed is a fact » was wrong.** On cafe-sales 84.5 % of checks came back broken, 157 of them on the type clause: `notes` was categorical in one half and text in the other in 100 checks of 200, `order_id` a number or an identifier in 57. The type the lab infers rests on how many distinct values a file happens to hold. What does not waver is how values read, as numbers, dates or words, and the clause now tests that; the inferred type stays in the contract for the reader. **(2) The missing-values clause broke 6 % of titanic's checks**, each column being tested alone at 95 %; the estimates of one check now share one level, as the drift report does. Measured again: no broken clause on fraud, mpg and energy, 2 % on titanic, drift warnings on 0.5 to 7.5 % of checks. On cafe-sales 53.5 % stay broken, and rightly: the file holds one negative price, and the half without it yields a contract the other half breaks. **How a clause is decided.** A column that is gone, values that no longer read as numbers, an impossible value: broken, with no threshold. A rule clean at the reference is broken by its first failure; a rule that already failed there, only by a measurably higher rate (Newcombe's interval). A share of missing values is broken only when measurably higher, never when lower. A distribution above its noise ceiling (V62) is a warning: the data moved without becoming invalid. A rule that finds nothing it can read warns and claims no failure. A column the contract does not describe is noted. **What is built.** `validity.ts` and `consistency.ts` now separate each rule's predicate (`applyRule`, `applyConsistency`) from its guard (`applicableRules`, `applicableConsistency`); `checkColumn` and `checkConsistency` are those two composed, and their tests pass unchanged. `data/quality/contract.ts`, pure: `buildContract`, `parseContract`, `checkContract`. The contract holds names, bounds, shares and counts, never a row. A file that is not a whole contract is refused and nothing is checked: a clause silently dropped would be a check silently skipped. A panel in the Data Studio exports the contract of the loaded file and reads the loaded file against one; the clauses that did not hold are spelled out by family, broken first, with counts and the first failing rows, and the ones that held are counted. **What this wave deliberately does not do**: let the user write rules (custom bounds and expressions are a language of their own); check a contract from the ML Lab's scoring panel, the model export keeping its own reference (V61); block, repair or version anything. 1204 unit tests, 130 e2e. | Approved 13/11/2026. The fourth wave in a row whose design was corrected by its own measurement before a line of the feature shipped. | | **V64 — delivered** | **A run, redone in Python.** The first of the three parts of F8, the two others staying proposed below. A run stayed inside the browser: its model, its predictions, its report and its card export, the training itself did not. This writes a scikit-learn script that redoes it. **What the code said before anything was written**: the lab's estimators are written by hand or come from ml.js, and `tests/golden/README.md` has held since V42 that requiring the same numbers of a tree, a forest, a boosting or a network « would be a false contract ». So the script could not promise the lab's figures, and the design starts there: carry exactly what can be carried, translate the rest, and print both figures with the gap. **Carried exactly**: the row numbers of the three splits (not a seed that should redo them), and the preprocessing, one transformer per column in the lab's order. **Translated**: each family to its nearest estimator with the lab's settings, labelled on every line it prints. **Measured, six demos and five seeds each, with scikit-learn 1.9.1, and the first run found three faults in the translation.** (1) A numeric column with missing values was encoded differently (0.36 on titanic's `age`): the lab standardizes on the values that are there and then imputes the median, the script did it the other way round and computed the mean on imputed cells. (2) The network, on a regression, gave an RMSE of 219 against the lab's 18 on energy: the lab's network learns a standardized target and converts back, and the script now wraps its estimator the same way. (3) k-NN was labelled « same algorithm » and moved by 0.39 on energy, a file with one feature column: two neighbours at the same distance are not chosen the same way by the two libraries. It has a label of its own. **After the fixes, on the 30 runs**: the matrix the script encodes from the training rows equals the lab's to within **2.9e-14**, free text included. The baseline, the linear regression and the Gaussian naive Bayes give the same test metric on every run. k-NN gives the same on four demos out of six, and differs on titanic (one row of 178 at worst) and energy (up to 1.32 of RMSE). The translated families differ by ±0.06 of accuracy on average at most and by up to 0.15 on one split, which on reviews' 48 test rows is seven rows; the lab's tree is 4.7 points better than scikit-learn's on titanic on average, its network 6 points better on iris. The whole record is committed (`tests/golden/python-bridge.md`) with the two commands that regenerate it, outside CI like the other references. **A column name is never code.** The run travels as one JSON block read by `json.loads`; the rest of the script is the same text for every run. Every apostrophe of the block is written as its JSON escape, so nothing can close the string that holds it; a test gives a column the name of a shell command and checks that Python reads the name and runs none of it. **The script is run in the suite.** `python3 -m py_compile`, then `--check`, a mode that reads the run with the standard library alone: a script that does not compile fails the tests, in CI too. It refuses a file with another number of rows or columns, since its row numbers would point at other rows. **What this wave deliberately does not do**: promise the lab's figures beyond the families where they were measured equal; export a notebook, an environment file or a project; redo the ensemble (named as not redone), the hyperparameter search, the learning curve, the group audit or the production check; read a spreadsheet, which it asks to be saved as CSV. 1224 unit tests, 131 e2e. | Approved 13/11/2026. A learner who trains here should be able to carry the run to a notebook and see, in figures, what changed on the way. | | **V65 — delivered** | **An unlabelled file becomes a submission.** The second part of F8; the glass box stays proposed below. Scoring a batch gave back every original column plus the prediction, the right file to join back into a system and the wrong one for a platform that expects two columns under its own names. Under a scored batch, a block now writes an identifier and a prediction. **What the code said before anything was written**: the lab fits on 64 % of the labelled rows and keeps 16 % to choose and 20 % to measure, and the usage in a competition is to fit again on everything before predicting. That was the real question of the wave, so it was measured first. **Measured, six demos, ten splits each, a quarter of the rows kept away from both models, every family**: the same family fitted on all the remaining rows instead of 64 % of them gained **+5.0 accuracy points on reviews** (180 rows; better 51 times of 70, worse 11), **3 % of RMSE on mpg** (47 of 60, worse 13), **2 % on energy** (44 of 60, worse 16), **+0.8 point on titanic** (41 of 70, worse 20), and **nothing on fraud** (-0.04 point; better 21, worse 25) **nor on iris** (-0.1 point; better 14, worse 17). The plan expected « a small and variable gain, clearer on small files ». The second half was wrong: iris is the smallest demo and gains nothing, because 72 rows already say all there is to say. The gain follows the learning curve, not the size, and the panel now says so and points at the curve (V26). Even where the refit pays it loses one time in five to one in three, so it is **offered and never the default**, and the result line names the model that predicted: the measured one, or its sibling « nobody measured ». A refit costs 18 ms to 3.6 s per family on the demos, done on demand. **The lab guesses nothing.** The user picks the identifier column (or asks for the rows to be numbered from 1), types the two names, and chooses what a prediction is: the class by name, the probability of the second class (binary), one probability per class (three classes or more), or the value (regression). A form with no object for the task is not offered. A column the training file read as an identifier is pointed at when there is exactly one, and not chosen. **No row lost or reordered.** The file has the rows of the scored file in their order; an identifier missing or repeated is written and counted, since a platform would refuse it. The end-to-end test scores a file whose identifiers are out of order and checks the order survives. **A submission is not a score**: the block says the lab knows neither the platform's metric nor its private rows, and that a public leaderboard wears like a test set (V60), each compared submission being a choice made with it. **Defects of this wave's own making, caught before the push**: (1) the refit was first sent the configuration held by the page; the worker now keeps the one its artifacts were trained with, so a refit can never repeat another run; (2) the blend has no entry in the model zoo, so asking to refit it raised an internal error: the option is disabled for it with the reason (its members are picked on validation rows); (3) on a phone the three fields pushed the whole page sideways, caught on the screenshot review: they now shrink with their column; (4) the first end-to-end run passed nothing because it ran against the previous build. **What this wave deliberately does not do**: send anything to a platform or know its rules; promise a score or a rank; measure the refitted model, which has no test set left; refit a blend, or build a submission from a re-imported model, which has no training rows; apply the decision threshold or the multiclass policy to the label written (it is the raw prediction, as in the scored CSV); blend several models into one submission. The glass box, last part of F8. 1251 unit tests, 132 e2e. | Approved 13/11/2026. A learner who trains here should be able to carry the run to a notebook and see, in figures, what changed on the way. | +| **V66 — delivered** | **The glass box: one row, replayed through the model.** The third and last part of F8. For a row typed in the what-if panel the lab gave a prediction and a Shapley explanation (V28), what weighed. It did not show what happened. A replay now tells it for four families: the questions a decision tree asked and the training rows that share its leaf, the count of a forest's trees, the five rows a k-NN compared the row to, the prediction a boosting builds round after round. **What the code said before anything was written**: F8 spoke of « hand-written » models, and the tree and the forest come from ml-cart and ml-random-forest. A replay stays possible by walking their exported JSON, which is also what a model rebuilt from a helper core holds (V37). No family kept what a replay needs: the boosting only summed all its trees, the k-NN search dropped the index of its neighbours, the tree exposed no path. **One rule: the replay is the model.** Nothing is approximated, and the last step of a replay must equal `predict`. **Measured before the panel, six demos, five seeds, 2,560 test rows**: zero mismatch for the tree, the k-NN and the boosting, in binary, multiclass and regression. **The forest failed on three rows of titanic**: on a 20 to 20 vote the replay kept the smallest class, and the library keeps the first class to reach the top count, in the order of its trees. The replay does the same now, flags a tied vote, and the forest, which the plan kept only « if its count is exact », is in. **Questions in the units of the file.** A threshold on a standardized number is given its unit back, a 0/1 column becomes « is it this category? ». Measured on the tree's paths: every question translates on five demos, and 6 of 1,878 on reviews, whose columns are free text: there a question is the weight of a word, shown as the model sees it. A path is 1.9 questions long on fraud and 8 on energy on average, 10 at most. **Two findings the replay made visible.** (1) **k-NN ties**: the next row is exactly as far as the last neighbour kept on 17 % of titanic's test rows and 39 % of energy's, 0 to 1 % elsewhere. V64 had met this from the outside, as a gap with scikit-learn; the panel flags it on the row concerned. (2) **The boosting's last rounds**: read on the validation rows, the error was lowest well before round 120 (more than 2 % under the final error) on 17 runs of 30. On titanic the lowest log loss came at rounds 21 to 25 on three seeds (0.43 against 0.45 to 0.48 at the end); on reviews at round 11 on one seed (0.67 against 0.79, worse than the 0.69 it started from); on energy the boosting never beat its starting point on three seeds of five. The lab runs its rounds to the end and has no early stopping. The panel shows the curve, on validation and never on the test set, and sets nothing; the fix is proposed as F9 below, to be measured on its own. **Defects of this wave's own making, caught before the push**: (1) the forest's tie, above; (2) ml-random-forest nests its parameters under `baseModel`, which the first replay did not read; (3) the three rounds told for the boosting were always rounds 1, 2 and 3, the same tree three times, seen on the screenshot review: the rounds told are now the largest movers among those asking different questions, each with the count of other rounds that asked the same. **What this wave deliberately does not do**: replay how a model was trained; replay a network, a linear model or a blend (the panel says why for each), or a forest tree by tree; stop the boosting early or change any setting from what is seen; replay a re-imported model, which carries no training rows; draw a whole tree. A replay is shown and saved nowhere: it is absent from the saved run and from the share link. A trace is not a cause, and the panel says so. F8 is complete. 1294 unit tests, 133 e2e. | Approved 13/11/2026. A learner who trains here should be able to carry the run to a notebook and see, in figures, what changed on the way. | Proposed features, ranked by value over effort. Each reuses a module that exists; none is scheduled. -| Feature | Content | Reuses | -| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -| F7 | **Counterfactuals.** The smallest change that flips a decision: a deterministic search, columns declared immutable, values kept inside observed ranges, a named refusal when nothing plausible exists. | `insights.ts`, `shapley.ts`, `score.ts` | -| F8 | **Glass box.** One part remains of the three first listed here; the bridge to Python shipped as V64 and the competition path as V65. Replay a hand-written model step by step on the user's data (boosting rounds, tree splits, neighbours). | `gbdt.ts`, `models.ts` | +| Feature | Content | Reuses | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| F7 | **Counterfactuals.** The smallest change that flips a decision: a deterministic search, columns declared immutable, values kept inside observed ranges, a named refusal when nothing plausible exists. | `insights.ts`, `shapley.ts`, `score.ts` | +| F9 | **Early stopping for the boosting, measured first.** V66 showed that on 17 runs of 30 the validation error of the boosting was lowest well before its 120th round, and that on energy it never beat its starting point on three splits of five. Stop at the best validation round, or keep 120: to decide on rows kept away from the choice, as V65 did for the refit, since the validation rows already pick the family. | `gbdt.ts`, `glass-box.ts` (`stagedValidation`) | Not proposed, because the project already refused them: an AutoML mode, a tenth model family, model-based imputation, tabular deep learning, telemetry. diff --git a/README.md b/README.md index 4010a0b..6a13697 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,7 @@ The project follows three non-negotiable principles: | MLOps loop | Score a **new batch** with honest test-vs-batch metrics; **compare two runs** side by side with cross-run uncertainty verdicts, or **up to six at once** read against the oldest of the selection; **export a model as JSON and re-import it later** — the exact predictor is rebuilt (byte-identical predictions) and scores any CSV without retraining | | Python bridge | **A run, redone with scikit-learn.** One readable script carries the row numbers of each split and the preprocessing, and translates each model to its nearest estimator. It does not promise the lab's figures: it prints them next to its own, with the gap. Measured on 30 runs: the encoded matrix is equal to within 2.9e-14, the baseline, the linear regression and the naive Bayes agree to the last digit, k-NN agrees until two neighbours tie, and the hand-written families differ by up to several test rows on one split. A column name is never code: the run travels as one JSON block. | | Competition path | **An unlabelled file becomes a submission.** Under a scored batch, one block writes an identifier and a prediction under the names the platform expects: a class, a probability or a value, every row kept in its order, missing and repeated identifiers counted. The lab guesses neither the identifier nor the names. The same family can be **fitted again on every labelled row**, announced as a model nobody measured: on the demos, against rows kept away from both models, it gained 5 accuracy points on the smallest text file, 0.8 on titanic, 2 to 3 % of RMSE on two regressions, nothing on two others, and lost one time in five to one in three even where it paid | +| Glass box | **One row, replayed through the model.** Beside the Shapley explanation (what weighed), a replay tells what happened: the questions a decision tree asked, in the units of the file, and the training rows that share its leaf; the count of a forest's 40 trees; the five rows of the file a k-NN compared it to, with its ties flagged; the prediction a boosting builds round after round, and its error on the validation rows. The replay walks the model itself: measured on 2,560 test rows of the demos, its last step is the model's answer on every one | | Speed | Heavy families train on **helper cores** (announced on the leaderboard, split by measured cost, never silent), and a model crosses back as JSON so it is rebuilt through the same path an imported model uses. Measured on a 60 000-row run: **74 s → 9.5 s**, with every leaderboard number identical. Every best-effort step that gives up is recorded in a **run journal** shown with the leaderboard and in the report: which step, which family, how many times, and the error it met | | Persistence | Local run history with attached artifacts, opted-in dataset storage (compressed, explicit 50 MB budget), self-contained HTML reports, data-free share links (a damaged link is refused, never half-rendered) | | Model card | A page for whoever must **decide to use** the model, in HTML or Markdown: intended use, data, performance with its interval, the selection gap, prediction-set coverage, the decision rule, where it fails, the run journal, and limits. The intended use is typed by the user; left empty the card says « not stated » and calls itself incomplete rather than guessing. Every analysis the run does not carry is listed under « Not assessed », and each section names the model it describes when that is not the winner | @@ -281,12 +282,12 @@ Wikimedia Commons), the portrait is NASA, public domain._ so), slow model families train on measured, announced caps scored against the same full test set, and parsing refuses past a named 20M-cell memory budget instead of letting the tab die, in every section and for a batch to score. -- **Performance.** Every page — the sections, the home page and each of the thirteen +- **Performance.** Every page — the sections, the home page and each of the fourteen documentation URLs — serves a prerendered static shell (hero paints before JavaScript; a doc page carries its whole article, in English until the app mounts); Lighthouse mobile ≈ 0.99 on `/ml` under real throttling. Heavy dependencies (Dexie, SheetJS, ONNX Runtime) load lazily. -- **Quality bar.** 1251 unit tests and 132 Playwright end-to-end tests across five +- **Quality bar.** 1294 unit tests and 133 Playwright end-to-end tests across five projects — desktop, a phone viewport in English and in French, dark mode, and Cloudflare Pages' own routing emulated by `wrangler pages dev` (a real 404, the security headers as served) — covering offline PWA, a fake webcam, a horizontal-overflow guard on diff --git a/e2e/glass-box.spec.ts b/e2e/glass-box.spec.ts new file mode 100644 index 0000000..f31badd --- /dev/null +++ b/e2e/glass-box.spec.ts @@ -0,0 +1,69 @@ +import { expect, test, type Page } from '@playwright/test'; + +test.use({ locale: 'en-US' }); +test.setTimeout(120_000); + +/** Inspects one family and replays the default what-if row through it. */ +async function replay(page: Page, family: RegExp) { + await page.getByRole('cell', { name: family }).click(); + const prediction = page.getByTestId('what-if-prediction'); + await expect(prediction).toBeVisible({ timeout: 30000 }); + await page.getByTestId('replay-button').click(); + const box = page.getByTestId('glass-box'); + await expect(box).toBeVisible({ timeout: 30000 }); + return { box, predicted: (await prediction.textContent())!.trim() }; +} + +// NOTE: keep this title ASCII-only: it names the test-results directory. +test('glass box: each family replays a row to the prediction shown', async ({ page }) => { + await page.goto('/ml?demo=iris&target=species'); + await page.getByTestId('train-button').click(); + await expect(page.getByTestId('train-again')).toBeVisible({ timeout: 60000 }); + + // The tree: questions in the units of the file, down to a leaf. + const tree = await replay(page, /Decision tree/); + await expect(tree.box).toHaveAttribute('data-kind', 'tree'); + await expect(tree.box.locator('ol li').first()).toContainText( + /(petal|sepal)_(length|width) < [\d.]+\? (yes|no)/, + ); + await expect(tree.box.getByTestId('glass-answer')).toContainText( + `The tree answers ${tree.predicted}.`, + ); + await expect(tree.box.getByTestId('glass-answer')).toContainText( + 'training rows end in the same leaf', + ); + + // k-NN: five rows of the file, and their vote. + const knn = await replay(page, /k-nearest neighbors/i); + await expect(knn.box).toHaveAttribute('data-kind', 'knn'); + await expect(knn.box.getByTestId('glass-neighbours').locator('tbody tr')).toHaveCount(5); + await expect(knn.box.getByTestId('glass-answer')).toContainText( + `The model answers ${knn.predicted}.`, + ); + + // The forest: a count of its trees. + const forest = await replay(page, /Random forest/); + await expect(forest.box.getByTestId('glass-answer')).toContainText(`40 trees voted`); + await expect(forest.box.getByTestId('glass-answer')).toContainText( + `The forest answers ${forest.predicted}.`, + ); + + // The boosting: a curve that ends on the class predicted, and the validation rows. + const boosting = await replay(page, /Gradient boosting/i); + await expect(boosting.box.getByTestId('glass-answer')).toContainText( + `the share of "${boosting.predicted}" the model begins with`, + ); + await expect(boosting.box.getByTestId('glass-validation')).toContainText('validation rows'); + + // A new row empties the replay, like the explanation: it described another row. + await page.getByTestId('what-if').locator('input[type="number"]').first().fill('7.7'); + await expect(page.getByTestId('glass-box')).toHaveCount(0); + await expect(page.getByTestId('replay-button')).toBeVisible(); + + // A family with no steps says so instead of offering a replay. + await page.getByRole('cell', { name: /Logistic regression/ }).click(); + await expect(page.getByTestId('glass-none')).toContainText('one weighted sum', { + timeout: 30000, + }); + await expect(page.getByTestId('replay-button')).toHaveCount(0); +}); diff --git a/package-lock.json b/package-lock.json index 1a22052..486cc62 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "labml", - "version": "1.65.0", + "version": "1.66.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "labml", - "version": "1.65.0", + "version": "1.66.0", "license": "MIT", "dependencies": { "@duckdb/duckdb-wasm": "1.28.0", diff --git a/package.json b/package.json index 8a10ad6..153c874 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "labml", "private": true, - "version": "1.65.0", + "version": "1.66.0", "license": "MIT", "type": "module", "engines": { diff --git a/src/content/docs/en/limits.md b/src/content/docs/en/limits.md index e45ab46..5a7ad95 100644 --- a/src/content/docs/en/limits.md +++ b/src/content/docs/en/limits.md @@ -62,6 +62,10 @@ They are not equivalent, and mixing them would be dishonest: | A score or a rank for a submission | The lab has neither the platform's metric nor its private rows. It counts the rows written and the identifiers a platform would refuse, nothing more | | A measure of the model refitted on every row | Fitting on everything spends the test set. The score shown stays the one of the model fitted on 64 % of the rows; on the demos the refit gained from nothing to 5 points, and lost one time in five to one in three even where it paid | | A submission from a re-imported model, a blend refitted, or a threshold applied | The submission is built from the live run. A re-imported model has no training rows to refit on, a blend picks its members on validation rows, and the label written is the model's raw prediction, as in the scored CSV | +| Replaying how a model was trained | The replay tells how the trained model predicts one row. How each tree was grown, round after round, is another story and a much longer one | +| Replaying a network, a linear model, a blend, or a forest tree by tree | A network has no steps that read as questions, a weighted sum is already read by the Shapley explanation, a blend averages other models, and forty trees are counted, not told. The panel says so for each | +| Stopping the boosting early | The replay shows the validation error round by round, and on the demos its lowest point came well before the last round on 17 runs out of 30. It is shown and sets nothing: changing the number of rounds is a training decision that needs its own measure | +| Replaying a re-imported model, or drawing a whole tree | The replay needs the training rows the run holds, which an export does not carry. It shows the path of one row, not the graph of the tree | | A generative chat backed by a remote API (V12) | Postponed by product decision (confirmed 09/10/2026). Today's chat runs entirely in the browser; a remote API would send out the question and the column schema, never the data, and would require a consent screen | ## Dropped after measurement diff --git a/src/content/docs/en/read-a-learning-curve.md b/src/content/docs/en/read-a-learning-curve.md index 237ffbf..0ffb421 100644 --- a/src/content/docs/en/read-a-learning-curve.md +++ b/src/content/docs/en/read-a-learning-curve.md @@ -40,5 +40,6 @@ beyond what was measured is a guess, and LabML does not offer one. ## Where to go next +- [Replay a prediction](/docs/rejouer-une-prediction) to read what the model did on one row. - [Compare two runs](/docs/comparer-deux-runs) to measure a change of features. - [The method choices](/docs/methode) on why the baseline comes first. diff --git a/src/content/docs/en/reference-ml.md b/src/content/docs/en/reference-ml.md index ee9c285..c3de64e 100644 --- a/src/content/docs/en/reference-ml.md +++ b/src/content/docs/en/reference-ml.md @@ -277,6 +277,15 @@ says so when it is not the one the card is about. The card holds figures only, never a row of the data. What you type is kept with the run in your browser and travels in its share link. +## Replaying one row + +The what-if panel can **replay** its row through the inspected model: the +questions a decision tree asked, the count of a forest's trees, the five rows a +k-NN compared it to, the prediction a boosting builds round after round. The +replay walks the model itself, so its last step is the prediction shown, and its +questions are written in the units of the file. See +[replay a prediction](/docs/rejouer-une-prediction). + ## Export, import, score The model exports to JSON with its manifest: family, pipeline, versions. It diff --git a/src/content/docs/en/replay-a-prediction.md b/src/content/docs/en/replay-a-prediction.md new file mode 100644 index 0000000..261319b --- /dev/null +++ b/src/content/docs/en/replay-a-prediction.md @@ -0,0 +1,89 @@ +--- +slug: rejouer-une-prediction +kind: how-to +order: 6 +title: Replay a prediction step by step +summary: Open the model on one row and read what it did, the questions a tree asked, the rows a k-NN consulted, the rounds of a boosting. +--- + +## The gesture + +1. Train a model and click a family in the leaderboard to inspect it. +2. In **What if…**, set the values of one row. The prediction updates. +3. Click **Replay it step by step**. + +:::try /ml?demo=titanic&target=survived | Train titanic and replay a passenger + +**Why this prediction?** (Shapley) says what weighed. The replay says what +happened: the steps the model took for this row, in the order it took them. +The two answer different questions and are worth reading together. + +## What each family tells + +| Family | What the replay shows | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Decision tree | each question asked of the row, how many training rows were asked the same, and the leaf it ends in: how many training rows share it and what they are | +| Random forest | how many of its 40 trees answered each class, or the spread of their values | +| k-NN | the 5 training rows the row was compared to: their row number in your file, their distance, their target and their main columns | +| Gradient boosting | the prediction round after round, the rounds that moved it most, and the error on the validation rows as the rounds add up | + +The other families have no steps to tell, and the panel says why: a linear or +logistic model is one weighted sum that the Shapley explanation already reads, a +network mixes every column at once, and the blend averages other models. + +## The replay is the model + +Nothing is approximated. A replay walks the structure the model itself predicts +with, and its last step is the prediction shown above it. This was measured +before the panel was built: on the six demos, five splits each, 2,560 test rows, +the replay gave the model's answer on every row for the four families. + +The first measure found one gap: three rows of titanic where the forest and its +replay disagreed. On a tie between two classes the library keeps the first class +to reach the top count, in the order of the trees, not the smallest one. The +replay now does the same, and says when a vote is tied. + +## Questions in the units of your file + +A model sees encoded columns: a number standardized, a category spread over 0/1 +columns. The replay translates what translates exactly: + +- a number gets its unit back: `age < 9.5`, not `age < -1.42`; +- a 0/1 column becomes a question about the category: « sex is "male"? »; +- a word of a free-text column and a frequency rank are shown as the model sees + them, under their encoded name. On the reviews demo, whose columns are text, + nearly every question of the tree is of that kind. + +## Reading the boosting + +Every row starts at the same point (the share of the class in training, or the +mean), and each round adds a small correction. The panel gives the round by +which 90 % of the way was made, and tells up to three rounds in full: the +largest movers among those asking different questions, each with the number of +other rounds that asked this row exactly the same. + +It also shows the error on the **validation rows** as the rounds add up. On the +demos the lowest validation error came well before the last round on 17 runs out +of 30, and on the energy demo the boosting never beat its starting point on +three splits out of five. The lab shows this and sets nothing: it always runs +its rounds to the end, and the curve is read on validation, never on the test +set. + +## Ties in a k-NN + +When the next row is exactly as far as the last neighbour kept, another row +order or another library would have kept the other one, and the answer can +change with it. It is common where columns hold few distinct values: 17 % of the +test rows on titanic, 39 % on energy. The panel flags it on the row concerned. + +## A trace is not a cause + +The path of a tree says which questions were asked of this row. It does not say +that a column makes the answer: another tree, trained on another split, would +ask other questions and often agree on the prediction. + +## Where to go next + +- [Read a learning curve](/docs/lire-une-courbe) to see whether more rows would help. +- [The ML Lab reference](/docs/reference-ml) for what each family is. +- [The limits](/docs/limites) for what the replay does not do. diff --git a/src/content/docs/fr/limites.md b/src/content/docs/fr/limites.md index 9b2770c..a038366 100644 --- a/src/content/docs/fr/limites.md +++ b/src/content/docs/fr/limites.md @@ -62,6 +62,10 @@ Elles ne se valent pas, et les mélanger serait malhonnête : | Un score ou un rang pour une soumission | Le labo n'a ni la métrique de la plateforme ni ses lignes privées. Il compte les lignes écrites et les identifiants qu'une plateforme refuserait, rien de plus | | Une mesure du modèle réentraîné sur toutes les lignes | S'entraîner sur tout consomme le jeu de test. Le score affiché reste celui du modèle entraîné sur 64 % des lignes ; sur les démos le réentraînement a gagné de rien à 5 points, et perdu une fois sur cinq à une fois sur trois même là où il rapportait | | Une soumission depuis un modèle réimporté, un mélange réentraîné, ou un seuil appliqué | La soumission se construit depuis le run en cours. Un modèle réimporté n'a pas de lignes d'entraînement, un mélange choisit ses membres sur les lignes de validation, et la classe écrite est la prédiction brute du modèle, comme dans le CSV scoré | +| Rejouer la façon dont un modèle a été entraîné | Le rejeu raconte comment le modèle entraîné prédit une ligne. Comment chaque arbre a été construit, tour après tour, est une autre histoire, bien plus longue | +| Rejouer un réseau, un modèle linéaire, un mélange, ou une forêt arbre par arbre | Un réseau n'a pas d'étapes qui se lisent comme des questions, une somme pondérée est déjà lue par l'explication de Shapley, un mélange fait la moyenne d'autres modèles, et quarante arbres se comptent, ils ne se racontent pas. Le panneau le dit pour chacun | +| Arrêter le boosting plus tôt | Le rejeu montre l'erreur de validation tour par tour, et sur les démos son point le plus bas arrivait bien avant le dernier tour sur 17 runs sur 30. C'est montré et cela ne règle rien : changer le nombre de tours est une décision d'entraînement qui demande sa propre mesure | +| Rejouer un modèle réimporté, ou dessiner un arbre entier | Le rejeu a besoin des lignes d'entraînement que le run détient, et qu'un export ne porte pas. Il montre le chemin d'une ligne, pas le graphe de l'arbre | | Un chat génératif branché sur une API distante (V12) | Reporté par décision produit (confirmé le 09/10/2026). Le chat actuel tourne entièrement dans le navigateur ; une API distante ferait sortir la question et le schéma des colonnes, jamais les données, et exigerait un écran de consentement | ## Ce qui a été abandonné après mesure diff --git a/src/content/docs/fr/lire-une-courbe.md b/src/content/docs/fr/lire-une-courbe.md index 53ff51a..37af7cc 100644 --- a/src/content/docs/fr/lire-une-courbe.md +++ b/src/content/docs/fr/lire-une-courbe.md @@ -42,5 +42,6 @@ propose pas. ## Et ensuite ? +- [Rejouer une prédiction](/docs/rejouer-une-prediction) pour lire ce que le modèle a fait sur une ligne. - [Comparer deux runs](/docs/comparer-deux-runs) pour mesurer un changement de variables. - [Les choix de méthode](/docs/methode) sur pourquoi la baseline vient d'abord. diff --git a/src/content/docs/fr/reference-ml.md b/src/content/docs/fr/reference-ml.md index 28b5646..8148b91 100644 --- a/src/content/docs/fr/reference-ml.md +++ b/src/content/docs/fr/reference-ml.md @@ -305,6 +305,16 @@ La fiche ne contient que des chiffres, jamais une ligne des données. Ce que vous saisissez est conservé avec le run dans votre navigateur et voyage dans son lien de partage. +## Rejouer une ligne + +Le panneau « Et si… » peut **rejouer** sa ligne à travers le modèle inspecté : +les questions posées par un arbre de décision, le décompte des arbres d'une +forêt, les cinq lignes auxquelles un k-NN l'a comparée, la prédiction qu'un +boosting construit tour après tour. Le rejeu parcourt le modèle lui-même : sa +dernière étape est la prédiction affichée, et ses questions sont écrites dans +les unités du fichier. Voir +[rejouer une prédiction](/docs/rejouer-une-prediction). + ## Exporter, importer, scorer Le modèle s'exporte en JSON avec son manifeste : famille, pipeline, versions. diff --git a/src/content/docs/fr/rejouer-une-prediction.md b/src/content/docs/fr/rejouer-une-prediction.md new file mode 100644 index 0000000..53ad68c --- /dev/null +++ b/src/content/docs/fr/rejouer-une-prediction.md @@ -0,0 +1,96 @@ +--- +slug: rejouer-une-prediction +kind: how-to +order: 6 +title: Rejouer une prédiction pas à pas +summary: Ouvrir le modèle sur une ligne et lire ce qu'il a fait, les questions d'un arbre, les lignes consultées par un k-NN, les tours d'un boosting. +--- + +## Le geste + +1. Entraînez un modèle et cliquez sur une famille du classement pour l'inspecter. +2. Dans **Et si…**, réglez les valeurs d'une ligne. La prédiction se met à jour. +3. Cliquez sur **Le rejouer pas à pas**. + +:::try /ml?demo=titanic&target=survived | Entraîner titanic et rejouer un passager + +**Pourquoi cette prédiction ?** (Shapley) dit ce qui a pesé. Le rejeu dit ce qui +s'est passé : les étapes que le modèle a suivies pour cette ligne, dans l'ordre +où il les a suivies. Les deux répondent à des questions différentes et gagnent à +être lus ensemble. + +## Ce que chaque famille raconte + +| Famille | Ce que le rejeu montre | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Arbre de décision | chaque question posée à la ligne, à combien de lignes d'entraînement elle a été posée, et la feuille d'arrivée : combien de lignes d'entraînement la partagent et ce qu'elles sont | +| Forêt aléatoire | combien de ses 40 arbres ont répondu chaque classe, ou l'étendue de leurs valeurs | +| k-NN | les 5 lignes d'entraînement auxquelles la ligne a été comparée : leur numéro dans votre fichier, leur distance, leur cible et leurs colonnes principales | +| Gradient boosting | la prédiction tour après tour, les tours qui l'ont le plus déplacée, et l'erreur sur les lignes de validation à mesure que les tours s'ajoutent | + +Les autres familles n'ont pas d'étapes à raconter, et le panneau dit pourquoi : +un modèle linéaire ou logistique est une seule somme pondérée que l'explication +de Shapley lit déjà, un réseau mélange toutes les colonnes à la fois, et le +mélange fait la moyenne d'autres modèles. + +## Le rejeu est le modèle + +Rien n'est approximé. Un rejeu parcourt la structure avec laquelle le modèle +prédit lui-même, et sa dernière étape est la prédiction affichée au-dessus. Cela +a été mesuré avant de construire le panneau : sur les six démos, cinq découpes +chacune, 2 560 lignes de test, le rejeu a donné la réponse du modèle sur chaque +ligne, pour les quatre familles. + +La première mesure a trouvé un écart : trois lignes de titanic où la forêt et +son rejeu n'étaient pas d'accord. En cas d'égalité entre deux classes, la +bibliothèque garde la première classe à atteindre le compte le plus haut, dans +l'ordre des arbres, et non la plus petite. Le rejeu fait maintenant de même, et +signale un vote à égalité. + +## Des questions dans les unités de votre fichier + +Un modèle voit des colonnes encodées : un nombre standardisé, une catégorie +étalée sur des colonnes 0/1. Le rejeu traduit ce qui se traduit exactement : + +- un nombre retrouve son unité : `age < 9,5`, pas `age < -1,42` ; +- une colonne 0/1 devient une question sur la catégorie : « sex vaut "male" ? » ; +- un mot d'une colonne de texte libre et un rang de fréquence sont montrés tels + que le modèle les voit, sous leur nom encodé. Sur la démo reviews, dont les + colonnes sont du texte, presque toutes les questions de l'arbre sont de ce + type. + +## Lire le boosting + +Toutes les lignes partent du même point (la part de la classe à l'entraînement, +ou la moyenne), et chaque tour ajoute une petite correction. Le panneau donne le +tour auquel 90 % du chemin était fait, et raconte jusqu'à trois tours en entier : +les plus grands déplacements parmi ceux qui posent des questions différentes, +chacun avec le nombre d'autres tours qui ont posé exactement les mêmes à cette +ligne. + +Il montre aussi l'erreur sur les **lignes de validation** à mesure que les tours +s'ajoutent. Sur les démos, l'erreur de validation la plus basse arrivait bien +avant le dernier tour sur 17 runs sur 30, et sur la démo energy le boosting n'a +jamais battu son point de départ sur trois découpes sur cinq. Le labo le montre +et ne règle rien : il fait toujours ses tours jusqu'au bout, et la courbe se lit +sur la validation, jamais sur le jeu de test. + +## Les ex æquo d'un k-NN + +Quand la ligne suivante est exactement aussi loin que le dernier voisin gardé, +un autre ordre des lignes ou une autre bibliothèque aurait gardé l'autre, et la +réponse peut changer avec elle. C'est fréquent quand les colonnes ont peu de +valeurs distinctes : 17 % des lignes de test sur titanic, 39 % sur energy. Le +panneau le signale sur la ligne concernée. + +## Une trace n'est pas une cause + +Le chemin d'un arbre dit quelles questions ont été posées à cette ligne. Il ne +dit pas qu'une colonne fait la réponse : un autre arbre, entraîné sur une autre +découpe, poserait d'autres questions et tomberait souvent sur la même prédiction. + +## Et ensuite ? + +- [Lire une courbe d'apprentissage](/docs/lire-une-courbe) pour voir si plus de lignes aideraient. +- [La référence du ML Lab](/docs/reference-ml) pour ce qu'est chaque famille. +- [Les limites](/docs/limites) pour ce que le rejeu ne fait pas. diff --git a/src/features/ml/components/insights/GlassBoxView.test.tsx b/src/features/ml/components/insights/GlassBoxView.test.tsx new file mode 100644 index 0000000..d9a629c --- /dev/null +++ b/src/features/ml/components/insights/GlassBoxView.test.tsx @@ -0,0 +1,273 @@ +import { render, screen } from '@testing-library/react'; +import { beforeEach, describe, expect, it } from 'vitest'; +import { GlassBoxView, isReplayable } from '@/features/ml/components/insights/GlassBoxView'; +import type { GlassBoxPayload, Replay } from '@/features/ml/train/glass-box'; +import i18n from '@/lib/i18n'; + +// V66: the view tells each family in its own steps, in the units of the file, +// and ends on the model's answer. + +const payload = (replay: Replay, over: Partial = {}): GlassBoxPayload => ({ + model: 'tree', + isClassification: true, + classes: ['no', 'yes'], + replay, + ...over, +}); + +const tree: Replay = { + kind: 'tree', + prediction: 1, + leafShares: [0.12, 0.88], + steps: [ + { + feature: 'sex=male', + column: 'sex', + kind: 'category', + operator: 'is', + category: 'male', + passed: false, + rows: 428, + }, + { + feature: 'age', + column: 'age', + kind: 'numeric', + operator: '<', + threshold: 9.5, + value: 22, + passed: false, + rows: 151, + }, + { + feature: 'review:great', + column: 'review', + kind: 'word', + operator: '<', + threshold: 0.12, + value: 0, + passed: true, + rows: 1, + }, + ], + leaf: { rows: 41, counts: [5, 36] }, +}; + +const boosting: Replay = { + kind: 'gbdt', + rounds: 120, + prediction: 1, + shares: [0.09, 0.91], + curve: Array.from({ length: 121 }, (_, i) => 0.38 + (0.53 * Math.min(i, 40)) / 40), + settledAt: 37, + told: [ + { + round: 3, + from: 0.41, + to: 0.47, + sameQuestions: 14, + steps: [ + { + feature: 'fare', + column: 'fare', + kind: 'numeric', + operator: '<=', + threshold: 15.2, + value: 71.3, + passed: false, + }, + ], + }, + ], + validation: { + metric: 'logLoss', + curve: Array.from({ length: 121 }, (_, i) => + i <= 22 ? 0.666 - i * 0.0106 : 0.4328 + (i - 22) * 0.00017, + ), + bestRound: 22, + rows: 143, + }, +}; + +describe('GlassBoxView', () => { + beforeEach(async () => { + await i18n.changeLanguage('en'); + }); + + it('knows which families have steps to tell', () => { + expect(['tree', 'forest', 'knn', 'gbdt'].every((key) => isReplayable(key as never))).toBe(true); + expect( + ['linear', 'logistic', 'naiveBayes', 'mlp', 'ensemble', 'baseline'].some((key) => + isReplayable(key as never), + ), + ).toBe(false); + }); + + it('shows nothing for a family with no steps', () => { + const { container } = render(); + expect(container).toBeEmptyDOMElement(); + }); + + it('tells the path of a tree as questions, in the units of the file', () => { + render(); + const box = screen.getByTestId('glass-box'); + expect(box).toHaveAttribute('data-kind', 'tree'); + expect(box).toHaveTextContent('sex is "male"? no · 428 training rows were asked'); + expect(box).toHaveTextContent('age < 9.5? no (this row: 22)'); + expect(box).toHaveTextContent( + 'weight of review:great < 0.12? yes (this row: 0) · 1 training row was asked', + ); + expect(screen.getByTestId('glass-answer')).toHaveTextContent( + '41 training rows end in the same leaf (no: 5 · yes: 36). The tree answers yes.', + ); + expect(box).toHaveTextContent('A trace is not a cause'); + }); + + it('tells a tree that asks nothing, and a regression leaf', () => { + render( + , + ); + expect(screen.getByTestId('glass-box')).toHaveTextContent('The tree asks no question'); + expect(screen.getByTestId('glass-answer')).toHaveTextContent( + '12 training rows end in the same leaf. The tree answers their mean: 23.457.', + ); + }); + + it('counts the trees of a forest, and says when two classes tie', () => { + render( + , + ); + expect(screen.getByTestId('glass-answer')).toHaveTextContent( + '40 trees voted (no: 20 · yes: 20). The forest answers no.', + ); + expect(screen.getByTestId('glass-box')).toHaveTextContent( + 'Two classes got the same number of trees', + ); + }); + + it('gives the spread of a regression forest', () => { + render( + , + ); + expect(screen.getByTestId('glass-answer')).toHaveTextContent( + '40 trees answered between 18 and 26.25. The forest answers their mean: 21.5.', + ); + }); + + it('names the neighbours by their row in the file, and flags a tie at the edge', () => { + render( + , + ); + const table = screen.getByTestId('glass-neighbours'); + expect(table).toHaveTextContent('1,203'); + expect(table).toHaveTextContent('0.123'); + expect(table).toHaveTextContent('female'); + expect(screen.getByTestId('glass-answer')).toHaveTextContent( + 'The 2 nearest rows voted (yes: 3 · no: 2). The model answers yes.', + ); + expect(screen.getByTestId('glass-edge-tie')).toHaveTextContent( + 'exactly as far as the last one kept', + ); + }); + + it('tells the boosting as a curve, its largest rounds, and the validation error', () => { + render(); + expect(screen.getByTestId('glass-answer')).toHaveTextContent( + 'Every row starts at 0.38, the share of "yes" the model begins with. After 120 rounds this row is at 0.91. 90 % of the way was made by round 37.', + ); + const box = screen.getByTestId('glass-box'); + expect(box).toHaveTextContent( + 'Round 3: from 0.41 to 0.47. 14 other rounds asked this row the same questions.', + ); + expect(box).toHaveTextContent('fare ≤ 15.2? no (this row: 71.3)'); + expect(screen.getByTestId('glass-validation')).toHaveTextContent( + 'On the 143 validation rows, the log loss was lowest at round 22 (0.433) and is 0.449 after round 120', + ); + expect(screen.getByTestId('glass-validation')).toHaveTextContent( + 'never on the test set, and it sets nothing', + ); + expect(screen.getAllByRole('img')).toHaveLength(2); + }); + + it('says when the boosting never beat its starting point, or kept helping', () => { + const base = boosting as Extract; + const { unmount } = render( + , + ); + expect(screen.getByTestId('glass-validation')).toHaveTextContent( + 'never beat its starting point', + ); + unmount(); + render( + , + ); + expect(screen.getByTestId('glass-validation')).toHaveTextContent('the rounds kept helping'); + }); + + it('speaks French', async () => { + await i18n.changeLanguage('fr'); + render(); + const box = screen.getByTestId('glass-box'); + expect(box).toHaveTextContent( + "sex vaut « male » ? non · question posée à 428 lignes d'entraînement", + ); + expect(box).toHaveTextContent('age < 9,5 ? non (cette ligne : 22)'); + expect(screen.getByTestId('glass-answer')).toHaveTextContent( + "41 lignes d'entraînement finissent dans la même feuille (no: 5 · yes: 36). L'arbre répond yes.", + ); + expect(box).toHaveTextContent("Une trace n'est pas une cause"); + }); +}); diff --git a/src/features/ml/components/insights/GlassBoxView.tsx b/src/features/ml/components/insights/GlassBoxView.tsx new file mode 100644 index 0000000..84241d1 --- /dev/null +++ b/src/features/ml/components/insights/GlassBoxView.tsx @@ -0,0 +1,309 @@ +import { useTranslation } from 'react-i18next'; +import type { + GlassBoxPayload, + Replay, + SplitStep, + StagedValidation, +} from '@/features/ml/train/glass-box'; +import type { ModelKey } from '@/features/ml/train/types'; + +/** The families a replay has steps to tell for. */ +const REPLAYABLE: ModelKey[] = ['tree', 'forest', 'knn', 'gbdt']; + +export function isReplayable(model: ModelKey): boolean { + return REPLAYABLE.includes(model); +} + +/** A curve as a small line: the shape matters here, the figures are in the text. */ +function Sparkline({ values, mark, label }: { values: number[]; mark?: number; label: string }) { + if (values.length < 2) return null; + const width = 240; + const height = 48; + const min = Math.min(...values); + const max = Math.max(...values); + const span = max - min || 1; + const x = (i: number) => (i / (values.length - 1)) * (width - 4) + 2; + const y = (value: number) => height - 4 - ((value - min) / span) * (height - 8); + return ( + + `${x(i).toFixed(1)},${y(value).toFixed(1)}`).join(' ')} + fill="none" + stroke="currentColor" + strokeWidth="1.5" + /> + {mark !== undefined && ( + + )} + + ); +} + +type Translate = (key: string, options?: Record) => string; + +function stepText(step: SplitStep, t: Translate, num: (value: number) => string): string { + const answer = t(step.passed ? 'ml.lab.glass.yes' : 'ml.lab.glass.no'); + if (step.kind === 'category') { + return t('ml.lab.glass.step.category', { + column: step.column, + category: step.category, + answer, + }); + } + return t(`ml.lab.glass.step.${step.kind}`, { + column: step.column, + feature: step.feature, + operator: step.operator === '<' ? '<' : '≤', + threshold: num(step.threshold ?? 0), + value: num(step.value ?? 0), + answer, + }); +} + +function Steps({ + steps, + t, + num, +}: { + steps: SplitStep[]; + t: Translate; + num: (v: number) => string; +}) { + const lang = useTranslation().i18n.resolvedLanguage ?? 'en'; + return ( +
    + {steps.map((step, i) => ( +
  1. + {stepText(step, t, num)} + {step.rows !== undefined && ( + + {' '} + {t('ml.lab.glass.step.rows', { + count: step.rows, + rows: step.rows.toLocaleString(lang), + })} + + )} +
  2. + ))} +
+ ); +} + +function validationKey(validation: StagedValidation): 'never' | 'early' | 'late' { + const last = validation.curve.length - 1; + if (validation.bestRound === 0) return 'never'; + // Two percent: below that the last rounds cost nothing worth a sentence. + return validation.curve[last] > validation.curve[validation.bestRound] * 1.02 ? 'early' : 'late'; +} + +/** + * V66: one row replayed through the inspected model. The last step shown is + * the model's own prediction, by construction and by test. + */ +export function GlassBoxView({ payload }: { payload: GlassBoxPayload }) { + const { t, i18n } = useTranslation(); + const lang = i18n.resolvedLanguage ?? 'en'; + const num = (value: number, digits = 3) => + value.toLocaleString(lang, { maximumFractionDigits: digits }); + const count = (value: number) => value.toLocaleString(lang); + const { classes, isClassification } = payload; + const answer = (prediction: number) => + isClassification ? (classes[prediction] ?? String(prediction)) : num(prediction); + const replay: Replay = payload.replay; + if (replay.kind === 'none') return null; + + return ( +
+

{t(`ml.lab.glass.title.${replay.kind}`)}

+ + {replay.kind === 'tree' && ( + <> + {replay.steps.length === 0 ? ( +

{t('ml.lab.glass.tree.noQuestion')}

+ ) : ( + num(value)} /> + )} +

+ {replay.leaf + ? isClassification + ? t('ml.lab.glass.tree.leafClasses', { + count: replay.leaf.rows, + rows: count(replay.leaf.rows), + detail: (replay.leaf.counts ?? []) + .map((value, c) => ({ label: classes[c] ?? String(c), value })) + .filter((item) => item.value > 0) + .map((item) => `${item.label}: ${count(item.value)}`) + .join(' · '), + answer: answer(replay.prediction), + }) + : t('ml.lab.glass.tree.leafValue', { + count: replay.leaf.rows, + rows: count(replay.leaf.rows), + answer: answer(replay.prediction), + }) + : t('ml.lab.glass.tree.leafBare', { answer: answer(replay.prediction) })} +

+ + )} + + {replay.kind === 'forest' && ( + <> +

+ {replay.votes + ? t('ml.lab.glass.forest.votes', { + trees: replay.trees, + detail: replay.votes + .map((value, c) => ({ label: classes[c] ?? String(c), value })) + .filter((item) => item.value > 0) + .sort((a, b) => b.value - a.value) + .map((item) => `${item.label}: ${item.value}`) + .join(' · '), + answer: answer(replay.prediction), + }) + : t('ml.lab.glass.forest.spread', { + trees: replay.trees, + min: num(replay.spread?.min ?? 0), + max: num(replay.spread?.max ?? 0), + answer: answer(replay.prediction), + })} +

+ {replay.tiedVote &&

{t('ml.lab.glass.forest.tie')}

} +

{t('ml.lab.glass.forest.note')}

+ + )} + + {replay.kind === 'knn' && ( + <> +
+ + + + + + + {replay.columns.map((name) => ( + + ))} + + + + {replay.rows.map((row, i) => ( + + + + + {row.cells.map((cell, c) => ( + + ))} + + ))} + +
{t('ml.lab.glass.knn.row')}{t('ml.lab.glass.knn.distance')}{t('ml.lab.glass.knn.target')} + {name} +
+ {row.row === null ? '?' : count(row.row)} + + {num(replay.neighbours[i].distance)} + {row.target} + {cell} +
+
+

+ {replay.votes + ? t('ml.lab.glass.knn.votes', { + k: replay.neighbours.length, + detail: replay.votes + .map((value, c) => ({ label: classes[c] ?? String(c), value })) + .filter((item) => item.value > 0) + .sort((a, b) => b.value - a.value) + .map((item) => `${item.label}: ${item.value}`) + .join(' · '), + answer: answer(replay.prediction), + }) + : t('ml.lab.glass.knn.mean', { + k: replay.neighbours.length, + answer: answer(replay.prediction), + })} +

+ {replay.tieAtTheEdge && ( +

+ {t('ml.lab.glass.knn.edgeTie')} +

+ )} + {replay.tiedVote &&

{t('ml.lab.glass.knn.voteTie')}

} +

{t('ml.lab.glass.knn.note')}

+ + )} + + {replay.kind === 'gbdt' && ( + <> +

+ {t(isClassification ? 'ml.lab.glass.gbdt.curveClass' : 'ml.lab.glass.gbdt.curveValue', { + class: answer(replay.prediction), + from: num(replay.curve[0]), + to: num(replay.curve[replay.rounds]), + rounds: replay.rounds, + settled: replay.settledAt, + })} +

+ + {replay.told.length > 0 && ( +
+

{t('ml.lab.glass.gbdt.toldTitle')}

+ {replay.told.map((item) => ( +
+

+ {t('ml.lab.glass.gbdt.round', { + round: item.round, + from: num(item.from), + to: num(item.to), + })}{' '} + {item.sameQuestions > 0 && ( + + {t('ml.lab.glass.gbdt.same', { count: item.sameQuestions })} + + )} +

+ num(value)} /> +
+ ))} +
+ )} + {replay.validation && ( +
+

+ {t(`ml.lab.glass.gbdt.validation.${validationKey(replay.validation)}`, { + metric: t(`ml.lab.glass.gbdt.metric.${replay.validation.metric}`), + rows: count(replay.validation.rows), + best: replay.validation.bestRound, + bestValue: num(replay.validation.curve[replay.validation.bestRound]), + last: replay.validation.curve.length - 1, + lastValue: num(replay.validation.curve[replay.validation.curve.length - 1]), + start: num(replay.validation.curve[0]), + })} +

+ +

{t('ml.lab.glass.gbdt.validationNote')}

+
+ )} + + )} + +

{t('ml.lab.glass.note')}

+
+ ); +} diff --git a/src/features/ml/components/insights/WhatIfPanel.tsx b/src/features/ml/components/insights/WhatIfPanel.tsx index f3ef61f..e02101b 100644 --- a/src/features/ml/components/insights/WhatIfPanel.tsx +++ b/src/features/ml/components/insights/WhatIfPanel.tsx @@ -1,9 +1,10 @@ -import { Sparkles } from 'lucide-react'; +import { Footprints, Sparkles } from 'lucide-react'; import { useEffect, useMemo, useState } from 'react'; import { useTranslation } from 'react-i18next'; import { Badge } from '@/components/ui/badge'; import { Button } from '@/components/ui/button'; import { Eyebrow } from '@/components/ui/eyebrow'; +import { GlassBoxView, isReplayable } from '@/features/ml/components/insights/GlassBoxView'; import { useLabStore } from '@/features/ml/lab-store'; /** Interactive single-row prediction against the inspected model. */ @@ -16,6 +17,8 @@ export function WhatIfPanel() { const requestWhatIf = useLabStore((s) => s.requestWhatIf); const explanation = useLabStore((s) => s.explanation); const requestExplanation = useLabStore((s) => s.requestExplanation); + const replay = useLabStore((s) => s.replay); + const requestReplay = useLabStore((s) => s.requestReplay); const featureProfiles = useMemo( () => (summary?.featureColumns ?? []).map((name) => profiles.find((p) => p.name === name)!), @@ -103,6 +106,17 @@ export function WhatIfPanel() { {t('ml.lab.insights.explainButton')} )} + {!replay && isReplayable(insights.model) && ( + + )} {whatIf.probabilities && (
{whatIf.probabilities.slice(0, 3).map(({ label, p }) => ( @@ -176,6 +190,13 @@ export function WhatIfPanel() {

)} + + {replay && replay.model === insights.model && } + {whatIf && whatIf.model === insights.model && !isReplayable(insights.model) && ( +

+ {t(`ml.lab.glass.none.${insights.model}`)} +

+ )} ); } diff --git a/src/features/ml/data/parse.worker.ts b/src/features/ml/data/parse.worker.ts index 6f644fe..375e525 100644 --- a/src/features/ml/data/parse.worker.ts +++ b/src/features/ml/data/parse.worker.ts @@ -16,6 +16,7 @@ import { explainPrediction } from '@/features/ml/train/shapley'; import { buildPythonScript } from '@/features/ml/train/python-export'; import { deserializeModel, type ImportedModel } from '@/features/ml/train/deserialize'; import { predictRows, scoreBatch, scoreRows } from '@/features/ml/train/score'; +import { replayRow, type GlassBoxCache } from '@/features/ml/train/glass-box'; import { buildSubmission } from '@/features/ml/train/submission'; import { refitOnAllRows } from '@/features/ml/train/refit'; import { analyzeSegments } from '@/features/ml/train/segments'; @@ -54,6 +55,8 @@ let lastFeatureColumns: string[] = []; let datasetName = ''; /** v22: a model rebuilt from an export — fully independent of any run. */ let imported: ImportedModel | null = null; +/** V66: what a replay computes once per run. Emptied with every training. */ +let glassCache: GlassBoxCache = {}; /** V65: the last file the live run scored, kept for its submission. Never leaves the worker. */ let lastBatch: { name: string; header: string[]; cols: Cell[][]; model: ModelKey } | null = null; /** V65: the configuration the artifacts were trained with: a refit repeats it. */ @@ -330,6 +333,7 @@ self.onmessage = async (event: MessageEvent) => { ); if (outcome) { artifacts = outcome.artifacts; + glassCache = {}; lastConfig = request.config; lastFeatureColumns = outcome.summary.featureColumns; post({ @@ -363,6 +367,19 @@ self.onmessage = async (event: MessageEvent) => { kind: 'explanation', payload: explainPrediction(artifacts, request.model, request.values), }); + } else if (request.kind === 'replay') { + if (!artifacts || !lastTarget) throw new Error('no-run'); + post({ + kind: 'replay-result', + payload: replayRow( + artifacts, + request.model, + request.values, + columnsAsMap(), + lastTarget, + glassCache, + ), + }); } else if (request.kind === 'cancel-curve') { cancelCurve = true; } else if (request.kind === 'learning-curve') { diff --git a/src/features/ml/lab-store.ts b/src/features/ml/lab-store.ts index 695ff9e..bad66fb 100644 --- a/src/features/ml/lab-store.ts +++ b/src/features/ml/lab-store.ts @@ -305,6 +305,7 @@ export const useLabStore = create((set, get) => { insights: null, whatIf: null, explanation: null, + replay: null, batchStatus: 'idle', batchResult: null, batchError: null, @@ -336,6 +337,12 @@ export const useLabStore = create((set, get) => { send({ kind: 'explain', model: state.insights.model, values }); }, + requestReplay(values) { + const state = get(); + if (state.trainStatus !== 'done' || !state.insights) return; + send({ kind: 'replay', model: state.insights.model, values }); + }, + tune(model) { const state = get(); if (!state.target || state.trainStatus !== 'done' || state.tuneStatus === 'running') return; diff --git a/src/features/ml/store/fence.ts b/src/features/ml/store/fence.ts index b584045..f3b0cc4 100644 --- a/src/features/ml/store/fence.ts +++ b/src/features/ml/store/fence.ts @@ -17,6 +17,7 @@ const RUN_DERIVED = new Set([ 'insights', 'what-if-result', 'explanation', + 'replay-result', 'tune-progress', 'tune-complete', 'tune-cancelled', diff --git a/src/features/ml/store/responses.test.ts b/src/features/ml/store/responses.test.ts index 6ac5a5b..ffad9e3 100644 --- a/src/features/ml/store/responses.test.ts +++ b/src/features/ml/store/responses.test.ts @@ -37,7 +37,12 @@ const CASES: [string, WorkerResponse, Partial][] = [ { kind: 'model-start', key: 'tree', index: 2, total: 9 }, { trainStatus: 'training', modelProgress: { key: 'tree', index: 2, total: 9 } }, ], - ['what-if-result', { kind: 'what-if-result', payload }, { whatIf: payload, explanation: null }], + [ + 'what-if-result', + { kind: 'what-if-result', payload }, + { whatIf: payload, explanation: null, replay: null }, + ], + ['replay-result', { kind: 'replay-result', payload }, { replay: payload }], [ 'tune-progress', { kind: 'tune-progress', done: 3, total: 12, bestCv: 0.8 }, diff --git a/src/features/ml/store/responses.ts b/src/features/ml/store/responses.ts index a75de55..9ef3408 100644 --- a/src/features/ml/store/responses.ts +++ b/src/features/ml/store/responses.ts @@ -198,7 +198,11 @@ export function createResponseHandlers({ } }, 'what-if-result': (message) => { - set({ whatIf: message.payload, explanation: null }); + set({ whatIf: message.payload, explanation: null, replay: null }); + }, + 'replay-result': (message) => { + // Row-level and tied to the screen: it is shown, and saved nowhere. + set({ replay: message.payload }); }, explanation: (message) => { set({ explanation: message.payload }); diff --git a/src/features/ml/store/state.ts b/src/features/ml/store/state.ts index f8f4d4f..97117ac 100644 --- a/src/features/ml/store/state.ts +++ b/src/features/ml/store/state.ts @@ -27,6 +27,7 @@ import type { RankingMetric, SplitChoice } from '@/features/ml/train/types'; import type { LedgerEntry } from '@/features/ml/train/ledger'; import type { ExplorationPayload } from '@/features/ml/unsupervised/explore'; import type { ForecastPayload } from '@/features/ml/timeseries/run'; +import type { GlassBoxPayload } from '@/features/ml/train/glass-box'; import type { ShapleyExplanation } from '@/features/ml/train/shapley'; import type { InsightsPayload, @@ -86,6 +87,8 @@ export interface LabState { whatIf: WhatIfResult | null; /** Shapley explanation of the latest what-if row (cleared with it). */ explanation: ShapleyExplanation | null; + /** V66: the latest what-if row replayed step by step (cleared with it). */ + replay: GlassBoxPayload | null; tuneStatus: 'idle' | 'running' | 'done'; tuneProgress: { done: number; total: number; bestCv: number | null } | null; tuneOutcome: TuneOutcome | null; @@ -160,6 +163,7 @@ export interface LabState { selectInsightModel: (model: ModelKey) => void; requestWhatIf: (values: Record) => void; requestExplanation: (values: Record) => void; + requestReplay: (values: Record) => void; tune: (model: TunableKey) => void; cancelTune: () => void; learningCurve: (model: ModelKey) => void; @@ -210,6 +214,7 @@ export const initialTraining = { insights: null, whatIf: null, explanation: null, + replay: null as GlassBoxPayload | null, tuneStatus: 'idle' as const, tuneProgress: null, tuneOutcome: null, diff --git a/src/features/ml/train/gbdt.ts b/src/features/ml/train/gbdt.ts index 3058231..0aa6242 100644 --- a/src/features/ml/train/gbdt.ts +++ b/src/features/ml/train/gbdt.ts @@ -23,7 +23,7 @@ export const GBDT_DEFAULTS: GbdtParams = { maxBins: 32, }; -interface TreeNode { +export interface GbdtNode { /** Feature index of the split; -1 for leaves. */ feature: number; /** Rows whose bin ≤ threshold go left. */ @@ -34,7 +34,7 @@ interface TreeNode { } export interface GbdtTree { - nodes: TreeNode[]; + nodes: GbdtNode[]; } interface Binning { @@ -62,7 +62,8 @@ function computeBinning(X: number[][], maxBins: number): Binning { return { edges }; } -function binValue(edges: number[], value: number): number { +/** The bin a raw value falls in: the first edge at or above it. Exported for the replay (V66). */ +export function binValue(edges: number[], value: number): number { // Binary search: first edge ≥ value. let lo = 0; let hi = edges.length - 1; @@ -90,7 +91,7 @@ function growTree( h: Float64Array, params: GbdtParams, ): GbdtTree { - const nodes: TreeNode[] = []; + const nodes: GbdtNode[] = []; const d = binning.edges.length; function leafValue(rows: number[]): number { diff --git a/src/features/ml/train/glass-box.test.ts b/src/features/ml/train/glass-box.test.ts new file mode 100644 index 0000000..4361b1e --- /dev/null +++ b/src/features/ml/train/glass-box.test.ts @@ -0,0 +1,352 @@ +import { describe, expect, it } from 'vitest'; +import { profileColumn } from '@/features/ml/data/profile'; +import { + describeSplit, + featureOrigins, + replayBoosting, + replayForest, + replayNeighbours, + replayRow, + replayTree, + stagedValidation, + type Replay, +} from '@/features/ml/train/glass-box'; +import { KNN_K, trainKnn } from '@/features/ml/train/models'; +import { runTraining, type TrainArtifacts } from '@/features/ml/train/trainer'; +import type { Cell } from '@/features/ml/data/types'; +import type { TrainConfig } from '@/features/ml/train/types'; + +// V66: a replay is the model. Its last step equals `predict` on every test +// row, for each family and each kind of task; a split is told in the units of +// the file where it translates exactly, and as the model sees it elsewhere. + +const N = 240; +const age = Array.from({ length: N }, (_, i) => String(18 + ((i * 37) % 60))); +const income = Array.from({ length: N }, (_, i) => String(20 + ((i * 53) % 90))); +const city = Array.from({ length: N }, (_, i) => ['paris', 'lyon', 'nice'][(i * 7) % 3]); +const binary = age.map((value, i) => + Number(value) + (city[i] === 'nice' ? 25 : 0) > 55 ? 'yes' : 'no', +); +const three = income.map((value) => + Number(value) < 45 ? 'low' : Number(value) < 80 ? 'mid' : 'high', +); +const amount = age.map((value, i) => String(Number(value) * 3 + Number(income[i]) + (i % 4))); + +async function run(target: string, data: Record) { + const columns = new Map(Object.entries(data)); + const profiles = Object.entries(data).map(([name, values]) => profileColumn(name, values)); + const config: TrainConfig = { + target, + features: ['age', 'income', 'city'], + seed: 7, + testRatio: 0.2, + }; + const outcome = await runTraining(columns, profiles, config, { + onModelStart() {}, + onModelResult() {}, + isCancelled: () => false, + }); + return { artifacts: outcome!.artifacts, columns }; +} + +const TASKS: [string, string, Cell[]][] = [ + ['binary', 'label', binary], + ['multiclass', 'label', three], + ['regression', 'amount', amount], +]; + +describe.each(TASKS)('the replay is the model: %s', (_name, target, values) => { + let artifacts: TrainArtifacts; + let columns: Map; + const ready = run(target, { age, income, city, [target]: values }).then((result) => { + artifacts = result.artifacts; + columns = result.columns; + }); + + it('walks the tree to the leaf the model answers from, and counts who shares it', async () => { + await ready; + const model = artifacts.models.get('tree')!; + const want = model.predict(artifacts.testX); + const k = artifacts.classes.length; + artifacts.testX.forEach((row, i) => { + const replay = replayTree( + model, + row, + artifacts.pipeline.specs, + artifacts.isClassification, + k, + ); + expect(replay.prediction).toBe(want[i]); + expect(replay.steps.length).toBeLessThanOrEqual(10); + }); + // A training row replayed with the fitted rows finds itself in its leaf. + const train = artifacts.trainIndices!; + const x = artifacts.pipeline.transform(train); + const y = train.map((index) => + artifacts.isClassification + ? artifacts.classes.indexOf(String(columns.get(target)![index])) + : Number(columns.get(target)![index]), + ); + const replay = replayTree( + model, + x[0], + artifacts.pipeline.specs, + artifacts.isClassification, + k, + { + x, + y, + }, + ); + expect(replay.leaf!.rows).toBeGreaterThanOrEqual(1); + if (replay.steps.length > 0) expect(replay.steps[0].rows).toBe(train.length); + for (let d = 1; d < replay.steps.length; d++) { + expect(replay.steps[d].rows!).toBeLessThanOrEqual(replay.steps[d - 1].rows!); + } + if (artifacts.isClassification) { + expect(replay.leaf!.counts!.reduce((a, v) => a + v, 0)).toBe(replay.leaf!.rows); + } + }); + + it('counts the trees of the forest to the answer the forest gives', async () => { + await ready; + const model = artifacts.models.get('forest')!; + const want = model.predict(artifacts.testX); + artifacts.testX.forEach((row, i) => { + const replay = replayForest(model, row, artifacts.isClassification, artifacts.classes.length); + if (artifacts.isClassification) { + expect(replay.prediction).toBe(want[i]); + expect(replay.votes!.reduce((a, v) => a + v, 0)).toBe(replay.trees); + } else { + expect(replay.prediction).toBeCloseTo(want[i], 9); + expect(replay.spread!.min).toBeLessThanOrEqual(replay.spread!.max); + } + }); + }); + + it('names the neighbours whose vote is the answer', async () => { + await ready; + const model = artifacts.models.get('knn')!; + const want = model.predict(artifacts.testX); + artifacts.testX.forEach((row, i) => { + const replay = replayNeighbours( + model, + row, + KNN_K, + artifacts.isClassification, + artifacts.classes.length, + ); + if (artifacts.isClassification) expect(replay.prediction).toBe(want[i]); + else expect(replay.prediction).toBeCloseTo(want[i], 9); + expect(replay.neighbours).toHaveLength(KNN_K); + for (let n = 1; n < KNN_K; n++) { + expect(replay.neighbours[n].distance).toBeGreaterThanOrEqual( + replay.neighbours[n - 1].distance, + ); + } + }); + }); + + it('adds the rounds up to the answer of the boosting', async () => { + await ready; + const model = artifacts.models.get('gbdt')!; + const want = model.predict(artifacts.testX); + const proba = model.predictProba?.(artifacts.testX); + artifacts.testX.forEach((row, i) => { + const replay = replayBoosting(model, row, artifacts.pipeline.specs); + expect(replay.prediction).toBe(want[i]); + expect(replay.curve).toHaveLength(replay.rounds + 1); + if (proba) { + expect(replay.curve[replay.rounds]).toBe(proba[i][want[i]]); + expect(replay.shares).toEqual(proba[i]); + } else { + expect(replay.curve[replay.rounds]).toBe(want[i]); + } + expect(replay.settledAt).toBeLessThanOrEqual(replay.rounds); + expect(replay.told.length).toBeLessThanOrEqual(3); + for (const told of replay.told) expect(told.to).toBe(replay.curve[told.round]); + // No tree is told twice: the rounds told ask different questions. + const asked = replay.told.map((told) => + told.steps.map((step) => `${step.feature}|${step.threshold}|${step.passed}`).join('>'), + ); + expect(new Set(asked).size).toBe(asked.length); + for (const told of replay.told) { + expect(told.sameQuestions).toBeGreaterThanOrEqual(0); + expect(told.sameQuestions).toBeLessThan(replay.rounds); + } + }); + // Every row shares the starting point. + const first = replayBoosting(model, artifacts.testX[0], artifacts.pipeline.specs); + const second = replayBoosting(model, artifacts.testX[1], artifacts.pipeline.specs); + if (first.prediction === second.prediction) expect(first.curve[0]).toBe(second.curve[0]); + }); + + it('reads the validation error round by round, ending on the error of the model', async () => { + await ready; + const model = artifacts.models.get('gbdt')!; + const staged = stagedValidation(model, artifacts.validationX, artifacts.validationY)!; + expect(staged.rows).toBe(artifacts.validationX.length); + expect(staged.metric).toBe(artifacts.isClassification ? 'logLoss' : 'rmse'); + const last = staged.curve.length - 1; + expect(staged.curve[staged.bestRound]).toBeLessThanOrEqual(staged.curve[last]); + if (!artifacts.isClassification) { + const predicted = model.predict(artifacts.validationX); + const rmse = Math.sqrt( + predicted.reduce((a, v, i) => a + (v - artifacts.validationY[i]) ** 2, 0) / + predicted.length, + ); + expect(staged.curve[last]).toBeCloseTo(rmse, 9); + } + expect(stagedValidation(model, [], [])).toBeNull(); + }); + + it('answers one row for each family through the worker entry, with rows of the file', async () => { + await ready; + const values = { age: '40', income: '60', city: 'nice' }; + const row = artifacts.pipeline.transformRow(values); + const cache = {}; + for (const key of ['tree', 'forest', 'knn', 'gbdt'] as const) { + const payload = replayRow(artifacts, key, values, columns, target, cache); + const replay = payload.replay as Exclude; + expect(replay.kind).toBe(key); + const [want] = artifacts.models.get(key)!.predict([row]); + if (artifacts.isClassification) expect(replay.prediction).toBe(want); + else expect(replay.prediction).toBeCloseTo(want, 9); + } + const tree = replayRow(artifacts, 'tree', values, columns, target, cache).replay; + expect(tree.kind === 'tree' && tree.leaf !== undefined).toBe(true); + + const knn = replayRow(artifacts, 'knn', values, columns, target, cache).replay; + if (knn.kind !== 'knn') throw new Error('expected neighbours'); + expect(knn.columns).toEqual(['age', 'income', 'city']); + knn.rows.forEach((neighbour, i) => { + // The row number points at the file: its cells are the cells of that row. + const index = artifacts.trainIndices![knn.neighbours[i].index]; + expect(neighbour.row).toBe(index + 1); + expect(neighbour.cells).toEqual([age[index], income[index], city[index]]); + expect(neighbour.target).toBe(String(columns.get(target)![index])); + }); + + for (const key of [ + 'linear', + 'logistic', + 'naiveBayes', + 'mlp', + 'ensemble', + 'baseline', + ] as const) { + if (!artifacts.models.has(key)) continue; + expect(replayRow(artifacts, key, values, columns, target, cache).replay.kind).toBe('none'); + } + expect(() => + replayRow({ ...artifacts, models: new Map() }, 'tree', values, columns, target), + ).toThrow('model-not-found'); + }); + + it('names a neighbour by the rows the family was fitted on when it was capped', async () => { + await ready; + const values = { age: '40', income: '60', city: 'nice' }; + // A cap keeps a subset: position p of the model is row fitIndices[p] of the file. + const shifted = artifacts.trainIndices!.map((index) => index + 1000); + const capped = { ...artifacts, fitIndices: { knn: shifted } }; + const knn = replayRow(capped, 'knn', values, columns, target).replay; + if (knn.kind !== 'knn') throw new Error('expected neighbours'); + knn.rows.forEach((neighbour, i) => { + expect(neighbour.row).toBe(shifted[knn.neighbours[i].index] + 1); + }); + }); +}); + +describe('describeSplit', () => { + const specs = [ + { kind: 'numeric' as const, name: 'age', median: 30, mean: 40, std: 10 }, + { kind: 'onehot' as const, name: 'sex', categories: ['male', 'female'], mode: 'male' }, + { kind: 'text' as const, name: 'review', terms: ['great', 'slow'], idf: [1, 2] }, + { + kind: 'ordinal' as const, + name: 'deck', + ranks: new Map([['C', 0]]), + mode: 'C', + mean: 1, + std: 2, + }, + ]; + const origins = featureOrigins(specs); + + it('maps each encoded feature to its source column, in the order of the encoder', () => { + expect(origins.map((origin) => origin.feature)).toEqual([ + 'age', + 'sex=male', + 'sex=female', + 'review:great', + 'review:slow', + 'deck', + ]); + }); + + it('gives a number back its unit', () => { + const step = describeSplit(origins[0], -1.5, 0.2, false, true); + expect(step).toMatchObject({ column: 'age', kind: 'numeric', operator: '<', passed: false }); + expect(step.threshold).toBeCloseTo(25); + expect(step.value).toBeCloseTo(42); + expect(describeSplit(origins[0], 0, 0, true, false).operator).toBe('<='); + }); + + it('reads a 0/1 column as a question about the category, whichever way the test is written', () => { + // The left side of a 0/1 split is "not this category". + expect(describeSplit(origins[2], 0.5, 1, false, true)).toMatchObject({ + column: 'sex', + kind: 'category', + operator: 'is', + category: 'female', + passed: true, + }); + expect(describeSplit(origins[1], 0, 0, true, false).passed).toBe(false); + }); + + it('shows a word and a rank as the model sees them', () => { + expect(describeSplit(origins[4], 0.12, 0, true, true)).toMatchObject({ + feature: 'review:slow', + column: 'review', + kind: 'word', + threshold: 0.12, + value: 0, + passed: true, + }); + expect(describeSplit(origins[5], 0.3, -0.5, true, false)).toMatchObject({ + kind: 'rank', + threshold: 0.3, + value: -0.5, + }); + }); +}); + +describe('the neighbour search told in full', () => { + const X = [[0], [1], [1], [3], [4], [5]]; + const y = [0, 0, 1, 1, 1, 1]; + const model = trainKnn(X, y, { task: 'classification', classCount: 2, seed: 1 }, 2); + + it('keeps the row seen first on a tie, as the prediction does, and flags the tie', () => { + // Rows 1 and 2 are both at distance 1 from 0; row 0 is at distance 0. + const replay = replayNeighbours(model, [0], 2, true, 2); + expect(replay.neighbours.map((n) => n.index)).toEqual([0, 1]); + expect(replay.tieAtTheEdge).toBe(true); + expect(replay.prediction).toBe(model.predict([[0]])[0]); + }); + + it('flags a tied vote, which the first class wins', () => { + const replay = replayNeighbours(model, [2], 2, true, 2); + // Rows 1 and 2 (distance 1, labels 0 and 1), then row 3 at the same distance. + expect(replay.votes).toEqual([1, 1]); + expect(replay.tiedVote).toBe(true); + expect(replay.prediction).toBe(0); + expect(replay.prediction).toBe(model.predict([[2]])[0]); + }); + + it('reports no tie when there is none', () => { + const replay = replayNeighbours(model, [5.2], 2, true, 2); + expect(replay.tieAtTheEdge).toBe(false); + expect(replay.tiedVote).toBe(false); + expect(replay.neighbours[0].distance).toBeCloseTo(0.2); + }); +}); diff --git a/src/features/ml/train/glass-box.ts b/src/features/ml/train/glass-box.ts new file mode 100644 index 0000000..015ebe6 --- /dev/null +++ b/src/features/ml/train/glass-box.ts @@ -0,0 +1,747 @@ +/** + * V66: the glass box. One row, replayed through the model that predicts it. + * + * Shapley (V28) answers "what weighed". This answers "what happened": the + * questions a tree asked, the rows a k-NN consulted, the prediction a + * boosting builds round after round, the trees of a forest that disagreed. + * + * One rule holds the module together: THE REPLAY IS THE MODEL. Nothing here + * approximates. A replay walks the structure the model itself predicts with + * (its exported parameters, or its own neighbour search), and its last step + * must equal `predict` on the same row. The tests check it on every test row + * of the demos; a replay that drifted would tell the story of another model. + * + * A model sees encoded columns: a number standardized, a category spread over + * 0/1 columns, a word weighed by TF-IDF. A threshold "age < -0.31" says + * nothing to a reader, so `describeSplit` translates what translates exactly + * (a number back to its unit, a 0/1 column to "is it this category?") and + * shows the rest as the model sees it, under its encoded name. + * + * A trace is not a cause. The path of a tree says which questions were asked + * of this row, not that the column makes the answer. + * + * Measured before the panel was built, six demos, five seeds, 2,560 test rows: + * + * - the replay equals `predict` on every row for the tree, the k-NN and the + * boosting. The forest missed three rows of titanic until its tie rule was + * copied (see `firstToTheTop`); + * - every question of the tree translates into the units of the file on five + * demos, and 6 of 1,878 on reviews, whose columns are free text; + * - the next row is exactly as far as the last neighbour kept on 17 % of + * titanic's test rows and 39 % of energy's, 0 to 1 % elsewhere; + * - the boosting's validation error was lowest well before its last round + * (more than 2 % under the final error) on 17 runs of 30, and on energy it + * never beat its starting point on three seeds of five. The replay shows + * it and sets nothing: stopping early is a training decision (F9). + * + * Pure and deterministic. + */ +import { isMissing, parseNumber } from '@/features/ml/data/infer'; +import type { Cell } from '@/features/ml/data/types'; +import { binValue, type GbdtTree } from '@/features/ml/train/gbdt'; +import { KNN_K, type TrainedModel } from '@/features/ml/train/models'; +import type { TrainArtifacts } from '@/features/ml/train/trainer'; +import type { ModelKey } from '@/features/ml/train/types'; +import type { FittedPipeline } from '@/features/ml/train/pipeline'; + +type Specs = FittedPipeline['specs']; + +/** How many boosting rounds are told in full. */ +const TOLD_ROUNDS = 3; + +// --- Reading an encoded split in the units of the file ---------------------- + +/** + * One question a tree asked of the row. `asked` is the test as the reader can + * check it; `passed` is whether the row passed it. + */ +export interface SplitStep { + /** The encoded feature, as the model names it (`sex=male`, `review:great`). */ + feature: string; + /** The source column of the file. */ + column: string; + kind: 'numeric' | 'category' | 'word' | 'rank'; + /** + * - `numeric`: is the column below (`<`) or at most (`<=`) `threshold`, in + * the unit of the file? + * - `category`: is the column this `category`? + * - `word`, `rank`: the encoded value against the encoded threshold, shown + * as the model sees them. + */ + operator: '<' | '<=' | 'is'; + threshold?: number; + category?: string; + /** The row's value: in the unit of the file when `kind` is numeric. */ + value?: number; + /** Whether the row passed the test as `operator` states it. */ + passed: boolean; + /** Training rows that reached this question, when the caller counted them. */ + rows?: number; +} + +interface FeatureOrigin { + spec: Specs[number]; + /** Position inside the spec: which category, which term. */ + offset: number; + feature: string; +} + +/** For each encoded feature, the spec it comes from. Same order as `buildRowEncoder`. */ +export function featureOrigins(specs: Specs): FeatureOrigin[] { + const origins: FeatureOrigin[] = []; + for (const spec of specs) { + if (spec.kind === 'onehot') { + spec.categories.forEach((category, offset) => + origins.push({ spec, offset, feature: `${spec.name}=${category}` }), + ); + } else if (spec.kind === 'text') { + spec.terms.forEach((term, offset) => + origins.push({ spec, offset, feature: `${spec.name}:${term}` }), + ); + } else { + origins.push({ spec, offset: 0, feature: spec.name }); + } + } + return origins; +} + +/** + * One split as a question. `goesLeft` is what the model did with the row; + * `strict` tells `<` (the tree of ml-cart) from `<=` (the boosting). + */ +export function describeSplit( + origin: FeatureOrigin, + encodedThreshold: number, + encodedValue: number, + goesLeft: boolean, + strict: boolean, +): SplitStep { + const { spec, feature } = origin; + if (spec.kind === 'numeric') { + return { + feature, + column: spec.name, + kind: 'numeric', + operator: strict ? '<' : '<=', + threshold: encodedThreshold * spec.std + spec.mean, + value: encodedValue * spec.std + spec.mean, + passed: goesLeft, + }; + } + if (spec.kind === 'onehot') { + // A 0/1 column: the left side is always "not this category". + return { + feature, + column: spec.name, + kind: 'category', + operator: 'is', + category: spec.categories[origin.offset], + passed: !goesLeft, + }; + } + return { + feature, + column: spec.name, + kind: spec.kind === 'text' ? 'word' : 'rank', + operator: strict ? '<' : '<=', + threshold: encodedThreshold, + value: encodedValue, + passed: goesLeft, + }; +} + +// --- Decision tree (ml-cart) ------------------------------------------------- + +/** A node of ml-cart as its JSON gives it. A leaf has no children. */ +interface CartNode { + splitColumn?: number; + splitValue?: number; + left?: CartNode; + right?: CartNode; + /** Leaf: class probabilities as a 1 x k matrix, or the mean in regression. */ + distribution?: number | number[][] | { data: ArrayLike[] }; +} + +function leafProbabilities(distribution: CartNode['distribution']): number[] { + if (distribution === undefined || typeof distribution === 'number') return []; + const rows = Array.isArray(distribution) ? distribution : distribution.data; + return Array.from(rows[0] ?? []); +} + +/** Walks one cart tree. `columns` maps the tree's own column numbers to the row's. */ +function walkCart( + root: CartNode, + row: readonly number[], + columns: readonly number[] | null, + visit?: (column: number, threshold: number, value: number, goesLeft: boolean) => void, +): CartNode { + let node = root; + while (node.left && node.right) { + const column = columns ? columns[node.splitColumn!] : node.splitColumn!; + const value = row[column]; + const goesLeft = value < node.splitValue!; + visit?.(column, node.splitValue!, value, goesLeft); + node = goesLeft ? node.left : node.right; + } + return node; +} + +function cartAnswer(leaf: CartNode, isClassification: boolean): number { + if (!isClassification) return leaf.distribution as number; + const probabilities = leafProbabilities(leaf.distribution); + return probabilities.indexOf(Math.max(...probabilities)); +} + +export interface TreeReplay { + kind: 'tree'; + steps: SplitStep[]; + /** The class index, or the value: what `predict` returns. */ + prediction: number; + /** Class shares the leaf holds (classification). */ + leafShares?: number[]; + /** Training rows that end in this leaf, and what they are. */ + leaf?: { rows: number; counts?: number[]; mean?: number }; +} + +/** The rows the tree was fitted on, encoded, to count who reached each question. */ +export interface FittedRows { + x: readonly (readonly number[])[]; + y: readonly number[]; +} + +function cartRoot(model: TrainedModel): CartNode { + // Through JSON on purpose: a tree fitted here holds class instances, a tree + // rebuilt from a helper core holds plain objects. Both read the same after. + const json = JSON.parse(JSON.stringify(model.toJSON!())) as { model: { root: CartNode } }; + return json.model.root; +} + +export function replayTree( + model: TrainedModel, + row: readonly number[], + specs: Specs, + isClassification: boolean, + classCount: number, + fitted?: FittedRows, +): TreeReplay { + const root = cartRoot(model); + const origins = featureOrigins(specs); + const steps: SplitStep[] = []; + /** The questions the row met, in order: the nodes of its path. */ + const path: CartNode[] = []; + let leaf = root; + while (leaf.left && leaf.right) { + const value = row[leaf.splitColumn!]; + const goesLeft = value < leaf.splitValue!; + steps.push(describeSplit(origins[leaf.splitColumn!], leaf.splitValue!, value, goesLeft, true)); + path.push(leaf); + leaf = goesLeft ? leaf.left : leaf.right; + } + + let reached: TreeReplay['leaf']; + if (fitted) { + // Each fitted row walks the tree for as long as it stays on the path of + // the replayed row: it counts at every question they share, and in the + // leaf when they share them all. + const atStep = new Array(steps.length).fill(0); + const counts = new Array(classCount).fill(0); + let rows = 0; + let sum = 0; + fitted.x.forEach((other, i) => { + let node = root; + let depth = 0; + while (node.left && node.right && node === path[depth]) { + atStep[depth] += 1; + node = other[node.splitColumn!] < node.splitValue! ? node.left : node.right; + depth += 1; + } + if (node === leaf) { + rows += 1; + if (isClassification) counts[fitted.y[i]] += 1; + else sum += fitted.y[i]; + } + }); + steps.forEach((step, depth) => (step.rows = atStep[depth])); + reached = isClassification ? { rows, counts } : { rows, ...(rows > 0 && { mean: sum / rows }) }; + } + + return { + kind: 'tree', + steps, + prediction: cartAnswer(leaf, isClassification), + ...(isClassification && { leafShares: leafProbabilities(leaf.distribution) }), + ...(reached && { leaf: reached }), + }; +} + +// --- Random forest (ml-random-forest) ----------------------------------------- + +export interface ForestReplay { + kind: 'forest'; + trees: number; + /** What `predict` returns: the most voted class, or the mean of the trees. */ + prediction: number; + /** Classification: how many trees answered each class. */ + votes?: number[]; + /** Two classes got the same number of trees: the first to get there wins. */ + tiedVote?: boolean; + /** Regression: the spread of the trees' answers. */ + spread?: { min: number; max: number; mean: number }; +} + +/** + * The most voted class as ml-random-forest picks it: the first class to + * REACH the highest count, in the order of the trees. On a tie that is not + * the smallest class, and three test rows of titanic tell the difference. + */ +function firstToTheTop(answers: readonly number[], classCount: number): number { + const counts = new Array(classCount).fill(0); + let best = answers[0] ?? 0; + let bestCount = 0; + for (const answer of answers) { + counts[answer] += 1; + if (counts[answer] > bestCount) { + bestCount = counts[answer]; + best = answer; + } + } + return best; +} + +export function replayForest( + model: TrainedModel, + row: readonly number[], + isClassification: boolean, + classCount: number, +): ForestReplay { + interface ForestJson { + indexes: number[][]; + estimators: { root: CartNode }[]; + } + // ml-random-forest nests its parameters one level down, under `baseModel`. + const json = JSON.parse(JSON.stringify(model.toJSON!())) as { + model: ForestJson & { baseModel?: ForestJson }; + }; + const forest = json.model.baseModel ?? json.model; + const answers = forest.estimators.map((estimator, i) => + cartAnswer(walkCart(estimator.root, row, forest.indexes[i]), isClassification), + ); + if (isClassification) { + const votes = new Array(classCount).fill(0); + for (const answer of answers) votes[answer] += 1; + const top = Math.max(...votes); + return { + kind: 'forest', + trees: answers.length, + prediction: firstToTheTop(answers, classCount), + votes, + tiedVote: votes.filter((count) => count === top).length > 1, + }; + } + const mean = answers.reduce((a, v) => a + v, 0) / (answers.length || 1); + return { + kind: 'forest', + trees: answers.length, + prediction: mean, + spread: { min: Math.min(...answers), max: Math.max(...answers), mean }, + }; +} + +// --- k nearest neighbours ------------------------------------------------------- + +export interface Neighbour { + /** Position in the rows the family was fitted on. */ + index: number; + distance: number; + /** The class index, or the value. */ + label: number; +} + +export interface NeighboursReplay { + kind: 'knn'; + neighbours: Neighbour[]; + prediction: number; + /** Classification: the votes per class. */ + votes?: number[]; + /** + * The next row is exactly as far as the last neighbour kept: another row + * order, or another library, would have kept the other one (V64). + */ + tieAtTheEdge: boolean; + /** Two classes got the same number of votes: the first in order wins. */ + tiedVote: boolean; +} + +export function replayNeighbours( + model: TrainedModel, + row: number[], + k: number, + isClassification: boolean, + classCount: number, +): NeighboursReplay { + const found = model.neighbours!(row, k + 1); + const neighbours = found.slice(0, k); + const tieAtTheEdge = + found.length > k && found[k].distance === neighbours[neighbours.length - 1].distance; + if (!isClassification) { + const mean = neighbours.reduce((a, n) => a + n.label, 0) / (neighbours.length || 1); + return { kind: 'knn', neighbours, prediction: mean, tieAtTheEdge, tiedVote: false }; + } + const votes = new Array(classCount).fill(0); + for (const neighbour of neighbours) votes[neighbour.label] += 1; + const top = Math.max(...votes); + return { + kind: 'knn', + neighbours, + prediction: votes.indexOf(top), + votes, + tieAtTheEdge, + tiedVote: votes.filter((count) => count === top).length > 1, + }; +} + +// --- Gradient boosting ------------------------------------------------------------ + +interface BoosterJson { + baseScore: number; + trees: GbdtTree[]; + edges: number[][]; +} + +interface GbdtJson { + task: 'regression' | 'classification'; + learningRate: number; + boosters: BoosterJson[]; +} + +function gbdtJson(model: TrainedModel): GbdtJson { + const json = model.toJSON!() as { + task: GbdtJson['task']; + learningRate: number; + boosters?: BoosterJson[]; + baseScore?: number; + trees?: GbdtTree[]; + edges?: number[][]; + }; + return { + task: json.task, + learningRate: json.learningRate, + boosters: json.boosters ?? [ + { baseScore: json.baseScore!, trees: json.trees!, edges: json.edges! }, + ], + }; +} + +function sigmoid(z: number): number { + return 1 / (1 + Math.exp(-z)); +} + +/** Raw score of one booster after 0, 1, 2... rounds, for one row. */ +function stagedScores(booster: BoosterJson, row: readonly number[], rate: number): number[] { + const binned = row.map((value, j) => binValue(booster.edges[j], value)); + const scores = [booster.baseScore]; + let score = booster.baseScore; + for (const tree of booster.trees) { + let node = tree.nodes[0]; + while (node.feature !== -1) { + node = + binned[node.feature] <= node.threshold ? tree.nodes[node.left] : tree.nodes[node.right]; + } + score += rate * node.value; + scores.push(score); + } + return scores; +} + +/** A booster that stopped early keeps its last score for the rounds it did not run. */ +function at(scores: readonly number[], round: number): number { + return scores[Math.min(round, scores.length - 1)]; +} + +/** What the model answers after `round` rounds: the value, or the class shares. */ +function answerAt(staged: readonly number[][], round: number, json: GbdtJson): number[] { + if (json.task === 'regression') return [at(staged[0], round)]; + if (staged.length === 1) { + const p = sigmoid(at(staged[0], round)); + return [1 - p, p]; + } + const scores = staged.map((scores) => sigmoid(at(scores, round))); + const sum = scores.reduce((a, v) => a + v, 0) || 1; + return scores.map((v) => v / sum); +} + +export interface BoostingReplay { + kind: 'gbdt'; + rounds: number; + /** The class index, or the value: what `predict` returns. */ + prediction: number; + /** Final class shares (classification). */ + shares?: number[]; + /** + * After 0, 1, 2... rounds: the predicted value, or the share of the class + * finally predicted. `curve[0]` is the starting point every row shares. + */ + curve: number[]; + /** The first round after which the curve has made 90 % of its whole move. */ + settledAt: number; + /** + * The rounds that moved the curve most among those asking different + * questions, with the questions their tree asked. + */ + told: { + round: number; + from: number; + to: number; + steps: SplitStep[]; + /** Other rounds whose tree asked this row exactly the same questions. */ + sameQuestions: number; + }[]; +} + +export function replayBoosting( + model: TrainedModel, + row: readonly number[], + specs: Specs, +): BoostingReplay { + const json = gbdtJson(model); + const staged = json.boosters.map((booster) => stagedScores(booster, row, json.learningRate)); + const rounds = Math.max(...staged.map((scores) => scores.length - 1)); + const last = answerAt(staged, rounds, json); + const isClassification = json.task === 'classification'; + const prediction = isClassification ? last.indexOf(Math.max(...last)) : last[0]; + const watched = isClassification ? prediction : 0; + + const curve: number[] = []; + for (let round = 0; round <= rounds; round++) curve.push(answerAt(staged, round, json)[watched]); + + const move = curve[rounds] - curve[0]; + let settledAt = rounds; + for (let round = 0; round <= rounds; round++) { + if (Math.abs(curve[round] - curve[0]) >= 0.9 * Math.abs(move)) { + settledAt = round; + break; + } + } + + // The tree told for a round is the one of the watched class: in multiclass + // each class has its own booster, and the others only rescale the share. + const booster = json.boosters[json.boosters.length === 1 ? 0 : watched]; + const origins = featureOrigins(specs); + const binned = row.map((value, j) => binValue(booster.edges[j], value)); + const pathOf = (round: number): SplitStep[] => { + const steps: SplitStep[] = []; + const tree = booster.trees[round - 1]; + let node = tree?.nodes[0]; + while (node && node.feature !== -1) { + const goesLeft = binned[node.feature] <= node.threshold; + steps.push( + describeSplit( + origins[node.feature], + booster.edges[node.feature][node.threshold], + row[node.feature], + goesLeft, + false, + ), + ); + node = goesLeft ? tree.nodes[node.left] : tree.nodes[node.right]; + } + return steps; + }; + // The first rounds always move a row most, and often ask the same questions + // again: telling rounds 1, 2 and 3 would tell one tree three times. So the + // rounds told are the largest movers whose questions DIFFER, and each says + // how many other rounds asked this row exactly the same. + const signature = (steps: SplitStep[]) => + steps.map((step) => `${step.feature}|${step.threshold ?? ''}|${step.passed}`).join('>'); + const paths = new Map(); + const sameAs = new Map(); + for (let round = 1; round <= Math.min(rounds, booster.trees.length); round++) { + const steps = pathOf(round); + const key = signature(steps); + paths.set(round, { steps, key }); + sameAs.set(key, (sameAs.get(key) ?? 0) + 1); + } + const seen = new Set(); + const told: BoostingReplay['told'] = []; + const movers = curve + .slice(1) + .map((value, i) => ({ round: i + 1, from: curve[i], to: value })) + .filter((item) => item.to !== item.from && paths.has(item.round)) + .sort((a, b) => Math.abs(b.to - b.from) - Math.abs(a.to - a.from) || a.round - b.round); + for (const item of movers) { + const { steps, key } = paths.get(item.round)!; + if (seen.has(key)) continue; + seen.add(key); + told.push({ ...item, steps, sameQuestions: (sameAs.get(key) ?? 1) - 1 }); + if (told.length === TOLD_ROUNDS) break; + } + told.sort((a, b) => a.round - b.round); + + return { + kind: 'gbdt', + rounds, + prediction, + ...(isClassification && { shares: last }), + curve, + settledAt, + told, + }; +} + +export interface StagedValidation { + /** `rmse` in regression, `logLoss` in classification. Lower is better. */ + metric: 'rmse' | 'logLoss'; + /** The error on the validation rows after 0, 1, 2... rounds. */ + curve: number[]; + /** The round with the lowest error. */ + bestRound: number; + rows: number; +} + +/** + * The error on the validation rows as the rounds add up. It shows whether the + * last rounds still helped; it sets nothing. Read on validation and never on + * the test set, which would otherwise be choosing a number of rounds (V60). + */ +export function stagedValidation( + model: TrainedModel, + validationX: readonly (readonly number[])[], + validationY: readonly number[], +): StagedValidation | null { + if (validationX.length === 0) return null; + const json = gbdtJson(model); + const perRow = validationX.map((row) => + json.boosters.map((booster) => stagedScores(booster, row, json.learningRate)), + ); + const rounds = Math.max(...perRow[0].map((scores) => scores.length - 1)); + const regression = json.task === 'regression'; + const curve: number[] = []; + for (let round = 0; round <= rounds; round++) { + let total = 0; + perRow.forEach((staged, i) => { + const answer = answerAt(staged, round, json); + if (regression) total += (answer[0] - validationY[i]) ** 2; + else total += -Math.log(Math.max(answer[validationY[i]] ?? 0, 1e-12)); + }); + const mean = total / perRow.length; + curve.push(regression ? Math.sqrt(mean) : mean); + } + let bestRound = 0; + for (let round = 1; round <= rounds; round++) + if (curve[round] < curve[bestRound]) bestRound = round; + return { metric: regression ? 'rmse' : 'logLoss', curve, bestRound, rows: perRow.length }; +} + +// --- One row, one model: what the worker answers --------------------------------- + +/** A neighbour as the reader can find it in the file. */ +export interface NeighbourRow { + /** Data row of the file, counted from 1. Null when the run kept no row numbers. */ + row: number | null; + /** The target cell of that row, as written in the file. */ + target: string; + /** The cells of `columns`, in order. */ + cells: string[]; +} + +export type Replay = + | TreeReplay + | ForestReplay + | (NeighboursReplay & { columns: string[]; rows: NeighbourRow[] }) + | (BoostingReplay & { validation: StagedValidation | null }) + /** A family with no steps to tell: the panel says why. */ + | { kind: 'none' }; + +export interface GlassBoxPayload { + model: ModelKey; + isClassification: boolean; + classes: string[]; + replay: Replay; +} + +/** What a replay computes once per run and reuses for every row. */ +export interface GlassBoxCache { + treeFit?: FittedRows | null; + validation?: StagedValidation | null; +} + +/** The columns shown beside a neighbour: enough to recognise the row, not the whole file. */ +const NEIGHBOUR_COLUMNS = 6; + +function cellText(cell: Cell | undefined): string { + return isMissing(cell ?? null) ? '' : String(cell).trim(); +} + +export function replayRow( + artifacts: TrainArtifacts, + modelKey: ModelKey, + values: Record, + columns: Map, + target: string, + cache: GlassBoxCache = {}, +): GlassBoxPayload { + const model = artifacts.models.get(modelKey); + if (!model) throw new Error('model-not-found'); + const { isClassification, classes, pipeline } = artifacts; + const row = pipeline.transformRow(values); + const base = { model: modelKey, isClassification, classes }; + const fitIndices = artifacts.fitIndices?.[modelKey] ?? artifacts.trainIndices; + const targetCells = columns.get(target); + + if (modelKey === 'tree' && model.toJSON) { + if (cache.treeFit === undefined) { + cache.treeFit = null; + if (fitIndices && targetCells) { + const y = fitIndices.map((index) => { + const text = cellText(targetCells[index]); + return isClassification ? classes.indexOf(text) : (parseNumber(text) ?? Number.NaN); + }); + cache.treeFit = { x: pipeline.transform(fitIndices), y }; + } + } + return { + ...base, + replay: replayTree( + model, + row, + pipeline.specs, + isClassification, + classes.length, + cache.treeFit ?? undefined, + ), + }; + } + if (modelKey === 'forest' && model.toJSON) { + return { ...base, replay: replayForest(model, row, isClassification, classes.length) }; + } + if (modelKey === 'knn' && model.neighbours) { + const replay = replayNeighbours(model, row, KNN_K, isClassification, classes.length); + const shown = [...new Set(pipeline.specs.map((spec) => spec.name))].slice(0, NEIGHBOUR_COLUMNS); + const rows = replay.neighbours.map((neighbour): NeighbourRow => { + const index = fitIndices?.[neighbour.index]; + return { + row: index === undefined ? null : index + 1, + target: + index === undefined + ? isClassification + ? (classes[neighbour.label] ?? '') + : String(neighbour.label) + : cellText(targetCells?.[index]), + cells: shown.map((name) => + index === undefined ? '' : cellText(columns.get(name)?.[index]), + ), + }; + }); + return { ...base, replay: { ...replay, columns: shown, rows } }; + } + if (modelKey === 'gbdt' && model.toJSON) { + if (cache.validation === undefined) { + cache.validation = stagedValidation(model, artifacts.validationX, artifacts.validationY); + } + return { + ...base, + replay: { ...replayBoosting(model, row, pipeline.specs), validation: cache.validation }, + }; + } + return { ...base, replay: { kind: 'none' } }; +} diff --git a/src/features/ml/train/models.ts b/src/features/ml/train/models.ts index 17a73e1..f643228 100644 --- a/src/features/ml/train/models.ts +++ b/src/features/ml/train/models.ts @@ -19,6 +19,12 @@ export interface TrainedModel { predictWithProba?(X: number[][]): { labels: number[]; proba: number[][] }; /** Serializable parameters for export — absent when not exportable (k-NN). */ toJSON?(): unknown; + /** + * V66: the `count` training rows nearest to one encoded row, nearest first, + * for the replay. `index` is a position in the rows the family was fitted + * on, `distance` a Euclidean distance in the encoded space. Only k-NN. + */ + neighbours?(row: number[], count: number): { index: number; distance: number; label: number }[]; } export interface ModelContext { @@ -40,7 +46,7 @@ export interface ModelDef { train(X: number[][], y: number[], ctx: ModelContext): TrainedModel; } -const KNN_K = 5; +export const KNN_K = 5; /** * V36: the ml-cart families cannot take sample weights, so class weighting @@ -284,8 +290,30 @@ export function trainKnn( return bestLabel; } + /** + * V66: the same search, told in full for one row. Off the hot path on + * purpose: it sorts every distance, which a replay of one row can afford and + * a prediction of 60 000 cannot. The sort is stable, so ties keep the row + * seen first, exactly as `neighbors` does. + */ + function neighbours(row: number[], count: number) { + const all: { index: number; distance: number; label: number }[] = []; + for (let i = 0; i < rowCount; i++) { + const base = i * width; + let sum = 0; + for (let j = 0; j < width; j++) { + const diff = row[j] - flat[base + j]; + sum += diff * diff; + } + all.push({ index: i, distance: sum, label: trainY[i] }); + } + all.sort((a, b) => a.distance - b.distance); + return all.slice(0, count).map((item) => ({ ...item, distance: Math.sqrt(item.distance) })); + } + if (ctx.task === 'regression') { return { + neighbours, predict: (rows) => rows.map((row) => { const near = neighbors(row); @@ -307,6 +335,7 @@ export function trainKnn( probabilities.map((p) => p.indexOf(Math.max(...p))); return { + neighbours, predict: (rows) => labelsOf(proba(rows)), predictProba: proba, // V37: a scorer wants both, and for k-NN both come out of the same diff --git a/src/features/ml/train/trainer.ts b/src/features/ml/train/trainer.ts index f6e6e47..4f93f8b 100644 --- a/src/features/ml/train/trainer.ts +++ b/src/features/ml/train/trainer.ts @@ -55,6 +55,12 @@ export interface TrainArtifacts { trainIndices?: number[]; /** V64: the rows held out for selection, so an export can name all three splits. */ validationIndices?: number[]; + /** + * V66: for a family fitted under its announced cap (V25), the original row + * index of each row it was fitted on. A family absent from here was fitted + * on `trainIndices`. The replay needs it to name a k-NN neighbour's row. + */ + fitIndices?: Partial>; classes: string[]; isClassification: boolean; seed: number; @@ -464,6 +470,15 @@ export async function runTraining( return sampleOrder.slice(0, cap).sort((a, b) => a - b); }; + // V66: which rows each capped family was fitted on, whoever fitted it (the + // helpers of V37 draw the same nested sample from the same seed). + const fitIndices: Partial> = {}; + for (const [key, cap] of Object.entries(MODEL_TRAIN_CAPS) as [ModelKey, number][]) { + if (train.length > cap) { + fitIndices[key] = cappedTrainPositions(cap).map((position) => train[position]); + } + } + // V36: class weights, only when asked for and only on classification. // Off by default — on a balanced target weighting changes nothing. const weights = @@ -641,6 +656,7 @@ export async function runTraining( testIndices: test, trainIndices: train, validationIndices: validation, + fitIndices, classes, isClassification, seed: config.seed, diff --git a/src/features/ml/worker-protocol.ts b/src/features/ml/worker-protocol.ts index 2c82941..7d69804 100644 --- a/src/features/ml/worker-protocol.ts +++ b/src/features/ml/worker-protocol.ts @@ -18,6 +18,7 @@ import type { import type { MulticlassDecisionPolicy } from '@/features/ml/train/multiclass-decision'; import type { UncertaintyAnalysis } from '@/features/ml/train/uncertainty'; import type { ShapleyExplanation } from '@/features/ml/train/shapley'; +import type { GlassBoxPayload } from '@/features/ml/train/glass-box'; import type { InsightsPayload, MetricMap, @@ -41,6 +42,8 @@ export type WorkerRequest = | { kind: 'model-insights'; model: ModelKey } | { kind: 'what-if'; model: ModelKey; values: Record } | { kind: 'explain'; model: ModelKey; values: Record } + /** V66: the same row, replayed step by step through the inspected model. */ + | { kind: 'replay'; model: ModelKey; values: Record } | { kind: 'tune'; model: TunableKey; config: TrainConfig } | { kind: 'cancel-tune' } // v26: learning curve — retrain on growing seeded prefixes of the train split. @@ -121,6 +124,7 @@ export type WorkerResponse = | { kind: 'insights'; payload: InsightsPayload } | { kind: 'what-if-result'; payload: WhatIfResult } | { kind: 'explanation'; payload: ShapleyExplanation } + | { kind: 'replay-result'; payload: GlassBoxPayload } | { kind: 'tune-progress'; done: number; total: number; bestCv: number | null } | { kind: 'tune-complete'; payload: TuneOutcome } | { kind: 'tune-cancelled' } diff --git a/src/locales/en.json b/src/locales/en.json index f6f1adc..26def76 100644 --- a/src/locales/en.json +++ b/src/locales/en.json @@ -696,6 +696,78 @@ "wordsSaturated": "This model cannot answer the word question: its probabilities are saturated — it returns almost only 0 or 1 — so erasing a word shifts the answer by exactly zero.", "wordsSaturatedAdvice": "That is a property of the model, not of the words. Pick another model in the leaderboard (logistic regression and gradient boosting give graded probabilities) to read the word effects." }, + "glass": { + "button": "Replay it step by step", + "none": { + "linear": "Nothing to replay step by step: this model is one weighted sum, and the explanation above already reads it.", + "logistic": "Nothing to replay step by step: this model is one weighted sum, and the explanation above already reads it.", + "naiveBayes": "Nothing to replay step by step: this model multiplies one probability per column, with no order between them.", + "mlp": "Nothing to replay step by step: a network mixes every column at once, and its layers do not read as questions.", + "ensemble": "Nothing to replay step by step: the blend averages other models. Inspect one of them to replay it.", + "baseline": "Nothing to replay: the baseline answers the same thing for every row." + }, + "title": { + "tree": "The questions the tree asked this row", + "forest": "What each tree of the forest answered", + "knn": "The training rows this row was compared to", + "gbdt": "How the boosting built this prediction" + }, + "yes": "yes", + "no": "no", + "step": { + "numeric": "{{column}} {{operator}} {{threshold}}? {{answer}} (this row: {{value}})", + "category": "{{column}} is \"{{category}}\"? {{answer}}", + "word": "weight of {{feature}} {{operator}} {{threshold}}? {{answer}} (this row: {{value}})", + "rank": "{{column}}, as its frequency rank, {{operator}} {{threshold}}? {{answer}} (this row: {{value}})", + "rows_one": "· {{rows}} training row was asked", + "rows_other": "· {{rows}} training rows were asked" + }, + "tree": { + "noQuestion": "The tree asks no question: it is a single leaf.", + "leafClasses_one": "{{rows}} training row ends in the same leaf ({{detail}}). The tree answers {{answer}}.", + "leafClasses_other": "{{rows}} training rows end in the same leaf ({{detail}}). The tree answers {{answer}}.", + "leafValue_one": "{{rows}} training row ends in the same leaf. The tree answers its value: {{answer}}.", + "leafValue_other": "{{rows}} training rows end in the same leaf. The tree answers their mean: {{answer}}.", + "leafBare": "The tree answers {{answer}}." + }, + "forest": { + "votes": "{{trees}} trees voted ({{detail}}). The forest answers {{answer}}.", + "spread": "{{trees}} trees answered between {{min}} and {{max}}. The forest answers their mean: {{answer}}.", + "tie": "Two classes got the same number of trees. The forest keeps the first one to reach that count, in the order of its trees.", + "note": "Forty trees are not told one by one: the count of their answers is what the forest predicts from. Inspect the decision tree to read a path." + }, + "knn": { + "row": "row", + "distance": "distance", + "target": "target", + "votes": "The {{k}} nearest rows voted ({{detail}}). The model answers {{answer}}.", + "mean": "The model answers the mean of the {{k}} nearest rows: {{answer}}.", + "edgeTie": "The next row is exactly as far as the last one kept. Another row order, or another library, would have kept the other one, and the answer can change with it.", + "voteTie": "Two classes got the same number of votes. The model keeps the first one in the order of the classes.", + "note": "The row number counts the data rows of the file from 1. The distance is measured on the encoded columns (numbers standardized, categories as 0/1), not in the units of the file." + }, + "gbdt": { + "curveClass": "Every row starts at {{from}}, the share of \"{{class}}\" the model begins with. After {{rounds}} rounds this row is at {{to}}. 90 % of the way was made by round {{settled}}.", + "curveValue": "Every row starts at {{from}}, the mean of the training rows. After {{rounds}} rounds this row is at {{to}}. 90 % of the way was made by round {{settled}}.", + "curveLabel": "The prediction for this row, round after round", + "toldTitle": "The rounds that moved this row most, among those asking different questions:", + "round": "Round {{round}}: from {{from}} to {{to}}.", + "metric": { + "rmse": "RMSE", + "logLoss": "log loss" + }, + "validation": { + "never": "On the {{rows}} validation rows, the {{metric}} was lowest before the first round ({{start}}) and is {{lastValue}} after round {{last}}: on these rows the boosting never beat its starting point.", + "early": "On the {{rows}} validation rows, the {{metric}} was lowest at round {{best}} ({{bestValue}}) and is {{lastValue}} after round {{last}}: the later rounds fitted the training rows and did not help these.", + "late": "On the {{rows}} validation rows, the {{metric}} went from {{start}} to {{lastValue}} after round {{last}}, its lowest being {{bestValue}} at round {{best}}: the rounds kept helping, or cost nothing." + }, + "validationLabel": "The error on the validation rows, round after round", + "validationNote": "This is read on the validation rows, never on the test set, and it sets nothing: the lab always runs its rounds to the end. Measured on the demos, the lowest validation error came well before the last round on 17 runs out of 30.", + "same_one": "{{count}} other round asked this row the same questions.", + "same_other": "{{count}} other rounds asked this row the same questions." + }, + "note": "A replay walks the model itself: its last step is the prediction above, not an approximation of it. A trace is not a cause: it says which steps were taken for this row, not that a column makes the answer." + }, "export": { "model": "Model (JSON)", "predictions": "Predictions (CSV)", diff --git a/src/locales/fr.json b/src/locales/fr.json index 9b371ba..cf3e85a 100644 --- a/src/locales/fr.json +++ b/src/locales/fr.json @@ -696,6 +696,78 @@ "wordsSaturated": "Ce modèle ne peut pas répondre à la question des mots : ses probabilités sont saturées — il ne renvoie presque que 0 ou 1 — donc effacer un mot déplace la réponse d'exactement zéro.", "wordsSaturatedAdvice": "C'est une propriété du modèle, pas des mots. Choisissez un autre modèle dans le leaderboard (la régression logistique et le gradient boosting donnent des probabilités nuancées) pour lire les effets par mot." }, + "glass": { + "button": "Le rejouer pas à pas", + "none": { + "linear": "Rien à rejouer pas à pas : ce modèle est une seule somme pondérée, et l'explication ci-dessus la lit déjà.", + "logistic": "Rien à rejouer pas à pas : ce modèle est une seule somme pondérée, et l'explication ci-dessus la lit déjà.", + "naiveBayes": "Rien à rejouer pas à pas : ce modèle multiplie une probabilité par colonne, sans ordre entre elles.", + "mlp": "Rien à rejouer pas à pas : un réseau mélange toutes les colonnes à la fois, et ses couches ne se lisent pas comme des questions.", + "ensemble": "Rien à rejouer pas à pas : le mélange fait la moyenne d'autres modèles. Inspectez l'un d'eux pour le rejouer.", + "baseline": "Rien à rejouer : la référence répond la même chose pour toutes les lignes." + }, + "title": { + "tree": "Les questions que l'arbre a posées à cette ligne", + "forest": "Ce que chaque arbre de la forêt a répondu", + "knn": "Les lignes d'entraînement auxquelles cette ligne a été comparée", + "gbdt": "Comment le boosting a construit cette prédiction" + }, + "yes": "oui", + "no": "non", + "step": { + "numeric": "{{column}} {{operator}} {{threshold}} ? {{answer}} (cette ligne : {{value}})", + "category": "{{column}} vaut « {{category}} » ? {{answer}}", + "word": "poids de {{feature}} {{operator}} {{threshold}} ? {{answer}} (cette ligne : {{value}})", + "rank": "{{column}}, par son rang de fréquence, {{operator}} {{threshold}} ? {{answer}} (cette ligne : {{value}})", + "rows_one": "· question posée à {{rows}} ligne d'entraînement", + "rows_other": "· question posée à {{rows}} lignes d'entraînement" + }, + "tree": { + "noQuestion": "L'arbre ne pose aucune question : c'est une seule feuille.", + "leafClasses_one": "{{rows}} ligne d'entraînement finit dans la même feuille ({{detail}}). L'arbre répond {{answer}}.", + "leafClasses_other": "{{rows}} lignes d'entraînement finissent dans la même feuille ({{detail}}). L'arbre répond {{answer}}.", + "leafValue_one": "{{rows}} ligne d'entraînement finit dans la même feuille. L'arbre répond sa valeur : {{answer}}.", + "leafValue_other": "{{rows}} lignes d'entraînement finissent dans la même feuille. L'arbre répond leur moyenne : {{answer}}.", + "leafBare": "L'arbre répond {{answer}}." + }, + "forest": { + "votes": "{{trees}} arbres ont voté ({{detail}}). La forêt répond {{answer}}.", + "spread": "{{trees}} arbres ont répondu entre {{min}} et {{max}}. La forêt répond leur moyenne : {{answer}}.", + "tie": "Deux classes ont reçu le même nombre d'arbres. La forêt garde la première à atteindre ce compte, dans l'ordre de ses arbres.", + "note": "Quarante arbres ne se racontent pas un à un : le décompte de leurs réponses est ce dont la forêt tire sa prédiction. Inspectez l'arbre de décision pour lire un chemin." + }, + "knn": { + "row": "ligne", + "distance": "distance", + "target": "cible", + "votes": "Les {{k}} lignes les plus proches ont voté ({{detail}}). Le modèle répond {{answer}}.", + "mean": "Le modèle répond la moyenne des {{k}} lignes les plus proches : {{answer}}.", + "edgeTie": "La ligne suivante est exactement aussi loin que la dernière gardée. Un autre ordre des lignes, ou une autre bibliothèque, aurait gardé l'autre, et la réponse peut changer avec elle.", + "voteTie": "Deux classes ont reçu le même nombre de votes. Le modèle garde la première dans l'ordre des classes.", + "note": "Le numéro de ligne compte les lignes de données du fichier à partir de 1. La distance se mesure sur les colonnes encodées (nombres standardisés, catégories en 0/1), pas dans les unités du fichier." + }, + "gbdt": { + "curveClass": "Toutes les lignes partent de {{from}}, la part de « {{class}} » dont le modèle part. Après {{rounds}} tours, cette ligne est à {{to}}. 90 % du chemin était fait au tour {{settled}}.", + "curveValue": "Toutes les lignes partent de {{from}}, la moyenne des lignes d'entraînement. Après {{rounds}} tours, cette ligne est à {{to}}. 90 % du chemin était fait au tour {{settled}}.", + "curveLabel": "La prédiction pour cette ligne, tour après tour", + "toldTitle": "Les tours qui ont le plus déplacé cette ligne, parmi ceux qui posent des questions différentes :", + "round": "Tour {{round}} : de {{from}} à {{to}}.", + "metric": { + "rmse": "RMSE", + "logLoss": "log loss" + }, + "validation": { + "never": "Sur les {{rows}} lignes de validation, la {{metric}} était la plus basse avant le premier tour ({{start}}) et vaut {{lastValue}} après le tour {{last}} : sur ces lignes, le boosting n'a jamais battu son point de départ.", + "early": "Sur les {{rows}} lignes de validation, la {{metric}} était la plus basse au tour {{best}} ({{bestValue}}) et vaut {{lastValue}} après le tour {{last}} : les tours suivants ont collé aux lignes d'entraînement sans aider celles-ci.", + "late": "Sur les {{rows}} lignes de validation, la {{metric}} est passée de {{start}} à {{lastValue}} après le tour {{last}}, son plus bas étant {{bestValue}} au tour {{best}} : les tours ont continué d'aider, ou n'ont rien coûté." + }, + "validationLabel": "L'erreur sur les lignes de validation, tour après tour", + "validationNote": "Ceci se lit sur les lignes de validation, jamais sur le jeu de test, et ne règle rien : le labo fait toujours ses tours jusqu'au bout. Mesuré sur les démos, l'erreur de validation la plus basse arrivait bien avant le dernier tour sur 17 runs sur 30.", + "same_one": "{{count}} autre tour a posé les mêmes questions à cette ligne.", + "same_other": "{{count}} autres tours ont posé les mêmes questions à cette ligne." + }, + "note": "Un rejeu parcourt le modèle lui-même : sa dernière étape est la prédiction ci-dessus, pas une approximation. Une trace n'est pas une cause : elle dit quelles étapes ont été suivies pour cette ligne, pas qu'une colonne fait la réponse." + }, "export": { "model": "Modèle (JSON)", "predictions": "Prédictions (CSV)",