docs: add axis classification design spec

Add design for honest PCA axis labeling — validates each compass axis against a party ideology reference CSV and labels dynamically (Links–Rechts, Coalitie–Oppositie, or fallback) instead of hardcoding Left–Right always.
1 month ago · bed911b92c
parent 50f8a06c6d
commit bed911b92c
1 changed files with 279 additions and 0 deletions
--- a/docs/superpowers/specs/2026-03-29-axis-classification-design.md
+++ b/docs/superpowers/specs/2026-03-29-axis-classification-design.md
@ -0,0 +1,279 @@
+---
+date: 2026-03-29
+topic: "Honest PCA Axis Classification"
+status: validated
+---
+
+# Axis Classification Design
+
+## Problem Statement
+
+The political compass always labels its X-axis "Links–Rechts" and Y-axis "Progressief–Conservatief"
+regardless of what the PCA actually found. In coalition years, the first principal component captures
+**coalition membership**, not ideology. The dominant axis of voting variation in Rutte II (VVD+PvdA)
+and Rutte III/IV (VVD+CDA+D66+CU) is "are you in the governing coalition?" PvdA and PVV end up at the
+same position because both were in opposition — technically correct voting similarity, but the label
+"Links–Rechts" is a lie.
+
+The fix: after each PCA, validate what the axes actually capture by correlating party positions against
+a small reference dataset of known ideological scores. Assign labels honestly.
+
+## Constraints
+
+- No changes to the PCA computation itself (`compute_2d_axes` is unchanged)
+- No new runtime dependencies (scipy is already optional; pandas is already present)
+- `party_ideologies.csv` and `coalition_membership.csv` are static data files — not derived from the DB
+- Backward-compatible: the compass still renders even when reference files are missing (falls back to
+  current hardcoded labels silently)
+
+## Approach
+
+Reference-validated PCA with dynamic labeling. For each time window, correlate the per-party PCA
+positions against known ideological scores. Assign a label based on which correlation is strongest.
+Surface the finding as a one-line caption in the UI when the axis diverges from "Links–Rechts".
+
+Rejected alternatives:
+- **Fixed anchor compass**: replaces honest complexity with comfortable fiction; loses behavioral
+  information entirely
+- **Dual view (behavioral + ideological)**: too much UI complexity for V1; can be done later
+
+## Architecture Overview
+
+A thin axis classification layer sits between `compute_2d_axes` (unchanged) and the compass UI.
+
+```
+compute_2d_axes()
+       ↓
+ positions_by_window  +  axes dict
+       ↓
+classify_axes(positions_by_window, axes, db_path)
+       ↓
+ axes dict enriched with:
+   - x_label, y_label      (global, most-common label across annual windows)
+   - x_quality             (dict: window_id → float, max |r|)
+   - y_quality             (dict: window_id → float, max |r|)
+   - x_interpretation      (dict: window_id → Dutch str)
+   - y_interpretation      (dict: window_id → Dutch str)
+       ↓
+ compass renderer uses labels + per-year quality captions
+```
+
+## Components
+
+### 1. Reference data files
+
+**`data/party_ideologies.csv`**
+
+One row per party. Party names must match entity IDs in the `svd_vectors` table exactly.
+
+```
+party,left_right,progressive
+VVD,0.65,0.10
+PvdA,-0.70,0.75
+SP,-0.90,0.50
+CDA,0.25,-0.45
+D66,-0.10,0.85
+GroenLinks,-0.70,0.90
+GL,-0.70,0.90
+GroenLinks-PvdA,-0.70,0.82
+ChristenUnie,0.10,-0.55
+SGP,0.35,-0.95
+PVV,0.90,-0.50
+DENK,-0.40,0.55
+50Plus,-0.05,-0.10
+FVD,0.90,-0.75
+PvdD,-0.60,0.85
+Volt,-0.20,0.80
+JA21,0.70,-0.30
+BBB,0.50,-0.35
+NSC,0.20,-0.20
+Nieuw Sociaal Contract,0.20,-0.20
+BVNL,0.85,-0.55
+Bij1,-0.90,0.90
+```
+
+Scores: left_right = −1 (far left) to +1 (far right). progressive = −1 (conservative) to +1 (progressive).
+These are expert judgments based on party programs and voting records, not derived algorithmically.
+
+**`data/coalition_membership.csv`**
+
+One row per (window_id, party) where that party held a government seat. Annual windows only; quarterly
+windows inherit from their year.
+
+```
+window_id,party
+2012,VVD
+2012,PvdA
+2013,VVD
+2013,PvdA
+2014,VVD
+2014,PvdA
+2015,VVD
+2015,PvdA
+2016,VVD
+2016,PvdA
+2017,VVD
+2017,CDA
+2017,D66
+2017,ChristenUnie
+2018,VVD
+2018,CDA
+2018,D66
+2018,ChristenUnie
+2019,VVD
+2019,CDA
+2019,D66
+2019,ChristenUnie
+2020,VVD
+2020,CDA
+2020,D66
+2020,ChristenUnie
+2021,VVD
+2021,CDA
+2021,D66
+2021,ChristenUnie
+2022,VVD
+2022,D66
+2022,CDA
+2022,ChristenUnie
+2023,VVD
+2023,D66
+2023,CDA
+2023,ChristenUnie
+2024,PVV
+2024,VVD
+2024,NSC
+2024,BBB
+2025,PVV
+2025,VVD
+2025,NSC
+2025,BBB
+2026,PVV
+2026,VVD
+2026,NSC
+2026,BBB
+```
+
+### 2. `analysis/axis_classifier.py` (new module)
+
+Single public function: `classify_axes(positions_by_window, axes, db_path)`.
+
+The function is pure except for reading two CSV files (cached module-level after first load).
+
+**Algorithm per window:**
+
+1. Collect parties that appear in both `positions_by_window[window_id]` and `party_ideologies.csv`.
+   Skip windows with fewer than 5 overlapping parties.
+2. Build vectors:
+   - `party_x`: per-party X positions from this window
+   - `party_y`: per-party Y positions from this window
+   - `ref_lr`: left_right scores from CSV
+   - `ref_pc`: progressive scores from CSV
+   - `coalition_dummy`: +1 if party is in government for this window's year, −1 otherwise
+     (quarterly windows: strip suffix to get year, e.g., `2016-Q3` → `2016`)
+3. Compute Pearson r for X against each reference dimension:
+   - `r_lr_x = pearsonr(party_x, ref_lr)[0]`
+   - `r_pc_x = pearsonr(party_x, ref_pc)[0]`
+   - `r_co_x = pearsonr(party_x, coalition_dummy)[0]`
+4. Assign label and interpretation using priority order (first threshold that fires wins):
+   - `|r_lr_x| ≥ 0.65` → label = `"Links–Rechts"`, flip sign if r < 0
+   - `|r_co_x| ≥ 0.65` → label = `"Coalitie–Oppositie"`
+   - `|r_pc_x| ≥ 0.65` → label = `"Progressief–Conservatief"`, flip sign if r < 0
+   - fallback → label = `"Stempatroon As 1"`
+5. Quality score for this window's X-axis: `max(|r_lr_x|, |r_pc_x|, |r_co_x|)`
+6. Repeat steps 3–5 for Y-axis using `party_y`.
+7. After processing all windows, pick global X label = modal label across annual windows only
+   (quarterly windows participate in quality tracking but not in the modal vote, to avoid
+   over-weighting).
+
+**Interpretation strings (Dutch):**
+
+| label | interpretation |
+|---|---|
+| Links–Rechts | "De horizontale as weerspiegelt de klassieke links-rechts tegenstelling." |
+| Coalitie–Oppositie | "De horizontale as weerspiegelt stemgedrag van coalitie- versus oppositiepartijen (r={r:.2f}). Links-rechts is minder dominant dit jaar." |
+| Progressief–Conservatief | "De horizontale as weerspiegelt de progressief-conservatieve tegenstelling." |
+| Stempatroon As 1 | "De horizontale as weerspiegelt een empirisch stempatroon zonder duidelijke ideologische richting." |
+
+Y-axis interpretations follow the same template with "verticale" instead of "horizontale".
+
+**Return value:** the input `axes` dict with four new keys added:
+`x_label`, `y_label`, `x_quality` (dict), `y_quality` (dict), `x_interpretation` (dict),
+`y_interpretation` (dict).
+
+### 3. `explorer.py` changes
+
+**`load_positions()`** — after calling `compute_2d_axes`, call `classify_axes` and store the enriched
+axes dict. If `classify_axes` raises for any reason, catch and log; use the original axes dict.
+
+**Compass renderer** — two changes only:
+1. Replace hardcoded `"Links–Rechts"` / `"Progressief–Conservatief"` axis title strings with
+   `axes.get("x_label", "Links–Rechts")` and `axes.get("y_label", "Progressief–Conservatief")`.
+2. Add a caption below the compass for the selected year. Show when either axis quality < 0.65:
+   > *"In 2016 weerspiegelt de horizontale as coalitie–oppositie stemgedrag (r=0.71)."*
+   
+   Source: `axes["x_interpretation"].get(selected_window_id, "")`.
+
+No other UI changes. The compass layout is untouched.
+
+## Data Flow
+
+```
+load_positions(db_path, window_size)
+  → compute_2d_axes(...)          [unchanged; returns positions_by_window, axes]
+  → classify_axes(               [new]
+       positions_by_window,
+       axes,
+       db_path=db_path
+    )
+       reads: data/party_ideologies.csv   (module-level cache)
+       reads: data/coalition_membership.csv  (module-level cache)
+       uses: positions_by_window already in memory
+       writes: new keys into axes dict (no mutation of positions)
+  → return positions_by_window, axes_enriched
+
+compass render (existing function)
+  → axes["x_label"]                       [was hardcoded "Links–Rechts"]
+  → axes["y_label"]                       [was hardcoded "Progressief–Conservatief"]
+  → axes["x_interpretation"][window_id]   [new caption]
+```
+
+No DB writes. No new DB queries. Pure in-memory correlation over data that's already loaded.
+CSV reads are ~microseconds and cached after first call.
+
+## Error Handling
+
+| Failure | Behaviour |
+|---|---|
+| `data/party_ideologies.csv` missing | Log WARNING, return `axes` unchanged (current labels preserved) |
+| `data/coalition_membership.csv` missing | Log WARNING, coalition dimension skipped; other correlations still computed |
+| Party in positions but not in CSV | Skip silently; log once at DEBUG per session |
+| Window has fewer than 5 overlapping parties | Skip classification for that window; use fallback label |
+| All correlations < 0.65 | Fallback label is always safe; no crash |
+| Any unexpected exception in `classify_axes` | Caller (`load_positions`) catches, logs, returns original `axes` dict |
+
+## Testing Strategy
+
+Three new tests added to `tests/test_political_compass.py`:
+
+**`test_axis_label_left_right`**
+Construct synthetic per-party positions where X values correlate strongly (r > 0.8) with the left_right
+column of a minimal inline CSV. Assert that `classify_axes` returns `x_label == "Links–Rechts"` and
+`x_quality[window] > 0.65`.
+
+**`test_axis_label_coalition_dominant`**
+Construct synthetic positions where X values match coalition membership pattern but NOT left-right.
+(E.g., coalition parties [VVD, PvdA] cluster at x=+1, opposition [PVV, SP] at x=−1, which is
+historically coherent for 2016.) Assert `x_label == "Coalitie–Oppositie"` and that the interpretation
+string contains "coalitie".
+
+**`test_axis_classifier_missing_csv`**
+Call `classify_axes` with a db_path pointing to a nonexistent directory so CSV loading fails. Assert
+that the function returns the axes dict unchanged and does not raise.
+
+All three tests use monkeypatching to inject CSV content as in-memory StringIO, following the existing
+pattern in `tests/test_political_compass.py` of patching module-level imports.
+
+## Open Questions
+
+None.