docs: correct the error-bar convention and README to match the actual app
Deploy to git-pages / deploy (push) Successful in 22s
Deploy to git-pages / deploy (push) Successful in 22s
AGENTS.md's "Error Bar Convention" paragraph was wrong in four ways after the last docs pass: it pointed "above" at a section that is below it, described the fallback as "synthetic draw generation" when it generates no draws at all, cited an `intervalWidth / 3.29` expression in RateDensityRidgeline.jsx that does not exist, and listed ModelDrawsComparison.jsx, a file that was deleted when the demo was reduced to 3 charts. Rewritten against the current code: the fallback is fitSkewedInterval's analytic two-piece normal, whose divisor is probit((1 + intervalMass) / 2) with intervalMass defaulting to 0.90, and the "if you change this" list now names the three files that actually encode 90%. README: 6 charts -> 3, the ridgeline is Chart 3 not Chart 5, Chart 2's use of real draws is now mentioned, the D3.js v7 claim is dropped (d3 is not a dependency), @duckdb/duckdb-wasm is listed in the tech stack, the file tree matches src/, and the container-size note accounts for the wasm engine.
This commit is contained in:
@@ -46,11 +46,14 @@ App.jsx (router)
|
||||
|
||||
### Error Bar Convention: 90% Intervals
|
||||
|
||||
The API returns 95% HPD intervals (`count_lower`, `count_upper`). However, all chart labels and calculations in this app use **90% intervals**. When converting HPD bounds to standard deviations for the synthetic draw generation fallback (used in the ridgeline chart if real draws can't be fetched — see "Real posterior draws via duckdb-wasm" above), the divisor used is **3.29** (corresponding to z = 1.645 for a two-tailed 90% interval).
|
||||
The API returns 95% HPD intervals (`count_lower`, `count_upper`). However, all chart labels and calculations in this app use **90% intervals**.
|
||||
|
||||
The 90% convention is baked into the analytic fallback in `src/utils/distributionApprox.js` (the path used when real posterior draws can't be fetched — see the duckdb-wasm section below). That fallback generates **no draws**: `fitSkewedInterval` fits a two-piece normal directly from `{median, lower, upper}`, converting each half-interval to its own sigma with `z = probit((1 + intervalMass) / 2)` and `intervalMass` defaulting to `0.90` (so z ≈ 1.645). For a symmetric interval that is equivalent to the old fixed "full width / 3.29" divisor, but it is computed from `intervalMass` rather than hardcoded, and each side gets its own sigma so the fitted shape stays skewed.
|
||||
|
||||
If you change this convention, update:
|
||||
- `RateDensityRidgeline.jsx` — SD calculation (`intervalWidth / 3.29`) and label text
|
||||
- `ModelDrawsComparison.jsx` — Legend labels mentioning "90%"
|
||||
- `distributionApprox.js` — the `intervalMass = 0.90` default in `fitSkewedInterval`, and its JSDoc claim that the API's bounds are a 90% interval
|
||||
- `RateByGroupBar.jsx` — the caption and component JSDoc, both of which say "the model's reported 90% interval"
|
||||
- `ArrestsOverTime.jsx` — the legend label "Modeled (median + 90% interval)"
|
||||
- Any documentation referencing confidence/credible intervals
|
||||
|
||||
## Common Pitfalls & Gotchas
|
||||
|
||||
Reference in New Issue
Block a user