feat(altair): implement scatter-lag

[github-actions]

Implementation: scatter-lag - altair

Implements the altair version of scatter-lag.

File: plots/scatter-lag/implementations/altair.py

Parent Issue: #5251

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot shows a scatter lag plot of approximately 499 points from a synthetic AR(1) process (phi=0.85). Points are colored using the viridis colormap — dark purple for early time indices and yellow-green for later — revealing temporal structure in the autocorrelation. A dashed gray diagonal reference line (y=x) traverses the chart, helping viewers assess autocorrelation strength. The x-axis is labeled "y(t)" and the y-axis "y(t + 1)". Title reads "scatter-lag · altair · pyplots.ai". A gradient colorbar legend on the right is labeled "Time Index" (0–400). The overall pattern is a clear positive linear cluster along the diagonal, visually confirming strong positive autocorrelation. Background is white with very subtle gridlines. The x-axis has quite dense tick marks at 0.4 increments, appearing crowded at display resolution.

Score: 79/100

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

Visual Quality (23/30)

• VQ-01: Text Legibility (7/8) — All sizes explicitly set (title 28pt, axis title 22pt, ticks 18pt); legend labels at 14pt fall slightly below the 16pt minimum guideline
• VQ-02: No Overlap (4/6) — X-axis tick labels at 0.4-unit intervals produce a dense label row; no hard collision but visually crowded
• VQ-03: Element Visibility (3/6) — size=120 with opacity=0.7 for 499 points exceeds the recommended 20–50 / 0.3–0.5 range; central cluster shows visible overplotting
• VQ-04: Color Accessibility (4/4) — Viridis is perceptually uniform and colorblind-safe; excellent choice
• VQ-05: Layout & Canvas (3/4) — Good proportions; minor excess whitespace in top-right corner near the isolated legend
• VQ-06: Axis Labels & Title (2/2) — "y(t)" and "y(t + 1)" are descriptive; title matches the required format

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Looks like a well-configured Altair default: viridis colormap and white point stroke add polish, but no custom typography or intentional visual hierarchy beyond the color gradient
• DE-02: Visual Refinement (3/6) — Grid opacity 0.2 and strokeWidth=0 on the view show deliberate refinement; however spines are not explicitly removed and the legend feels somewhat disconnected from the chart area
• DE-03: Data Storytelling (3/6) — The viridis temporal gradient is a meaningful encoding choice that reveals time-ordering in the autocorrelation; the diagonal reference line frames the story well; no correlation coefficient annotation to anchor the viewer's interpretation

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct lag scatter plot with y(t) on x-axis and y(t+1) on y-axis
• SC-02: Required Features (4/4) — Diagonal reference line ✓, color by time index ✓, configurable lag ✓, realistic AR(1) data ✓
• SC-03: Data Mapping (3/3) — X/Y correctly assigned; full data range visible
• SC-04: Title & Legend (3/3) — Title "scatter-lag · altair · pyplots.ai" is correct; legend label "Time Index" is appropriate

Data Quality (13/15)

• DQ-01: Feature Coverage (5/6) — Strong autocorrelation pattern clearly visible; shows the main diagnostic purpose of a lag plot; a slight deduction because the data doesn't vary lag order or demonstrate the contrast between correlated and uncorrelated data
• DQ-02: Realistic Context (4/5) — Synthetic AR(1) process is explicitly listed in the spec as a valid example; plausible and neutral; minor deduction since data is purely abstract without a named real-world domain
• DQ-03: Appropriate Scale (4/4) — Values ~−5 to +6 are typical for a zero-mean AR(1) with unit noise; realistic

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data → reference line → points → chart → save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — Only altair, numpy, pandas; all used
• CQ-04: Code Elegance (2/2) — Well-organized, appropriate complexity; layer composition cleanly separates the two chart components
• CQ-05: Output & API (1/1) — chart.save("plot.png", scale_factor=3.0) is correct; also saves HTML

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Excellent Altair usage: declarative encoding types (:Q), layer composition via +, configure_axis/configure_view, alt.Scale and alt.Legend with full parameterization
• LM-02: Distinctive Features (3/5) — Layer composition and interactive tooltip encoding are Altair-specific; HTML export leverages Altair's interactive nature; however no use of selections, transformations, or other higher-level Altair features (e.g., alt.Chart.transform_calculate for lag derivation, or interactive brush selection)

