feat(altair): implement spectrogram-mel

[github-actions]

Implementation: spectrogram-mel - altair

Implements the altair version of spectrogram-mel.

File: plots/spectrogram-mel/implementations/altair.py

Parent Issue: #4672

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a mel-spectrogram using the inferno colormap on a dark-to-bright (black/purple to yellow/white) scale. The X-axis shows "Time (s)" from 0.0 to 4.0, and the Y-axis shows "Frequency (Hz)" on a logarithmic scale with tick marks at 50, 100, 200, 500, 1000, 2000, 5000, and 10000 Hz. A vertical colorbar on the right is labeled "Power (dB)" ranging from -80 to 0. The title reads "spectrogram-mel · altair · pyplots.ai" with a subtitle describing the synthesized signal. Several distinct features are visible: a descending frequency sweep with harmonics appearing as bright diagonal lines from upper-left to lower-right, a persistent bright horizontal band around 400-500 Hz from the pulsed 440 Hz tone, a chirp burst between 1.5-2.5s visible in the 2000-5000 Hz range, and a subtle noise floor at the lowest frequencies. The lower mel bins appear as visibly larger rectangular blocks due to mel-scale compression.

Score: 86/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 28pt, subtitle 17pt, axis titles 22pt, tick labels 18pt, legend title 18pt, legend labels 16pt. All clearly readable.
• VQ-02: No Overlap (6/6) — No overlapping text elements. Tick values are well-spaced.
• VQ-03: Element Visibility (4/6) — Rectangles at lower mel bands are noticeably coarse/blocky due to subsampling (every 2nd frame and mel bin). The mel-scale compression makes low-frequency bins very large visually, reducing resolution fidelity.
• VQ-04: Color Accessibility (4/4) — Inferno is perceptually uniform and colorblind-safe. Excellent contrast between low and high energy regions.
• VQ-05: Layout & Canvas (3/4) — Good proportions overall, but some wasted space above/below the colorbar on the right side. Plot fills roughly 60% of canvas.
• VQ-06: Axis Labels & Title (2/2) — "Time (s)" and "Frequency (Hz)" with units. Colorbar labeled "Power (dB)".

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Inferno colormap is a strong choice for spectrograms, custom font sizing throughout, subtitle adds context. Above configured defaults but not quite publication-level polish (e.g., no custom tick formatting, no frequency band annotations).
• DE-02: Visual Refinement (4/6) — Grid explicitly disabled, view stroke removed, padding configured. Good whitespace management. Missing: more refined axis styling or background treatment.
• DE-03: Data Storytelling (3/6) — The subtitle tells the viewer what to look for. The synthesized signal creates visually interesting patterns (sweep, harmonics, chirp). However, there's no strong emphasis mechanism — all features compete equally for attention. A focal point or visual hierarchy would improve storytelling.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct mel-spectrogram visualization.
• SC-02: Required Features (4/4) — All spec requirements met: dB scale conversion, inferno sequential colormap, time in seconds on X, mel-scaled frequency with Hz labels on Y, colorbar in dB, n_fft=2048, hop_length=512, n_mels=128, synthesized audio data.
• SC-03: Data Mapping (3/3) — X=time, Y=frequency (log scale), color=power in dB. All correct.
• SC-04: Title & Legend (3/3) — Title format "spectrogram-mel · altair · pyplots.ai" is correct. Colorbar serves as legend with proper label.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Rich synthesized signal shows frequency sweep with harmonics, pulsed tone at 440 Hz with amplitude modulation, high-frequency chirp burst, and noise floor. Excellent variety of audio features.
• DQ-02: Realistic Context (5/5) — Audio signal analysis is a real-world application. The synthesized signal mimics characteristics found in actual audio (harmonics, sweeps, transients).
• DQ-03: Appropriate Scale (4/4) — Sample rate 22050 Hz (standard for audio), frequencies in audible range, 4-second duration, mel bands 0-11025 Hz. All realistic values.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → signal synthesis → STFT → mel filterbank → data preparation → chart → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set for noise component.
• CQ-03: Clean Imports (2/2) — Only altair, numpy, pandas — all used.
• CQ-04: Code Elegance (2/2) — Manual STFT and mel filterbank computation avoids external dependency (librosa). Appropriate complexity for the domain.
• CQ-05: Output & API (1/1) — Saves as plot.png and plot.html. Current API usage.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of mark_rect() with x/x2/y/y2 encoding for explicit rectangle bounds, proper quantitative encoding types, Scale with log type, Legend configuration, Title with subtitle, configure_axis/configure_view. However, building explicit rectangle bounds manually is somewhat low-level for Altair's declarative philosophy.
• LM-02: Distinctive Features (3/5) — Tooltips with formatted values, HTML export alongside PNG, and the declarative rect-based heatmap approach leverage Altair's grammar-of-graphics paradigm. However, doesn't use more advanced Altair features like selections or layer composition.

