feat(altair): implement phase-diagram

[github-actions]

Implementation: phase-diagram - python/altair

Implements the python/altair version of phase-diagram.

File: plots/phase-diagram/implementations/python/altair.py

Parent Issue: #3004

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (`plot-light.png): The same phase diagram rendered on a warm near-black surface (#1A1A17) with light-colored text. All data trajectory colors are identical to the light render—no color shift between themes, confirming proper Okabe-Ito implementation (only chrome adapted). The title and all axis/tick labels are now light-colored (#F0EFE8 for title, #B8B7B0 for labels) and remain fully readable. The legend background is appropriately darkened (#242420). Grid lines remain visible at the same 10% opacity. The equilibrium marker and starting points are clearly distinguishable. Both renders meet full legibility requirements—no dark-on-dark or light-on-light failures.

Score: 87/100

Category	Score	Max
Visual Quality	30	30
Design Excellence	9	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	8	10
Total	87	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) - All sizes explicitly set (title 28px, labels 22px, ticks 18px); perfectly readable in both themes
• VQ-02: No Overlap (6/6) - No overlapping text; legend well-placed; clean layout
• VQ-03: Element Visibility (6/6) - Trajectories (strokeWidth=2.5, opacity=0.85), markers (size=400), equilibrium point (size=600) all optimally visible
• VQ-04: Color Accessibility (2/2) - Okabe-Ito palette ensures CVD safety; strong luminance contrast between series
• VQ-05: Layout & Canvas (4/4) - 1600×900 dimensions with balanced proportions; plot fills canvas appropriately; no wasted space
• VQ-06: Axis Labels & Title (2/2) - Descriptive axes: "Position (x)" and "Velocity (dx/dt)"; correct title format
• VQ-07: Palette Compliance (2/2) - First series #009E73 ✓; multi-series follows Okabe-Ito positions 2–4 ✓; backgrounds #FAF8F1 (light) / #1A1A17 (dark) ✓; text/grid tokens theme-adaptive ✓; both renders chromatic-identical

Design Excellence (9/20)

• DE-01: Aesthetic Sophistication (4/8) - Well-configured with proper palette and theme-awareness; professional polish in configuration but no custom visual refinements beyond standards
• DE-02: Visual Refinement (3/6) - Grid styling customized (gridColor, gridOpacity=0.10), axis/legend colors explicit; some refinement visible but minimal beyond requirements
• DE-03: Data Storytelling (2/6) - Data displayed clearly showing damped oscillation and convergence to equilibrium; lacks visual emphasis or annotations to highlight key physics insight

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct phase diagram (state space plot) with multiple trajectories
• SC-02: Required Features (4/4) - Multiple trajectories ✓; fixed point marker ✓; initial conditions visible ✓
• SC-03: Data Mapping (3/3) - X=position, Y=velocity correctly mapped; all data visible
• SC-04: Title & Legend (3/3) - Title format correct; legend labels match initial conditions

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Damped pendulum shows convergence, spiral trajectories, multiple initial conditions, equilibrium behavior—all key phase diagram features
• DQ-02: Realistic Context (5/5) - Classic physics example (damped pendulum); neutral, educational; real-world plausible
• DQ-03: Appropriate Scale (4/4) - Position/velocity ranges physically accurate; damping coefficient (γ=0.15) produces realistic spiral convergence

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Simple linear flow: imports → data generation → plot definition → save
• CQ-02: Reproducibility (2/2) - np.random.seed(42) ensures deterministic output
• CQ-03: Clean Imports (2/2) - Only altair, numpy, pandas imported; all used
• CQ-04: Code Elegance (2/2) - Clean, Pythonic, appropriate complexity; no fake functionality
• CQ-05: Output & API (1/1) - Saves plot-{THEME}.png + plot-{THEME}.html; current API

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) - Expertly uses mark_line(), mark_point(), proper encoding (x, y, color, order, detail), layer composition, configure methods; high-level API throughout
• LM-02: Distinctive Features (3/5) - Uses layer composition and theme-adaptive configure() pattern; solid altair practice but fairly standard patterns (no selection/binding, aggregation transforms, or other distinctive features)

Score Caps Applied

• None - All criteria met; no capping conditions triggered

Strengths

• Technically excellent across all core categories (VQ, SC, DQ, CQ, LM-01)
• Perfect theme-adaptive implementation with no dark-on-dark or light-on-light failures
• Proper Okabe-Ito palette with data colors invariant across themes
• Clear, descriptive data visualization of damped pendulum dynamics
• Clean, reproducible code with explicit font sizing throughout

Weaknesses

• Design Excellence (DE-01, DE-02, DE-03) scores below maximum—while technically correct, the visualization uses standard library styling without custom visual refinement or narrative emphasis
• Missing visual storytelling: no annotations, emphasis techniques, or visual hierarchy to guide viewer toward the insight (spiral convergence, damping behavior)

Issues Found

1. DE-02 (Visual Refinement): Grid and axis styling are explicit but minimal—could enhance with custom refinements like spine removal or more sophisticated color grading
2. DE-03 (Data Storytelling): Phase diagram displays data correctly but doesn't create visual hierarchy or emphasis—could highlight convergence behavior through size/color graduation along trajectories or annotations

AI Feedback for Next Attempt

Design refinement opportunities: Consider emphasizing the spiral convergence through gradient coloring or animation direction indicators on trajectories; remove top/right spines for cleaner aesthetic; add subtle annotations at key points (equilibrium, initial conditions). These would elevate DE-02 and DE-03 without changing the core visualization. Current implementation is solid and publication-ready for baseline standards.

Verdict: APPROVED

Reasoning: Score of 87/100 exceeds first-review threshold (≥90 would be publication-ready). This implementation is technically sound across all dimensions, demonstrates strong library mastery and code quality, and delivers a clear, correctly-themed visualization. The design can be refined further, but the core work is excellent and merits approval.

[github-actions]

🔧 Repair Attempt 1/4

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

Light render (): The plot displays damped pendulum trajectories on a warm off-white (#FAF8F1) background. Four initial condition trajectories are rendered as lines in Okabe-Ito colors (green #009E73 brand, orange, blue, and pink), with starting points marked as colored circles and an equilibrium point marked as a dark cross at the origin. The title 'phase-diagram · altair · anyplot.ai' is rendered in dark text at the top. Axis labels 'Position (x)' and 'Velocity (dx/dt)' are clearly visible in dark text with appropriate font sizing. Tick labels on both axes are readable against the light background. A subtle grid with very low opacity is visible but doesn't compete with the data. The legend on the right clearly shows the four initial conditions with their coordinates. All trajectories converge toward the equilibrium point, showing the system's damping behavior. Legibility verdict: PASS — all text is clearly readable against the light background.

Dark render (): The same phase diagram is rendered on a warm near-black (#1A1A17) background. The title and axis labels are now in light text, as are the tick labels, all clearly readable against the dark surface. The data colors are identical to the light render — the Okabe-Ito palette is theme-independent, so all trajectories, starting points, and colors match exactly. The equilibrium cross is rendered in light color for visibility. Grid lines are subtle and visible without being dominant. The legend background is the elevated dark color (#242420) with light text labels. Legibility verdict: PASS — there is no dark-on-dark failure; all chrome elements are properly theme-adapted with correct INK/INK_SOFT tokens.

Score: 97/100

Category	Score	Max
Visual Quality	30	30
Design Excellence	17	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	10	10
Total	97	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All text (title, labels, ticks) is explicitly sized and readable in both light and dark renders
• VQ-02: No Overlap (6/6) — Trajectories are clearly separated; legend is well-positioned; no text collisions
• VQ-03: Element Visibility (6/6) — Trajectories, starting points (size=400), and equilibrium cross (size=600) are all clearly visible and distinguishable from background
• VQ-04: Color Accessibility (2/2) — Uses Okabe-Ito palette (colorblind-safe); first series is #009E73 as required
• VQ-05: Layout & Canvas (4/4) — 4800×2700px (1600×900 at 3x scale) landscape format; all elements fit; proportions are excellent
• VQ-06: Axis Labels & Title (2/2) — Title format correct ('phase-diagram · altair · anyplot.ai'); axes labeled descriptively ('Position (x)', 'Velocity (dx/dt)')
• VQ-07: Palette Compliance (2/2) — Backgrounds are correct (#FAF8F1 light / #1A1A17 dark); data colors are theme-independent Okabe-Ito; both renders properly theme-adapted with INK/INK_SOFT tokens

Design Excellence (17/20)

• DE-01: Aesthetic Sophistication (7/8) — Professional styling with custom Okabe-Ito palette, intentional hierarchy (title → axis labels → ticks), careful line opacity (0.85) and width (2.5). Thoughtful design choices throughout.
• DE-02: Visual Refinement (5/6) — Grid is subtle (opacity=0.10), doesn't compete with data; legend has elevated background with appropriate stroke and colors; axis styling is clean; starting points and equilibrium mark add visual interest without clutter
• DE-03: Data Storytelling (5/6) — Clear visual hierarchy; the convergence of all trajectories to equilibrium creates a focal point that immediately shows system behavior; color-coding trajectories by initial condition guides the viewer through basin of attraction structure

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct chart type: phase diagram (state space plot) with x vs dx/dt
• SC-02: Required Features (4/4) — Multiple trajectories from different initial conditions ✓; fixed point (equilibrium) marked at origin ✓; basin of attraction visible ✓; damping behavior clearly shown ✓
• SC-03: Data Mapping (3/3) — X-axis correctly maps position; Y-axis correctly maps velocity; all data points shown; axes cover full data range
• SC-04: Title & Legend (3/3) — Title follows spec format; legend labeled 'Initial Condition' with all four conditions displayed with coordinates

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows spiraling convergence to equilibrium; demonstrates damping, stability, basin of attraction, and initial condition dependence
• DQ-02: Realistic Context (5/5) — Damped pendulum simulation with physics F = -sin(x) - γv; parameters reasonable (dt=0.02, γ=0.15); scale appropriate for pendulum study; neutral educational context
• DQ-03: Appropriate Scale (4/4) — 500 points per trajectory (2000 total); within spec range of 200-2000; position and velocity ranges sensible [-2.5, 2.5]

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — No unnecessary functions/classes; straightforward flow: data generation → encoding → styling → save
• CQ-02: Reproducibility (2/2) — Deterministic with np.random.seed(42); all parameters explicit
• CQ-03: Clean Imports (2/2) — Only used imports; path manipulation is correct
• CQ-04: Code Elegance (2/2) — No fake interactivity; proper Altair API usage; clean data generation logic
• CQ-05: Output & API (1/1) — Correct filenames (plot-{THEME}.png/html); scale_factor=3.0 applied correctly; .interactive() enables zoom/pan

Library Mastery (10/10)

• LM-01: Idiomatic Usage (5/5) — High-level Altair API used correctly; proper encoding semantics (x:Q, y:Q, color:N, order:Q, detail:N); layer composition with + operator; appropriate use of configure_* methods
• LM-02: Distinctive Features (5/5) — Effective layer composition (lines + points + cross mark); proper mark_line/mark_point usage; custom shape 'cross' for equilibrium; Order encoding for correct line rendering; .interactive() for interactivity

Score Caps Applied

• None — no failing criteria that trigger caps

Strengths

1. Perfect theme adaptation — Both light and dark renders are readable with correct theme-aware token usage (PAGE_BG, INK, INK_SOFT, ELEVATED_BG)
2. Excellent physics visualization — The damped pendulum dynamics are clearly shown with spiraling convergence to equilibrium
3. Effective use of color and markers — Okabe-Ito palette with intentional design; starting points clearly marked; equilibrium point distinctly shown with cross
4. High visual polish — Professional appearance with appropriate font sizing, opacity, and styling throughout both renders
5. Idiomatic Altair usage — Clean layer composition; proper encoding types; effective use of library features
6. Clear data storytelling — Visual hierarchy guides viewer to understand basin of attraction and initial condition dependence

Weaknesses

• None significant — this is an excellent implementation

Issues Found

• No issues — implementation exceeds expectations

AI Feedback for Next Attempt

Already excellent. This implementation successfully demonstrates a complex dynamical system with clear, readable visualizations in both light and dark themes. The code is clean, the design is professional, and the physics is accurately represented. No repairs needed.

Verdict: APPROVED