# jp-election-data 日本の選挙データを一次資料から構造化した事実データセット。 --- ## このデータセットについて 本データセットは、47都道府県の選挙管理委員会が公開する公式選挙結果を、再実行可能なパイプラインで構造化したものである。対象範囲は47都道府県だが、主な事実データの粒度は市区町村単位である。 公開対象: `catalog/current.yaml` と `catalog/public-manifest.json` が指す current release 対象範囲: current release に含まれる選挙・都道府県 最新版: `catalog/current.yaml` を参照 ### 公開時点の注意 - **人手による全面確認は実施していない。** 47都道府県 coverage と整合性検証は通しているが、全ファイルを人手で逐一監査したものではない。 - **公開後に人間査読段階を置く設計である。** exhaustive な人手監査を公開前の必須条件にはせず、公開後に独立確認・差分報告・版更新を入れる。 - **AI を含むパイプライン出力を基に整形している。** 一次資料からの構造化、検証、公開用 artifact の組み立てに AI-assisted workflow を使っている。 - **本公開パッケージは内部パイプライン本体から独立した配布層である。** 公開物は配布用に再構成しており、内部運用ログや試走物は含めない。 - **既知の差分・残差が存在する。** 総務省 block aggregate baseline との residual diff は公開しており、詳細は `verification/known-residuals.md` と `verification/soumu-block-aggregate-diff-summary.md` を参照すること。 - **利用条件、再配布、責任範囲、免責は `LICENSE.md` を参照すること。** ### 公開後査読について - 公開は「非公開のまま長く抱える」より、機械可読な current release を先に提示することを優先する - 公開後の人間確認・外部査読・独立再計算は、設計上の正式な後段プロセスである - 査読で見つかった問題は、既知の残差・差分資料・版更新を通じて開示し、次版へ反映する - したがって、`公開済み` は `全件人手査読済み` を意味しない ### 何が含まれるか - **fact_candidate_votes.csv**: 政党 × 市区町村の得票数（47 election × 各数百〜数千行） - **fact_district_stats.csv**: 市区町村ごとの有権者数・投票者数・有効票・無効票 - **public-summary.\*.csv**: Layer 2 facts を読みやすく再構成した公開用派生 CSV - **辞書**: 政党マスタ、市区町村マスタ、エイリアス、スコープ定義 - **補助辞書**: Gazetteer ベースのローマ字参照と公開補助 override - **英語案内**: `README.en.md` と `english-conversion-guide.md` に、英語文書と英語表記の導出方針をまとめる - **一次資料登録一覧**: raw source の URL・形式・SHA-256・公開向け provenance を整理した公開 register - **SPEC**: データ契約（Tidy_rule）、四層モデル定義、ソースカタログ仕様 - **正規化規則**: 公開情報ベースの alias / aggregate-row / romanization rule - **検証成果物**: 総務省ブロック集計値との突合結果、既知の残差一覧 ### 何が含まれないか - 一次資料そのもの（ソース URL は source.yaml に記録） - 集計済みデータ（都道府県合計、ブロック合計等） - 候補者個人の情報（比例代表ブロックのため） - AI orchestration protocol、学習層、運用ログ --- ## 利用上の重要な警告 **本データセットは、公的選挙データの検証・分析に特化して設計されている。** 多目的利用（汎用データ分析、商用 BI ツールへの投入、AI パイプラインの入力等）においては、データの構造・粒度・正規化方針が設計の想定外の動作を引き起こす。詳細は [specs/tidy-rule.md](specs/tidy-rule.md) の §0.2 および §9 を参照すること。 ### 最低限知っておくべきこと 1. **行政区分割行が存在する。** 政令指定都市では同一行政区が複数行に分割される。単純な SUM は二重計上になる → [§4](specs/tidy-rule.md#4-行政区分割ルール) 2. **辞書なしでは使えない。** `party_id` はコードであり、`party_master.csv` との結合が必須 → [§2](specs/tidy-rule.md#2-辞書依存) 3. **prefecture_code は文字列である。** `"01"` を数値 `1` にすると結合が壊れる → [§1.1](specs/tidy-rule.md#11-fact_candidate_votes) 4. **集計済みデータは含まれない。** これは設計上の意図的な判断である → [§0.2](specs/tidy-rule.md#02-設計上の前提と制約) ### 主要キー - `election_key`: project 内の選挙キー。`20260208_hr_block_12` のような形式 - `prefecture_code`: 都道府県コード。文字列として扱う - `prefecture_name`: 都道府県名 - `jis_code`: 市区町村コード。市区町村単位の結合キー - `municipality_name`: 市区町村名 - `party_id`: 政党コード。`party_master.csv` / `party_alias.csv` を正本にする - `votes`: 政党別得票数 - `actual_voters`, `valid_votes`, `invalid_votes`: 投票統計の主要列 `fact_candidate_votes.csv` は主に `jis_code / municipality_name / party_id / votes` を、`fact_district_stats.csv` は `jis_code / municipality_name / actual_voters / valid_votes / invalid_votes` を中心に読むとよい。 ### 英語表記と英語文書 - 英語文書の入口は `README.en.md` を参照すること - 地名・政党名の英語表記は `english-conversion-guide.md` を参照すること - 英語表記は presentation-layer derivative であり、join と URL 解決には `prefecture_code` / `jis_code` / `party_id` を使うこと - 地名は `gazetteer_japan_2021.csv` を第一根拠、`municipality_romanization_overrides.csv` を補助とする - 政党名は `party_alias.csv` で `party_id` に正規化してから `party_master.csv:name_en` を使うこと --- ## クイックスタート ### データの確認 ```bash # 任意の election_key の得票データを確認 head -20 data/by-election/national//fact_candidate_votes.csv # 任意の election_key の投票統計を確認 head -20 data/by-election/national//fact_district_stats.csv # 政党マスタを確認 cat data/dictionaries/common/party_master.csv ``` ### 基本的な分析（Python） ```python import pandas as pd # ファクトと辞書を読み込む votes = pd.read_csv( "data/by-election/national//fact_candidate_votes.csv", dtype={"prefecture_code": str, "jis_code": str} # 文字列型を維持 ) party = pd.read_csv("data/dictionaries/common/party_master.csv") # 政党名を結合 votes = votes.merge(party[["party_id", "formal_name"]], on="party_id") # 北海道全体の政党別得票数（集計行のみ使用、leaf行の二重計上を回避） # ※ 正確な集計には §4 の行政区分割ルールの理解が必要 hokkaido_total = votes.groupby("formal_name")["votes"].sum() print(hokkaido_total.sort_values(ascending=False)) ``` **注意:** 上記の `groupby` は行政区分割を考慮していない簡易例である。正確な集計方法は [specs/tidy-rule.md §4](specs/tidy-rule.md#4-行政区分割ルール) を参照すること。 --- ## ディレクトリ構成 ``` jp-election-data/ ├── README.md ← この文書 ├── LICENSE.md ← ライセンス（公的利用特化） ├── CITATION.cff ← 引用情報 ├── data/ │ ├── by-election/ │ │ └── national/ │ │ ├── / ← 例: 20250720_hc_multi_01 │ │ │ ├── fact_candidate_votes.csv │ │ │ ├── fact_district_stats.csv │ │ │ └── source.yaml │ │ ├── / │ │ │ └── ... │ │ └── ... │ └── dictionaries/ │ └── common/ │ ├── party_master.csv │ ├── area_master.csv │ ├── area_alias.csv │ ├── scope_master.csv │ └── region_block_master.csv ├── specs/ │ ├── tidy-rule.md ← データ契約（必読） │ ├── artifact-layers.md ← 四層モデル定義 │ ├── source-catalog.md ← ソース真正性基準 │ └── output-views.md ← 出力形式定義 ├── verification/ │ ├── soumu-block-aggregate-diff-summary.md │ ├── known-residuals.md │ └── by-election/ ← 県別検証結果 └── pipeline/ ← 最小再実行パイプライン ├── README.md ├── requirements.txt └── run/ ``` --- ## 検証状況 47都道府県の内部整合性（`actual_voters = valid_votes + invalid_votes`, `SUM(votes) = valid_votes`）は全件通過済み。 総務省ブロック集計値との外部整合性は pilot 検証を実施済み。既知の残差は [verification/known-residuals.md](verification/known-residuals.md) に一覧化している。 既知の残差: - 近畿ブロック microdiff - 北関東・四国 overseas-turnout scope delta - 一部県の invalid-only diff - 奈良県 aggregate-row drift（9 area） これらは verification/ に詳細を公開しており、外部の研究者が独立に検証可能である。 --- ## ライセンス [jp-election-data License v1.0](LICENSE.md) 公的利用（選挙データの検証・分析・研究・報道・市民活動・教育）は無制限に許可。 営利利用・AI モデル学習データとしての体系的利用は禁止。 フォーク・改変は同一ライセンス条件の継承を条件に許可。 --- ## 引用 ```bibtex @misc{jp-election-data-2026, title = {Japanese Election Structured Facts Dataset}, year = {2026}, url = {https://github.com/[TBD]/jp-election-data}, note = {2026-02-08 HR Block PR, 47 prefectures, v033} } ``` --- ## コントリビューション Issue・Pull Request を歓迎する。特に以下の貢献を求めている。 - 既知の残差に対する独立検証 - 行政区分割パターンの追加報告 - 辞書の表記揺れ追加 - 他の選挙（小選挙区、参院選、地方選）への拡張 コントリビューションは同一ライセンス条件を継承する。