132 lines
6.1 KiB
Markdown
132 lines
6.1 KiB
Markdown
# Static dashboard specification
|
|
|
|
## Release status and language
|
|
|
|
The checked-in site is a **development preview** built from suppressed
|
|
aggregates derived from the private, page-sampled 10,000-vehicle development
|
|
cohort. Every value is a sample result, **not a population estimate**. The site
|
|
must not present statewide prevalence, county rankings, causal comparisons, or
|
|
individual predictions.
|
|
|
|
Use **Utah Vehicle Health** as the project name and **next-episode first-attempt
|
|
non-pass** for the modeled outcome. Non-pass combines fail, reject, and abort.
|
|
The dashboard is not a diagnosis, certification, safety assessment,
|
|
roadworthiness assessment, or guarantee.
|
|
|
|
## Implemented four-view prototype
|
|
|
|
### Overview
|
|
|
|
- Visibly persistent development-preview warning
|
|
- Rounded published support and sample pass/non-pass rates
|
|
- Sample first-attempt non-pass trend for approved, pre-2025 periods
|
|
- County **feed-coverage** map, with unavailable counties shown as unavailable
|
|
rather than zero
|
|
- Sample non-pass pattern by coarsened vehicle-age band
|
|
- Plain-language target and limitations callout
|
|
|
|
County values provide sample/feed context only. They must not be sorted,
|
|
headlined, or described as population county performance.
|
|
|
|
### Sample cohorts
|
|
|
|
- Search and compare only supported, suppression-cleared make/model cohorts
|
|
- Combine documented source abbreviations and trim labels for newly published
|
|
model families before applying the unchanged publication thresholds
|
|
- Keep earlier public cohort definitions stable across releases so differences
|
|
cannot expose a formerly suppressed slice
|
|
- Identify Silverado 1500, Ram 1500, Elantra, Altima, Outback, 4Runner,
|
|
Corolla, and Tacoma as combined families; identify F150, Accord, Civic, and
|
|
Camry as exact source-label cohorts
|
|
- Show observed sample non-pass rates and rounded support
|
|
- Default sorting by support rather than risk
|
|
- Disable filters or adjusted views that the aggregate bundle cannot support
|
|
- Explain that omitted cohorts may be suppressed or unavailable
|
|
|
|
These are descriptive development-sample cohorts, not reliability ratings,
|
|
causal make/model effects, or recommendations.
|
|
|
|
### Model & benchmark
|
|
|
|
- Identify calibrated logistic regression as the sole final prototype model.
|
|
- Identify calibrated histogram gradient boosting as benchmark-only.
|
|
- Show only pre-2025, 2024 calibration-fit diagnostics from the private sample.
|
|
- Explain that those same-partition values are calibration checks, not
|
|
independent final-performance or population estimates.
|
|
- Keep the opened 2025 holdout comparison in the private report/presentation,
|
|
not in the browser bundle.
|
|
- State plainly that the finished prototype has no vehicle-level prediction
|
|
service, personal input form, or row-level output.
|
|
|
|
### Data & methods
|
|
|
|
- First-attempt returning-vehicle episode and binary-target definitions
|
|
- Point-in-time feature and leakage controls
|
|
- Coverage timeline by source era
|
|
- Chronological development-sample split and one-time 2025-gate disclosure
|
|
- Evidence-governance summary for the logistic final model and tree benchmark
|
|
- Known sampling, coverage, label, validation, and interpretation limits
|
|
- Private-to-public publication flow
|
|
|
|
The boosted tree appears only in benchmark context, never as a second final
|
|
model. The dashboard never requests a VIN, plate, ZIP, exact address, station,
|
|
technician, free text, or current-test diagnostic.
|
|
|
|
## Public data contract
|
|
|
|
| Asset | Allowed content |
|
|
| --- | --- |
|
|
| `data_manifest.json` | Release ID, model versions, scope flags, definitions, and suppression settings |
|
|
| `overview_period_county.json` | Suppressed quarter x covered-feed county sample aggregates |
|
|
| `cohort_scorecard.json` | Suppressed make/model sample aggregates with rounded support |
|
|
| `age_risk_curve.json` | Suppressed sample rates by coarsened vehicle-age band |
|
|
| `filter_catalog.json` | Publishable categories and supported periods |
|
|
| `model_diagnostics.json` | Train/tune/calibration development metrics only; no 2025 metrics |
|
|
| `coverage_quality.json` | Source-era availability by year |
|
|
| `sha256_manifest.json` | Checksums for the approved bundle |
|
|
|
|
Every JSON asset must declare `development_preview=true` and
|
|
`population_estimate_allowed=false`. The public manifest must declare
|
|
`locked_test_metrics_published=false`. The browser validates the complete bundle
|
|
and shows no estimates if any required asset fails its contract.
|
|
|
|
The browser bundle must never contain raw analytical rows, prediction lookup
|
|
rows, hidden unsuppressed chart layers, or values recoverable only through the
|
|
developer console.
|
|
|
|
## Suppression and privacy controls
|
|
|
|
- Require at least 100 eligible episodes and 100 distinct private vehicles per
|
|
published cell.
|
|
- Require at least 10 observations and 10 distinct vehicles in both binary
|
|
outcome classes.
|
|
- Apply complementary suppression when a visible total could reveal a hidden
|
|
cell.
|
|
- Combine rare categories, coarsen age/year fields, and round support.
|
|
- Recheck thresholds for the exact grain of every released asset.
|
|
- Omit suppressed rows entirely; do not send them to the browser.
|
|
- Publish no VIN, plate, ZIP, exact address, station, technician identifier,
|
|
private token, raw JSON, credential, operational record, free text, or
|
|
row-level prediction.
|
|
- Make no browser or hosted-service connection to `countydata`.
|
|
|
|
## Accessibility and visual behavior
|
|
|
|
- Use semantic headings, landmarks, labels, status messages, and keyboard-
|
|
reachable navigation.
|
|
- Provide text alternatives or accessible labels for charts.
|
|
- Do not rely on color alone.
|
|
- Use a restrained Utah/desert palette and direct probability/rate encodings;
|
|
avoid gauges and decorative risk scores.
|
|
- Preserve the warning banner and fail-closed unavailable state on desktop and
|
|
mobile layouts.
|
|
|
|
## Demo boundary
|
|
|
|
The current delivery is a same-network live demo started with
|
|
`node dashboard/server.mjs --lan`. The local server resolves files only beneath
|
|
`dashboard/` and serves only its explicit shell, JavaScript, stylesheet, and
|
|
approved aggregate allowlist. It does not expose `.env`, private `data/`, model
|
|
artifacts, SQL, pipeline scripts, or repository history. Stop the server after
|
|
the demo; no public hosting step is required.
|