feat(pygal): implement heatmap-chromagram

[github-actions]

Implementation: heatmap-chromagram - pygal

Implements the pygal version of heatmap-chromagram.

File: plots/heatmap-chromagram/implementations/pygal.py

Parent Issue: #4564

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a chromagram heatmap with 12 pitch classes (B at top, C at bottom) on the y-axis labeled "Pitch Class" and time from 0.0 to 7.2+ seconds on the x-axis labeled "Time (seconds)". An inferno-inspired sequential colormap ranges from near-black/dark purple (0.0 energy) through magenta and orange to bright yellow (1.0 energy). A vertical colorbar on the right is titled "Energy" with scale marks at 0.0, 0.5, and 1.0. The title reads "heatmap-chromagram · pygal · pyplots.ai". Four chord regions are clearly visible: C major (C, E, G bright from 0–1.6s), G major (G, B, D bright from 2–4s), A minor (A, C, E bright from 4–5.6s), and F major (F, A, C bright from 6–7.9s). Background noise is visible as low-intensity dark cells throughout.

Score: 85/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 64px, axis titles 48px, pitch labels 44px, time labels 36px). All text clearly readable.
• VQ-02: No Overlap (6/6) — No overlapping text. Time labels show every 10th frame to prevent crowding.
• VQ-03: Element Visibility (6/6) — Heatmap cells are well-sized and clearly visible with good density.
• VQ-04: Color Accessibility (4/4) — Inferno-inspired colormap is perceptually uniform and colorblind-safe.
• VQ-05: Layout & Canvas (3/4) — Good overall layout; some wasted space at left/right margins.
• VQ-06: Axis Labels & Title (2/2) — "Pitch Class" and "Time (seconds)" with units.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Custom inferno-inspired colormap with smooth interpolation, clean white background, styled bold axis titles. Above defaults but not publication-level polish.
• DE-02: Visual Refinement (4/6) — No grid lines (appropriate for heatmap), clean colorbar with border, good whitespace. Some margin refinement possible.
• DE-03: Data Storytelling (3/6) — Chord progression is visible through color patterns but there's no explicit visual hierarchy or emphasis guiding the viewer to the harmonic transitions.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct heatmap type showing chromagram data.
• SC-02: Required Features (4/4) — All 12 pitch classes, sequential colormap, colorbar, time axis in seconds, realistic harmonic patterns.
• SC-03: Data Mapping (3/3) — X=time, Y=pitch class, color=energy all correctly mapped.
• SC-04: Title & Legend (3/3) — Title format "heatmap-chromagram · pygal · pyplots.ai" correct. Colorbar serves as legend.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: varying energy levels, clear chord transitions, background noise, four distinct chords (C, G, Am, F).
• DQ-02: Realistic Context (5/5) — Realistic MIR scenario with C→G→Am→F chord progression and smooth transitions between chords.
• DQ-03: Appropriate Scale (4/4) — Normalized energy 0–1, 0.1s frame duration, 80 frames covering 8 seconds.

Code Quality (9/10)

• CQ-01: KISS Structure (2/3) — Custom class extending Graph is necessary for pygal heatmaps but adds structural complexity.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports used. sys.path manipulation required to avoid pygal name collision.
• CQ-04: Code Elegance (2/2) — Well-structured code. SVG tooltips via <title> elements are native pygal functionality.
• CQ-05: Output & API (1/1) — Saves as plot.png via render_to_png.

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Correctly extends Graph base class with _plot/_compute methods, uses svg.node API and Style system. However, most rendering is custom SVG work rather than pygal high-level API.
• LM-02: Distinctive Features (3/5) — Uses pygal's Graph extension model, SVG node system, native tooltips via <title> elements, and render_to_png/render_to_file. These are distinctive to pygal.

Score Caps Applied

• None

Strengths

• Excellent data quality with realistic C→G→Am→F chord progression and smooth transitions
• Full spec compliance — all required features present (12 pitch classes, sequential colormap, colorbar, time axis)
• Custom inferno-inspired colormap with smooth color interpolation between 10 anchor points
• Native SVG tooltips showing pitch, time, and energy values for each cell
• Clean colorbar implementation with proper scale markings and "Energy" title