Score Caps Applied

• None applied — all cap conditions unmet

Strengths

• Perfect spec compliance: diagonal reference line, viridis color encoding by time index, correct axis labels, and required title format all present
• Flawless code quality: reproducible seed, clean KISS structure, idiomatic Altair layer composition
• Excellent library usage: declarative encoding, proper configure_axis/configure_view, correct PNG output at 4800×2700 px
• Viridis colormap is a great choice — colorblind-safe and visually communicates temporal order

Weaknesses

• Point size (120) and opacity (0.7) are too large/opaque for 499 data points; reduce to ~40–60 size and 0.4–0.5 opacity to reduce overplotting in the center cluster
• Dense x-axis tick labels (0.4-unit increments) create a crowded axis; reduce tick density or use axis tick count to limit to ~10–12 ticks
• Legend label font size (14pt) is slightly below the minimum 16pt guideline
• Design lacks a correlation coefficient annotation (the spec suggests "r value" as an enhancement) which would significantly improve storytelling
• No intentional visual hierarchy beyond color; consider a subtle background annotation or reference text to guide the viewer

Issues Found

1. VQ-03 LOW: Marker size 120 + opacity 0.7 for 499 points causes overplotting
   • Fix: Reduce to size ~50 and opacity ~0.45 to follow density guidelines for 300+ points
2. DE-01 MEDIUM: No design elements beyond well-configured defaults
   • Fix: Add a correlation coefficient text annotation (r = ...) on the chart; refine legend positioning; consider removing top/right spines explicitly
3. DE-02 MEDIUM: Spines not explicitly configured; legend disconnected from data area
   • Fix: Use configure_view and configure_axis to fully remove spines; consider placing legend inside or adjacent to the plot
4. VQ-02 MINOR: Dense x-axis ticks at 0.4 intervals
   • Fix: Add tickCount=10 or similar to alt.X scale or axis to reduce crowding

AI Feedback for Next Attempt

Primary improvements needed: (1) Reduce marker size to ~50 and opacity to ~0.45 for 499 data points to reduce overplotting. (2) Add a correlation coefficient text annotation (computed as np.corrcoef(y_t, y_t_lag)[0,1]) placed in a corner of the chart — this is explicitly suggested by the spec and dramatically improves storytelling. (3) Reduce x-axis tick density to ~10–12 ticks. (4) Increase legend label font size to 16pt. (5) For design refinement, explicitly configure spines away and integrate the legend more tightly with the plot area.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/3

Applied fixes based on AI review feedback.

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

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

A scatter lag plot showing 499 points from a synthetic AR(1) process (φ=0.85). The x-axis is labeled "y(t)" and the y-axis "y(t + 1)", both ranging from about -5 to 6. Points are colored using the viridis colormap (purple/blue = early time index, yellow-green = late time index), with opacity=0.45 and white edge strokes. A dashed gray diagonal reference line (y=x) runs from bottom-left to top-right, making the strong positive autocorrelation immediately visible. A bold "r = 0.834" annotation appears in the lower-right of the plot area. The title reads "scatter-lag · altair · pyplots.ai" with subtitle "AR(1) process (φ = 0.85) | lag = 1". A vertical viridis color legend labeled "Time Index" is positioned on the right. The background is white with an extremely subtle grid, no axis border, and clean typography throughout.