Score Caps Applied

• None

Strengths

• Perfect spec compliance — all required features implemented correctly
• Excellent synthesized audio data with rich, varied frequency content showing multiple audio phenomena
• Strong colormap choice (inferno) with proper dB scaling and colorbar
• All font sizes explicitly set and clearly readable
• Clean code that avoids external audio dependencies by implementing STFT and mel filterbank from scratch

Weaknesses

• Low-frequency mel bins appear as coarse blocks due to subsampling, reducing visual fidelity
• No visual hierarchy or emphasis mechanism — all audio features compete equally for attention
• Could benefit from more design refinement (e.g., frequency band annotations, refined tick formatting)

Issues Found

1. VQ-03 MEDIUM: Subsampling (every 2nd frame and mel bin) creates visible blockiness, especially at lower frequencies where mel bins are already wide
   • Fix: Reduce subsampling step or use finer resolution for lower mel bands
2. DE-01 MEDIUM: Good but not exceptional design — missing the polish for publication quality
   • Fix: Add subtle frequency band annotations (e.g., "Bass", "Midrange"), refine axis tick formatting, consider a more refined background treatment
3. DE-03 MEDIUM: No clear visual hierarchy or focal point in the spectrogram
   • Fix: Use the subtitle or annotations to highlight key features, or adjust the color scale to emphasize the most interesting frequency range

AI Feedback for Next Attempt

Improve visual fidelity by reducing the subsampling step (especially for mel bins) to eliminate blockiness at lower frequencies. Enhance design excellence by adding frequency band annotations or reference lines, refining axis tick formatting, and creating visual hierarchy that guides the viewer to the most interesting features of the spectrogram. Consider adjusting the dB range or adding contour-like emphasis to create a focal point.

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

The plot displays a mel-spectrogram with the inferno colormap on a light gray (#fafafa) background. The x-axis shows "Time (s)" from 0.0 to 4.0, and the y-axis shows "Frequency (Hz)" on a logarithmic scale from ~50 Hz to 10k Hz with formatted labels (50, 100, 200, 500, 1k, 2k, 5k, 10k). A vertical colorbar on the right is labeled "Power (dB)" ranging from -80 to 0. The title reads "spectrogram-mel · altair · pyplots.ai" with a descriptive subtitle. Three white text annotations with dark outlines and triangle markers identify key features: "Harmonic Sweep" at ~0.6s/1200Hz pointing to descending frequency lines with visible harmonics, "Chirp Burst" at ~2.2s/6500Hz highlighting a rising frequency burst between 1.5–2.5s, and "440 Hz Tone" at ~3.5s/350Hz marking a constant bright horizontal band with pulsating intensity. The low-frequency region shows noise texture, and the overall spectrogram has excellent color gradation from dark purple/black (quiet) through red/orange to bright yellow (loud).

Score: 91/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	16	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	91	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 28pt, axis titles 22pt, ticks 18pt, legend 18/16pt). Subtitle at 17pt is slightly below guideline but still legible.
• VQ-02: No Overlap (5/6) — No significant overlap. "440 Hz Tone" annotation near right edge is slightly cramped.
• VQ-03: Element Visibility (6/6) — All 128 mel bins rendered, excellent spectrogram resolution across full frequency range.
• VQ-04: Color Accessibility (4/4) — Inferno is perceptually uniform and colorblind-safe. Good contrast against light background.
• VQ-05: Layout & Canvas (4/4) — Good proportions (1400×800), balanced padding, well-positioned colorbar.
• VQ-06: Axis Labels & Title (2/2) — "Time (s)" and "Frequency (Hz)" both descriptive with units.

