feat(altair): implement spectrogram-basic

[github-actions]

Implementation: spectrogram-basic - python/altair

Implements the python/altair version of spectrogram-basic.

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

Parent Issue: #2927

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The spectrogram displays a time-frequency heatmap on a warm off-white background (#FAF8F1) with the chirp signal clearly visible as a yellow-green diagonal band sweeping from ~100 Hz (lower left) to ~800 Hz (upper right) over a 2-second duration. The viridis colormap effectively encodes power in dB, with darker purples representing low power and bright yellows showing the signal peak. Title "spectrogram-basic · altair · anyplot.ai" is rendered in dark text (#1A1A17) at the top; x-axis label "Time (s)" and y-axis label "Frequency (Hz)" are clearly visible in dark secondary text (#4A4A44). Tick labels on both axes are readable. The colorbar legend on the right shows "Power (dB)" with proper font sizing and theme-correct coloring. Grid is subtle (opacity 0.10) and does not compete with data. All text is legible against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same spectrogram rendered on a warm near-black background (#1A1A17). The viridis colormap colors are identical to the light render—the chirp signal band maintains its purple-to-yellow gradient without modification, confirming correct data color consistency. Title, axis labels, and tick labels are now rendered in light text (theme-adaptive chrome), which contrasts sharply against the dark background and remains fully readable. The legend "Power (dB)" is properly styled with the elevated background color (#242420) and light text. Grid remains subtle. No dark-on-dark failures detected. The chrome (background, text, grid, legend) correctly adapts to the dark theme while data colors stay constant. Legibility verdict: PASS.

Score: 92/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set; title 28px, labels 22px, ticks 18px; perfectly readable in both themes
• VQ-02: No Overlap (6/6) — All text elements properly spaced; no overlaps
• VQ-03: Element Visibility (6/6) — Spectrogram rectangles optimally sized for time-frequency resolution
• VQ-04: Color Accessibility (2/2) — Viridis is perceptually uniform and colorblind-safe
• VQ-05: Layout & Canvas (4/4) — Plot fills ~65% of canvas with balanced margins; excellent layout proportions
• VQ-06: Axis Labels & Title (2/2) — Descriptive labels with units (Time in seconds, Frequency in Hz)
• VQ-07: Palette Compliance (2/2) — Viridis for continuous power data ✓; backgrounds correct (#FAF8F1 light, #1A1A17 dark) ✓; chrome theme-correct in both renders ✓

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (4/8) — Uses appropriate perceptually-uniform viridis colormap; follows Altair best practices; configuration-level polish but no exceptional aesthetic innovations
• DE-02: Visual Refinement (4/6) — Grid opacity explicitly set to 0.10 (subtle); legend styled with theme-adaptive colors; thoughtful customization without over-engineering
• DE-03: Data Storytelling (4/6) — Chirp signal frequency sweep is visually clear through color progression; viewer immediately understands time-frequency progression; no annotations needed

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct spectrogram chart type as time-frequency heatmap
• SC-02: Required Features (4/4) — Colorbar with power in dB ✓; time axis ✓; frequency axis ✓; amplitude representation ✓
• SC-03: Data Mapping (3/3) — X=Time (s), Y=Frequency (Hz), Color=Power (dB); correct assignments
• SC-04: Title & Legend (3/3) — Title format "spectrogram-basic · altair · anyplot.ai" ✓; legend title "Power (dB)" ✓

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Full frequency range 100→800 Hz shown; complete 2-second time window; realistic white noise component
• DQ-02: Realistic Context (5/5) — Chirp signal is a standard, real-world test signal for spectrogram analysis; authentic use case
• DQ-03: Appropriate Scale (4/4) — Sample rate 4000 Hz (realistic); duration 2 seconds (good visualization window); frequency range respects Nyquist limit

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear pipeline: imports → data generation → STFT → DataFrame → plot → save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ensures deterministic output
• CQ-03: Clean Imports (2/2) — All imports used: os, altair, numpy, pandas
• CQ-04: Code Elegance (2/2) — Clean STFT implementation; appropriate complexity; no fake functionality
• CQ-05: Output & API (1/1) — Correct output format plot-{THEME}.png/html; scale_factor=3.0 for proper resolution

Library Mastery (10/10)

• LM-01: Idiomatic Usage (5/5) — Expert fluent API: alt.Chart().mark_rect().encode().properties().configure_*() pattern; x2/y2 encoding for pixel-perfect heatmap rectangles
• LM-02: Distinctive Features (5/5) — Uses Altair's x2/y2 encoding (unique for proper heatmap cell sizing); Legend with custom theme-adaptive fillColor/strokeColor; .save() with scale_factor

Score Caps Applied

• None — No auto-reject conditions triggered

Strengths

• Perfect theme adaptation: both light and dark renders correctly implement theme tokens without breaking readability
• Expert Altair implementation using x2/y2 for proper heatmap rectangles and fluent API patterns
• Excellent data quality: realistic chirp signal with noise demonstrates real-world use case
• Clean, deterministic code with explicit font sizing ensuring legibility at high resolution
• Correct palette compliance: viridis colormap for continuous power data, theme-correct chrome in both renders

Weaknesses

• Design excellence is solid but not exceptional: while the plot follows best practices, there are no special aesthetic touches or visual innovations beyond well-configured defaults
• Could benefit from slightly more visual emphasis through color intensity variation or spatial layout adjustments (though this would be refinement, not a fix)

Issues Found

None. Implementation passes all quality criteria.

AI Feedback for Next Attempt

N/A — Implementation approved on first review.

Verdict: APPROVED