From 8a2c0e44ee14e72a007e3a8de0f74611c2621376 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 19:50:10 +0000 Subject: [PATCH] feat(ml): V68 counterfactuals, what would have to change For one row of a classification, the what-if panel can now look for the smallest change that makes the inspected model answer another class: one column at a time, then two, never three. Only values the training rows hold are tried, free text is never edited, and the columns the user locks are left alone. Nothing found is an answer, given with what was tried. Measured first on the classification demos. One column is enough on most rows of three demos and two are needed on up to 69 %. Two findings shaped the panel: 8 to 60 % of the nearest changes were farther from every training row than training rows are from each other, so the search prefers a change that is not and flags the rest; and only 14 to 54 % of the other trained models followed the same change, so each answer says how many do. New how-to page in both languages, limits, reference, README, PLAN row V68, version 1.68.0. The list of proposed features is now empty. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01AyBsUet8WybTG986ubroar --- CHANGELOG.md | 6 + PLAN.md | 8 +- README.md | 12 +- e2e/counterfactual.spec.ts | 57 ++ package-lock.json | 4 +- package.json | 2 +- src/content/docs/en/find-a-counterfactual.md | 94 ++++ src/content/docs/en/limits.md | 84 +-- src/content/docs/en/reference-ml.md | 10 + src/content/docs/en/replay-a-prediction.md | 1 + .../docs/fr/chercher-un-contrefactuel.md | 101 ++++ src/content/docs/fr/limites.md | 84 +-- src/content/docs/fr/reference-ml.md | 11 + src/content/docs/fr/rejouer-une-prediction.md | 1 + .../insights/CounterfactualView.test.tsx | 159 ++++++ .../insights/CounterfactualView.tsx | 120 +++++ .../ml/components/insights/WhatIfPanel.tsx | 102 +++- src/features/ml/data/parse.worker.ts | 18 + src/features/ml/lab-store.ts | 7 + src/features/ml/store/fence.ts | 1 + src/features/ml/store/responses.test.ts | 7 +- src/features/ml/store/responses.ts | 6 +- src/features/ml/store/state.ts | 9 + src/features/ml/train/counterfactual.test.ts | 237 +++++++++ src/features/ml/train/counterfactual.ts | 486 ++++++++++++++++++ src/features/ml/worker-protocol.ts | 11 + src/locales/en.json | 23 + src/locales/fr.json | 23 + 28 files changed, 1585 insertions(+), 99 deletions(-) create mode 100644 e2e/counterfactual.spec.ts create mode 100644 src/content/docs/en/find-a-counterfactual.md create mode 100644 src/content/docs/fr/chercher-un-contrefactuel.md create mode 100644 src/features/ml/components/insights/CounterfactualView.test.tsx create mode 100644 src/features/ml/components/insights/CounterfactualView.tsx create mode 100644 src/features/ml/train/counterfactual.test.ts create mode 100644 src/features/ml/train/counterfactual.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index f25f723..83f9baa 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. +## V68 — Counterfactuals: what would have to change + +F7, the last feature proposed. + +_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. + ## V67 — Early stopping for the boosting: measured, and not built F9, opened by V66, which had shown the boosting's validation error lowest well before its 120th round on 17 runs of 30. diff --git a/PLAN.md b/PLAN.md index 93b0188..522e18b 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 V67 are delivered. Every other row is a proposal with its launch +V53 to V68 are delivered. Every other row is a proposal with its launch condition, and none starts without an explicit launch command. | Wave | Content | Why | @@ -701,13 +701,13 @@ condition, and none starts without an explicit launch command. | **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. | | **V67 — delivered** | **Early stopping for the boosting: measured, and not built.** F9, opened by V66, which had shown the boosting's validation error lowest well before its 120th round on 17 runs of 30. The obvious reading is overfitting and the obvious fix is to stop at that round. This wave measured the fix before writing it, and the measure says no. **The trap seen before measuring**: the validation rows choose the family (V35, V53). A boosting that also chooses its number of rounds on them would be scored on rows it tuned itself on, against families that tuned nothing there. So three stops were compared, not one: (A) at the lowest error on the run's validation rows; (B) at the lowest error on 15 or 20 % of the training rows held out inside the boosting, keeping that smaller model; (C) the round found by B, applied to the model fitted on all the training rows. Plus a stop by patience (10 or 20 rounds without progress) against the global minimum. **Measured on six demos, ten splits each, a quarter of the rows kept away from everything, against the 120 fixed rounds, on the metric the leaderboard ranks on.** Titanic: A gains 0.4 accuracy point, better on 5 splits and worse on 4. Fraud, iris and mpg: no change. **Reviews: A loses 4.0 accuracy points** (worse 6, better 2), B and C lose 5 to 7. Energy: RMSE 3.5 % lower with A (better 9, worse 1), where the stop is often round 0, the mean of the training rows: there the boosting does no better than the baseline, and it is the family chosen on validation on none of the ten splits. B and C did no better than A on five demos of six, and B, which gives up rows, was the worst of the three on four demos. Patience and global minimum gave the same result within noise. **What does improve is the log loss**: better on 10 splits of 10 on titanic (0.02) and on reviews (0.10). Fewer rounds give better probabilities and no better predictions, and on reviews both at once: a lower log loss and 4 points less accuracy. V66's curve is a log loss in classification, which is why it turned early while the classes predicted kept improving or held. **The trap was real**: with A the boosting's validation score rose above its score on the private rows by 0.9 accuracy point on titanic, 6 points on reviews, 0.04 of RMSE on mpg and 0.18 on energy, beyond what it already did at round 120. On the choice of the family it changed little, and never for the better: the family chosen on validation scored 0.828 on the private rows with A against 0.832 without on titanic, an RMSE of 3.034 against 3.023 on mpg, the same elsewhere. **Decision, by the rule the plan had set (« ship only what the measure justifies »)**: nothing changes in training. The boosting keeps its 120 rounds, no figure of any run moves, and no golden reference is regenerated. **What ships**: the measure, written in `gbdt.ts` where the next reader will look for early stopping; the glass box's sentence, which said the later rounds « did not help » and let the reader conclude that fewer rounds would predict better, now says what was measured; the how-to page and the limits page in both languages carry the table. F9 is closed. **Defects of this wave's own making**: V66's own wording, above, was the defect: it read a log-loss curve as a verdict on the predictions. **What this wave deliberately does not do**: stop early when the user ranks on log loss, where the measure does favour fewer rounds on two demos of four: the lab ranks on accuracy or RMSE by default, and a stop tied to the ranking metric is another design, with the validation trap to solve first; tune depth or learning rate; touch the network or the forest. 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. | +| **V68 — delivered** | **Counterfactuals: what would have to change.** F7, the last feature proposed. For a row typed in the what-if panel the lab said what the model predicts, what weighed (Shapley, V28) and what happened (the glass box, V66). It did not answer the question a person told « no » asks: what would have had to be different? The user looked for it by hand, one field at a time. **A search a reader can follow, not an optimisation**: one column at a time, every value the training rows hold tried in place of the row's own, the column keeping the nearest that flips the answer; two columns together only when no single one flips it; never three. Only observed values, no interpolation; free text is never edited; the columns the user locks are left alone, since the lab does not guess that an age cannot change. Nothing found is an answer, given with what was tried. The plan spoke of refining a numeric threshold by bisection; that would have produced values no row holds, against the rule just stated, and was dropped. **Measured on the four classification demos, three seeds, 60 test rows each, seven families.** One column is enough on 63 to 98 % of titanic's rows, 28 to 100 % of fraud's, 96 to 100 % of iris's; two are needed on up to 30 % (titanic, logistic) and 69 % (fraud, forest), so the pair search earns its place. On reviews most families find nothing (100 % of rows for the naive Bayes, 97 % for the tree): the answer is in the text. A search costs 30 ms at most (the forest), 100 to 550 predictions: no progress indicator is needed. **Two findings changed the design.** (1) **Plausibility**: 8 to 60 % of the nearest changes landed farther from every training row than 95 % of training rows are from their nearest neighbour; the model was answering where it had seen nothing. The search now keeps, per column, the nearest flipping value that stays inside that cloud, and flags the rest. It helps where an alternative exists (the tree on titanic from 8 to 4 %, the naive Bayes on fraud from 14 to 0 %) and not where none does: about half of iris's answers stay flagged, its four columns moving together. (2) **Fragility**: of the other trained models that agreed on the row, only 14 to 54 % answered the new class for the same change. A minimal change lands just across one model's boundary; each answer therefore says how many of the others follow. **What the flag does not catch**, seen on the screenshot review: on titanic the forest proposed `adult_male`: True to False while `sex` stayed `male`. Each value exists, the row does not, and a 0/1 column moving alone is not far from the cloud. The lab does not know two columns say the same thing; the panel and the limits page say so and tell the user to lock or drop the duplicate. **Defects of this wave's own making, caught before the push**: (1) the first search returned the nearest change whatever it was, above; (2) a category loaded into the form from a counterfactual could be rarer than the eight the form lists, and the field then showed another value than the one predicted on: the form now lists the loaded value; (3) the lock checkbox was first put inside the label of its field, so one label named two controls: two existing end-to-end tests that fill a field by its label failed, and the lock is now a control of its own beside the label; (4) the new page quoted a duration in milliseconds, which the documentation refuses since a test says so. **What this wave deliberately does not do**: give advice about the world, a counterfactual speaks of the model and the panel says so; search beyond two columns or edit free text; detect redundant columns; apply the chosen decision threshold (the change flips the prediction the what-if panel shows); handle a regression, where « another class » has no meaning, or a re-imported model, which carries no training rows; implement a published method (DiCE and others). A counterfactual is shown and saved nowhere. The list of proposed features is now empty. 1320 unit tests, 134 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` | +None at the moment: the features proposed here were delivered, or measured and closed, +through V68. A new proposal goes here with the module it reuses and its launch condition. 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 504c039..6cb347a 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,7 @@ The project follows three non-negotiable principles: | 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. The replay showed the boosting's validation error turning well before its last round; early stopping was then measured on rows kept away from everything and **not built**: fewer rounds improved the probabilities, not the predictions | +| Counterfactuals | **What would have to change.** For one row of a classification, the smallest change, one column or two, that makes the inspected model answer another class: only values the training rows hold, the columns the user locks left alone, free text never edited, and a plain « nothing found » with what was tried. Each change carries two readings the measure made necessary: whether the changed row still looks like a training row (8 to 60 % of the nearest changes did not), and how many of the other trained models follow it (14 to 54 % did). A counterfactual speaks of the model, not of the world | | 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 | @@ -282,12 +283,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 fourteen +- **Performance.** Every page — the sections, the home page and each of the fifteen 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.** 1294 unit tests and 133 Playwright end-to-end tests across five +- **Quality bar.** 1320 unit tests and 134 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 @@ -404,9 +405,10 @@ has arbitrated (V60), a production check that reads a new batch against a refere carried by the model export (V61), and a noise ceiling under the Data Studio's drift report, which had been calling small files drifted (V62), a data contract that requires of the next file what was found on a reference (V63), and a scikit-learn script -that redoes a run outside the browser and measures its own gap (V64). Proposed, each with its launch condition and none -scheduled: counterfactuals, a step-by-step view of the hand-written models, and a -competition path from an unlabeled file to a submission. The consented generative chat (V12) stays +that redoes a run outside the browser and measures its own gap (V64), a submission file +for a competition (V65), a step-by-step replay of one row through the model (V66), early +stopping for the boosting, measured and not built (V67), and counterfactuals (V68). No +feature is proposed at the moment. The consented generative chat (V12) stays postponed by product decision. No wave starts without an explicit launch command. The full plan, delivery log and design decisions live in [PLAN.md](PLAN.md); [CHANGELOG.md](CHANGELOG.md) is extracted from it — one entry per wave, newest first — by `npm run changelog`, and a test fails when the two disagree. diff --git a/e2e/counterfactual.spec.ts b/e2e/counterfactual.spec.ts new file mode 100644 index 0000000..aaa3787 --- /dev/null +++ b/e2e/counterfactual.spec.ts @@ -0,0 +1,57 @@ +import { expect, test } from '@playwright/test'; + +test.use({ locale: 'en-US' }); +test.setTimeout(120_000); + +// NOTE: keep this title ASCII-only: it names the test-results directory. +test('counterfactual: a change found is loaded and flips the prediction shown', async ({ + page, +}) => { + await page.goto('/ml?demo=fraud&target=status'); + await page.getByTestId('train-button').click(); + await expect(page.getByTestId('train-again')).toBeVisible({ timeout: 60000 }); + await page.getByRole('cell', { name: /Logistic regression/ }).click(); + + const prediction = page.getByTestId('what-if-prediction'); + await expect(prediction).toBeVisible({ timeout: 30000 }); + const before = (await prediction.textContent())!.trim(); + + await page.getByTestId('counterfactual-button').click(); + const box = page.getByTestId('counterfactual'); + await expect(box).toBeVisible({ timeout: 30000 }); + await expect(box).toContainText(`stop answering "${before}"`); + const first = box.getByTestId('counterfactual-item').first(); + await expect(first).toBeVisible(); + // The first change names its column: lock that one and ask again. + const column = (await first.locator('span').first().textContent())!.split(':')[0].trim(); + await expect(first).toContainText('The model then answers'); + await expect(first.getByTestId('counterfactual-followed')).toContainText( + 'other models that agreed', + ); + await expect(box).toContainText('A counterfactual speaks of the model, not of the world'); + + // Loading it changes the row, and the prediction shown is the class announced. + await first.getByTestId('counterfactual-apply').click(); + await expect(prediction).not.toHaveText(before, { timeout: 30000 }); + // A new row empties the answer, which described the previous one. + await expect(page.getByTestId('counterfactual')).toHaveCount(0); + + // Locked, the column is left alone and named. + await page.getByTestId(`lock-${column}`).check(); + await page.getByTestId('counterfactual-button').click(); + const again = page.getByTestId('counterfactual'); + await expect(again).toBeVisible({ timeout: 30000 }); + await expect(again.getByTestId('counterfactual-kept')).toContainText( + `Left as they are because you locked them: ${column}.`, + ); + for (const item of await again.getByTestId('counterfactual-item').all()) { + await expect(item.locator('span').first()).not.toContainText(`${column}:`); + } + + // A regression has no other class to reach: the button is not offered. + await page.goto('/ml?demo=mpg&target=mpg'); + await page.getByTestId('train-button').click(); + await expect(page.getByTestId('train-again')).toBeVisible({ timeout: 60000 }); + await expect(page.getByTestId('what-if-prediction')).toBeVisible({ timeout: 30000 }); + await expect(page.getByTestId('counterfactual-button')).toHaveCount(0); +}); diff --git a/package-lock.json b/package-lock.json index 354c3a2..3958488 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "labml", - "version": "1.67.0", + "version": "1.68.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "labml", - "version": "1.67.0", + "version": "1.68.0", "license": "MIT", "dependencies": { "@duckdb/duckdb-wasm": "1.28.0", diff --git a/package.json b/package.json index f7e4325..a83dd59 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "labml", "private": true, - "version": "1.67.0", + "version": "1.68.0", "license": "MIT", "type": "module", "engines": { diff --git a/src/content/docs/en/find-a-counterfactual.md b/src/content/docs/en/find-a-counterfactual.md new file mode 100644 index 0000000..6c41c20 --- /dev/null +++ b/src/content/docs/en/find-a-counterfactual.md @@ -0,0 +1,94 @@ +--- +slug: chercher-un-contrefactuel +kind: how-to +order: 7 +title: Find what would change a prediction +summary: For one row, the smallest change of its values that makes the model answer another class, and how far to trust it. +--- + +## The gesture + +1. Train a classification model and click a family in the leaderboard to inspect it. +2. In **What if…**, set the values of one row. +3. Tick **locked** on the columns that cannot change for this case: an age, a sex, a + past event. The lab does not guess them. +4. Click **What would have to change?** + +:::try /ml?demo=titanic&target=survived | Train titanic and look for a change + +Each answer is a change you could have typed yourself, « `pclass`: 3 → 1 », with a +button to load it into the form and see the prediction move. + +## How the search works + +It is a search a reader can follow, not an optimisation: + +1. **one column at a time.** Every value the training rows hold for that column is + tried in place of the row's own; the column keeps the nearest one that changes + the answer; +2. **two columns together**, only when no single column changes the answer; +3. **never three.** A change of five columns is no longer an explanation. + +Only values some training row holds are tried: no number outside the file, no +category that does not exist, nothing interpolated. Free-text columns are never +edited. With three classes or more you can ask for one class in particular. + +When nothing changes the answer within these limits, the panel says so and says +how many rows it tried. That is an answer too: for this model, this row is far +from any other class. + +## What the measure showed + +On the classification demos, 60 test rows per run, seven families: + +| Demo | One column is enough | Two are needed | Nothing found | +| ------- | -------------------- | -------------- | ------------- | +| titanic | 63 to 98 % of rows | 2 to 30 % | 0 to 9 % | +| fraud | 28 to 100 % | 0 to 69 % | 0 to 9 % | +| iris | 96 to 100 % | 0 to 4 % | none | +| reviews | 0 to 100 % | 0 to 38 % | 0 to 100 % | + +On reviews most models find nothing: the answer is in the text, which the search +does not edit. + +Two findings shaped the panel. + +## Reading one: does the changed row still exist? + +A row built from values that each exist can still look like no row at all. The +first search kept the nearest change whatever it was, and **8 to 60 % of its +answers were farther from every training row than training rows usually are from +each other**: the model was answering where it had seen nothing. + +So the search now prefers, for each column, the nearest change that stays inside +the cloud of training rows, and flags the ones that do not. On iris about half +the answers stay flagged whatever is tried: its four columns move together, and +changing one alone leaves the cloud. + +The lab also does not know that two columns say the same thing. On titanic, +`sex`, `who` and `adult_male` describe one fact; changing `adult_male` alone +describes a passenger who cannot exist. Lock the columns that duplicate another, +or better, leave them out of the features. + +## Reading two: do the other models follow? + +The smallest change that flips a model lands just across its boundary. Measured: +of the other trained models that agreed on the row, **only 14 to 54 % answered the +new class** for the same change. + +So each answer says how many of the other models follow. A change most of them +follow says something about the data. A change only this model follows is an edge +of this model. + +## A counterfactual speaks of the model, not of the world + +« The model would answer yes with an income of 52 » is not « earn 52 and you will +get yes ». The model learned which values go together in the file, not what +causes what. Use a counterfactual to understand and to challenge a model, not as +advice to the person the row describes. + +## Where to go next + +- [Replay a prediction](/docs/rejouer-une-prediction) to read the steps the model took. +- [The limits](/docs/limites) for what the search does not do. +- [The ML Lab reference](/docs/reference-ml) for the rest of the what-if panel. diff --git a/src/content/docs/en/limits.md b/src/content/docs/en/limits.md index d75c8fa..907b457 100644 --- a/src/content/docs/en/limits.md +++ b/src/content/docs/en/limits.md @@ -27,46 +27,50 @@ They are not equivalent, and mixing them would be dishonest: ## Set aside by choice -| Set aside | Why | -| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| An AutoML « we handle everything » mode | The exact opposite of a lab that shows its decisions | -| A tenth model family | Nine is plenty; a tenth improves neither honesty nor understanding | -| Tabular deep learning | High cost, no gain at this scale, and no longer hand-written | -| A spreadsheet-style cell editor | Hand edits break reproducibility — the recipe is the only record | -| Fuzzy deduplication | Guaranteed false positives on names and addresses: silently merging two real people | -| Model-based imputation | Opaque, and it fabricates plausible values — refused twice, in V39 and V40 | -| Caching models across runs | The cache key would be the whole configuration plus the data; a stale hit is a wrong leaderboard with no warning | -| Guessing a file's locale | The browser has no relationship to the file dropped into it | -| Making the absence indicator mandatory | It would add columns to every existing recipe: imposing is not announcing | -| Translating the changelog and prerendering the French docs | The changelog is an engineering log, not editorial content; without per-language routes, hreflang alternates would lie | -| Catching async errors and shipping crash reports | React boundaries cannot see callbacks or event handlers — claiming otherwise would be false; and nothing leaves the browser, telemetry included | -| A daily Dependabot and `npm audit fix --force` | A daily cadence drowns the signal; `--force` moves majors without reading the break. The remaining advisories sit in build tooling, and we say so instead of hiding it | -| Picking multiclass thresholds automatically | The lab shows its decisions instead of making them for you; and abstention is neither uncertainty calibration nor a conformal guarantee (that guarantee exists on its own panel, as prediction sets) | -| A run id in every worker message | The worker answers in the order it is written to, so the training status is enough to recognise a stale answer. The id becomes necessary the day requests can overlap | -| A « rare class » warning in the interface | A one-row class stays in training, and a target where every class has one row is refused by name; a banner would flag a problem the split already handles | -| Splitting the ML Lab store into independent slices | Every action shares one worker: slicing would have moved code without separating anything | -| Correcting a score for the runs it was compared with | The inflation depends on how close the runs really are (0.2 to 0.8 times the split-to-split noise at 5 runs across the demos), and the lab cannot know that. The test-set ledger counts and warns; the score stays the one measured | -| Fingerprinting a file's content for the ledger | The ledger recognises a file by its name and shape. Two files sharing both would share a count; hashing every file on every load was not worth that rare case | -| Counting a tuning or an analysis in the ledger | They read the test set without choosing between runs; the ledger counts what a comparison between runs can inflate | -| Saying « retrain » from a drift alone | A drift says the inputs or the answers moved, not that the model is wrong more often: on the mpg demo the batch that moved furthest had a lower error. Without labels the production check stops at « watch » | -| Weighting a drift by the importance of its column | The export does not carry importances, and a column the model barely uses can still be the first sign that the population changed. Every column of the model is read the same way | -| A history of the batches checked | Each check reads one batch against the reference. Following a trend across batches needs a store of past checks, which nothing has asked for yet | -| Changing how the PSI is computed | The bins, the smoothing of empty bins and the formula are the ones everyone uses, so a PSI read here compares with one read elsewhere. What changed in V62 is what the number is compared to: its own noise ceiling | -| A verdict on a shift of the missing rate | It is shown beside each column and left to the reader: a column going from 3 % to 0 % missing is a fact about the export, not a distribution to test | -| Hand-written rules in a data contract | A contract freezes what the lab knows how to find: seven rules, the readings, the shares. Custom bounds and expressions are a language of their own, with its parser, its errors and its tests, and nothing has asked for it yet | -| Checking a contract from the ML Lab's scoring panel | A file is checked in the Data Studio, where it already leaves for the lab. The model export keeps its own reference for the batch it scores (V61) | -| A contract that blocks | It reports and stops. A broken contract still loads, cleans and trains: the decision stays with whoever reads the clauses | -| The same figures in Python as in the lab | The exported script carries the rows of each split and the preprocessing exactly, and translates the models: the lab's estimators are written by hand. Measured on 30 runs, three families agree to the last digit and the others differ by up to several test rows on one split. The script prints both figures and the gap instead of promising one | -| A notebook, an environment file or a project as the Python export | One readable `.py` file to put where you like. A notebook format, pinned versions and a folder layout are choices that belong to whoever runs it | -| Guessing a competition's format, or sending the file to it | The lab knows no platform: you name the identifier, the columns and what a prediction is, and the file is downloaded. Nothing leaves the browser | -| 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 | Measured (V67) on rows kept away from everything: stopping at the lowest validation error made predictions no more accurate on four demos of six, 4 points less accurate on reviews, and better only on energy, where the boosting does no better than the mean. It improves the probabilities (log loss), not the classes. Choosing the round on the validation rows would also flatter the boosting on the very rows that choose the family. The lab keeps its 120 rounds | -| 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 | +| Set aside | Why | +| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| An AutoML « we handle everything » mode | The exact opposite of a lab that shows its decisions | +| A tenth model family | Nine is plenty; a tenth improves neither honesty nor understanding | +| Tabular deep learning | High cost, no gain at this scale, and no longer hand-written | +| A spreadsheet-style cell editor | Hand edits break reproducibility — the recipe is the only record | +| Fuzzy deduplication | Guaranteed false positives on names and addresses: silently merging two real people | +| Model-based imputation | Opaque, and it fabricates plausible values — refused twice, in V39 and V40 | +| Caching models across runs | The cache key would be the whole configuration plus the data; a stale hit is a wrong leaderboard with no warning | +| Guessing a file's locale | The browser has no relationship to the file dropped into it | +| Making the absence indicator mandatory | It would add columns to every existing recipe: imposing is not announcing | +| Translating the changelog and prerendering the French docs | The changelog is an engineering log, not editorial content; without per-language routes, hreflang alternates would lie | +| Catching async errors and shipping crash reports | React boundaries cannot see callbacks or event handlers — claiming otherwise would be false; and nothing leaves the browser, telemetry included | +| A daily Dependabot and `npm audit fix --force` | A daily cadence drowns the signal; `--force` moves majors without reading the break. The remaining advisories sit in build tooling, and we say so instead of hiding it | +| Picking multiclass thresholds automatically | The lab shows its decisions instead of making them for you; and abstention is neither uncertainty calibration nor a conformal guarantee (that guarantee exists on its own panel, as prediction sets) | +| A run id in every worker message | The worker answers in the order it is written to, so the training status is enough to recognise a stale answer. The id becomes necessary the day requests can overlap | +| A « rare class » warning in the interface | A one-row class stays in training, and a target where every class has one row is refused by name; a banner would flag a problem the split already handles | +| Splitting the ML Lab store into independent slices | Every action shares one worker: slicing would have moved code without separating anything | +| Correcting a score for the runs it was compared with | The inflation depends on how close the runs really are (0.2 to 0.8 times the split-to-split noise at 5 runs across the demos), and the lab cannot know that. The test-set ledger counts and warns; the score stays the one measured | +| Fingerprinting a file's content for the ledger | The ledger recognises a file by its name and shape. Two files sharing both would share a count; hashing every file on every load was not worth that rare case | +| Counting a tuning or an analysis in the ledger | They read the test set without choosing between runs; the ledger counts what a comparison between runs can inflate | +| Saying « retrain » from a drift alone | A drift says the inputs or the answers moved, not that the model is wrong more often: on the mpg demo the batch that moved furthest had a lower error. Without labels the production check stops at « watch » | +| Weighting a drift by the importance of its column | The export does not carry importances, and a column the model barely uses can still be the first sign that the population changed. Every column of the model is read the same way | +| A history of the batches checked | Each check reads one batch against the reference. Following a trend across batches needs a store of past checks, which nothing has asked for yet | +| Changing how the PSI is computed | The bins, the smoothing of empty bins and the formula are the ones everyone uses, so a PSI read here compares with one read elsewhere. What changed in V62 is what the number is compared to: its own noise ceiling | +| A verdict on a shift of the missing rate | It is shown beside each column and left to the reader: a column going from 3 % to 0 % missing is a fact about the export, not a distribution to test | +| Hand-written rules in a data contract | A contract freezes what the lab knows how to find: seven rules, the readings, the shares. Custom bounds and expressions are a language of their own, with its parser, its errors and its tests, and nothing has asked for it yet | +| Checking a contract from the ML Lab's scoring panel | A file is checked in the Data Studio, where it already leaves for the lab. The model export keeps its own reference for the batch it scores (V61) | +| A contract that blocks | It reports and stops. A broken contract still loads, cleans and trains: the decision stays with whoever reads the clauses | +| The same figures in Python as in the lab | The exported script carries the rows of each split and the preprocessing exactly, and translates the models: the lab's estimators are written by hand. Measured on 30 runs, three families agree to the last digit and the others differ by up to several test rows on one split. The script prints both figures and the gap instead of promising one | +| A notebook, an environment file or a project as the Python export | One readable `.py` file to put where you like. A notebook format, pinned versions and a folder layout are choices that belong to whoever runs it | +| Guessing a competition's format, or sending the file to it | The lab knows no platform: you name the identifier, the columns and what a prediction is, and the file is downloaded. Nothing leaves the browser | +| 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 | Measured (V67) on rows kept away from everything: stopping at the lowest validation error made predictions no more accurate on four demos of six, 4 points less accurate on reviews, and better only on energy, where the boosting does no better than the mean. It improves the probabilities (log loss), not the classes. Choosing the round on the validation rows would also flatter the boosting on the very rows that choose the family. The lab keeps its 120 rounds | +| 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 | +| Advice from a counterfactual | It says what would make the model answer otherwise, not what would change the outcome in the world: the model learned which values go together, not what causes what | +| A counterfactual of more than two columns, or one that edits free text | A change of five columns is no longer an explanation, and a sentence has no nearest neighbour to try. When the answer sits in the text, the search finds nothing and says so | +| Knowing that two columns say the same thing | Changing one of two redundant columns alone can describe a row that cannot exist. The search flags a changed row far from every training row, which does not catch this case: lock the duplicate, or leave it out of the features | +| Counterfactuals for a regression, a re-imported model, or with the decision threshold | « Another class » has no meaning for a value; an export carries no training rows to draw observed values from; and the change found flips the prediction the what-if panel shows, not the decision of a chosen threshold | +| 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/reference-ml.md b/src/content/docs/en/reference-ml.md index c3de64e..705b942 100644 --- a/src/content/docs/en/reference-ml.md +++ b/src/content/docs/en/reference-ml.md @@ -286,6 +286,16 @@ 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). +## What would change the answer + +On a classification, the same panel can look for a **counterfactual**: the +smallest change of the row, one column or two, that makes the inspected model +answer another class. Only values observed in the training rows are tried, the +columns you lock are left alone, and each change comes with two readings: whether +the changed row still looks like a training row, and how many of the other +trained models follow. See +[find what would change a prediction](/docs/chercher-un-contrefactuel). + ## 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 index 4c7634c..67825d7 100644 --- a/src/content/docs/en/replay-a-prediction.md +++ b/src/content/docs/en/replay-a-prediction.md @@ -102,6 +102,7 @@ ask other questions and often agree on the prediction. ## Where to go next +- [Find what would change a prediction](/docs/chercher-un-contrefactuel), the question after « what happened ». - [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/chercher-un-contrefactuel.md b/src/content/docs/fr/chercher-un-contrefactuel.md new file mode 100644 index 0000000..89f0a58 --- /dev/null +++ b/src/content/docs/fr/chercher-un-contrefactuel.md @@ -0,0 +1,101 @@ +--- +slug: chercher-un-contrefactuel +kind: how-to +order: 7 +title: Chercher ce qui changerait une prédiction +summary: Pour une ligne, le plus petit changement de ses valeurs qui fait répondre une autre classe au modèle, et jusqu'où s'y fier. +--- + +## Le geste + +1. Entraînez un modèle de classification et cliquez sur une famille du classement + pour l'inspecter. +2. Dans **Et si…**, réglez les valeurs d'une ligne. +3. Cochez **verrouillée** sur les colonnes qui ne peuvent pas changer pour ce cas : + un âge, un sexe, un événement passé. Le labo ne les devine pas. +4. Cliquez sur **Que faudrait-il changer ?** + +:::try /ml?demo=titanic&target=survived | Entraîner titanic et chercher un changement + +Chaque réponse est un changement que vous auriez pu saisir vous-même, +« `pclass` : 3 → 1 », avec un bouton pour le charger dans le formulaire et voir la +prédiction bouger. + +## Comment la recherche procède + +C'est une recherche qu'on peut suivre, pas une optimisation : + +1. **une colonne à la fois.** Chaque valeur que les lignes d'entraînement portent + pour cette colonne est essayée à la place de celle de la ligne ; la colonne garde + la plus proche qui change la réponse ; +2. **deux colonnes ensemble**, seulement quand aucune colonne seule ne change la + réponse ; +3. **jamais trois.** Un changement de cinq colonnes n'est plus une explication. + +Seules des valeurs qu'une ligne d'entraînement porte sont essayées : aucun nombre +hors du fichier, aucune catégorie inexistante, rien d'interpolé. Les colonnes de +texte libre ne sont jamais modifiées. Avec trois classes ou plus, vous pouvez +viser une classe en particulier. + +Quand rien ne change la réponse dans ces limites, le panneau le dit, et dit +combien de lignes il a essayées. C'est aussi une réponse : pour ce modèle, cette +ligne est loin de toute autre classe. + +## Ce que la mesure a montré + +Sur les démos de classification, 60 lignes de test par run, sept familles : + +| Démo | Une colonne suffit | Il en faut deux | Rien trouvé | +| ------- | -------------------- | --------------- | ----------- | +| titanic | 63 à 98 % des lignes | 2 à 30 % | 0 à 9 % | +| fraud | 28 à 100 % | 0 à 69 % | 0 à 9 % | +| iris | 96 à 100 % | 0 à 4 % | aucune | +| reviews | 0 à 100 % | 0 à 38 % | 0 à 100 % | + +Sur reviews, la plupart des modèles ne trouvent rien : la réponse est dans le +texte, que la recherche ne modifie pas. + +Deux constats ont façonné le panneau. + +## Première lecture : la ligne modifiée existe-t-elle encore ? + +Une ligne construite avec des valeurs qui existent chacune peut ne ressembler à +aucune ligne. La première recherche gardait le changement le plus proche quel +qu'il soit, et **8 à 60 % de ses réponses étaient plus loin de toute ligne +d'entraînement que les lignes d'entraînement ne le sont d'ordinaire entre elles** : +le modèle répondait là où il n'avait rien vu. + +La recherche préfère donc, pour chaque colonne, le changement le plus proche qui +reste dans le nuage des lignes d'entraînement, et signale ceux qui n'y restent +pas. Sur iris, environ la moitié des réponses restent signalées quoi qu'on +essaie : ses quatre colonnes bougent ensemble, et en changer une seule fait sortir +du nuage. + +Le labo ne sait pas non plus que deux colonnes disent la même chose. Sur titanic, +`sex`, `who` et `adult_male` décrivent un seul fait ; changer `adult_male` seul +décrit un passager qui ne peut pas exister. Verrouillez les colonnes qui en +doublent une autre, ou mieux, retirez-les des variables. + +## Seconde lecture : les autres modèles suivent-ils ? + +Le plus petit changement qui fait basculer un modèle tombe juste de l'autre côté +de sa frontière. Mesuré : parmi les autres modèles entraînés qui étaient d'accord +sur la ligne, **seuls 14 à 54 % répondaient la nouvelle classe** pour le même +changement. + +Chaque réponse dit donc combien d'autres modèles suivent. Un changement que la +plupart suivent dit quelque chose des données. Un changement que seul ce modèle +suit est un bord de ce modèle. + +## Un contrefactuel parle du modèle, pas du monde + +« Le modèle répondrait oui avec un revenu de 52 » n'est pas « gagnez 52 et vous +aurez oui ». Le modèle a appris quelles valeurs vont ensemble dans le fichier, pas +ce qui cause quoi. Servez-vous d'un contrefactuel pour comprendre et contester un +modèle, pas comme d'un conseil à la personne que la ligne décrit. + +## Et ensuite ? + +- [Rejouer une prédiction](/docs/rejouer-une-prediction) pour lire les étapes suivies par le modèle. +- [Les limites](/docs/limites) pour ce que la recherche ne fait pas. +- [La référence du ML Lab](/docs/reference-ml) pour le reste du panneau « Et si… ». diff --git a/src/content/docs/fr/limites.md b/src/content/docs/fr/limites.md index 8e37acb..1546dd8 100644 --- a/src/content/docs/fr/limites.md +++ b/src/content/docs/fr/limites.md @@ -27,46 +27,50 @@ Elles ne se valent pas, et les mélanger serait malhonnête : ## Ce qui a été écarté par choix -| Écarté | Pourquoi | -| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Un mode AutoML « on s'occupe de tout » | L'exact contraire d'un laboratoire qui montre ses décisions | -| Une dixième famille de modèles | Neuf suffisent ; une dixième n'améliore ni l'honnêteté ni la compréhension | -| Le deep learning tabulaire | Coût élevé, aucun gain à cette échelle, et ce ne serait plus écrit à la main | -| Un éditeur de cellules façon tableur | Les retouches à la main cassent la reproductibilité — la recette est le seul enregistrement | -| La déduplication floue | Faux positifs garantis sur des noms et des adresses : fusionner deux personnes réelles en silence | -| L'imputation par modèle | Opaque, et elle fabrique des valeurs plausibles — refusée deux fois, en V39 et en V40 | -| Cacher les modèles entre exécutions | La clé de cache serait la configuration entière plus les données ; un hit périmé, c'est un classement faux sans avertissement | -| Deviner la locale d'un fichier | Le navigateur n'a aucun rapport avec le fichier qu'on y dépose | -| Rendre l'indicateur d'absence obligatoire | Il ajouterait des colonnes à toute recette existante : imposer n'est pas annoncer | -| Traduire le changelog et prérendre la documentation française | Le changelog est un journal d'ingénierie, pas un contenu éditorial ; sans routes par langue, des alternates hreflang mentiraient | -| Capter les erreurs asynchrones et envoyer des rapports de plantage | Les boundaries React ne voient pas les callbacks ni les gestionnaires d'événements — prétendre le contraire serait faux ; et rien ne quitte le navigateur, télémétrie comprise | -| Un Dependabot quotidien et un `npm audit fix --force` | Une cadence quotidienne noie le signal ; `--force` change des majeures sans lire la rupture. Les advisories restantes touchent les outils de build, et on le dit plutôt que de le masquer | -| Choisir les seuils multiclasses automatiquement | Le laboratoire montre ses décisions au lieu de les prendre à votre place ; et l'abstention n'est ni une calibration d'incertitude ni une garantie conforme (cette garantie existe dans son propre panneau, sous forme d'ensembles de prédiction) | -| Un identifiant de run dans chaque message du worker | Le worker répond dans l'ordre où on lui écrit : l'état de l'entraînement suffit à reconnaître une réponse périmée. L'identifiant deviendra nécessaire le jour où des requêtes pourront se chevaucher | -| Un avertissement « classe rare » dans l'interface | Une classe d'une seule ligne reste à l'entraînement, et une cible où chaque classe n'a qu'une ligne est refusée par son nom ; un bandeau signalerait un problème que la découpe règle déjà | -| Découper le store du ML Lab en tranches indépendantes | Toutes ses actions partagent un seul worker : découper aurait déplacé du code sans rien séparer | -| Corriger un score selon les runs auxquels il a été comparé | L'optimisme dépend de l'écart réel entre les runs (0,2 à 0,8 fois le bruit entre deux découpes à 5 runs sur les démos), et le labo ne peut pas le connaître. Le registre du jeu de test compte et avertit ; le score reste celui qui a été mesuré | -| Prendre l'empreinte du contenu d'un fichier pour le registre | Le registre reconnaît un fichier à son nom et à sa forme. Deux fichiers qui partagent les deux partageraient un compte ; hacher chaque fichier à chaque chargement ne valait pas ce cas rare | -| Compter un réglage ou une analyse dans le registre | Ils lisent le jeu de test sans choisir entre des runs ; le registre compte ce qu'une comparaison entre runs peut gonfler | -| Dire « réentraîner » à partir d'une dérive seule | Une dérive dit que les entrées ou les réponses ont bougé, pas que le modèle se trompe davantage : sur la démo mpg, le lot qui avait le plus bougé avait une erreur plus faible. Sans étiquettes, la vérification en production s'arrête à « surveiller » | -| Pondérer une dérive par l'importance de sa colonne | L'export ne porte pas les importances, et une colonne que le modèle utilise peu peut être le premier signe que la population a changé. Toutes les colonnes du modèle sont lues de la même façon | -| Un historique des lots vérifiés | Chaque vérification lit un lot contre la référence. Suivre une tendance d'un lot à l'autre demande de garder les vérifications passées, ce que rien n'a encore demandé | -| Changer le calcul du PSI | Les tranches, le lissage des tranches vides et la formule sont ceux de tout le monde : un PSI lu ici se compare à un PSI lu ailleurs. Ce que V62 a changé, c'est ce à quoi on compare le chiffre : son propre plafond de bruit | -| Un verdict sur un déplacement du taux de manquants | Il est affiché à côté de chaque colonne et laissé au lecteur : une colonne qui passe de 3 % à 0 % de manquants est un fait sur l'export, pas une distribution à tester | -| Des règles écrites à la main dans un contrat de données | Un contrat fige ce que le labo sait constater : sept règles, les lectures, les parts. Des bornes sur mesure et des expressions sont un langage à part entière, avec son analyseur, ses erreurs et ses tests, et rien ne l'a encore demandé | -| Vérifier un contrat depuis le panneau de scoring du ML Lab | Un fichier se vérifie dans le Data Studio, d'où il part déjà vers le lab. L'export de modèle garde sa propre référence pour le lot qu'il score (V61) | -| Un contrat qui bloque | Il signale et s'arrête. Un contrat rompu se charge, se nettoie et s'entraîne quand même : la décision reste à qui lit les clauses | -| Les mêmes chiffres en Python que dans le labo | Le script exporté reprend à l'identique les lignes de chaque découpe et le prétraitement, et traduit les modèles : les estimateurs du labo sont écrits à la main. Mesuré sur 30 exécutions, trois familles concordent au dernier chiffre et les autres s'écartent jusqu'à plusieurs lignes de test sur une découpe. Le script affiche les deux chiffres et l'écart au lieu d'en promettre un | -| Un notebook, un fichier d'environnement ou un projet comme export Python | Un seul fichier `.py` lisible, à poser où l'on veut. Un format de notebook, des versions épinglées et une arborescence sont des choix qui reviennent à qui l'exécute | -| Deviner le format d'une compétition, ou lui envoyer le fichier | Le labo ne connaît aucune plateforme : vous nommez l'identifiant, les colonnes et ce qu'est une prédiction, et le fichier se télécharge. Rien ne quitte le navigateur | -| 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 | Mesuré (V67) sur des lignes tenues à l'écart de tout : s'arrêter à l'erreur de validation la plus basse n'a pas rendu les prédictions plus justes sur quatre démos sur six, les a rendues moins justes de 4 points sur reviews, et meilleures seulement sur energy, où le boosting ne fait pas mieux que la moyenne. Cela améliore les probabilités (log loss), pas les classes. Choisir le tour sur les lignes de validation flatterait en plus le boosting sur les lignes mêmes qui choisissent la famille. Le labo garde ses 120 tours | -| 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 | +| Écarté | Pourquoi | +| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Un mode AutoML « on s'occupe de tout » | L'exact contraire d'un laboratoire qui montre ses décisions | +| Une dixième famille de modèles | Neuf suffisent ; une dixième n'améliore ni l'honnêteté ni la compréhension | +| Le deep learning tabulaire | Coût élevé, aucun gain à cette échelle, et ce ne serait plus écrit à la main | +| Un éditeur de cellules façon tableur | Les retouches à la main cassent la reproductibilité — la recette est le seul enregistrement | +| La déduplication floue | Faux positifs garantis sur des noms et des adresses : fusionner deux personnes réelles en silence | +| L'imputation par modèle | Opaque, et elle fabrique des valeurs plausibles — refusée deux fois, en V39 et en V40 | +| Cacher les modèles entre exécutions | La clé de cache serait la configuration entière plus les données ; un hit périmé, c'est un classement faux sans avertissement | +| Deviner la locale d'un fichier | Le navigateur n'a aucun rapport avec le fichier qu'on y dépose | +| Rendre l'indicateur d'absence obligatoire | Il ajouterait des colonnes à toute recette existante : imposer n'est pas annoncer | +| Traduire le changelog et prérendre la documentation française | Le changelog est un journal d'ingénierie, pas un contenu éditorial ; sans routes par langue, des alternates hreflang mentiraient | +| Capter les erreurs asynchrones et envoyer des rapports de plantage | Les boundaries React ne voient pas les callbacks ni les gestionnaires d'événements — prétendre le contraire serait faux ; et rien ne quitte le navigateur, télémétrie comprise | +| Un Dependabot quotidien et un `npm audit fix --force` | Une cadence quotidienne noie le signal ; `--force` change des majeures sans lire la rupture. Les advisories restantes touchent les outils de build, et on le dit plutôt que de le masquer | +| Choisir les seuils multiclasses automatiquement | Le laboratoire montre ses décisions au lieu de les prendre à votre place ; et l'abstention n'est ni une calibration d'incertitude ni une garantie conforme (cette garantie existe dans son propre panneau, sous forme d'ensembles de prédiction) | +| Un identifiant de run dans chaque message du worker | Le worker répond dans l'ordre où on lui écrit : l'état de l'entraînement suffit à reconnaître une réponse périmée. L'identifiant deviendra nécessaire le jour où des requêtes pourront se chevaucher | +| Un avertissement « classe rare » dans l'interface | Une classe d'une seule ligne reste à l'entraînement, et une cible où chaque classe n'a qu'une ligne est refusée par son nom ; un bandeau signalerait un problème que la découpe règle déjà | +| Découper le store du ML Lab en tranches indépendantes | Toutes ses actions partagent un seul worker : découper aurait déplacé du code sans rien séparer | +| Corriger un score selon les runs auxquels il a été comparé | L'optimisme dépend de l'écart réel entre les runs (0,2 à 0,8 fois le bruit entre deux découpes à 5 runs sur les démos), et le labo ne peut pas le connaître. Le registre du jeu de test compte et avertit ; le score reste celui qui a été mesuré | +| Prendre l'empreinte du contenu d'un fichier pour le registre | Le registre reconnaît un fichier à son nom et à sa forme. Deux fichiers qui partagent les deux partageraient un compte ; hacher chaque fichier à chaque chargement ne valait pas ce cas rare | +| Compter un réglage ou une analyse dans le registre | Ils lisent le jeu de test sans choisir entre des runs ; le registre compte ce qu'une comparaison entre runs peut gonfler | +| Dire « réentraîner » à partir d'une dérive seule | Une dérive dit que les entrées ou les réponses ont bougé, pas que le modèle se trompe davantage : sur la démo mpg, le lot qui avait le plus bougé avait une erreur plus faible. Sans étiquettes, la vérification en production s'arrête à « surveiller » | +| Pondérer une dérive par l'importance de sa colonne | L'export ne porte pas les importances, et une colonne que le modèle utilise peu peut être le premier signe que la population a changé. Toutes les colonnes du modèle sont lues de la même façon | +| Un historique des lots vérifiés | Chaque vérification lit un lot contre la référence. Suivre une tendance d'un lot à l'autre demande de garder les vérifications passées, ce que rien n'a encore demandé | +| Changer le calcul du PSI | Les tranches, le lissage des tranches vides et la formule sont ceux de tout le monde : un PSI lu ici se compare à un PSI lu ailleurs. Ce que V62 a changé, c'est ce à quoi on compare le chiffre : son propre plafond de bruit | +| Un verdict sur un déplacement du taux de manquants | Il est affiché à côté de chaque colonne et laissé au lecteur : une colonne qui passe de 3 % à 0 % de manquants est un fait sur l'export, pas une distribution à tester | +| Des règles écrites à la main dans un contrat de données | Un contrat fige ce que le labo sait constater : sept règles, les lectures, les parts. Des bornes sur mesure et des expressions sont un langage à part entière, avec son analyseur, ses erreurs et ses tests, et rien ne l'a encore demandé | +| Vérifier un contrat depuis le panneau de scoring du ML Lab | Un fichier se vérifie dans le Data Studio, d'où il part déjà vers le lab. L'export de modèle garde sa propre référence pour le lot qu'il score (V61) | +| Un contrat qui bloque | Il signale et s'arrête. Un contrat rompu se charge, se nettoie et s'entraîne quand même : la décision reste à qui lit les clauses | +| Les mêmes chiffres en Python que dans le labo | Le script exporté reprend à l'identique les lignes de chaque découpe et le prétraitement, et traduit les modèles : les estimateurs du labo sont écrits à la main. Mesuré sur 30 exécutions, trois familles concordent au dernier chiffre et les autres s'écartent jusqu'à plusieurs lignes de test sur une découpe. Le script affiche les deux chiffres et l'écart au lieu d'en promettre un | +| Un notebook, un fichier d'environnement ou un projet comme export Python | Un seul fichier `.py` lisible, à poser où l'on veut. Un format de notebook, des versions épinglées et une arborescence sont des choix qui reviennent à qui l'exécute | +| Deviner le format d'une compétition, ou lui envoyer le fichier | Le labo ne connaît aucune plateforme : vous nommez l'identifiant, les colonnes et ce qu'est une prédiction, et le fichier se télécharge. Rien ne quitte le navigateur | +| 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 | Mesuré (V67) sur des lignes tenues à l'écart de tout : s'arrêter à l'erreur de validation la plus basse n'a pas rendu les prédictions plus justes sur quatre démos sur six, les a rendues moins justes de 4 points sur reviews, et meilleures seulement sur energy, où le boosting ne fait pas mieux que la moyenne. Cela améliore les probabilités (log loss), pas les classes. Choisir le tour sur les lignes de validation flatterait en plus le boosting sur les lignes mêmes qui choisissent la famille. Le labo garde ses 120 tours | +| 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 conseil tiré d'un contrefactuel | Il dit ce qui ferait répondre autrement le modèle, pas ce qui changerait le résultat dans le monde : le modèle a appris quelles valeurs vont ensemble, pas ce qui cause quoi | +| Un contrefactuel de plus de deux colonnes, ou qui modifie du texte libre | Un changement de cinq colonnes n'est plus une explication, et une phrase n'a pas de plus proche voisine à essayer. Quand la réponse est dans le texte, la recherche ne trouve rien et le dit | +| Savoir que deux colonnes disent la même chose | Changer une seule de deux colonnes redondantes peut décrire une ligne qui ne peut pas exister. La recherche signale une ligne modifiée loin de toute ligne d'entraînement, ce qui n'attrape pas ce cas : verrouillez le doublon, ou retirez-le des variables | +| Des contrefactuels pour une régression, un modèle réimporté, ou avec le seuil de décision | « Une autre classe » n'a pas de sens pour une valeur ; un export ne porte pas de lignes d'entraînement où puiser des valeurs observées ; et le changement trouvé fait basculer la prédiction que montre le panneau « Et si… », pas la décision d'un seuil choisi | +| 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/reference-ml.md b/src/content/docs/fr/reference-ml.md index 8148b91..2cc86db 100644 --- a/src/content/docs/fr/reference-ml.md +++ b/src/content/docs/fr/reference-ml.md @@ -315,6 +315,17 @@ dernière étape est la prédiction affichée, et ses questions sont écrites da les unités du fichier. Voir [rejouer une prédiction](/docs/rejouer-une-prediction). +## Ce qui changerait la réponse + +Sur une classification, le même panneau peut chercher un **contrefactuel** : le +plus petit changement de la ligne, sur une ou deux colonnes, qui fait répondre +une autre classe au modèle inspecté. Seules des valeurs observées dans les lignes +d'entraînement sont essayées, les colonnes que vous verrouillez sont laissées +telles quelles, et chaque changement vient avec deux lectures : la ligne modifiée +ressemble-t-elle encore à une ligne d'entraînement, et combien des autres modèles +entraînés suivent. Voir +[chercher ce qui changerait une prédiction](/docs/chercher-un-contrefactuel). + ## 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 index 08cea4c..b75906b 100644 --- a/src/content/docs/fr/rejouer-une-prediction.md +++ b/src/content/docs/fr/rejouer-une-prediction.md @@ -111,6 +111,7 @@ découpe, poserait d'autres questions et tomberait souvent sur la même prédict ## Et ensuite ? +- [Chercher ce qui changerait une prédiction](/docs/chercher-un-contrefactuel), la question d'après « que s'est-il passé ». - [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/CounterfactualView.test.tsx b/src/features/ml/components/insights/CounterfactualView.test.tsx new file mode 100644 index 0000000..24e2384 --- /dev/null +++ b/src/features/ml/components/insights/CounterfactualView.test.tsx @@ -0,0 +1,159 @@ +import { fireEvent, render, screen } from '@testing-library/react'; +import { beforeEach, describe, expect, it, vi } from 'vitest'; +import { CounterfactualView } from '@/features/ml/components/insights/CounterfactualView'; +import type { CounterfactualPayload } from '@/features/ml/train/counterfactual'; +import i18n from '@/lib/i18n'; + +// V68: each change is shown with its two readings, and a search that found +// nothing says what it tried. + +const payload = (over: Partial = {}): CounterfactualPayload => ({ + model: 'forest', + classes: ['no', 'yes'], + current: 0, + target: null, + columnsChanged: 1, + found: [ + { + changes: [{ column: 'pclass', from: '3', to: '1' }], + prediction: 1, + probability: 0.6234, + distance: 2.4, + far: false, + followed: { by: 4, of: 5 }, + }, + { + changes: [{ column: 'fare', from: '7.25', to: '512.33' }], + prediction: 1, + distance: 9.1, + far: true, + followed: { by: 1, of: 5 }, + }, + ], + tried: { columns: ['pclass', 'fare', 'age'], locked: ['sex'], rows: 131, pairs: false }, + untouched: ['name'], + ...over, +}); + +describe('CounterfactualView', () => { + beforeEach(async () => { + await i18n.changeLanguage('en'); + }); + + it('shows each change with the answer it gives and how many other models follow', () => { + render( undefined} />); + const box = screen.getByTestId('counterfactual'); + expect(box).toHaveAttribute('data-found', '2'); + expect(box).toHaveTextContent('What would have to change for the model to stop answering "no"'); + expect(screen.getByTestId('counterfactual-size')).toHaveTextContent('One column is enough'); + const items = screen.getAllByTestId('counterfactual-item'); + expect(items[0]).toHaveTextContent('pclass: 3 → 1'); + expect(items[0]).toHaveTextContent('The model then answers yes (62.3 %).'); + expect(items[0]).toHaveTextContent('4 of the 5 other models that agreed on this row follow.'); + expect(items[1]).toHaveTextContent('The model then answers yes.'); + }); + + it('flags a changed row that looks like no training row, and a change few models follow', () => { + render( undefined} />); + expect(screen.getAllByTestId('counterfactual-far')).toHaveLength(1); + expect(screen.getByTestId('counterfactual-far')).toHaveTextContent( + 'the model is answering where it has seen nothing', + ); + const followed = screen.getAllByTestId('counterfactual-followed'); + expect(followed[0]).not.toHaveClass('text-copper'); + expect(followed[1]).toHaveClass('text-copper'); + }); + + it('says which columns were left alone, and that it speaks of the model', () => { + render( undefined} />); + expect(screen.getByTestId('counterfactual-kept')).toHaveTextContent( + 'Left as they are because you locked them: sex. Never edited, being free text: name.', + ); + expect(screen.getByTestId('counterfactual')).toHaveTextContent( + 'A counterfactual speaks of the model, not of the world', + ); + }); + + it('hands the changes back to load them into the form', () => { + const apply = vi.fn(); + render(); + fireEvent.click(screen.getAllByTestId('counterfactual-apply')[0]); + expect(apply).toHaveBeenCalledWith([{ column: 'pclass', from: '3', to: '1' }]); + }); + + it('says when two columns were needed, and names the class asked for', () => { + render( + undefined} + />, + ); + expect(screen.getByTestId('counterfactual')).toHaveTextContent( + 'for the model to answer "high" instead of "low"', + ); + expect(screen.getByTestId('counterfactual-size')).toHaveTextContent( + 'No single column changes the answer. Two together do', + ); + expect(screen.getByTestId('counterfactual-item')).toHaveTextContent( + 'age: ∅ → 40 · city: paris → nice', + ); + expect(screen.queryByTestId('counterfactual-followed')).toBeNull(); + expect(screen.queryByTestId('counterfactual-far')).toBeNull(); + }); + + it('says what was tried when nothing flips, and when everything is locked', () => { + const { unmount } = render( + undefined} + />, + ); + expect(screen.getByTestId('counterfactual-none')).toHaveTextContent( + 'Nothing changes the answer by editing one or two of the 3 columns left open. 1,204 rows built from values of the training file were tried.', + ); + expect(screen.queryByTestId('counterfactual-kept')).toBeNull(); + unmount(); + render( + undefined} + />, + ); + expect(screen.getByTestId('counterfactual-none')).toHaveTextContent('Every column is locked'); + }); + + it('speaks French', async () => { + await i18n.changeLanguage('fr'); + render( undefined} />); + const box = screen.getByTestId('counterfactual'); + expect(box).toHaveTextContent('pour que le modèle cesse de répondre « no »'); + expect(screen.getAllByTestId('counterfactual-item')[0]).toHaveTextContent( + "Le modèle répond alors yes (62,3 %). 4 des 5 autres modèles d'accord sur cette ligne suivent.", + ); + expect(box).toHaveTextContent('Un contrefactuel parle du modèle, pas du monde'); + }); +}); diff --git a/src/features/ml/components/insights/CounterfactualView.tsx b/src/features/ml/components/insights/CounterfactualView.tsx new file mode 100644 index 0000000..41f2e7f --- /dev/null +++ b/src/features/ml/components/insights/CounterfactualView.tsx @@ -0,0 +1,120 @@ +import { useTranslation } from 'react-i18next'; +import { Button } from '@/components/ui/button'; +import type { Change, CounterfactualPayload } from '@/features/ml/train/counterfactual'; + +/** + * V68: what would have to change for the model to answer another class. Each + * change comes with its two readings: does the changed row still look like a + * training row, and do the other models follow. + */ +export function CounterfactualView({ + payload, + onApply, +}: { + payload: CounterfactualPayload; + onApply: (changes: Change[]) => void; +}) { + const { t, i18n } = useTranslation(); + const lang = i18n.resolvedLanguage ?? 'en'; + const name = (index: number) => payload.classes[index] ?? String(index); + const percent = (value: number) => + (value * 100).toLocaleString(lang, { maximumFractionDigits: 1 }); + const { tried } = payload; + + return ( +
+

