You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
89 lines
4.1 KiB
89 lines
4.1 KiB
---
|
|
date: 2026-03-30
|
|
topic: "compass-trajectory-consistency"
|
|
status: draft
|
|
---
|
|
|
|
# Implementation Plan — Compass ↔ Trajectory Consistency
|
|
|
|
This plan implements the validated design (thoughts/shared/designs/2026-03-30-compass-trajectory-consistency-design.md) with the following firm constraints from the user:
|
|
- Use per-window MP-centroid party coordinates as the canonical source for components 1 & 2
|
|
- When a party has no MPs in a window, use the first chronological party vector as fallback
|
|
- **Update all callers** to the new explicit API; do NOT keep backward compatibility shims
|
|
|
|
|
|
## Goal
|
|
|
|
Make the political compass numeric values identical to trajectory centroids for SVD components 1 and 2 by passing explicit per-party (x,y) coordinates (computed from positions_by_window) to the compass renderer and updating all callers to use that API.
|
|
|
|
|
|
## Micro-tasks (ordered, small, actionable)
|
|
|
|
All tasks assume a development branch and running tests locally. Each task should be one commit.
|
|
|
|
1) Add explorer_helpers.py (pure helper)
|
|
- Create compute_party_coords(positions_by_window, party_map, window_id, fallback_party_scores=None)
|
|
- Returns (party_coords: Dict[str,(x,y)], fallback_used: Set[str])
|
|
- Unit tests: tests/test_explorer_helpers.py
|
|
- Estimate: 2.0h
|
|
|
|
2) Update explorer.py to the new strict API
|
|
- Replace _build_party_axis_figure to accept only explicit party_coords for comp_sel 1 & 2.
|
|
- Remove old polymorphic/legacy path; callers must pass party_coords or raise a clear error.
|
|
- Update rendering glue to call _build_party_axis_figure with explicit party_coords.
|
|
- Ensure hover text shows fallback notes for parties where fallback_used contains the party.
|
|
- Update/clean Streamlit caption behavior when no coords available.
|
|
- Tests: modify tests/test_explorer_chart.py to supply party_coords shape and assert behavior.
|
|
- Estimate: 4.5h
|
|
|
|
3) Update all callers across repo to pass explicit party_coords
|
|
- Grep for places that previously passed party vectors into _build_party_axis_figure or used load_party_axis_scores for compass rendering.
|
|
- Update each call site to compute party_coords via compute_party_coords, passing the fallback_party_scores (first-chronological vector) when needed.
|
|
- Caller list (non-exhaustive — verify with repo search):
|
|
- explorer.build_svd_components_tab
|
|
- explorer._render_party_axis_chart (if present)
|
|
- any scripts or tests that directly call _build_party_axis_figure
|
|
- Update tests referencing legacy vector shape.
|
|
- Estimate: 3.0h
|
|
|
|
4) Add integration consistency test
|
|
- tests/test_compass_trajectory_consistency.py — synthetic positions_by_window and party_map to assert compute_party_coords equals centroid computations used by trajectories.
|
|
- Estimate: 1.0h
|
|
|
|
5) Run full test suite and fix regressions
|
|
- Run pytest; address failures introduced by strict API change.
|
|
- If other modules relied on old shape in ways not covered by tests, update them to use compute_party_coords.
|
|
- Estimate: 1.5h
|
|
|
|
6) Manual QA
|
|
- Run streamlit run explorer.py and visually verify compass tooltips and trajectories hover values match (comps 1 & 2) for several parties and windows.
|
|
- Verify fallback tooltip and logger WARN when a party uses fallback vector.
|
|
- Estimate: 1.0h
|
|
|
|
7) Commit and push (or open PR) with description:
|
|
"feat(explorer): use explicit per-party (x,y) coords from positions_by_window for compass (components 1 & 2); update callers and add tests"
|
|
- Estimate: 0.5h
|
|
|
|
|
|
## Verification commands
|
|
|
|
- Unit tests:
|
|
- python -m pytest tests/test_explorer_helpers.py
|
|
- python -m pytest tests/test_explorer_chart.py
|
|
- python -m pytest tests/test_compass_trajectory_consistency.py
|
|
- Full test suite:
|
|
- python -m pytest
|
|
- Manual UI:
|
|
- streamlit run explorer.py
|
|
|
|
|
|
## Rollback and mitigation
|
|
|
|
- If the strict API uncovers many call sites, revert to a temporary feature branch, document call sites, and migrate them in smaller patches.
|
|
- Keep commits small and self-contained to ease review.
|
|
|
|
|
|
## Notes
|
|
|
|
- This plan follows the user's instruction to update all callers and to use the first chronological party vector as fallback.
|
|
- The helper is pure Python to keep tests simple; callers may cache if needed.
|
|
|