feat(altair): implement line-timeseries

[github-actions]

Implementation: line-timeseries - python/altair

Implements the python/altair version of line-timeseries.

File: plots/line-timeseries/implementations/python/altair.py

Parent Issue: #2006

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot displays a time series of stock prices over 252 trading days on a warm off-white background (#FAF8F1). The title "line-timeseries · altair · anyplot.ai" is rendered in dark text (#1A1A17) at the top center. The X-axis is labeled "Date" with month-year format labels rotated -45° (Feb 2024, Mar 2024, etc.), all clearly readable. The Y-axis is labeled "Stock Price ($)" with tick values from 76-120, also clearly readable in dark text. The data line is rendered in the Okabe-Ito brand color (#009E73) with 3px stroke width and point markers visible along the line. Subtle gray grid lines at ~10% opacity aid readability. All elements are legible with excellent contrast against the light background.

Dark render (plot-dark.png): The same plot on a warm near-black background (#1A1A17) maintains visual integrity perfectly. The title and axis labels are now rendered in light text (#F0EFE8 for title, #B8B7B0 for ticks), providing excellent contrast against the dark background. The data line color (#009E73) is identical to the light render, clearly visible and unchanged. Grid lines are now rendered in light gray at ~10% opacity, maintaining the same subtle appearance. All text is readable with no "dark-on-dark" failures. The plot background is the correct warm near-black, not pure black.

Score: 92/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — Title 28px, axis labels 22px, tick labels 18px all properly sized and readable in both themes
• VQ-02: No Overlap (6/6) — X-axis labels rotated -45° prevent overlap; Y-axis well-spaced
• VQ-03: Element Visibility (6/6) — 3px line stroke with 150-size point markers clearly visible; no hidden elements
• VQ-04: Color Accessibility (2/2) — Okabe-Ito #009E73 colorblind-safe; excellent contrast with both backgrounds
• VQ-05: Layout & Canvas (4/4) — Proper 4800x2700px proportions; title, axes, and data well-positioned; nothing cut off
• VQ-06: Axis Labels & Title (2/2) — "Date" and "Stock Price ($)" descriptive with units
• VQ-07: Palette Compliance (2/2) — Correct backgrounds (#FAF8F1 light / #1A1A17 dark), first series #009E73, theme-adaptive chrome (labels, grid, title) properly applied to both renders

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (5/8) — Clean, professional execution with proper theme tokens throughout. Well-implemented standard design; could enhance with custom enhancements like highlighting specific periods or reference lines
• DE-02: Visual Refinement (5/6) — Subtle grid at 10% opacity, clean axis presentation, generous whitespace. Minimal but effective refinement
• DE-03: Data Storytelling (4/6) — Clear temporal trend showing stock volatility and upward drift; visual hierarchy supports pattern recognition; could emphasize specific intervals or turning points

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct time series line chart with datetime X-axis and numeric Y-axis
• SC-02: Required Features (4/4) — Intelligent date formatting ("%b %Y"), adaptive to annual scale; rotated labels prevent overlap; grid lines on both axes; interactive tooltips included
• SC-03: Data Mapping (3/3) — X-axis uses date:T (temporal); Y-axis uses price:Q (quantitative); scale=zero=False appropriate for price data; axes show full 252-point range
• SC-04: Title & Legend (3/3) — Title "line-timeseries · altair · anyplot.ai" ✓; single-series plot correctly omits legend

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — 252 trading days (one year) with realistic volatility and trend demonstrates temporal patterns, downtrends, and recovery cycles
• DQ-02: Realistic Context (5/5) — Stock price simulation (starting $100, range $76-$120) is realistic and domain-appropriate; random walk with drift is neutral and non-controversial
• DQ-03: Appropriate Scale (4/4) — Price values sensible for stock data; Y-axis ticks well-distributed; date range (full trading year) appropriate for time series analysis

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — No unnecessary functions or classes; direct chart construction using declarative altair API
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ensures deterministic data generation; consistent output across runs
• CQ-03: Clean Imports (2/2) — Only altair, numpy, pandas imported; all used; no extraneous libraries
• CQ-04: Code Elegance (2/2) — No fake functionality, no problematic patterns; clean theme-token handling; appropriate complexity for time series
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png with scale_factor=3.0 and plot-{THEME}.html; current altair API

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Excellent use of altair declarative API. Proper mark_line() with encoding layers, .properties() for canvas, .configure_*() for theme adaptation, .interactive() for interactivity
• LM-02: Distinctive Features (3/5) — Good use of hover tooltips with proper date formatting ("%B %d, %Y"), temporal encoding (date:T), and .interactive() for exploration. Could leverage more advanced altair patterns like selection, conditional encoding, or layering

Score Caps Applied

• None — no cap conditions triggered

Strengths

• Perfect visual legibility in both light and dark themes with all text clearly readable
• Correct theme-adaptive chrome throughout (backgrounds, text colors, grid colors properly themed)
• Proper Okabe-Ito palette usage (#009E73) maintained identically across both renders
• Clean, well-structured code with deterministic data generation via seed
• Effective interactive features with meaningful date/price tooltips
• Appropriate date label rotation (-45°) and formatting ("%b %Y") for readability
• Realistic time series data demonstrating stock price volatility and trend

Weaknesses

• Design could leverage more sophisticated enhancements (custom reference lines, period highlighting, secondary insights)
• Limited exploration of altair's advanced features (selection objects, conditional encoding, cross-filtering)

Issues Found

• None — no blocking issues

AI Feedback for Next Attempt

Implementation is approved. If enhancing further, consider: (1) adding a reference line for opening price or moving average to create visual hierarchy, (2) using altair's selection for interactive period filtering, (3) annotating significant market events or turning points.

Verdict: APPROVED