+ {payload.target === null + ? t('ml.lab.counterfactual.titleAny', { current: name(payload.current) }) + : t('ml.lab.counterfactual.titleTarget', { + current: name(payload.current), + target: name(payload.target), + })} +

+ + {payload.found.length === 0 ? ( +

+ {tried.columns.length === 0 + ? t('ml.lab.counterfactual.allLocked') + : t('ml.lab.counterfactual.none', { + count: tried.columns.length, + rows: tried.rows.toLocaleString(lang), + })} +

+ ) : ( + <> +

+ {t( + payload.columnsChanged === 1 + ? 'ml.lab.counterfactual.oneColumn' + : 'ml.lab.counterfactual.twoColumns', + )} +

+
    + {payload.found.map((item, i) => ( +
  • + + {item.changes + .map((change) => `${change.column}: ${change.from || '∅'} → ${change.to}`) + .join(' · ')} + + + {item.probability === undefined + ? t('ml.lab.counterfactual.answers', { class: name(item.prediction) }) + : t('ml.lab.counterfactual.answersProba', { + class: name(item.prediction), + percent: percent(item.probability), + })}{' '} + {item.followed.of > 0 && ( + + {t('ml.lab.counterfactual.followed', { + by: item.followed.by, + count: item.followed.of, + })} + + )} + + {item.far && ( + + {t('ml.lab.counterfactual.far')} + + )} + + + +
  • + ))} +
+ + )} + + {(tried.locked.length > 0 || payload.untouched.length > 0) && ( +

+ {[ + tried.locked.length > 0 && + t('ml.lab.counterfactual.locked', { list: tried.locked.join(', ') }), + payload.untouched.length > 0 && + t('ml.lab.counterfactual.untouched', { list: payload.untouched.join(', ') }), + ] + .filter(Boolean) + .join(' ')} +

+ )} +

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

