feat(seaborn): implement spectrogram-basic

[github-actions]

Implementation: spectrogram-basic - python/seaborn

Implements the python/seaborn version of spectrogram-basic.

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

Parent Issue: #2927

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The spectrogram displays a chirp signal (100–800 Hz) over 2 seconds on a warm off-white background (#FAF8F1). The heatmap uses the viridis colormap, transitioning from dark purple (low power) through green, yellow, to bright white (high power). Time axis (x) ranges 0–2 seconds with 5 tick marks labeled 0.0, 0.5, 1.0, 1.5, 2.0. Frequency axis (y) inverted (flipped for standard convention) shows 0–2000 Hz with tick labels at key frequencies. Axis labels "Time (s)" and "Frequency (Hz)" are rendered in dark text (#1A1A17). Tick labels use secondary text color (#4A4A44). Title "spectrogram-basic · seaborn · anyplot.ai" is clearly visible. Colorbar with label "Power (dB)" is on the right side. All text is readable with good contrast against the light background. No overlap between elements.

Dark render (plot-dark.png): Same spectrogram layout on a warm near-black background (#1A1A17). The viridis colormap data colors (purple through green/yellow/white) are identical to the light render — only the background and text chrome have flipped to dark theme. Axis labels and tick labels are now rendered in light text (#F0EFE8 for primary, #B8B7B0 for secondary). Tick label colors are correctly set to INK_SOFT per theme tokens. Title and all text elements are clearly readable against the dark background with no dark-on-dark failures. The colorbar text is also light-colored and readable. Chirp pattern diagonal trajectory is equally clear in both renders.

Score: 82/100

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

Visual Quality (25/30)

• VQ-01: Text Legibility (7/8) - Font sizes explicitly set (16pt ticks, 20pt labels, 24pt title). Readable in both light and dark. Minor: could push to 8 with 18pt colorbar label.
• VQ-02: No Overlap (6/6) - Tick positions use linspace; no collisions. Layout clean.
• VQ-03: Element Visibility (6/6) - Heatmap grid adapts well to 256×110 time-frequency matrix. Markers/cells clearly visible.
• VQ-04: Color Accessibility (2/2) - Viridis is perceptually uniform and CVD-safe. Adequate contrast across dynamic range.
• VQ-05: Layout & Canvas (2/4) - 16:9 aspect ratio fills ~70% of canvas with good margins. Adequate but could be tighter.
• VQ-06: Axis Labels & Title (2/2) - "Time (s)" and "Frequency (Hz)" include units. Title format correct.
• VQ-07: Palette Compliance (2/2) - Viridis colormap correct for continuous heatmap data. Background colors theme-correct: #FAF8F1 (light) and #1A1A17 (dark). Text colors adapted properly in both renders.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (4/8) - Clean, functional defaults from seaborn. Heatmap styling is professional but generic. No custom color choices or design flourishes.
• DE-02: Visual Refinement (4/6) - Rasterized heatmap (efficient), minimal spines for heatmap type, subtle cbar shrink factor. Good attention to detail.
• DE-03: Data Storytelling (4/6) - Chirp pattern (increasing frequency) is clear visually. Diagonal progression from low-left to high-right tells the story of increasing frequency over time. Good visual hierarchy through intensity gradient.

Spec Compliance (13/15)

• SC-01: Plot Type (5/5) - Correct spectrogram heatmap with time-frequency representation.
• SC-02: Required Features (4/4) - Chirp signal, frequency label, time label, dB scale colorbar, proper window/overlap.
• SC-03: Data Mapping (3/3) - Time on x-axis, frequency on y-axis (inverted per convention), spectrogram power mapped to color.
• SC-04: Title & Legend (1/3) - Title format correct but frequency tick labels display backwards (labels in descending order due to axis flip), which is confusing to readers.

Data Quality (13/15)

• DQ-01: Feature Coverage (6/6) - Chirp shows full frequency range (100–800 Hz), full time span, clean noise level. Demonstrates spectrogram capability.
• DQ-02: Realistic Context (5/5) - Chirp signal is a standard, realistic, neutral test case for spectral analysis. Plausible audio/vibration example.
• DQ-03: Appropriate Scale (2/4) - Sampling rate 4000 Hz appropriate for 800 Hz max (Nyquist criterion satisfied). Window size 256 samples ~64ms, overlap 200 samples reasonable. dB scale logical. However, frequency axis extends to nyquist limit but interpretation could be clearer.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Imports, data generation, spectrogram computation, plot, save. Linear, no functions.
• CQ-02: Reproducibility (2/2) - Seed set (np.random.seed(42)). Deterministic output.
• CQ-03: Clean Imports (2/2) - scipy.signal, numpy, matplotlib, seaborn, os only. All used.
• CQ-04: Code Elegance (2/2) - Clean, Pythonic. No over-engineering or fake UI. Proper rasterization for performance.
• CQ-05: Output & API (1/1) - Saves as plot-{THEME}.png correctly. Uses current matplotlib/seaborn API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) - sns.heatmap() with proper kwargs (cmap, cbar, rasterized). Idiomatic seaborn pattern.
• LM-02: Distinctive Features (4/5) - Uses seaborn's high-level heatmap API well, but does NOT leverage seaborn-specific features like custom palettes, clustermap annotations, or styling variants. Implementation is solid but could showcase more seaborn expertise.

Score Caps Applied

• None / All caps criteria passed

Strengths

• Clean, readable theme-adaptive implementation with correct dark mode support
• All text explicitly sized and readable in both renders
• Proper spectrogram computation with scipy (windowing, overlap, dB scale)
• Correct axis inversions for standard time-frequency convention
• Efficient use of rasterization for large matrices
• Viridis colormap correctly chosen for continuous data
• No defects in auto-reject checks (AR-01 through AR-08)

Weaknesses

• Generic design: uses library defaults without custom refinement or visual hierarchy
• Frequency tick labels reversed and confusing (descending order on y-axis)
• No data story beyond basic pattern display — could emphasize transitions or key features
• Seaborn-specific features underutilized

Issues Found

1. VQ-05 MODERATE: Layout fills ~70% of canvas. For heatmaps, square aspect ratio (3600×3600) might be more appropriate than 16:9.
2. SC-04 MINOR: Frequency tick labels read backwards (descending 800→0) due to axis flip. Clear but unconventional ordering.
3. DE-01 LOW: Generic defaults without custom design thought. Consider refining colorbar appearance or grid styling.
4. LM-02 MODERATE: Seaborn-specific features barely used. Could showcase mastery with custom cbar styling or annotations.

AI Feedback for Next Attempt

The implementation is technically sound and theme-correct (82/100), meeting the Review 3 approval threshold (≥70). To reach 90+: (1) improve aesthetic design by refining colorbar and axis styling; (2) fix frequency label ordering or add clarity annotations; (3) showcase seaborn mastery through distinctive features. Current state demonstrates solid competence with room for design excellence.

Verdict: APPROVED

[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 (plot-light.png): The spectrogram displays clearly on a warm off-white background (#FAF8F1). The title "spectrogram-basic · seaborn · anyplot.ai" is rendered in dark text and highly legible. The X-axis label "Time (s)" and Y-axis label "Frequency (Hz)" are clearly visible in large, dark text. Tick labels on both axes are readable in secondary dark color. The heatmap uses the viridis colormap correctly, showing a clear chirp signal as a diagonal yellow-green stripe rising from lower-left to upper-right, representing increasing frequency over time. The power scale ranges from dark purple (low power, ~-90 dB) to bright yellow (high power, ~-20 dB). The colorbar on the right side is clearly labeled "Power (dB)" with legible tick marks. All text is readable against the light background with proper contrast. Legibility verdict: PASS.

Dark render (plot-dark.png): The spectrogram renders identically on a warm near-black background (#1A1A17). The title and axis labels are now rendered in light text and remain highly legible against the dark background. The heatmap data colors are identical to the light render—the viridis colormap is theme-independent, showing the same diagonal chirp pattern. Only the chrome elements (background, title, labels, tick colors) have adapted to the dark theme. All text is clearly readable with appropriate light-on-dark contrast. No "dark-on-dark" legibility failures. The colorbar remains clear and properly styled. Legibility verdict: PASS.

Score: 86/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	7	10
Total	86	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) - All text properly sized and readable in both themes
• VQ-02: No Overlap (6/6) - No collisions or overlapping elements
• VQ-03: Element Visibility (6/6) - Heatmap and chirp pattern clearly visible and distinguishable
• VQ-04: Color Accessibility (2/2) - Viridis is perceptually uniform and colorblind-safe
• VQ-05: Layout & Canvas (4/4) - Good proportions, nothing cut off, generous whitespace
• VQ-06: Axis Labels & Title (2/2) - Descriptive with units ("Time (s)", "Frequency (Hz)", "Power (dB)")
• VQ-07: Palette Compliance (2/2) - Viridis used correctly for continuous data; backgrounds are #FAF8F1 (light) and #1A1A17 (dark); both renders theme-correct

Design Excellence (9/20)

• DE-01: Aesthetic Sophistication (4/8) - Functional heatmap with correct data representation, but uses standard seaborn styling without custom visual refinement
• DE-02: Visual Refinement (2/6) - Minimal customization; uses default heatmap appearance without spine removal or grid styling
• DE-03: Data Storytelling (3/6) - The chirp signal (diagonal yellow-green stripe showing frequency increase over time) clearly tells the story of a non-stationary signal

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct spectrogram/time-frequency heatmap
• SC-02: Required Features (4/4) - Time-frequency heatmap, colorbar with dB scale, axis labels all present
• SC-03: Data Mapping (3/3) - Time axis 0-2.0s, frequency axis 0-2000 Hz, data correctly mapped
• SC-04: Title & Legend (3/3) - Title format correct; colorbar serves as legend with proper label

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Shows all aspects of spectrogram: time, frequency, power/amplitude via color
• DQ-02: Realistic Context (5/5) - Chirp signal (100-800 Hz over 2 seconds at 4000 Hz sample rate) is realistic for signal processing
• DQ-03: Appropriate Scale (4/4) - dB scale appropriate for spectral power representation

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear, no unnecessary functions/classes
• CQ-02: Reproducibility (2/2) - np.random.seed(42) ensures deterministic output
• CQ-03: Clean Imports (2/2) - All imports (os, matplotlib, numpy, seaborn, scipy) are used
• CQ-04: Code Elegance (2/2) - No fake UI, appropriate complexity, clean implementation
• CQ-05: Output & API (1/1) - Saves as plot-{THEME}.png; uses current API

Library Mastery (7/10)

• LM-01: Idiomatic Usage (5/5) - Uses seaborn.heatmap() idiomatically; scipy.signal.spectrogram() correctly applied; theme management via os.getenv() is standard
• LM-02: Distinctive Features (2/5) - Custom colorbar styling (cbar_kws, manual tick management) shows some seaborn customization but limited distinctive features

Score Caps Applied

• None

Strengths

• Perfect theme-adaptive implementation—both light and dark renders display correctly with proper contrast and color consistency
• Technically correct spectrogram computation using scipy with proper dB scaling for amplitude representation
• Clear visual communication—the chirp signal is immediately obvious as a diagonal stripe, effectively showing frequency increase over time
• All spec requirements met: proper axes, colorbar with units, correct data mapping
• Clean, reproducible code with proper seeding and theme management

Weaknesses

• Limited design excellence—relies on standard seaborn heatmap defaults without custom visual refinement
• Colorbar styling could be more sophisticated (custom appearance, better integration)
• No enhanced visual hierarchy to emphasize the key signal pattern beyond the automatic viridis gradient

Issues Found

1. DE-01 LOW: Generic styling with standard seaborn heatmap defaults
   • Fix: Add custom spine styling, refine colorbar frame/appearance, consider subtle enhancements to visual polish
2. DE-02 LOW: Minimal visual refinement
   • Fix: Remove unnecessary spines, customize grid appearance if adding one, refine typography hierarchy

AI Feedback for Next Attempt

Improve design excellence: Consider removing top/right spines, adding subtle axis styling, and customizing the colorbar appearance for a more polished look. The core functionality is excellent; focus on visual sophistication and refined aesthetics to elevate the implementation.

Verdict: APPROVED