Design Excellence (16/20)

• DE-01: Aesthetic Sophistication (6/8) — Inferno colormap is excellent for spectrograms. Intentional text color hierarchy (feat(plotly): implement area-basic #111→[line-basic] seaborn implementation #222→[area-basic] plotnine implementation #333→feat(plotly): implement donut-labeled #555), custom axis styling, off-white background. Clearly above defaults.
• DE-02: Visual Refinement (5/6) — Grid disabled, view stroke removed, custom background, generous padding, subtle axis domain/tick colors (feat(plotnine): implement scatter-basic #444). Well-configured colorbar gradient.
• DE-03: Data Storytelling (5/6) — Three annotations with triangle markers guide viewer to key signal features. Subtitle provides context. Clear visual hierarchy.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct mel-spectrogram as heatmap with log-scaled frequency axis.
• SC-02: Required Features (4/4) — All features: dB conversion, sequential colormap (inferno), time in seconds, mel-scaled Hz labels, colorbar in dB, n_fft=2048, hop_length=512, n_mels=128, synthesized audio.
• SC-03: Data Mapping (3/3) — X=time, Y=frequency (log), color=power(dB). Correct.
• SC-04: Title & Legend (3/3) — Title matches format. Colorbar legend labeled "Power (dB)".

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Rich signal: descending sweep with harmonics, pulsed 440 Hz tone with AM envelope, chirp burst, noise floor. Multiple audio features demonstrated.
• DQ-02: Realistic Context (5/5) — Audio signal analysis is a real, neutral scientific domain with realistic components.
• DQ-03: Appropriate Scale (4/4) — Standard values: 22050 Hz sample rate, 4s duration, -80 to 0 dB, Nyquist-appropriate frequencies.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean imports → data → STFT → mel → plot → save. No functions/classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports used (altair, numpy, pandas).
• CQ-04: Code Elegance (2/2) — Well-structured. Manual STFT/mel avoids librosa dependency appropriately.
• CQ-05: Output & API (1/1) — Saves plot.png and plot.html. Current Altair API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good declarative grammar: mark_rect with x/x2/y/y2, alt.Scale, alt.Legend, alt.Title with subtitle, layer composition, configure methods. Bulk of computation is manual NumPy (necessary).
• LM-02: Distinctive Features (3/5) — Layer composition for annotations, interactive tooltips, HTML export, declarative x2/y2 rectangle encoding. Leverages Altair's grammar-of-graphics approach.

Score Caps Applied

• None — no caps triggered.

Strengths

• Excellent data storytelling with three well-placed annotations identifying key signal features (Harmonic Sweep, Chirp Burst, 440 Hz Tone)
• Rich synthesized audio signal showcasing multiple audio analysis features (sweeps, harmonics, AM modulation, chirp)
• Strong visual refinement: inferno colormap, disabled grid, removed view stroke, intentional text color hierarchy, subtle axis styling
• Full 128 mel bins used for high-resolution spectrogram without blockiness
• Clean log-frequency axis with formatted Hz labels (50, 100, ..., 1k, 2k, ..., 10k)

Weaknesses

• "440 Hz Tone" annotation near right edge appears slightly cramped
• Subtitle font size (17pt) is slightly below the recommended 20pt label guideline

Issues Found

1. VQ-02 MINOR: "440 Hz Tone" annotation at x=3.5 is near the right edge of the 4s plot, making it slightly cramped
   • Fix: Move annotation slightly left or adjust dx offset
2. VQ-01 MINOR: Subtitle at 17pt is slightly small relative to other text elements
   • Fix: Increase subtitle font size to 18-19pt

AI Feedback for Next Attempt

Strong implementation scoring 91/100. The mel-spectrogram is well-executed with excellent data storytelling through annotations, a rich synthesized signal, and polished visual design. Minor improvements possible: reposition the "440 Hz Tone" annotation slightly left to avoid crowding the right edge, and consider bumping the subtitle font size to 18-19pt for better consistency.

Verdict: APPROVED