+
+ ); +} diff --git a/src/features/ml/components/insights/WhatIfPanel.tsx b/src/features/ml/components/insights/WhatIfPanel.tsx index e02101b..929b0f4 100644 --- a/src/features/ml/components/insights/WhatIfPanel.tsx +++ b/src/features/ml/components/insights/WhatIfPanel.tsx @@ -1,9 +1,10 @@ -import { Footprints, Sparkles } from 'lucide-react'; +import { Footprints, Shuffle, 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 { CounterfactualView } from '@/features/ml/components/insights/CounterfactualView'; import { GlassBoxView, isReplayable } from '@/features/ml/components/insights/GlassBoxView'; import { useLabStore } from '@/features/ml/lab-store'; @@ -19,6 +20,8 @@ export function WhatIfPanel() { const requestExplanation = useLabStore((s) => s.requestExplanation); const replay = useLabStore((s) => s.replay); const requestReplay = useLabStore((s) => s.requestReplay); + const counterfactual = useLabStore((s) => s.counterfactual); + const requestCounterfactual = useLabStore((s) => s.requestCounterfactual); const featureProfiles = useMemo( () => (summary?.featureColumns ?? []).map((name) => profiles.find((p) => p.name === name)!), @@ -38,6 +41,9 @@ export function WhatIfPanel() { // The parent remounts this panel (via `key`) when the inspected model or the // feature set changes, so initializing from the defaults once is enough. const [values, setValues] = useState(defaults); + // V68: the columns the search for a change must leave alone, and the class wanted. + const [locked, setLocked] = useState([]); + const [target, setTarget] = useState(null); const model = insights?.model; useEffect(() => { @@ -47,6 +53,8 @@ export function WhatIfPanel() { }, [values, model, requestWhatIf]); if (!summary || !insights) return null; + const classes = insights.classes ?? []; + const isClassification = classes.length > 0; return (
{featureProfiles.map((profile) => ( -
@@ -117,6 +164,39 @@ export function WhatIfPanel() { {t('ml.lab.glass.button')} )} + {!counterfactual && isClassification && ( + + + {classes.length > 2 && ( + + )} + + )} {whatIf.probabilities && (
{whatIf.probabilities.slice(0, 3).map(({ label, p }) => ( @@ -191,6 +271,18 @@ export function WhatIfPanel() {
)} + {counterfactual && counterfactual.model === insights.model && ( + + setValues((current) => { + const next = { ...current }; + for (const change of changes) next[change.column] = change.to; + return next; + }) + } + /> + )} {replay && replay.model === insights.model && } {whatIf && whatIf.model === insights.model && !isReplayable(insights.model) && (

diff --git a/src/features/ml/data/parse.worker.ts b/src/features/ml/data/parse.worker.ts index 375e525..08e3d1a 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 { counterfactualsFor, type CounterfactualCache } from '@/features/ml/train/counterfactual'; import { replayRow, type GlassBoxCache } from '@/features/ml/train/glass-box'; import { buildSubmission } from '@/features/ml/train/submission'; import { refitOnAllRows } from '@/features/ml/train/refit'; @@ -55,6 +56,8 @@ let lastFeatureColumns: string[] = []; let datasetName = ''; /** v22: a model rebuilt from an export — fully independent of any run. */ let imported: ImportedModel | null = null; +/** V68: the observed values and the cloud of training rows, once per run. */ +let counterfactualCache: CounterfactualCache = {}; /** 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. */ @@ -334,6 +337,7 @@ self.onmessage = async (event: MessageEvent) => { if (outcome) { artifacts = outcome.artifacts; glassCache = {}; + counterfactualCache = {}; lastConfig = request.config; lastFeatureColumns = outcome.summary.featureColumns; post({ @@ -380,6 +384,20 @@ self.onmessage = async (event: MessageEvent) => { glassCache, ), }); + } else if (request.kind === 'counterfactual') { + if (!artifacts) throw new Error('no-run'); + post({ + kind: 'counterfactual-result', + payload: counterfactualsFor( + artifacts, + request.model, + request.values, + request.locked, + request.target, + columnsAsMap(), + counterfactualCache, + ), + }); } 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 bad66fb..0dfa5b6 100644 --- a/src/features/ml/lab-store.ts +++ b/src/features/ml/lab-store.ts @@ -306,6 +306,7 @@ export const useLabStore = create((set, get) => { whatIf: null, explanation: null, replay: null, + counterfactual: null, batchStatus: 'idle', batchResult: null, batchError: null, @@ -337,6 +338,12 @@ export const useLabStore = create((set, get) => { send({ kind: 'explain', model: state.insights.model, values }); }, + requestCounterfactual(values, locked, target) { + const state = get(); + if (state.trainStatus !== 'done' || !state.insights) return; + send({ kind: 'counterfactual', model: state.insights.model, values, locked, target }); + }, + requestReplay(values) { const state = get(); if (state.trainStatus !== 'done' || !state.insights) return; diff --git a/src/features/ml/store/fence.ts b/src/features/ml/store/fence.ts index f3b0cc4..849d8ab 100644 --- a/src/features/ml/store/fence.ts +++ b/src/features/ml/store/fence.ts @@ -18,6 +18,7 @@ const RUN_DERIVED = new Set([ 'what-if-result', 'explanation', 'replay-result', + 'counterfactual-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 ffad9e3..4efffb6 100644 --- a/src/features/ml/store/responses.test.ts +++ b/src/features/ml/store/responses.test.ts @@ -40,9 +40,14 @@ const CASES: [string, WorkerResponse, Partial][] = [ [ 'what-if-result', { kind: 'what-if-result', payload }, - { whatIf: payload, explanation: null, replay: null }, + { whatIf: payload, explanation: null, replay: null, counterfactual: null }, ], ['replay-result', { kind: 'replay-result', payload }, { replay: payload }], + [ + 'counterfactual-result', + { kind: 'counterfactual-result', payload }, + { counterfactual: 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 9ef3408..a4735d1 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, replay: null }); + set({ whatIf: message.payload, explanation: null, replay: null, counterfactual: null }); + }, + 'counterfactual-result': (message) => { + // Row-level and tied to the screen, like the replay: shown, saved nowhere. + set({ counterfactual: message.payload }); }, 'replay-result': (message) => { // Row-level and tied to the screen: it is shown, and saved nowhere. diff --git a/src/features/ml/store/state.ts b/src/features/ml/store/state.ts index 97117ac..67644ad 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 { CounterfactualPayload } from '@/features/ml/train/counterfactual'; import type { GlassBoxPayload } from '@/features/ml/train/glass-box'; import type { ShapleyExplanation } from '@/features/ml/train/shapley'; import type { @@ -89,6 +90,8 @@ export interface LabState { explanation: ShapleyExplanation | null; /** V66: the latest what-if row replayed step by step (cleared with it). */ replay: GlassBoxPayload | null; + /** V68: what would have to change for that row (cleared with it). */ + counterfactual: CounterfactualPayload | null; tuneStatus: 'idle' | 'running' | 'done'; tuneProgress: { done: number; total: number; bestCv: number | null } | null; tuneOutcome: TuneOutcome | null; @@ -164,6 +167,11 @@ export interface LabState { requestWhatIf: (values: Record) => void; requestExplanation: (values: Record) => void; requestReplay: (values: Record) => void; + requestCounterfactual: ( + values: Record, + locked: string[], + target: number | null, + ) => void; tune: (model: TunableKey) => void; cancelTune: () => void; learningCurve: (model: ModelKey) => void; @@ -215,6 +223,7 @@ export const initialTraining = { whatIf: null, explanation: null, replay: null as GlassBoxPayload | null, + counterfactual: null as CounterfactualPayload | null, tuneStatus: 'idle' as const, tuneProgress: null, tuneOutcome: null, diff --git a/src/features/ml/train/counterfactual.test.ts b/src/features/ml/train/counterfactual.test.ts new file mode 100644 index 0000000..8a71282 --- /dev/null +++ b/src/features/ml/train/counterfactual.test.ts @@ -0,0 +1,237 @@ +import { describe, expect, it } from 'vitest'; +import { profileColumn } from '@/features/ml/data/profile'; +import { + counterfactualsFor, + observedValues, + searchCounterfactuals, + type Answer, + type CandidateColumn, + type SearchInput, +} from '@/features/ml/train/counterfactual'; +import { runTraining, type TrainArtifacts } from '@/features/ml/train/trainer'; +import type { Cell } from '@/features/ml/data/types'; + +// V68: the smallest change that flips the model, among values the training +// rows hold, leaving locked columns alone, and saying so when nothing flips. + +const columns: CandidateColumn[] = [ + { name: 'income', kind: 'numeric', values: ['20', '30', '40', '50', '60', '70'], scale: 10 }, + { name: 'age', kind: 'numeric', values: ['20', '30', '40', '50'], scale: 10 }, + { name: 'city', kind: 'category', values: ['paris', 'lyon', 'nice'] }, +]; + +/** A rule the test can read: yes when income >= 50, or when in nice and aged 40 or more. */ +function rule(row: Record): Answer { + const yes = Number(row.income) >= 50 || (row.city === 'nice' && Number(row.age) >= 40); + return { label: yes ? 1 : 0, probability: yes ? 0.8 : 0.7 }; +} + +function input(over: Partial = {}): SearchInput { + return { + values: { income: '30', age: '40', city: 'paris' }, + columns, + locked: new Set(), + current: 0, + target: null, + predict: (rows) => rows.map(rule), + ...over, + }; +} + +describe('observedValues', () => { + it('keeps the distinct numbers in order, one per value, both ends included', () => { + expect(observedValues(['3', '1', '', null, '2', '3.0', 'x', '1'], 'numeric', 10)).toEqual([ + '1', + '2', + '3', + ]); + const many = Array.from({ length: 101 }, (_, i) => String(i)); + const picked = observedValues(many, 'numeric', 5); + expect(picked).toEqual(['0', '25', '50', '75', '100']); + }); + + it('gives the categories most frequent first, capped', () => { + expect(observedValues(['b', 'a', 'b', 'c', 'a', 'b', ' '], 'category', 2)).toEqual(['b', 'a']); + }); +}); + +describe('searchCounterfactuals', () => { + it('finds the nearest value of each column that flips, smallest change first', () => { + const result = searchCounterfactuals(input()); + expect(result.columnsChanged).toBe(1); + expect(result.found.map((item) => item.changes)).toEqual([ + [{ column: 'city', from: 'paris', to: 'nice' }], + [{ column: 'income', from: '30', to: '50' }], + ]); + expect(result.found[0].distance).toBe(1); + expect(result.found[1].distance).toBe(2); + expect(result.found[0]).toMatchObject({ prediction: 1, probability: 0.8 }); + // Age alone flips nothing here, and is not invented. + expect(result.found.some((item) => item.changes[0].column === 'age')).toBe(false); + }); + + it('returns only changes that do flip the model', () => { + const result = searchCounterfactuals(input()); + for (const item of result.found) { + const row = { ...input().values }; + for (const change of item.changes) row[change.column] = change.to; + expect(rule(row).label).toBe(item.prediction); + expect(item.prediction).not.toBe(0); + } + }); + + it('never changes a locked column', () => { + const result = searchCounterfactuals(input({ locked: new Set(['city']) })); + expect(result.found.map((item) => item.changes[0].column)).toEqual(['income']); + expect(result.tried.locked).toEqual(['city']); + expect(result.tried.columns).toEqual(['income', 'age']); + }); + + it('tries two columns only when no single one flips', () => { + const result = searchCounterfactuals( + input({ values: { income: '30', age: '20', city: 'paris' }, locked: new Set(['income']) }), + ); + expect(result.columnsChanged).toBe(2); + expect(result.tried.pairs).toBe(true); + expect(result.found).toHaveLength(1); + expect(result.found[0].changes).toEqual([ + { column: 'age', from: '20', to: '40' }, + { column: 'city', from: 'paris', to: 'nice' }, + ]); + expect(result.found[0].distance).toBe(3); + }); + + it('says so when nothing flips, with what was tried', () => { + const result = searchCounterfactuals( + input({ predict: (rows) => rows.map(() => ({ label: 0 })) }), + ); + expect(result.found).toEqual([]); + expect(result.columnsChanged).toBe(0); + expect(result.tried.rows).toBeGreaterThan(10); + const allLocked = searchCounterfactuals(input({ locked: new Set(['income', 'age', 'city']) })); + expect(allLocked.found).toEqual([]); + expect(allLocked.tried.columns).toEqual([]); + expect(allLocked.tried.rows).toBe(0); + }); + + it('only tries values the training rows hold', () => { + const seen: Record[] = []; + searchCounterfactuals( + input({ + predict: (rows) => { + seen.push(...rows); + return rows.map(() => ({ label: 0 })); + }, + }), + ); + for (const row of seen) { + for (const column of columns) { + expect([...column.values, input().values[column.name]]).toContain(row[column.name]); + } + } + }); + + it('reaches the class asked for, not just any other', () => { + const three = (row: Record): Answer => ({ + label: Number(row.income) >= 60 ? 2 : Number(row.income) >= 40 ? 1 : 0, + }); + const any = searchCounterfactuals(input({ predict: (rows) => rows.map(three) })); + expect(any.found[0].changes[0]).toMatchObject({ column: 'income', to: '40' }); + expect(any.found[0].prediction).toBe(1); + const wanted = searchCounterfactuals(input({ predict: (rows) => rows.map(three), target: 2 })); + expect(wanted.found[0].changes[0]).toMatchObject({ column: 'income', to: '60' }); + expect(wanted.found[0].prediction).toBe(2); + }); + + it('prefers a change that still looks like a training row, and flags the one that does not', () => { + // Nice is declared far: income becomes the first answer, nice has no other value and is flagged. + const result = searchCounterfactuals( + input({ far: (row) => row.city === 'nice' || row.income === '50' }), + ); + expect(result.found.map((item) => [item.changes[0].to, item.far])).toEqual([ + ['60', false], + ['nice', true], + ]); + }); + + it('gives the same answer twice', () => { + expect(searchCounterfactuals(input())).toEqual(searchCounterfactuals(input())); + }); +}); + +describe('counterfactualsFor', () => { + const N = 240; + const income = Array.from({ length: N }, (_, i) => String(20 + ((i * 53) % 90))); + const age = Array.from({ length: N }, (_, i) => String(18 + ((i * 37) % 60))); + const city = Array.from({ length: N }, (_, i) => ['paris', 'lyon', 'nice'][(i * 7) % 3]); + const note = Array.from({ length: N }, (_, i) => `free words about row number ${i} here`); + const label = income.map((value) => (Number(value) >= 65 ? 'yes' : 'no')); + const amount = income.map((value, i) => String(Number(value) * 2 + (i % 3))); + + async function run(target: string, data: Record) { + const table = new Map(Object.entries(data)); + const profiles = Object.entries(data).map(([name, cells]) => profileColumn(name, cells)); + const outcome = await runTraining( + table, + profiles, + { target, features: ['income', 'age', 'city', 'note'], seed: 3, testRatio: 0.2 }, + { onModelStart() {}, onModelResult() {}, isCancelled: () => false }, + ); + return { artifacts: outcome!.artifacts as TrainArtifacts, table }; + } + + it('flips the inspected model with values of the file, reads the other models, and leaves text alone', async () => { + const { artifacts, table } = await run('label', { income, age, city, note, label }); + const values = { income: '30', age: '40', city: 'paris', note: 'free words' }; + const cache = {}; + for (const key of ['tree', 'logistic', 'gbdt', 'knn'] as const) { + const payload = counterfactualsFor(artifacts, key, values, [], null, table, cache)!; + expect(artifacts.classes[payload.current]).toBe('no'); + expect(payload.untouched).toEqual(['note']); + expect(payload.found.length).toBeGreaterThan(0); + const model = artifacts.models.get(key)!; + for (const item of payload.found) { + const changed: Record = { ...values }; + for (const change of item.changes) { + changed[change.column] = change.to; + expect(change.column).not.toBe('note'); + expect(table.get(change.column)).toContain(change.to); + } + expect(model.predict([artifacts.pipeline.transformRow(changed)])[0]).toBe(item.prediction); + expect(artifacts.classes[item.prediction]).toBe('yes'); + expect(item.followed.by).toBeLessThanOrEqual(item.followed.of); + expect(typeof item.far).toBe('boolean'); + } + // The rule is on income: the first change is on income, and it is a real one. + expect(payload.found[0].changes[0].column).toBe('income'); + expect(Number(payload.found[0].changes[0].to)).toBeGreaterThan(30); + } + }); + + it('leaves a locked column alone and says which', async () => { + const { artifacts, table } = await run('label', { income, age, city, note, label }); + const values = { income: '30', age: '40', city: 'paris', note: 'free words' }; + const payload = counterfactualsFor(artifacts, 'tree', values, ['income'], null, table)!; + expect(payload.tried.locked).toEqual(['income']); + for (const item of payload.found) { + expect(item.changes.some((change) => change.column === 'income')).toBe(false); + } + }); + + it('has nothing to say of a regression, and refuses a model that is not there', async () => { + const { artifacts, table } = await run('amount', { income, age, city, note, amount }); + const values = { income: '30', age: '40', city: 'paris', note: 'x' }; + expect(counterfactualsFor(artifacts, 'tree', values, [], null, table)).toBeNull(); + const classification = await run('label', { income, age, city, note, label }); + expect(() => + counterfactualsFor( + { ...classification.artifacts, models: new Map() }, + 'tree', + values, + [], + null, + classification.table, + ), + ).toThrow('model-not-found'); + }); +}); diff --git a/src/features/ml/train/counterfactual.ts b/src/features/ml/train/counterfactual.ts new file mode 100644 index 0000000..9659b13 --- /dev/null +++ b/src/features/ml/train/counterfactual.ts @@ -0,0 +1,486 @@ +/** + * V68: counterfactuals. For one row, the smallest change of its values that + * makes the inspected model answer another class. + * + * The what-if panel says what the model predicts, Shapley (V28) what weighed, + * the glass box (V66) what happened. This answers the question a person told + * "no" actually asks: what would have had to be different? + * + * A search, not an optimisation, and one a reader can follow: + * + * 1. one column at a time: each value OBSERVED in the training rows is tried + * in the place of the row's own; a column keeps the nearest value that + * flips the answer; + * 2. only when no single column flips it: two columns at a time, on a + * thinner grid of the same observed values; + * 3. never three. A change of five columns is no longer an explanation. + * + * Rules the code keeps: + * - a column the user locked is never changed; the lab does not guess that + * an age or a sex cannot change; + * - a value tried is a value some training row holds: no interpolation, no + * number outside the file, no category that does not exist. Free text is + * never edited; + * - nothing found is an answer too, returned with what was tried. + * + * A counterfactual speaks of the model, not of the world: "the model would + * answer yes" is not "do this and you will get yes". Two readings are given + * with each one, because the measure showed they were needed (see PLAN.md, + * V68): whether the changed row still looks like a training row, and how many + * of the other trained models follow the same change. + * + * Measured before the panel, four classification demos, 60 test rows per run, + * seven families: one column is enough on 63 to 100 % of the rows of three + * demos and two are needed on up to 69 %; on reviews most families find + * nothing, the answer being in the text; a search costs 30 ms at most. The + * nearest change was farther from every training row than training rows are + * from each other on 8 to 60 % of the rows, hence `far` and the preference + * for a change that is not; and 14 to 54 % of the other models followed it, + * hence `followed`. + * + * Pure and deterministic. + */ +import type { Cell } from '@/features/ml/data/types'; +import type { TrainArtifacts } from '@/features/ml/train/trainer'; +import type { ModelKey } from '@/features/ml/train/types'; + +/** How many distinct observed values a column offers the one-column search. */ +export const SINGLE_GRID = 40; +/** And each column of a pair: the pair search is quadratic in this. */ +export const PAIR_GRID = 10; +/** How many counterfactuals are returned at most. */ +export const KEPT = 3; + +export interface CandidateColumn { + name: string; + kind: 'numeric' | 'category'; + /** Values observed in the training rows, as written in the file. */ + values: string[]; + /** Numeric: the standard deviation of the column, to compare changes across columns. */ + scale?: number; +} + +export interface Change { + column: string; + from: string; + to: string; +} + +export interface Counterfactual { + changes: Change[]; + /** The class the model answers once the changes are made. */ + prediction: number; + /** Its probability, when the family gives one. */ + probability?: number; + /** Number of columns first, then this: changes in standard deviations, 1 per category. */ + distance: number; + /** + * The changed row is farther from every training row than training rows + * usually are from each other: the model is answering where it saw nothing. + * Absent when the caller gave no way to tell. + */ + far?: boolean; +} + +export interface Answer { + label: number; + probability?: number; +} + +export interface SearchInput { + /** The row, as the what-if form holds it. */ + values: Record; + columns: CandidateColumn[]; + locked: ReadonlySet; + /** What the model answers for the row as it is. */ + current: number; + /** The class wanted, or null for any class other than the current one. */ + target: number | null; + /** The model: one answer per row, in order. */ + predict(rows: Record[]): Answer[]; + /** + * Whether a changed row is far from every training row. When given, a + * column keeps its nearest flipping value that is NOT far, and falls back + * on a far one, flagged, only when it has no other. + */ + far?(row: Record): boolean; +} + +export interface SearchResult { + found: Counterfactual[]; + /** 1 when one column was enough, 2 when pairs were needed, 0 when nothing flips. */ + columnsChanged: 0 | 1 | 2; + /** What was tried, for the refusal to say so. */ + tried: { columns: string[]; locked: string[]; rows: number; pairs: boolean }; +} + +function asNumber(text: string): number { + const value = Number(text.trim().replace(',', '.')); + return Number.isFinite(value) ? value : Number.NaN; +} + +/** + * Up to `limit` of the distinct values a column holds in the training rows: + * for a number, evenly spread over the sorted distinct values, both ends + * kept; for a category, the most frequent first. + */ +export function observedValues( + cells: readonly (string | null | undefined)[], + kind: CandidateColumn['kind'], + limit: number, +): string[] { + const counts = new Map(); + for (const cell of cells) { + const text = (cell ?? '').trim(); + if (text === '') continue; + counts.set(text, (counts.get(text) ?? 0) + 1); + } + if (kind === 'category') { + return [...counts.entries()] + .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])) + .slice(0, limit) + .map(([value]) => value); + } + const numbers = [...counts.keys()] + .map((text) => ({ text, value: asNumber(text) })) + .filter((item) => !Number.isNaN(item.value)) + .sort((a, b) => a.value - b.value || a.text.localeCompare(b.text)); + // The same number written twice ("3" and "3.0") is one value. + const distinct = numbers.filter((item, i) => i === 0 || item.value !== numbers[i - 1].value); + if (distinct.length <= limit) return distinct.map((item) => item.text); + const picked: string[] = []; + for (let i = 0; i < limit; i++) { + picked.push(distinct[Math.round((i * (distinct.length - 1)) / (limit - 1))].text); + } + return [...new Set(picked)]; +} + +/** How far one change is: in standard deviations for a number, 1 for a category. */ +function changeDistance(column: CandidateColumn, from: string, to: string): number { + if (column.kind === 'category') return 1; + const a = asNumber(from); + const b = asNumber(to); + if (Number.isNaN(a) || Number.isNaN(b)) return 1; + return Math.abs(a - b) / (column.scale && column.scale > 0 ? column.scale : 1); +} + +function same(column: CandidateColumn, a: string, b: string): boolean { + if (column.kind === 'numeric') { + const x = asNumber(a); + const y = asNumber(b); + if (!Number.isNaN(x) && !Number.isNaN(y)) return x === y; + } + return a.trim() === b.trim(); +} + +/** A thinner grid for the pair search: evenly spread, order kept. */ +function thin(values: string[], limit: number): string[] { + if (values.length <= limit) return values; + const picked: string[] = []; + for (let i = 0; i < limit; i++) { + picked.push(values[Math.round((i * (values.length - 1)) / (limit - 1))]); + } + return [...new Set(picked)]; +} + +interface Flip { + row: Record; + answer: Answer; + changes: Change[]; + distance: number; +} + +/** + * Of the changes that flip the answer, the nearest one whose row still looks + * like a training row; a far one, flagged, only when there is no other. The + * flips are walked nearest first, so `far` is asked as few times as possible. + */ +function nearest(flips: Flip[], far: SearchInput['far']): Counterfactual | null { + if (flips.length === 0) return null; + // A stable sort: among equal distances the order of the candidates holds, + // which for a category is most frequent first. + const ordered = [...flips].sort((a, b) => a.distance - b.distance); + const build = (flip: Flip, isFar?: boolean): Counterfactual => ({ + changes: flip.changes, + prediction: flip.answer.label, + ...(flip.answer.probability !== undefined && { probability: flip.answer.probability }), + distance: flip.distance, + ...(isFar !== undefined && { far: isFar }), + }); + if (!far) return build(ordered[0]); + for (const flip of ordered) if (!far(flip.row)) return build(flip, false); + return build(ordered[0], true); +} + +/** Plausible first, then the smallest change. */ +function byRank(a: Counterfactual, b: Counterfactual): number { + return Number(a.far ?? false) - Number(b.far ?? false) || a.distance - b.distance; +} + +export function searchCounterfactuals(input: SearchInput): SearchResult { + const { values, current, target, predict } = input; + const open = input.columns.filter( + (column) => !input.locked.has(column.name) && column.values.length > 0, + ); + const flips = (answer: Answer) => + target === null ? answer.label !== current : answer.label === target; + let rows = 0; + + // --- One column at a time --------------------------------------------------- + const singles: Counterfactual[] = []; + for (const column of open) { + const from = values[column.name] ?? ''; + const tries = column.values.filter((value) => !same(column, value, from)); + if (tries.length === 0) continue; + const answers = predict(tries.map((to) => ({ ...values, [column.name]: to }))); + rows += tries.length; + // The nearest value that flips; candidates come most-frequent-first for a + // category, so among equals the commonest wins. + const best = nearest( + tries.flatMap((to, i) => + flips(answers[i]) + ? [ + { + row: { ...values, [column.name]: to }, + answer: answers[i], + changes: [{ column: column.name, from, to }], + distance: changeDistance(column, from, to), + }, + ] + : [], + ), + input.far, + ); + if (best !== null) singles.push(best); + } + const tried = { + columns: open.map((column) => column.name), + locked: input.columns + .filter((column) => input.locked.has(column.name)) + .map((column) => column.name), + }; + if (singles.length > 0) { + singles.sort((a, b) => byRank(a, b) || a.changes[0].column.localeCompare(b.changes[0].column)); + return { + found: singles.slice(0, KEPT), + columnsChanged: 1, + tried: { ...tried, rows, pairs: false }, + }; + } + + // --- Two columns at a time --------------------------------------------------- + const pairs: Counterfactual[] = []; + for (let a = 0; a < open.length; a++) { + for (let b = a + 1; b < open.length; b++) { + const first = open[a]; + const second = open[b]; + const fromA = values[first.name] ?? ''; + const fromB = values[second.name] ?? ''; + const triesA = thin(first.values, PAIR_GRID).filter((value) => !same(first, value, fromA)); + const triesB = thin(second.values, PAIR_GRID).filter((value) => !same(second, value, fromB)); + const batch: { toA: string; toB: string }[] = []; + for (const toA of triesA) for (const toB of triesB) batch.push({ toA, toB }); + if (batch.length === 0) continue; + const answers = predict( + batch.map(({ toA, toB }) => ({ ...values, [first.name]: toA, [second.name]: toB })), + ); + rows += batch.length; + const best = nearest( + batch.flatMap(({ toA, toB }, i) => + flips(answers[i]) + ? [ + { + row: { ...values, [first.name]: toA, [second.name]: toB }, + answer: answers[i], + changes: [ + { column: first.name, from: fromA, to: toA }, + { column: second.name, from: fromB, to: toB }, + ], + distance: changeDistance(first, fromA, toA) + changeDistance(second, fromB, toB), + }, + ] + : [], + ), + input.far, + ); + if (best !== null) pairs.push(best); + } + } + pairs.sort( + (a, b) => + byRank(a, b) || + a.changes + .map((change) => change.column) + .join() + .localeCompare(b.changes.map((change) => change.column).join()), + ); + return { + found: pairs.slice(0, KEPT), + columnsChanged: pairs.length > 0 ? 2 : 0, + tried: { ...tried, rows, pairs: true }, + }; +} + +// --- One row, one model: what the worker answers --------------------------------- + +/** A counterfactual with the second reading: do the other models follow? */ +export interface ReadCounterfactual extends Counterfactual { + /** + * Of the other trained models that answered like this one for the row as it + * was, how many answer the new class once the changes are made. A change + * few models follow is an edge of this model, not a rule of the data. + */ + followed: { by: number; of: number }; +} + +export interface CounterfactualPayload { + model: ModelKey; + classes: string[]; + current: number; + target: number | null; + found: ReadCounterfactual[]; + columnsChanged: SearchResult['columnsChanged']; + tried: SearchResult['tried']; + /** Columns the search never edits: free text. */ + untouched: string[]; +} + +/** What a search computes once per run and reuses for every row. */ +export interface CounterfactualCache { + columns?: CandidateColumn[]; + untouched?: string[]; + /** A sample of the encoded training rows, and how far apart they usually are. */ + cloud?: { rows: number[][]; reach: number } | null; +} + +/** Enough rows to know the cloud, few enough to ask it thousands of times. */ +const CLOUD_ROWS = 400; +/** A row is far when it is farther from the cloud than 95 % of the cloud's own rows are. */ +const CLOUD_SHARE = 0.95; + +function squared(a: readonly number[], b: readonly number[]): number { + let sum = 0; + for (let j = 0; j < a.length; j++) sum += (a[j] - b[j]) ** 2; + return sum; +} + +function nearestSquared(row: readonly number[], rows: readonly number[][], skip = -1): number { + let best = Number.POSITIVE_INFINITY; + for (let i = 0; i < rows.length; i++) { + if (i === skip) continue; + const distance = squared(row, rows[i]); + if (distance < best) best = distance; + } + return best; +} + +/** Null for a regression: "another class" has no meaning for a value. */ +export function counterfactualsFor( + artifacts: TrainArtifacts, + modelKey: ModelKey, + values: Record, + locked: readonly string[], + target: number | null, + columns: Map, + cache: CounterfactualCache = {}, +): CounterfactualPayload | null { + if (!artifacts.isClassification) return null; + const model = artifacts.models.get(modelKey); + if (!model) throw new Error('model-not-found'); + const { pipeline, classes } = artifacts; + const fitted = artifacts.fitIndices?.[modelKey] ?? artifacts.trainIndices ?? []; + + if (cache.columns === undefined) { + const candidates: CandidateColumn[] = []; + const untouched: string[] = []; + for (const spec of pipeline.specs) { + if (spec.kind === 'text') { + untouched.push(spec.name); + continue; + } + const kind = spec.kind === 'numeric' ? 'numeric' : 'category'; + const cells = columns.get(spec.name) ?? []; + candidates.push({ + name: spec.name, + kind, + values: observedValues( + (artifacts.trainIndices ?? []).map((index) => cells[index] as string | null), + kind, + SINGLE_GRID, + ), + ...(spec.kind === 'numeric' && { scale: spec.std }), + }); + } + cache.columns = candidates; + cache.untouched = untouched; + } + if (cache.cloud === undefined) { + cache.cloud = null; + if (fitted.length > 1) { + const step = Math.max(1, Math.floor(fitted.length / CLOUD_ROWS)); + const rows = pipeline.transform(fitted.filter((_, i) => i % step === 0).slice(0, CLOUD_ROWS)); + const apart = rows.map((row, i) => nearestSquared(row, rows, i)).sort((a, b) => a - b); + cache.cloud = { rows, reach: apart[Math.floor((apart.length - 1) * CLOUD_SHARE)] }; + } + } + const cloud = cache.cloud; + + const encode = (rows: Record[]) => rows.map((row) => pipeline.transformRow(row)); + const answer = (rows: Record[]): Answer[] => { + const x = encode(rows); + const both = model.predictWithProba?.(x); + const labels = both?.labels ?? model.predict(x); + const proba = both?.proba ?? model.predictProba?.(x); + return labels.map((label, i) => ({ + label, + ...(proba && { probability: proba[i][label] ?? 0 }), + })); + }; + const [{ label: current }] = answer([values]); + + const result = searchCounterfactuals({ + values, + columns: cache.columns, + locked: new Set(locked), + current, + target: target === current ? null : target, + predict: answer, + ...(cloud && { + far: (row: Record) => + nearestSquared(pipeline.transformRow(row), cloud.rows) > cloud.reach, + }), + }); + + // The other families that answered like this one for the row as it was. + const [before] = encode([values]); + const peers = [...artifacts.models.entries()].filter( + ([key, peer]) => + key !== modelKey && + key !== 'baseline' && + key !== 'ensemble' && + peer.predict([before])[0] === current, + ); + const found = result.found.map((item): ReadCounterfactual => { + const changed = { ...values }; + for (const change of item.changes) changed[change.column] = change.to; + const [x] = encode([changed]); + return { + ...item, + followed: { + by: peers.filter(([, peer]) => peer.predict([x])[0] === item.prediction).length, + of: peers.length, + }, + }; + }); + + return { + model: modelKey, + classes, + current, + target: target === current ? null : target, + found, + columnsChanged: result.columnsChanged, + tried: result.tried, + untouched: cache.untouched ?? [], + }; +} diff --git a/src/features/ml/worker-protocol.ts b/src/features/ml/worker-protocol.ts index 7d69804..3691feb 100644 --- a/src/features/ml/worker-protocol.ts +++ b/src/features/ml/worker-protocol.ts @@ -19,6 +19,7 @@ import type { MulticlassDecisionPolicy } from '@/features/ml/train/multiclass-de 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 { CounterfactualPayload } from '@/features/ml/train/counterfactual'; import type { InsightsPayload, MetricMap, @@ -44,6 +45,14 @@ export type WorkerRequest = | { kind: 'explain'; model: ModelKey; values: Record } /** V66: the same row, replayed step by step through the inspected model. */ | { kind: 'replay'; model: ModelKey; values: Record } + /** V68: the smallest change of that row that makes the model answer another class. */ + | { + kind: 'counterfactual'; + model: ModelKey; + values: Record; + locked: string[]; + target: number | null; + } | { kind: 'tune'; model: TunableKey; config: TrainConfig } | { kind: 'cancel-tune' } // v26: learning curve — retrain on growing seeded prefixes of the train split. @@ -125,6 +134,8 @@ export type WorkerResponse = | { kind: 'what-if-result'; payload: WhatIfResult } | { kind: 'explanation'; payload: ShapleyExplanation } | { kind: 'replay-result'; payload: GlassBoxPayload } + // null = a regression: there is no other class to reach. + | { kind: 'counterfactual-result'; payload: CounterfactualPayload | null } | { 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 328ae49..a800852 100644 --- a/src/locales/en.json +++ b/src/locales/en.json @@ -768,6 +768,29 @@ }, "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." }, + "counterfactual": { + "button": "What would have to change?", + "lock": "locked", + "lockTitle": "Locked: the search for a change leaves this column as it is", + "target": "Class wanted", + "targetAny": "any other class", + "titleAny": "What would have to change for the model to stop answering \"{{current}}\"", + "titleTarget": "What would have to change for the model to answer \"{{target}}\" instead of \"{{current}}\"", + "oneColumn": "One column is enough. The smallest changes, each on its own:", + "twoColumns": "No single column changes the answer. Two together do:", + "answers": "The model then answers {{class}}.", + "answersProba": "The model then answers {{class}} ({{percent}} %).", + "followed_one": "{{by}} of the {{count}} other model that agreed on this row follows.", + "followed_other": "{{by}} of the {{count}} other models that agreed on this row follow.", + "far": "This changed row is farther from every training row than training rows usually are from each other: the model is answering where it has seen nothing.", + "apply": "Load into the form", + "none_one": "Nothing changes the answer by editing the {{count}} column left open, alone. {{rows}} rows built from values of the training file were tried.", + "none_other": "Nothing changes the answer by editing one or two of the {{count}} columns left open. {{rows}} rows built from values of the training file were tried.", + "allLocked": "Every column is locked or is free text: there is nothing the search may change.", + "locked": "Left as they are because you locked them: {{list}}.", + "untouched": "Never edited, being free text: {{list}}.", + "note": "A counterfactual speaks of the model, not of the world: \"the model would answer otherwise\" is not \"do this and the outcome changes\". Only values some training row holds are tried, one or two columns at a time. The lab does not know that two columns say the same thing: a change of one alone can describe a row that cannot exist. A change few other models follow is an edge of this model, not a rule of the data." + }, "export": { "model": "Model (JSON)", "predictions": "Predictions (CSV)", diff --git a/src/locales/fr.json b/src/locales/fr.json index 2e358ab..1599e04 100644 --- a/src/locales/fr.json +++ b/src/locales/fr.json @@ -768,6 +768,29 @@ }, "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." }, + "counterfactual": { + "button": "Que faudrait-il changer ?", + "lock": "verrouillée", + "lockTitle": "Verrouillée : la recherche d'un changement laisse cette colonne telle quelle", + "target": "Classe visée", + "targetAny": "n'importe quelle autre classe", + "titleAny": "Ce qu'il faudrait changer pour que le modèle cesse de répondre « {{current}} »", + "titleTarget": "Ce qu'il faudrait changer pour que le modèle réponde « {{target}} » au lieu de « {{current}} »", + "oneColumn": "Une colonne suffit. Les plus petits changements, chacun pris seul :", + "twoColumns": "Aucune colonne seule ne change la réponse. Deux ensemble, oui :", + "answers": "Le modèle répond alors {{class}}.", + "answersProba": "Le modèle répond alors {{class}} ({{percent}} %).", + "followed_one": "{{by}} sur {{count}} autre modèle d'accord sur cette ligne suit.", + "followed_other": "{{by}} des {{count}} autres modèles d'accord sur cette ligne suivent.", + "far": "Cette ligne modifiée est plus loin de toute ligne d'entraînement que les lignes d'entraînement ne le sont d'ordinaire entre elles : le modèle répond là où il n'a rien vu.", + "apply": "Charger dans le formulaire", + "none_one": "Rien ne change la réponse en modifiant la seule colonne laissée ouverte. {{rows}} lignes construites avec des valeurs du fichier d'entraînement ont été essayées.", + "none_other": "Rien ne change la réponse en modifiant une ou deux des {{count}} colonnes laissées ouvertes. {{rows}} lignes construites avec des valeurs du fichier d'entraînement ont été essayées.", + "allLocked": "Toutes les colonnes sont verrouillées ou sont du texte libre : la recherche n'a rien le droit de changer.", + "locked": "Laissées telles quelles parce que vous les avez verrouillées : {{list}}.", + "untouched": "Jamais modifiées, car texte libre : {{list}}.", + "note": "Un contrefactuel parle du modèle, pas du monde : « le modèle répondrait autrement » n'est pas « faites ceci et le résultat change ». Seules des valeurs qu'une ligne d'entraînement porte sont essayées, une ou deux colonnes à la fois. Le labo ne sait pas que deux colonnes disent la même chose : changer l'une seule peut décrire une ligne qui ne peut pas exister. Un changement que peu d'autres modèles suivent est un bord de ce modèle, pas une règle des données." + }, "export": { "model": "Modèle (JSON)", "predictions": "Prédictions (CSV)",