feat(highcharts): implement heatmap-cohort-retention

[github-actions]

Implementation: heatmap-cohort-retention - highcharts

Implements the highcharts version of heatmap-cohort-retention.

File: plots/heatmap-cohort-retention/implementations/highcharts.py

Parent Issue: #4570

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a triangular heatmap of cohort retention data with a blue sequential colormap. The title reads "heatmap-cohort-retention · highcharts · pyplots.ai" at the top, followed by a subtitle "Monthly cohort retention rates — percentage of users returning each month after signup" and the x-axis title "Months Since Signup" — all three lines stacked closely together at the top. The x-axis shows "Month 0" through "Month 9" along the top edge. The y-axis on the left shows cohort labels from "Oct 2024 (1,290)" at the top to "Jan 2024 (1,240)" at the bottom, with "Signup Cohort (Users)" as the axis title. Each cell contains the retention percentage as text — white text on dark blue cells, dark text on light blue cells. The triangular shape is correct: Oct 2024 has only 1 column (100%), while Jan 2024 spans all 10 months (100% → 22.5%). A vertical color bar on the right shows "Retention %" from 0% to 100%. The background is a subtle off-white (#fafafa). Cell borders match the background, creating clean visual separation.

Score: 85/100

Category	Score	Max
Visual Quality	26	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	14	15
Code Quality	10	10
Library Mastery	7	10
Total	85	100

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8) - All font sizes explicitly set (title 48px, subtitle 28px, axis titles 30px, labels 26-28px, data labels 24px). All readable at full size.
• VQ-02: No Overlap (4/6) - The subtitle, x-axis title "Months Since Signup", and x-axis category labels are stacked very closely at the top, creating visual crowding. Not severe overlap but lacks clean separation.
• VQ-03: Element Visibility (6/6) - Heatmap cells are well-sized with clear border separation. Data labels clearly visible with adaptive colors.
• VQ-04: Color Accessibility (4/4) - Blue sequential colormap is colorblind-safe. Good contrast. Adaptive text colors ensure readability on both light and dark cells.
• VQ-05: Layout & Canvas (3/4) - Chart fills canvas reasonably well. Right margin for colorbar is generous. Triangular shape naturally leaves empty space in bottom-right.
• VQ-06: Axis Labels & Title (2/2) - "Months Since Signup" and "Signup Cohort (Users)" are descriptive and contextual.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (6/8) - Custom 7-stop blue gradient, custom font family (Segoe UI/Roboto), #fafafa background, adaptive data label colors via JS formatter. Clearly above defaults.
• DE-02: Visual Refinement (4/6) - Grid lines removed, axis lines removed, cell borders styled to match background for clean separation. Good whitespace overall.
• DE-03: Data Storytelling (3/6) - The triangular shape and color gradient naturally convey retention decay. Cohort sizes add context. However, no strong focal point or emphasis — e.g., no highlight on best/worst performing cohort or notable drop-off patterns.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct heatmap with triangular shape
• SC-02: Required Features (4/4) - All spec features present: period 0 = 100%, triangular shape, sequential colormap, retention % in cells, cohort sizes in y-labels, "Month N" x-labels, color bar legend
• SC-03: Data Mapping (3/3) - X = periods, Y = cohorts, color = retention rate. All correct.
• SC-04: Title & Legend (3/3) - Title follows {spec-id} · {library} · pyplots.ai format. Color bar labeled "Retention %".

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Shows retention decay, triangular shape, cohort size variation. Cohorts have slight variation but are somewhat similar in decay pattern — more differentiation would better demonstrate the format.
• DQ-02: Realistic Context (5/5) - SaaS monthly cohort retention is a classic, realistic business scenario.
• DQ-03: Appropriate Scale (4/4) - Retention from 100% to ~17-22% over 9 months is realistic for SaaS products. Cohort sizes (1,190–1,680) are plausible.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear flow: imports → data generation → chart config → HTML → screenshot
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set
• CQ-03: Clean Imports (2/2) - All imports are used
• CQ-04: Code Elegance (2/2) - Clean, well-organized. Chart config as a dict is idiomatic. Fallback URLs for JS downloads.
• CQ-05: Output & API (1/1) - Saves as plot.png. Also saves plot.html for interactive version.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Constructs Highcharts heatmap via JSON config + Selenium screenshot. Valid approach but bypasses the highcharts-core Python library.
• LM-02: Distinctive Features (3/5) - Uses Highcharts-specific features: heatmap module, colorAxis with gradient stops, custom JS formatter for adaptive data label colors, tooltip with pointFormat, opposite x-axis placement.