Weaknesses

• No visual hierarchy or emphasis to guide the viewer through the chord progression (DE-03)
• Layout has some wasted margin space, especially on left and right sides (VQ-05)
• Mostly custom SVG rendering rather than leveraging pygal's higher-level patterns (LM-01)

Issues Found

1. DE-03 LOW: No visual hierarchy — the four chord sections blend together without visual emphasis
   • Fix: Add subtle vertical separator lines or section labels at chord boundaries to highlight the C→G→Am→F progression
2. DE-01 MODERATE: Styling is good but not publication-level
   • Fix: Consider adding a subtle background tint to the heatmap area, or thin horizontal lines between pitch classes for visual grouping
3. LM-01 MODERATE: Heavy reliance on manual SVG work
   • Fix: Explore using more of pygal's built-in configuration and rendering pipeline where possible

AI Feedback for Next Attempt

Improve data storytelling (DE-03): add visual markers or subtle separators at chord transition boundaries (frames 20, 40, 60) to emphasize the harmonic progression. Consider thin white or semi-transparent vertical lines at transitions. Improve layout by tightening margins to maximize canvas utilization. For design polish (DE-01), consider subtle horizontal separator lines between pitch class rows to aid readability.

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 chromagram heatmap with 12 pitch classes (B at top, C at bottom) on the y-axis labeled "Pitch Class" and time from 0.0 to 7.2+ seconds on the x-axis labeled "Time (seconds)". The title reads "heatmap-chromagram · pygal · pyplots.ai" at the top. An inferno-inspired sequential colormap is used, ranging from near-black/dark purple (0.0 energy) through magenta and orange to bright yellow (1.0 energy). A vertical colorbar on the right is titled "Energy" with tick marks at 0.0, 0.5, and 1.0. Four chord region labels appear in italic bold gray text above the heatmap: "C major", "G major", "A minor", and "F major", with dashed vertical separator lines at chord boundaries. Subtle alternating background bands behind the heatmap distinguish regions. The chord progression is clearly visible: C/E/G rows are bright during 0–1.6s (C major), G/B/D bright during 2–4s (G major), A/C/E bright during 4–5.6s (A minor), and F/A/C bright during 6–7.9s (F major). Low-energy background noise appears as dark purple throughout non-active pitch rows.

Score: 86/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	9	10
Library Mastery	6	10
Total	86	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 64px, axis titles 48px, pitch labels ~44px, time labels 36px, chord labels 38px, colorbar labels 36px). All clearly readable. Slight deduction: pitch row labels could be a touch larger for perfect readability at full resolution.
• VQ-02: No Overlap (6/6) — No overlapping text anywhere. Time labels use every-10th-frame stepping to prevent crowding.
• VQ-03: Element Visibility (6/6) — Heatmap cells are well-sized, color differences clearly distinguishable across the full energy range.
• VQ-04: Color Accessibility (4/4) — Inferno-inspired colormap is perceptually uniform and colorblind-safe (sequential purple→orange→yellow).
• VQ-05: Layout & Canvas (3/4) — Good overall layout with heatmap filling most of the canvas. Left margin is slightly generous due to rotated y-axis title positioning (240px offset). Minor wasted space.
• VQ-06: Axis Labels & Title (2/2) — "Pitch Class" and "Time (seconds)" are descriptive with units.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Custom inferno colormap with smooth 10-point interpolation, clean white background, bold styled axis titles, italic chord region labels. Clearly above library defaults but not publication-level polish (e.g., no refined typography hierarchy, no subtle background texture).
• DE-02: Visual Refinement (4/6) — No grid lines (appropriate for heatmap), clean heatmap border, dashed vertical separators at chord boundaries, subtle alternating background bands, colorbar with border. Good refinement but could benefit from thin horizontal separators between pitch rows for visual grouping.
• DE-03: Data Storytelling (4/6) — Chord region labels ("C major", "G major", etc.) and dashed separators effectively guide the viewer through the harmonic progression. Alternating background bands reinforce section boundaries. The viewer can immediately identify the chord structure. Could be elevated further with stronger emphasis on transitions or a summary annotation.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct heatmap type showing chromagram data.
• SC-02: Required Features (4/4) — All 12 pitch classes labeled C to B, sequential colormap (inferno-inspired), colorbar with energy scale, time axis in seconds, realistic harmonic patterns with chord alternation.
• SC-03: Data Mapping (3/3) — X=time frames, Y=pitch classes, color=energy intensity — all correctly mapped.
• SC-04: Title & Legend (3/3) — Title format "heatmap-chromagram · pygal · pyplots.ai" correct. Colorbar serves as energy legend.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: varying energy levels per pitch class, clear chord transitions with smoothing, background noise, four distinct chords (C major, G major, A minor, F major).
• DQ-02: Realistic Context (5/5) — Realistic MIR scenario with I–V–vi–IV chord progression (one of the most common in popular music), smooth transitions between chords, and plausible energy distribution.
• DQ-03: Appropriate Scale (4/4) — Normalized energy 0–1, 0.1s frame duration, 80 frames covering 8 seconds — all appropriate for chroma feature extraction.

