# derived extraction catalog map

This map is the stable entrypoint for selector-oriented derived datasets.

## first-wave datasets

| family | dataset | primary selector | selector dir | row grain | meaning |
|---|---|---|---|---|---|
| `municipality-series` | `stats` | `jis_code` | `by-jis` | `jis_code x election_key` | one municipality's election-by-election basic statistics |
| `municipality-series` | `party-votes` | `jis_code` | `by-jis` | `jis_code x election_key x party_id` | one municipality's election-by-election party votes |
| `municipality-series` | `proportional-party-comparison-2025-2026` | `jis_code` | `by-jis` | `comparison_key x jis_code x party_id` | one municipality's 2025 to 2026 proportional party vote and vote-share comparison |
| `prefecture-series` | `stats` | `prefecture_code` | `by-prefecture` | `prefecture_code x election_key` | one prefecture's election-by-election basic statistics |
| `prefecture-series` | `party-votes` | `prefecture_code` | `by-prefecture` | `prefecture_code x election_key x party_id` | one prefecture's election-by-election party votes |
| `prefecture-series` | `comparison-stats` | `prefecture_code` | `by-prefecture` | `comparison_key x prefecture_code x component_family` | one prefecture's cross-election comparison statistics aligned on semantic component family |
| `party-series` | `national-votes` | `party_id` | `by-party` | `party_id x election_set_key x vote_system` | one party's election-by-election national votes |
| `party-series` | `proportional-votes` | `party_id` | `by-party` | `party_id x election_set_key` | one party's election-by-election national proportional votes |

## selector rule

- `current.yaml` is the contract for one dataset.
- `primary_selector_field` identifies the shard key.
- `primary_selector_index_dir` identifies the shard directory under `latest/` and `releases/<source_release_version>/`.
- `nationwide.csv` is the full stable convenience table for one dataset, not a canonical aggregate.

## graph-ui note

Graph UI should treat this map as the routing layer:

1. choose selector family
2. read dataset `current.yaml`
3. resolve shard from `primary_selector_index_dir`
4. read one selector CSV or `nationwide.csv`