# jp-election-data

Structured election facts derived from official Japanese election sources.

---

## About This Dataset

This dataset structures official election results published by prefectural election commissions for all 47 prefectures of Japan.

Coverage is nationwide across 47 prefectures, but the main fact grain is municipality-level.

Published scope: the current release pointed to by `catalog/current.yaml` and `catalog/public-manifest.json`  
Coverage: the election family and prefectures included in the current release  
Latest release: see `catalog/current.yaml`

### Important Notes

- Full manual review has not been completed.
- Post-publication human review is an explicit design stage. Publication can precede exhaustive manual audit, with later corrections flowing back through disclosed residuals and versioned updates.
- The public package is assembled from an AI-assisted pipeline.
- This public package is independent from the internal operational pipeline.
- Known residual differences exist and are disclosed publicly.
- Terms of use, redistribution, responsibility, and disclaimer are defined in `LICENSE.md`.

### Post-publication review

- Release first, then human review, is a deliberate operating model for this dataset.
- Independent human checking, external review, and follow-up corrections are expected after publication.
- Published does not mean fully manually audited.
- When review finds issues, they should be disclosed through residual notes, diff summaries, and subsequent release versions.

### Main Files

- `fact_candidate_votes.csv`: party-by-municipality vote facts
- `fact_district_stats.csv`: municipality-level turnout and ballot statistics
- `public-summary.*.csv`: public-facing derived CSV rebuilt from Layer 2 facts
- common dictionaries for party, area, scope, and region interpretation
- auxiliary dictionaries for romanization and English-facing labels

### Key Columns

- `election_key`: project-scoped election key
- `prefecture_code`: prefecture code, treat as string
- `prefecture_name`: prefecture name in Japanese
- `jis_code`: municipality code, the primary municipality join key
- `municipality_name`: municipality name in Japanese
- `party_id`: canonical party code
- `votes`: party votes
- `actual_voters`, `valid_votes`, `invalid_votes`: main turnout/stat columns

Read `fact_candidate_votes.csv` primarily through `jis_code / municipality_name / party_id / votes`.
Read `fact_district_stats.csv` primarily through `jis_code / municipality_name / actual_voters / valid_votes / invalid_votes`.

### English-Facing Use

Canonical keys remain Japanese/JIS-anchored.
English-facing labels are derived presentation fields.

For English-facing use:

- read `english-conversion-guide.md`
- use `gazetteer_japan_2021.csv` and `municipality_romanization_overrides.csv` for municipality names
- use `party_alias.csv` -> `party_id` -> `party_master.csv:name_en` for party names
- do not replace canonical keys with English labels

### Residuals

Residual differences against the official Ministry of Internal Affairs and Communications block aggregate baseline are publicly documented.

See:

- `known-residuals.md`
- `verification/soumu-block-aggregate-diff-summary.md`

### License

See `LICENSE.md`.