spb/cancerindex

1# Data explorer — methodology23`/explore` charts and exports registry observations stored in `epidemiology_observations` (see4`docs/DATA-MODEL.md` and `docs/METHODOLOGY.md` §1–2). It shows values **exactly as published by the5source**; CancerIndex harmonizes units (`count`, `per_100k`) and labels, never the numbers. Nothing6is estimated, interpolated, summed across site groups or extrapolated beyond the years a source7publishes. Every chart and table states unit, geography, sex, age group, years, standard population,8source and retrieval date, and each row keeps its `provenance_id`.910Population statistics describe groups defined by geography, period, sex and age; they never predict11an individual outcome (METHODOLOGY §325).1213## 1. Comparability rules1415Two observations are drawn on **one axis** only when they share all of:1617| Dimension | Why it matters |18|---|---|19| `metric` | deaths, new cases, crude rates and age-standardized rates are different quantities |20| `unit` | `count` vs `per_100k` |21| `geography` | a country and one of its subdivisions are not comparable series |22| `source` | registries differ in coverage, site definitions (e.g. USCS "Pancreas" = ICD-10 C25 vs another grouping), vintage and revisions; the same year from CDC WONDER and USCS is two observations, not one |23| `standard_population` | rates standardized to the "2000 U.S. standard population" and to the "World (Segi)" standard are not on the same scale; crude rates and counts have no standard population |24| `age_group` | all ages vs 65+ etc. |2526Observations that differ on any of these dimensions are rendered as **separate charts**, and a caption27names the dimension(s) that differ, e.g. *"Shown as 2 separate charts: the observations differ by28source (cdc-uscs vs cdc-wonder) and standard population (2000 U.S. standard population (19 age groups)29vs 2000 U.S. Std. Population)."* The groups are never overlaid, indexed or rescaled to appear30comparable. Inside one group the series are **cancer × sex** (× estimate type × site definition when a31source publishes two definitions for one cancer). Series whose `estimate_type` is not `observed`32(estimated, projected) are dashed and labelled.3334Implementation: `apps/web/src/lib/explorer-series.ts` (`groupComparable`, `explainSplit`), unit-tested35in `apps/web/test/explorer-series.test.ts`.3637### Small multiples3839When more than 4 series would be overlaid, or when the user chooses `view=multiples`, a group is40split into one panel per cancer. Panels **share one y-axis** (0 to the group maximum, stated above the41panels) so heights remain comparable. Colour follows the entity (cancer × sex) across panels and42groups and is never cycled; beyond eight identities, colour follows the sex inside each panel and the43panel title carries the cancer. Colour is never the only carrier: every series has a text legend44entry, a tooltip with the series name, and the observations table lists every value.4546### Sex4748`sex=all` shows the source's "both sexes" observation (as published — not the sum of male and49female). `sex=any` shows every sex the source publishes as separate series inside the same group.5051## 2. Defaults (computed, not curated)5253When the URL carries no parameter:5455- `metric` = `mortality_count` when present in the database, else the first metric present;56- `geography` = `united-states` when it carries observations, else the first geography that does;57- `sex` = `all`, `age` = `all`;58- `cancers` = the **5 top-level cancers with the highest value in the latest year** of the selected59  metric, geography, sex and age group (`topCancersByLatest`, one row per cancer — when two sources60  publish the same year, the larger value decides membership only; both sources are then charted61  separately). The results header says so and names the year;62- `from`/`to` = the full year span of the metric for the geography.6364The list of metrics, geographies, sexes, age groups, years and sources offered by the form is read from65the observations (`explorerOptions`), so the explorer never advertises data it does not hold. Sources66registered for epidemiology but not yet ingested (IARC/GLOBOCAN under license review, SEER awaiting67credentials) are listed as such.6869## 3. Permalink parameters7071The URL is the state. `serializeExplorerParams` writes every dimension explicitly so a link stays72stable when the computed defaults change.7374| Parameter | Values | Notes |75|---|---|---|76| `metric` | `mortality_count`, `as_mortality_rate`, `mortality_rate`, `incidence_count`, `as_incidence_rate`, … | one metric per view |77| `cancers` | comma-separated slugs or `CI-CAN-…` ids, max 6 | repeated `cancers=` also accepted; unknown refs are ignored and reported |78| `geography` | slug or ISO3 (`united-states`, `USA`) | |79| `sex` | `all` (default), `male`, `female`, `any` | `any` = every sex, one series each |80| `age` | age group label as stored (`all` default) | |81| `from`, `to` | years (inclusive); swapped when inverted | multi-year observations match when the span overlaps |82| `view` | `lines` (default), `multiples` | |83| `normalize` | `none` (only value in Phase 1) | reserved for indexed views |84| `page` | observations table page (50 rows/page) | omitted from downloads |8586Examples:8788- `/explore` — defaults;89- `/explore?metric=as_mortality_rate&cancers=malignant-lung-neoplasm,malignant-breast-neoplasm&geography=united-states&sex=any&age=all&from=1999&to=2024`;90- `/explore?metric=mortality_count&cancers=malignant-pancreatic-neoplasm&geography=united-states&sex=all&age=all&from=2018&to=2024&view=multiples`.9192## 4. Downloads and API9394- **CSV** — `/api/export/epidemiology.csv?<same parameters>` (metric, cancers, geography required).95  Header rows prefixed `#`: CancerIndex attribution and licence of the harmonization (CC BY 4.0),96  each underlying source with its licence text, dataset, version and retrieval timestamp, source97  attribution sentences, methodology URL and comparability reminder, generation time and row count.98  Columns: `cancer_id, cancer_slug, cancer_name, geography_id, geography_slug, geography_name, iso3,99  year, year_end, sex, age_group, metric, value, unit, lower_ci, upper_ci, standard_population,100  estimate_type, site_definition, source_slug, source_name, provenance_id, dataset, dataset_version,101  source_url, retrieved_at`. RFC 4180 quoting. Capped at 50 000 rows (stated in the header).102- **JSON** — `GET /api/v1/epidemiology?metric=&cancer=<repeatable, max 8>&geography=&sex=&age=&from=&to=&source=&estimateType=&limit&offset`103  (paginated, max 200 per page, envelope with `sources`), `GET /api/v1/epidemiology/coverage?cancer=&geography=&metric=`104  and `GET /api/v1/epidemiology/metrics`. Each observation carries `standardPopulation`,105  `estimateType`, `siteDefinition`, `source` and `provenance {id, dataset, datasetVersion, sourceUrl, retrievedAt}`106  so consumers can apply the same comparability rules.107- **Coverage matrix** — `/explore/coverage`: metric × geography × sex × age × source × standard108  population with year span, distinct years, observations and cancers. The empty state of `/explore`109  shows the same matrix restricted to the selected cancers/geography so a user sees what exists.110111## 5. Citation112113The "Cite" line combines CancerIndex (URL, access date) with every underlying source, its dataset and114retrieval date. Underlying observations remain under their providers' licences (CDC WONDER and USCS:115US Government work, statistical reporting only); CancerIndex's harmonization is CC BY 4.0.116