Score Caps Applied

• None

Strengths

• Perfect spec compliance — all required features present including triangular shape, retention percentages in cells, cohort sizes, and color bar
• Strong data quality with realistic SaaS retention scenario and plausible values
• Custom 7-stop blue colorAxis with adaptive white/dark text labels via JS formatter — shows good Highcharts knowledge
• Clean code structure with fallback CDN URLs for reliability

Weaknesses

• Subtitle, x-axis title, and x-axis category labels are crowded at the top — need more spacing
• No data storytelling emphasis — all cohorts look similar with no focal point highlighting insights
• Could leverage more distinctive Highcharts features

Issues Found

1. VQ-02 MEDIUM: Top area crowded — subtitle, "Months Since Signup" axis title, and month labels are stacked too closely
   • Fix: Increase marginTop, adjust subtitle y position, or increase spacing between subtitle and x-axis title
2. DE-03 LOW: No visual hierarchy or storytelling — all cohorts appear equally weighted
   • Fix: Consider highlighting best/worst cohort, or adding emphasis on notable retention drop-offs through color contrast or annotation
3. VQ-05 MINOR: Right margin is generous for the colorbar, slightly reducing chart area
   • Fix: Reduce marginRight slightly for better canvas utilization

AI Feedback for Next Attempt

Fix the crowding at the top of the chart by increasing spacing between subtitle and x-axis elements. Add visual storytelling: consider emphasizing the best or worst-performing cohort, or highlighting the typical retention cliff after Month 1. Reduce the right margin slightly for better canvas utilization.

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 triangular cohort retention heatmap with the title "heatmap-cohort-retention · highcharts · pyplots.ai" at the top. Below the title is a subtitle: "Monthly cohort retention rates — percentage of users returning each month after signup" with colored annotations highlighting the best cohort (Jun 2024 — new onboarding, in blue with a star) and worst cohort (Apr 2024 — buggy release, in red). The x-axis at the top shows "Month 0" through "Month 9" with the label "Months Since Signup." The y-axis on the left shows cohort labels with user counts (e.g., "Jan 2024 (1,240)"). The heatmap uses a blue sequential colormap from very light blue (low retention) to very dark navy (high retention/100%). Each cell displays its retention percentage with adaptive text color (white on dark cells, dark on light cells). The triangular shape is correctly formed — Jan 2024 at the bottom has all 10 periods, while Oct 2024 at the top has only 1. A vertical color bar on the right shows "Retention %" from 0% to 100%. The Jun 2024 row has a subtle blue plotBand and its y-axis label is bold with a star; the Apr 2024 row has a subtle red plotBand and red-colored label. The background is a soft off-white (#fafafa).

Score: 90/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 48px, subtitle 26px, axis titles 28px, axis labels 24-26px, data labels 24px, color bar labels 22px). Subtitle annotations at 22px are readable but slightly small relative to canvas.
• VQ-02: No Overlap (6/6) — No overlapping text anywhere. Data labels fit neatly within cells. Y-axis labels well-spaced.
• VQ-03: Element Visibility (6/6) — Heatmap cells are well-sized with clear 3px borders creating crisp separation. Triangular shape is well-defined with transparent null cells.
• VQ-04: Color Accessibility (4/4) — Blue sequential colormap is colorblind-safe. Adaptive text colors (white on dark, dark on light) ensure excellent contrast throughout.
• VQ-05: Layout & Canvas (3/4) — Good use of canvas with appropriate margins. The triangular shape inherently leaves empty space in the upper-right, and some space around the color bar could be tighter.
• VQ-06: Axis Labels & Title (2/2) — "Months Since Signup" and "Signup Cohort (Users)" are descriptive with context.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: custom 8-stop blue sequential palette, adaptive data label colors, highlighted best/worst cohorts with star/color coding, off-white background, custom font family stack. Clearly above defaults.
• DE-02: Visual Refinement (4/6) — Grid lines and axis lines removed (lineWidth: 0, gridLineWidth: 0), clean cell borders matching background color, subtle plotBands for emphasis rows. Good refinement.
• DE-03: Data Storytelling (5/6) — Excellent storytelling: best cohort (Jun 2024) marked with star and blue highlighting, worst cohort (Apr 2024) in red, subtitle explains WHY each stands out (new onboarding vs buggy release), plotBands draw visual attention to key rows. Viewer immediately understands the narrative.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct triangular heatmap with proper cohort structure.
• SC-02: Required Features (4/4) — All spec features present: triangular shape, retention percentages in cells, cohort sizes next to labels, sequential blue colormap, color bar legend, "Month N" x-axis labels.
• SC-03: Data Mapping (3/3) — X=periods (Month 0-9), Y=cohorts (Jan-Oct 2024). Period 0 = 100% for all cohorts. Triangular shape correct.
• SC-04: Title & Legend (3/3) — Title format "heatmap-cohort-retention · highcharts · pyplots.ai" correct. Color bar labeled "Retention %".

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows differentiated retention curves with clear best/worst cohorts, realistic decay patterns, varied cohort sizes reflecting marketing pushes, and proper triangular structure.
• DQ-02: Realistic Context (5/5) — SaaS monthly cohort retention is a real, neutral business analytics scenario. Cohort narratives (new onboarding, buggy release) add plausible context.
• DQ-03: Appropriate Scale (4/4) — Retention values realistic: 100% at Month 0, decaying to ~20-30% by Month 9. Cohort sizes 1,190-1,680 are plausible for a SaaS product.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data generation → chart config → HTML generation → screenshot. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set for deterministic data generation.
• CQ-03: Clean Imports (2/2) — All imports used: json, tempfile, time, urllib.request, Path, numpy, selenium.
• CQ-04: Code Elegance (2/2) — Clean code with appropriate complexity. JavaScript formatters for adaptive colors are necessary, not over-engineered. No fake UI elements.
• CQ-05: Output & API (1/1) — Saves as plot.png via Selenium screenshot. Current API usage.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (3/5) — Constructs Highcharts config as raw JSON dict rather than using the highcharts-core Python library (Chart, HighchartsOptions classes). The approach works correctly but bypasses the Python API wrapper.
• LM-02: Distinctive Features (4/5) — Good use of Highcharts-specific features: colorAxis with custom stops, plotBands for row highlighting, useHTML with custom formatters for adaptive label rendering, heatmap module, tooltip configuration.

Score Caps Applied

• None — no caps triggered.

Strengths

• Excellent data storytelling with highlighted best/worst cohorts, star annotations, and color-coded labels explaining the narrative
• Adaptive data label colors (white on dark, dark on light cells) ensure readability across the full retention range
• Clean triangular shape with transparent null cells and matching border colors
• Realistic SaaS retention data with differentiated cohort curves and plausible context

Weaknesses

• Does not use the highcharts-core Python library; constructs raw JSON configuration instead

Issues Found

1. LM-01 MODERATE: Raw JSON config approach instead of highcharts-core Python API
   • Fix: Use from highcharts_core.chart import Chart and HighchartsOptions for idiomatic Python usage

AI Feedback for Next Attempt

Implementation is strong across all categories. The main improvement area is adopting the highcharts-core Python library instead of raw JSON construction, which would raise Library Mastery. Visual quality and storytelling are excellent for a second attempt.

Verdict: APPROVED