feat(altair): implement scatter-basic

[github-actions]

Implementation: scatter-basic - python/altair

Implements the python/altair version of scatter-basic.

File: plots/scatter-basic/implementations/python/altair.py

Parent Issue: #611

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white #FAF8F1 background. The title "scatter-basic · altair · anyplot.ai" appears in dark ink (#1A1A17) at the top-left (anchor=start), followed by a muted subtitle "n = 180 · Pearson r = 0.92" in tertiary ink. X-axis label "Study Hours per Week" and Y-axis label "Exam Score (%)" are clearly rendered in dark ink. Tick labels display as readable dark numbers. 180 data points in brand green (#009E73) are shown with white strokes and opacity=0.7, creating a clear upward-trending cluster. Subtle horizontal and vertical grid lines at 10% opacity are visible without competing with data. All text is fully readable against the light background.

Dark render (plot-dark.png): The same plot on a warm near-black #1A1A17 background. The title, subtitle, axis labels, and tick labels all switch to light ink (#F0EFE8 / #B8B7B0), remaining fully readable. Data markers are the identical brand green #009E73 — no hue shift between themes, confirming Okabe-Ito invariance. Subtle grid lines and axis domain lines are visible. No dark-on-dark failures detected: all chrome elements (text, axis lines, ticks) are correctly light-colored against the dark surface. Both renders pass theme-readability checks.

Score: 89/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All sizes explicitly set: title 28px, axis labels 22px, tick labels 18px; all match pixel-based library guidelines exactly; fully readable in both themes
• VQ-02: No Overlap (6/6) — No text collisions; tick labels well-spaced; subtitle and title cleanly separated
• VQ-03: Element Visibility (6/6) — 180 points at size=170, opacity=0.7; appropriately scaled for the data density; individual points distinguishable
• VQ-04: Color Accessibility (2/2) — Single brand green series; good contrast on both surfaces; no red-green reliance
• VQ-05: Layout & Canvas (4/4) — Plot fills ~75% of canvas; balanced margins; nothing cut off; title placement looks editorial
• VQ-06: Axis Labels & Title (2/2) — X: "Study Hours per Week", Y: "Exam Score (%)" — both descriptive with units
• VQ-07: Palette Compliance (2/2) — First (only) series uses #009E73; backgrounds are #FAF8F1 (light) / #1A1A17 (dark); chrome tokens correct in both renders

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above well-configured defaults: left-aligned title (anchor=start), Pearson r subtitle, no view stroke box, white edge strokes on markers. Intentional but not yet at publication-ready FiveThirtyEight level.
• DE-02: Visual Refinement (4/6) — Solid refinement: ticks disabled, view stroke=None removes box border, grid at 10% opacity, generous labelPadding/titlePadding. Could reach 6 with a trend line or more deliberate spine treatment.
• DE-03: Data Storytelling (4/6) — The Pearson r subtitle and real-world scenario (study hours vs. exam scores) carry genuine narrative weight. No visual hierarchy within the data cloud itself (no regression line, no outlier emphasis) prevents a higher score.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct scatter plot using mark_circle()
• SC-02: Required Features (4/4) — Transparency (~0.7) ✓, axis labels ✓, grid lines ✓, appropriate point sizing ✓
• SC-03: Data Mapping (3/3) — Independent variable (study hours) on X, dependent (exam score) on Y; full range displayed
• SC-04: Title & Legend (3/3) — Title "scatter-basic · altair · anyplot.ai" ✓; single-series, no legend needed

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows 180 scattered points with clear positive correlation and moderate spread. The computed Pearson r=0.92 is stronger than the spec's suggested ~0.7, producing a visually tighter cloud than a typical "moderate correlation" example.
• DQ-02: Realistic Context (5/5) — Study hours vs. exam scores: immediately relatable, neutral educational scenario
• DQ-03: Appropriate Scale (4/4) — Study hours 1–12 hr/week, exam scores 30–100%: both realistic and within expected ranges

Code Quality (9/10)

• CQ-01: KISS Structure (2/3) — Linear structure with no functions/classes. The importlib/sys.path workaround adds minor complexity (needed to avoid naming conflict since the file is named altair.py), but departs from the clean import pattern.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ✓
• CQ-03: Clean Imports (2/2) — All imports (os, sys, importlib, alt, np, pd) are actually used
• CQ-04: Code Elegance (2/2) — Clean chained Altair API; no fake UI; appropriate complexity for the visualization
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png (scale_factor=3.0) and plot-{THEME}.html; no bare plot.png

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Expert Altair patterns: mark_circle with proper :Q type annotations, alt.X/alt.Y with alt.Axis/alt.Scale, alt.Title with subtitle, configure_* methods, .interactive() — all idiomatic Vega-Lite/Altair
• LM-02: Distinctive Features (3/5) — Tooltips with format specifications and .interactive() for HTML export leverage Altair's declarative grammar. These go beyond matplotlib-equivalent code, though a second chart layer (e.g., regression line) would showcase Altair's layering strength.

Score Caps Applied

• None — no caps apply (no zeros in key criteria)

Strengths

• Perfect visual quality: all font sizes explicitly set to guideline values; both themes fully legible with no chrome failures
• Correct Okabe-Ito brand green as the sole data color; backgrounds and chrome tokens exactly match theme spec
• Informative Pearson r subtitle adds storytelling without annotations — a thoughtful editorial choice
• White stroke on markers (stroke=PAGE_BG) provides excellent definition for overlapping points
• Idiomatic Altair: proper type annotations, alt.Title, configure_* chain, .interactive() for HTML
• Complete output: both PNG (scale_factor=3.0 → 4800×2700) and HTML artifacts

Weaknesses

• DE-01 (5/8): Design is clean but not yet publication-ready — lacks a second layer (e.g., regression line) or other design elements that would elevate it beyond a polished single-series scatter
• DE-02 (4/6): Minor: could further refine by also removing bottom/left domain lines for a spine-free minimal look, or by removing the grid entirely for a very clean scatter
• DE-03 (4/6): No visual hierarchy within the data — a trend/regression line would reinforce the r=0.92 story shown in the subtitle and create a clear focal point
• DQ-01 (5/6): Correlation r=0.92 is stronger than the spec's suggested ~0.7 moderate correlation — the scatter cloud is tighter than a typical scatter-basic example; increasing noise would produce a more representative moderate-scatter pattern
• CQ-01 (2/3): The importlib/sys.path workaround is functional but adds complexity relative to a direct import

Issues Found

1. DE-03 LOW (4/6): No visual hierarchy within the scatter cloud itself — the Pearson r subtitle tells the story verbally but nothing visual guides the eye
   • Fix: Add a regression line as a second Altair layer (transform_regression + mark_line) to visually reinforce the correlation trend
2. DE-01 (5/8): Not yet at publication-ready level
   • Fix: The regression line would also improve DE-01; alternatively, subtle size encoding or color-intensity gradient by density would add sophistication
3. DQ-01 (5/6): Data correlation r=0.92 exceeds the spec's ~0.7 target
   • Fix: Increase noise standard deviation (e.g., 12–15) so the computed r falls in the 0.65–0.75 range, producing a more typical moderate-scatter pattern

AI Feedback for Next Attempt

Add a regression line using Altair's built-in transform_regression + mark_line() as a second layer composed with +. This single change addresses three issues at once: DE-03 (visual hierarchy and storytelling), DE-01 (sophistication — Altair's native regression transform is a library-distinctive feature), and LM-02. Also increase noise (std=12–14) so the Pearson r drops toward ~0.70–0.75 as specified. The rest of the implementation is excellent — don't over-engineer it.

Verdict: REJECTED