chore: convert mindmodel from YAML to markdown and clean up
Delete 17 malformed YAML constraint files and 10 stale numbered constraint files. Convert domain glossary, patterns, stack, and anti-patterns to markdown format. Update manifest.yaml to reference new markdown files.
This commit is contained in:
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: Domain Glossary
|
||||
category: domain
|
||||
---
|
||||
|
||||
# Domain Glossary - Dutch Political Terms
|
||||
|
||||
## CRITICAL INVARIANTS
|
||||
|
||||
> **Rule 1**: Centroid of right-wing parties on RIGHT side of ALL axes
|
||||
> - PVV, FVD, JA21, SGP centroid must appear on the RIGHT
|
||||
> - Individual right-wing parties may vary slightly from the centroid
|
||||
> - This is non-negotiable for any compass/axis visualization
|
||||
|
||||
> **Rule 2**: SVD labels are empirically derived from voting data
|
||||
> - Labels represent WHAT THE DATA SHOWS, not party self-identification or public opinion
|
||||
> - Labels are derived from outliers and 20 representative motions (10 positive, 10 negative)
|
||||
> - See SVD Label Derivation section below
|
||||
|
||||
---
|
||||
|
||||
## SVD Label Derivation
|
||||
|
||||
### The Process
|
||||
|
||||
SVD (Singular Value Decomposition) finds axes that maximize variance in the MP × Motion voting matrix. To label each axis:
|
||||
|
||||
1. **Identify outliers**: Find the two MPs with most extreme positions on that axis
|
||||
2. **Select representative motions**: Pick 20 motions where these outliers disagreed most sharply (10 they voted opposite on, 10 where both voted same direction but with other extremes)
|
||||
3. **Interpret theme**: Read the motion titles to derive what the axis represents
|
||||
4. **Assign label**: Label describes the empirical theme, could be:
|
||||
- Left-Right
|
||||
- Coalition-Opposition
|
||||
- Progressive-Conservative
|
||||
- EU-National sovereignty
|
||||
- Populist-Establishment
|
||||
- Or whatever the voting patterns show
|
||||
|
||||
### Example
|
||||
|
||||
| Step | Description |
|
||||
|------|-------------|
|
||||
| Outlier A | Wilders (PVV) - extreme positive on Dim 1 |
|
||||
| Outlier B | Marijnissen (SP) - extreme negative on Dim 1 |
|
||||
| 20 Motions | Immigration, integration, law & order themes dominate |
|
||||
| Label | "Links-Rechts" (Left-Right) |
|
||||
|
||||
### Labeling Rules
|
||||
|
||||
- **Never use party names in labels** (e.g., not "PVV-SP axis")
|
||||
- **Never use semantic/ideological labels** (e.g., not "progressive-conservative" unless that's what the motions show)
|
||||
- **Use motion-derived themes** (e.g., "Immigration", "EU", "Economy")
|
||||
- **Fallback**: If theme is unclear, use "Axis 1", "Axis 2"
|
||||
|
||||
---
|
||||
|
||||
## Core Entities
|
||||
|
||||
### Motion / Motie
|
||||
- Parliamentary motion submitted by MPs
|
||||
- Fields: `id`, `title`, `date`, `category`
|
||||
- MPs vote: **For** (+1), **Against** (-1), **Abstain** (0), **Absent**
|
||||
|
||||
### MP / Kamerlid
|
||||
- Member of Parliament (Tweede Kamerlid)
|
||||
- Identified by full name (e.g., "Van Dijk, I.")
|
||||
- Has voting record, party affiliation, SVD position vector
|
||||
|
||||
### Party / Fractie
|
||||
- Political party (e.g., "GroenLinks-PvdA", "PVV", "VVD")
|
||||
- Party centroids: average SVD position of all MPs in party
|
||||
|
||||
### Vote / Stemming
|
||||
- Individual MP's vote on a motion: +1, 0, -1
|
||||
- Aggregated to compute SVD vectors
|
||||
|
||||
---
|
||||
|
||||
## Time & Analysis Concepts
|
||||
|
||||
### Window / Tijdsvenster
|
||||
- Time period for analysis (annual or quarterly)
|
||||
- Values: "2023", "2023-Q1", "2024", etc.
|
||||
- SVD vectors computed per window
|
||||
|
||||
### Trajectory
|
||||
- MP's position change across multiple windows
|
||||
- Computed from `svd_vectors` + window ordering
|
||||
|
||||
---
|
||||
|
||||
## Mathematical / Algorithmic Terms
|
||||
|
||||
### SVD Vector
|
||||
- 2D vector from Singular Value Decomposition of MP × Motion vote matrix
|
||||
- Represents MP's position in political space
|
||||
|
||||
### SVD Label
|
||||
- Empirically derived axis label based on outlier MPs and representative motions
|
||||
- Describes the theme of disagreement on that axis
|
||||
- NOT based on party ideology or semantic labels
|
||||
|
||||
### Political Compass
|
||||
- 2D visualization with SVD axes mapped to compass quadrants
|
||||
- X-axis: First SVD dimension (labeled from voting data)
|
||||
- Y-axis: Second SVD dimension (labeled from voting data)
|
||||
|
||||
### Procrustes Alignment
|
||||
- Algorithm to align SVD vectors across time windows
|
||||
- Ensures comparable positions across years/quarters
|
||||
|
||||
### UMAP
|
||||
- Uniform Manifold Approximation and Projection
|
||||
- Dimensionality reduction for visualization
|
||||
- Optional dependency with graceful SVD fallback
|
||||
|
||||
---
|
||||
|
||||
## Database Table Reference
|
||||
|
||||
| Table | Key Fields |
|
||||
|-------|-----------|
|
||||
| `motions` | id, title, date, category |
|
||||
| `mp_votes` | mp_id, motion_id, vote |
|
||||
| `svd_vectors` | entity_id, window, vector_2d (list[2]) |
|
||||
| `mp_party_history` | mp_id, party, start_date, end_date |
|
||||
| `windows` | window_id, start_date, end_date, period_type |
|
||||
| `mp_trajectories` | mp_id, window, trajectory_vector |
|
||||
|
||||
---
|
||||
|
||||
## Dutch Political Parties
|
||||
|
||||
### Canonical Right-Wing (centroid on RIGHT of axes)
|
||||
- PVV (Partij voor de Vrijheid)
|
||||
- FVD (Forum voor Democratie)
|
||||
- JA21
|
||||
- SGP (Staatkundig Gereformeerde Partij)
|
||||
|
||||
### Other Major Parties
|
||||
- VVD (Volkspartij voor Vrijheid en Democratie)
|
||||
- GL-PvdA (GroenLinks-PvdA)
|
||||
- NSC (Nieuw Sociaal Contract)
|
||||
- BBB (BoerBurgerBeweging)
|
||||
- SP (Socialistische Partij)
|
||||
- D66 (Democraten 66)
|
||||
@@ -1,107 +0,0 @@
|
||||
# Domain Glossary - Dutch Political Terms
|
||||
|
||||
## Core Entities
|
||||
|
||||
### Motion / Motie
|
||||
- Parliamentary motion submitted by MPs
|
||||
- Fields: `id`, `title`, `date`, `category`
|
||||
- MPs vote: **For** (+1), **Against** (-1), **Abstain** (0), **Absent**
|
||||
|
||||
### MP / Kamerlid
|
||||
- Member of Parliament (Tweede Kamerlid)
|
||||
- Identified by full name (e.g., "Van Dijk, I.")
|
||||
- Has voting record, party affiliation, SVD position vector
|
||||
- Historical: `mp_party_history` tracks party changes over time
|
||||
|
||||
### Party / Fractie
|
||||
- Political party (e.g., "GroenLinks-PvdA", "PVV", "VVD")
|
||||
- Party centroids: average SVD position of all MPs in party
|
||||
- Aliases: multiple spelling variants exist (see anti-patterns.yaml)
|
||||
|
||||
### Vote / Stemming
|
||||
- Individual MP's vote on a motion: +1, 0, -1
|
||||
- Aggregated to compute SVD vectors
|
||||
|
||||
---
|
||||
|
||||
## Time & Analysis Concepts
|
||||
|
||||
### Window / Tijdsvenster
|
||||
- Time period for analysis (annual or quarterly)
|
||||
- Values: "2023", "2023-Q1", "2024", etc.
|
||||
- SVD vectors computed per window
|
||||
- Windows can be aligned across time using Procrustes
|
||||
|
||||
### Trajectory
|
||||
- MP's position change across multiple windows
|
||||
- Computed from `svd_vectors` + window ordering
|
||||
- Used for trend analysis in Evolution tab
|
||||
|
||||
---
|
||||
|
||||
## Mathematical / Algorithmic Terms
|
||||
|
||||
### SVD Vector
|
||||
- 2D vector from Singular Value Decomposition of MP × Motion vote matrix
|
||||
- Represents MP's position in political space
|
||||
- `entity_id` in `svd_vectors`: either MP name (when individual MPs) or party name (when party-level)
|
||||
|
||||
### Political Compass
|
||||
- 2D visualization: X-axis = Left↔Right, Y-axis = Progressive↔Conservative
|
||||
- SVD vectors mapped to compass quadrants
|
||||
- UMAP used for projection
|
||||
|
||||
### Procrustes Alignment
|
||||
- Algorithm to align SVD vectors across time windows
|
||||
- Ensures comparable positions across years/quarters
|
||||
- Implemented via `scipy.spatial.procrustes` or scikit-learn
|
||||
|
||||
### Centroid
|
||||
- Geometric center of a set of points
|
||||
- Party centroid = average SVD position of all MPs in that party
|
||||
- Computed from `svd_vectors` filtered by party
|
||||
|
||||
### UMAP
|
||||
- Uniform Manifold Approximation and Projection
|
||||
- Dimensionality reduction for visualization
|
||||
- Optional dependency — graceful fallback if unavailable
|
||||
|
||||
---
|
||||
|
||||
## Visualization
|
||||
|
||||
### PARTY_COLOURS
|
||||
- Dict mapping party names to hex color codes
|
||||
- Used in all Plotly charts for consistent party coloring
|
||||
- Source: `config.py` → `PARTY_COLOURS` constant
|
||||
- **Issue**: 3 separate alias dictionaries exist (no single source of truth)
|
||||
|
||||
---
|
||||
|
||||
## Application Pages
|
||||
|
||||
### Home
|
||||
- Landing page with app overview
|
||||
|
||||
### Stemwijzer (Quiz)
|
||||
- User answers questions → matched to parties
|
||||
- Thin wrapper around quiz module
|
||||
|
||||
### Explorer (4 tabs)
|
||||
- **Motion tab**: SVD positions colored by vote on selected motion
|
||||
- **MP tab**: Individual MP trajectories across windows
|
||||
- **Party tab**: Party centroids with members as scatter
|
||||
- **Evolution tab**: How positions change over time
|
||||
|
||||
---
|
||||
|
||||
## Database Table Reference
|
||||
| Table | Key Fields |
|
||||
|-------|-----------|
|
||||
| `motions` | id, title, date, category |
|
||||
| `mp_votes` | mp_id, motion_id, vote |
|
||||
| `svd_vectors` | entity_id, window, vector_2d (list[2]) |
|
||||
| `party_centroids` | party, window, centroid_2d |
|
||||
| `mp_party_history` | mp_id, party, start_date, end_date |
|
||||
| `windows` | window_id, start_date, end_date, period_type |
|
||||
| `mp_trajectories` | mp_id, window, trajectory_vector |
|
||||
Reference in New Issue
Block a user