Files
threshing-atlas/README.md
T
ekcSchianoandClaude Opus 5.5 7366af2f7d Release pass: wording, colour-blind-safe colours, map visibility, phone layout
Walked every tab on desktop and phone, clicked every link and button:
- Colours: new map inks and page colours, checked with simulated
  protanopia/deuteranopia/tritanopia (worst pair ~12 CIEDE2000, was 1.4 for
  Red/Green on the map and 9.7 for Orange/Brown on the page). Map label text
  is always dark ink; dragon colour goes on borders. docs/COLOURS.md and
  research/python/check_colours.py.
- Valley map: dragons get a paper halo and a visibility floor (faded ones never
  drop below 0.3; bonding dragons start at 0.5); "no shadow" roll labelled
  correctly.
- Wording: methods updated (strata, the newer form's questions, missing
  answers, a new section on the solver, The Odds cards and genuine attempts);
  findings use readable factor names and no longer claim a date adjustment;
  'Load a newer route export above'; code links include solver.js and
  explorer.js; The Odds shows 93% instead of '1 in 1'.
- Deep Dive route map treats all six dragons alike ('Bond a dragon' row,
  default 'Bond any dragon'; rare sightings separate).
- Phone: Deep Dive no longer overflows (sections and selects can shrink).
- scripts/qa/crawl.js and mapcheck.js for future release checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ
2026-11-02 17:57:51 +00:00

118 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Threshing Atlas
Route probabilities and path finding for the Dragonkind threshing: which choices lead to which
dragon, how often, how sure we can be, and (in progress) the best route to each colour.
Unofficial fan project. Not affiliated with Dragonkind or the Fourth Wing publishers.
## Layout
```
apps/atlas/ the web page. The Valley (explorer.js: the map, the dragons, routes on demand; dragons.js:
original silhouettes), The Odds, The Dragons, Deep Dive, Data & Methods
packages/core/ @threshing-atlas/core, no dependencies, runs in Node and the browser:
src/engine.js coding rules and statistics for the community form
src/graph.js the shared route graph: scene graph, decision-variable graph,
bot-to-form crosswalk, Beta credible intervals
src/solver.js best decisions per dragon colour (history-dependent decision tree,
empirical-Bayes back-off, two objectives) + the bot advisor
packages/ingest/ @threshing-atlas/ingest: DragonKind bot importer (fingerprints and choice text only)
research/python/ independent Python implementation of the coding rules and statistics
tests/ JS/Python parity tests (they fail loudly if the two disagree)
scripts/build-site.js assembles the static site into dist/
scripts/build-graph.js combines every source into data/public/graph.json
scripts/build-policy.js solves for every colour -> data/public/policy.json; policy-report.js -> docs/POLICY.md
data/raw/ source exports (form .xlsx; the register export stays local, git-ignored)
data/public/ what the page loads: form_responses.json, register.json, graph.json
data/sources.json where the community spreadsheets and the PDF are downloaded from
data/derived/ coded runs (runs_clean.csv)
data/bot/ anonymised DragonKind bot runs, added by pull request
docs/ ROADMAP.md, BOT_DATA_PROTOCOL.md, REDDIT_POST.md
```
## Run it locally
Requirements: Node 18+, Python 3.9+ (`pip install -r research/python/requirements.txt`).
```
npm run dev # builds dist/ and serves it at http://localhost:8000
npm test # JS engine + Python reference + parity checks
```
## New data from the community sources
A GitHub Action (`.github/workflows/update-sources.yml`) runs every day. It downloads the Threshing Routes
responses, the Dragon Register and the route PDF, and if anything changed it rebuilds the data, runs the
tests and opens a pull request that says what changed: new responses, new or renamed questions, and for
the PDF the pages and lines that are new. The PDF itself is never committed, only a fingerprint
(`data/derived/pdf_fingerprint.json`). If a link stops working, the Action opens an issue. You can also
run it by hand from the Actions tab, or locally with `npm run check-sources`.
## Best routes (the solver)
`npm run policy` rebuilds `data/public/policy.json` and the readable `docs/POLICY.md` (about 2.5 minutes:
200 posterior draws for two data samples). For every colour it gives the best decision at every point under two
objectives: the chance of bonding that colour on this attempt, and the chance the account eventually ends on that
colour when you die on purpose whenever a run goes wrong. Chance events (which dragon appears, whether the shadow
shows) may depend on earlier choices; how much is learned from the data. See the top of
`packages/core/src/solver.js` for the model and `docs/BOT_INTEGRATION.md` for how the bot uses it.
## Bot data
The private DragonKind bot's files are converted locally, and only the anonymised result is committed:
```
DK_ACCOUNT_SALT=... npm run import-bot -- --bot /path/to/DragonKind --tag 2026-11-01
npm run graph
```
This writes `data/bot/scenes.json` and `data/bot/trajectories-<tag>.jsonl`: scene fingerprints, short labels,
choice text and outcomes, with no game prose and no account names. The importer refuses to write anything that
looks like prose. See `docs/BOT_DATA_PROTOCOL.md` for what the bot should log.
## Updating with new form data by hand
In the browser: open the page and use **Load a newer export** with the responses spreadsheet
(Google Sheets → File → Download → Microsoft Excel). Everything recomputes. Questions are matched by
wording; a renamed question is listed as "not found", and then `COLUMN_KEYS` in
`packages/core/src/engine.js` and `research/python/clean.py` need updating.
To update the bundled snapshot, put the new export in `data/raw/form/`, then:
```
cd research/python
python export_raw.py ../../data/raw/form/NEW_EXPORT.xlsx ../../data/public/form_responses.json
python clean.py ../../data/raw/form/NEW_EXPORT.xlsx
cd ../..
npm test
```
## Changing a coding rule
Every rule lives in `codeRow()` in `packages/core/src/engine.js` and `code_row()` in
`research/python/clean.py`. Change both and run `npm test`.
## Statistics in one paragraph
Rates use 95% Wilson score intervals. Each answer is compared with the other answers to the same
question by odds ratio (Woolf CI, +0.5 Haldane correction for zero cells) and Fisher's exact test, with
Benjamini–Hochberg q-values. Because Blue- and Black-chasers report rare sightings far more often than
players who log every run, key outcomes are also modelled with ridge-penalised logistic regression
(λ = 1) that includes data source and chase goal, and route rankings use a Mantel–Haenszel odds ratio
stratified by the same factors. The page's Methods section has the details.
## Licences
Code: MIT (`LICENSE`). Data produced by this project: CC BY 4.0 (`DATA_LICENSE.md`), which also lists
third-party sources that keep their own terms.
## Release checks
```
npm test # parity and unit tests
python research/python/check_colours.py # dragon colours stay distinguishable (docs/COLOURS.md)
npm run build && python3 -m http.server 8765 -d dist &
node scripts/qa/crawl.js /tmp/qa # every tab on desktop and phone: text, links, buttons, errors, overflow
node scripts/qa/mapcheck.js /tmp/qa # every dragon's routes: off-map labels, overlaps, too-faint dragons
```