Score: 90/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 28pt, subtitle 18pt, axis titles 22pt, tick labels 18pt, legend 16pt, annotation 20pt bold. Fully readable.
• VQ-02: No Overlap (6/6) — No text or data element collisions. Legend on right is well-separated from plot area.
• VQ-03: Element Visibility (6/6) — 500 points at size=45, opacity=0.45 with white stroke. Matches the 300+ guideline (size 20-50, alpha 0.3-0.5). Points are individually distinguishable even in dense center region.
• VQ-04: Color Accessibility (4/4) — Viridis is perceptually uniform and colorblind-safe. Excellent choice for sequential time data.
• VQ-05: Layout & Canvas (4/4) — Plot fills ~70% of canvas with balanced margins. Title top-left, legend right, annotation bottom-right — well distributed.
• VQ-06: Axis Labels & Title (1/2) — Labels "y(t)" and "y(t + 1)" are mathematically descriptive but carry no physical units. Appropriate for abstract time series but scores 1/2.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above defaults: viridis colormap chosen deliberately, opacity=0.45 with white edge strokes adds depth, dashed reference line (#aaaaaa) is subtle and appropriate, configure_view(strokeWidth=0) removes border, domainWidth=0 removes axis lines. Cohesive design system clearly above "configured defaults" but not quite publication-ready.
• DE-02: Visual Refinement (4/6) — Subtle grid (opacity 0.15, width 0.5), removed axis border and domain line, soft tick colors (#999999), title anchored to start with offset. More refined than library defaults.
• DE-03: Data Storytelling (4/6) — The r=0.834 annotation quantifies the visible pattern; viridis time-coloring reveals temporal structure; diagonal reference line enables direct visual interpretation. Together they guide the viewer to the insight: strong positive autocorrelation with no obvious temporal trend.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct lag plot: scatter of y(t) vs y(t+k).
• SC-02: Required Features (4/4) — Diagonal reference line ✓, color by time index ✓, correlation coefficient annotation ✓, configurable lag (variable) ✓.
• SC-03: Data Mapping (3/3) — X=y(t), Y=y(t+1). Correct orientation. All 499 points visible.
• SC-04: Title & Legend (3/3) — Title exactly "scatter-lag · altair · pyplots.ai" ✓. Legend labeled "Time Index" ✓.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all key aspects: strong autocorrelation pattern, diagonal reference for comparison, temporal coloring revealing no drift, correlation quantified.
• DQ-02: Realistic Context (5/5) — AR(1) process (φ=0.85) is a real, neutral statistical scenario. Subtitle identifies parameters clearly.
• DQ-03: Appropriate Scale (4/4) — 500 observations, values ~N(0, ~2.8) as expected for AR(1) with φ=0.85. Perfectly realistic.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → data → chart layers → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — altair, numpy, pandas — all used, none unnecessary.
• CQ-04: Code Elegance (2/2) — Altair layer composition (reference_line + points + annotation) is clean and idiomatic. No over-engineering.
• CQ-05: Output & API (1/1) — Saves plot.png with scale_factor=3.0 and plot.html. Uses current altair 6.0.0 API.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Expert Altair usage: declarative encoding with typed fields (Q/N), layer composition via +, alt.Scale/Axis/Legend for fine control, configure_axis/configure_view/configure_title global styling.
• LM-02: Distinctive Features (3/5) — Layer composition (+), interactive tooltips, HTML export alongside PNG, declarative color scheme (alt.Scale(scheme="viridis")). These are distinctly Altair patterns, though still somewhat basic within the library's capabilities.

Score Caps Applied

• None — DE-01=5 > 2 and DE-02=4 > 2, so the 75-point cap does not apply.

Strengths

• Viridis colormap with opacity and white edge strokes creates a professional, layered look
• All required spec features present: reference line, time coloring, correlation annotation, configurable lag
• Altair layer composition (reference_line + points + annotation) is idiomatic and clean
• Explicit font sizing throughout ensures legibility at 4800×2700px
• Subtle grid (opacity 0.15) and no axis border give a polished, clean background

Weaknesses

• DE-01 held back by lacking a truly distinctive visual signature (e.g., custom highlight color for high-lag-period points, or a marginal distribution element)
• DE-02 could reach 6/6 with generous outer padding and a slightly more intentional whitespace strategy
• VQ-06 partial: axis labels use mathematical notation without units (appropriate but not 2/2)
• LM-02: could leverage Altair's selection/brush interactivity or faceting to show multiple lag values side-by-side

Issues Found

None blocking approval.

AI Feedback for Next Attempt

This implementation is strong. If regenerated, consider: (1) faceting to show lag=1, lag=7, lag=12 side-by-side using alt.facet() to leverage Altair's distinctive multi-view composition; (2) increasing outer padding for more generous whitespace; (3) a subtle regression line in addition to the y=x reference to better highlight the difference between autocorrelation and perfect dependence.

Verdict: APPROVED