Code Quality (9/10)

• CQ-01: KISS Structure (2/3) — Custom class extending pygal's Graph is necessary since pygal has no native heatmap, but adds structural complexity beyond the ideal flat script pattern.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports used. sys.path manipulation is necessary to avoid pygal name collision.
• CQ-04: Code Elegance (2/2) — Well-structured custom Graph subclass. SVG tooltips via native <title> elements are legitimate pygal functionality, not fake interactivity.
• CQ-05: Output & API (1/1) — Saves as plot.png via render_to_png, also generates plot.svg and plot.html.

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Correctly extends pygal's Graph base class with _plot() and _compute() methods, uses the svg.node() API for SVG construction, and leverages the Style configuration system. However, the majority of rendering is hand-built SVG rather than using pygal's higher-level chart abstractions.
• LM-02: Distinctive Features (3/5) — Uses pygal's Graph extension model (subclassing Graph with custom _plot), SVG node construction API (svg.node()), native SVG tooltips via <title> elements, Style system, and render_to_png/render_to_file methods. These are distinctive to pygal's architecture.

Score Caps Applied

• None

Strengths

• Excellent data quality with realistic I–V–vi–IV chord progression and smooth inter-chord transitions
• Full spec compliance with all required features present and correctly implemented
• Effective data storytelling with chord region labels, dashed separators, and alternating background bands
• Custom inferno-inspired colormap with smooth 10-point color interpolation
• Native SVG tooltips showing pitch, time, and energy values for each cell (via <title> elements)
• Clean colorbar implementation with proper scale markings and title

Weaknesses

• Design polish not yet at publication level — lacks fine typographic hierarchy and subtle visual grouping (e.g., thin horizontal separators between pitch rows)
• Left margin slightly oversized due to rotated y-axis title positioning
• Heavy reliance on custom SVG rendering rather than pygal's higher-level chart patterns (inherent limitation for heatmaps in pygal)

Issues Found

1. DE-01 MODERATE: Aesthetic sophistication good but not publication-level
   • Fix: Add thin semi-transparent horizontal lines between pitch class rows to improve visual grouping and readability
2. DE-03 MODERATE: Storytelling improved with chord labels but could be stronger
   • Fix: Consider adding a brief subtitle or annotation highlighting the harmonic progression pattern (I–V–vi–IV)
3. VQ-05 MINOR: Left margin slightly oversized
   • Fix: Reduce the y-axis title offset from 240px to ~200px and margin_left from 280 to ~250 to reclaim canvas space

AI Feedback for Next Attempt

To reach 90+: (1) Add thin semi-transparent horizontal separator lines between pitch class rows for better visual grouping and readability. (2) Tighten left margin by reducing y-axis title offset and margin_left values. (3) Consider adding a subtle subtitle or small annotation indicating the I–V–vi–IV progression pattern to strengthen data storytelling. (4) These refinements would push DE-01 toward 6-7 and DE-02 toward 5, bringing the total above 90.

Verdict: REJECTED