# party-series / national-votes / 政党系列 全国得票

This dataset stores national party-vote rows as selector-oriented derived extraction CSV.  
この dataset は、全国の政党得票 row を selector-oriented な derived extraction CSV として保存します。

## Boundary / 境界

- this is not canonical fact storage  
  これは canonical fact storage ではありません
- source of truth remains Layer 2 release facts and release manifests  
  正本は Layer 2 release facts と release manifests に残ります
- this dataset is a deterministic rearrangement for party-centric national lookup  
  この dataset は party-centric national lookup のための deterministic rearrangement です
- this dataset is not a graph payload and not a semantic aggregate packet  
  この dataset は graph payload でも semantic aggregate packet でもありません

## Selector and row grain / selector と row grain

- family: `party-series`
- dataset: `national-votes`
- primary selector field: `party_id`
- selector shard directory: `by-party`
- row grain: `party_id x election_set_key x vote_system`

## Important semantics rules / 重要な semantic 規則

- `vote_system` remains row-level authority and must not be dropped  
  `vote_system` は row-level authority なので落としてはいけません
- this dataset may contain `block`, `pr`, `smd`, and `multi` rows together  
  この dataset には `block`, `pr`, `smd`, `multi` が混在し得ます
- this dataset does not itself define `proportional` or `constituency` series  
  この dataset 自体は `proportional` や `constituency` の series を定義しません
- `party_id` alone must not be treated as a mixed-component trend series without downstream semantic grouping  
  downstream semantic grouping なしに `party_id` 単独を mixed-component trend series とみなしてはいけません

## Files in this directory / このディレクトリのファイル

- `current.yaml`: contract and latest metadata for this dataset  
  この dataset の contract と latest metadata
- `latest/nationwide.csv`: stable convenience table for the whole dataset  
  dataset 全体の stable convenience table
- `latest/by-party/<party_id>.csv`: one selector shard  
  1 selector 分の shard CSV
- `releases/<source_release_version>/...`: release-scoped materialization snapshot  
  release 単位の materialization snapshot

## `current.yaml` keys / `current.yaml` の主要キー

| key | meaning / 意味 |
|---|---|
| `dataset_id` | fixed dataset contract id / 固定の dataset 契約 ID |
| `family` | extraction family name / extraction family 名 |
| `dataset` | dataset name within the family / family 内 dataset 名 |
| `source_release_version` | Layer 2 release version used to build this snapshot / この snapshot の build 元になった Layer 2 release version |
| `source_layer` | upstream layer authority / 上流 authority layer |
| `primary_selector_field` | shard key field / shard の主キー列 |
| `primary_selector_index_dir` | directory name used for shard files / shard ファイルに使う directory 名 |
| `row_grain` | one-row meaning / 1 row の意味 |
| `built_at` | UTC build timestamp / UTC build 時刻 |
| `notes` | dataset-specific contract note / dataset 固有の契約メモ |
| `source_election_set_keys` | election sets included in the build / build に含めた election set 一覧 |
| `files` | latest/release nationwide artifact metadata / latest/release artifact metadata |
| `summary` | selector count and shard summary / selector 件数と shard 要約 |

## CSV columns / CSV 列定義

| column | meaning / 意味 |
|---|---|
| `election_set_key` | election-set id such as `20260208_hr` / `20260208_hr` のような election-set id |
| `election_date` | election date in `YYYY-MM-DD` / `YYYY-MM-DD` の election date |
| `election_type` | election type such as `hr`, `hc` / `hr`, `hc` などの election type |
| `vote_system` | vote system such as `smd`, `block`, `multi`, `pr` / `smd`, `block`, `multi`, `pr` などの vote system |
| `party_id` | normalized party id / 正規化済み party id |
| `votes` | national votes for that party in that row grain / その row grain における全国得票 |
| `valid_votes` | national valid votes for the same election component, when available / 同一 election component における全国 valid votes |
| `vote_share_pct_national` | national vote share for the party in that row, when available / 当該 row における全国得票率 |

## Notes / 注意

- blank numeric fields mean the upstream Layer 2 fact did not expose a stable value for this row  
  空の数値列は upstream Layer 2 fact に stable な値がなかったことを意味します
- if you need `proportional` or `constituency`, build those semantics downstream with explicit `component_family`  
  `proportional` や `constituency` が必要なら、downstream で `component_family` を明示して組みます
- an explicit sibling dataset now exists for proportional-only lookup: `party-series/proportional-votes`  
  比例専用 lookup 用の sibling dataset として `party-series/proportional-votes` もあります