feat(altair): implement heatmap-cohort-retention

[github-actions]

Implementation: heatmap-cohort-retention - altair

Implements the altair version of heatmap-cohort-retention.

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

Parent Issue: #4570

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a triangular cohort retention heatmap using a blue sequential colormap. The title "heatmap-cohort-retention · altair · pyplots.ai" is centered at the top in large font. The y-axis labeled "Signup Cohort" shows 10 cohorts from "Jan 2024 (n=1,926)" to "Oct 2024 (n=1,266)" with cohort sizes in parentheses. The x-axis labeled "Months Since Signup" shows "Month 0" through "Month 9". Each cell contains a retention percentage value displayed in bold text — white text on darker (high-retention) cells and dark gray text on lighter (low-retention) cells. The triangular shape is correct: Jan 2024 has all 10 periods while Oct 2024 has only Month 0. Cells are separated by white borders. A vertical color bar legend on the right shows "Retention %" ranging from 0 to 100. Period 0 is always 100% (darkest blue), with realistic decay patterns across subsequent months.

Score: 86/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set throughout (title 28, axis titles 22, axis labels 15–17, cell text 16). Y-axis labels at 15pt are slightly small for the target resolution.
• VQ-02: No Overlap (6/6) — No overlapping text anywhere. All labels and cell annotations are fully readable.
• VQ-03: Element Visibility (6/6) — Heatmap cells are well-sized with clear color differentiation. White borders separate cells cleanly.
• VQ-04: Color Accessibility (4/4) — Blues sequential colormap is colorblind-safe. Conditional text color (white/dark) ensures readability on all backgrounds.
• VQ-05: Layout & Canvas (3/4) — Good overall layout. The triangular shape inherently leaves empty space in the lower-right, but the chart fills the available area well. Minor empty space near the color bar.
• VQ-06: Axis Labels & Title (2/2) — "Months Since Signup" and "Signup Cohort" are descriptive and contextual.

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (5/8) — Blues colormap is well-chosen, white cell borders add polish, and conditional text coloring shows design thought. Above defaults but not publication-level.
• DE-02: Visual Refinement (3/6) — View stroke removed via configure_view(strokeWidth=0), white cell separators provide clean structure. Some refinement but grid/spines could be further polished.
• DE-03: Data Storytelling (3/6) — The triangular shape and color gradient naturally guide the eye to retention decay patterns. Variation between cohorts (e.g., Jul 2024 retains better) invites comparison, but no explicit focal point or emphasis on key insights.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct triangular heatmap with cohort rows and period columns.
• SC-02: Required Features (4/4) — All spec features present: triangular shape, retention percentages in cells, cohort sizes in y-axis labels, sequential colormap, color bar legend.
• SC-03: Data Mapping (3/3) — X-axis = periods since signup, Y-axis = cohorts. Correct mapping.
• SC-04: Title & Legend (3/3) — Title follows exact format "heatmap-cohort-retention · altair · pyplots.ai". Color bar legend labeled "Retention %".

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows full retention decay patterns, variation between cohorts, triangular shape from different cohort ages, and period 0 always at 100%.
• DQ-02: Realistic Context (5/5) — SaaS monthly cohort retention with plausible user counts (921–2,438) and realistic decay (55–72% after month 1, gradual decay thereafter).
• DQ-03: Appropriate Scale (4/4) — Retention values follow realistic patterns. Sharp initial drop then gradual decay. Cohort sizes are plausible for a mid-size SaaS product.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data generation → chart creation → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set at the top.
• CQ-03: Clean Imports (2/2) — All three imports (altair, numpy, pandas) are used.
• CQ-04: Code Elegance (2/2) — Clean, well-structured code. Appropriate complexity for the visualization. No over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot.png with scale_factor=3.0 and also saves plot.html. Current API usage.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of Altair's declarative API: mark_rect + mark_text layering, proper encoding types (:O, :Q), alt.Scale, alt.Axis configuration. Could use tooltip encoding for the HTML export.
• LM-02: Distinctive Features (3/5) — Uses alt.condition for conditional text coloring, layer composition with +, configure_view for view styling. These are Altair-specific patterns.

Score Caps Applied

• None

Strengths

• Perfect spec compliance — all required features implemented correctly (triangular shape, cell annotations, cohort sizes, color bar)
• Excellent data quality with realistic SaaS retention patterns and plausible cohort sizes
• Clean, idiomatic Altair code with good use of layer composition and conditional encoding
• Smart conditional text coloring (white on dark, dark on light) for readability

Weaknesses

• Design excellence could be improved — the plot looks like a well-configured default rather than publication-quality
• No visual emphasis or storytelling to highlight interesting patterns (e.g., Jul 2024 cohort retaining better)
• Y-axis label font size (15pt) is slightly small relative to other text elements

Issues Found

1. DE-01 MODERATE: Good but not exceptional aesthetics — blues scheme is appropriate but could use a more curated palette or additional design touches
   • Fix: Consider a green gradient (as spec suggests), add subtle background styling, or use a more distinctive color scheme
2. DE-02 MODERATE: Some visual refinement but room for improvement
   • Fix: Add padding/margins, refine axis styling further, consider background color for the chart area
3. DE-03 MODERATE: Data is displayed well but no storytelling emphasis
   • Fix: Use color or annotation emphasis to highlight notable patterns (e.g., best/worst retaining cohorts)

AI Feedback for Next Attempt

To reach 90+: (1) Enhance design excellence — consider a green sequential palette as spec suggests, add subtle background styling, and increase visual polish. (2) Add data storytelling — highlight the best-retaining cohort or annotate notable retention drops to create a focal point. (3) Bump y-axis label font to 17pt for consistent legibility. The implementation is technically excellent with perfect spec and data compliance.

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 10 monthly cohorts (Jan 2024 through Oct 2024) on the y-axis and months since signup (Month 0 through Month 9) on the x-axis. The cells use a custom sequential palette transitioning from light gray/white (low retention) through teals to dark navy (high retention). Each cell contains a bold retention percentage with a smaller "%" suffix. The triangular shape is correctly formed — Jan 2024 has all 10 periods while Oct 2024 has only 1. Cohort sizes (e.g., n=1,926) appear in parentheses next to each cohort label. A vertical color bar legend ("Retention %") is positioned on the right. The title reads "heatmap-cohort-retention · altair · pyplots.ai" with a subtitle "Monthly SaaS user retention — earliest cohorts show strongest long-term engagement". Cell borders are subtle light gray with rounded corners. The background is clean white.

Score: 90/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title=28, axis titles=22, tick labels=17, cell text=15). The % suffix at fontSize=10 is intentionally small but still readable at full resolution.
• VQ-02: No Overlap (6/6) — No overlapping text anywhere. The separate % layer with dx offset avoids collision.
• VQ-03: Element Visibility (6/6) — Rectangles well-sized with cornerRadius=3 and subtle stroke borders. All cells clearly visible.
• VQ-04: Color Accessibility (4/4) — Sequential teal-to-navy palette is colorblind-safe. Good luminance contrast between low and high retention values.
• VQ-05: Layout & Canvas (3/4) — Chart width=1400 (4200px at 3x) is slightly narrower than the ideal 4800px. The triangular shape inherently leaves empty space in the lower-right, but overall canvas utilization is good.
• VQ-06: Axis Labels & Title (2/2) — "Months Since Signup" and "Signup Cohort" are descriptive and contextual.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom 6-stop gradient palette (light gray → teals → dark navy), rounded cell corners, subtle cell borders, separate % symbol layer for typographic polish, informative subtitle. Clearly above configured defaults.
• DE-02: Visual Refinement (4/6) — View stroke removed, axis domains and ticks set to 0 width (effectively removing spines), generous padding on all sides, subtle #e8e8e8 cell borders. Good refinement.
• DE-03: Data Storytelling (4/6) — Subtitle communicates the key insight ("earliest cohorts show strongest long-term engagement"). Color gradient naturally guides the eye from dark (high retention) to light (churn). The triangular shape itself tells a temporal story.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct triangular heatmap with cohort rows and period columns.
• SC-02: Required Features (4/4) — All spec features present: triangular shape, retention % text in cells, cohort sizes in y-axis labels, sequential colormap, color bar legend.
• SC-03: Data Mapping (3/3) — X=periods since signup, Y=cohorts. All data visible and correctly mapped.
• SC-04: Title & Legend (3/3) — Title format "heatmap-cohort-retention · altair · pyplots.ai" is correct. Color bar legend with "Retention %" label serves as the appropriate legend.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows realistic decay patterns across cohorts, period 0 always 100%, varying cohort sizes (800-2500), different retention curves per cohort, full triangular structure.
• DQ-02: Realistic Context (5/5) — Monthly SaaS user retention is a real, neutral business scenario. Cohort labels use real month names.
• DQ-03: Appropriate Scale (4/4) — Retention decays realistically from 100% to ~19.5% over 9 months. Cohort sizes (921-2,438) are plausible for a SaaS product.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data generation → heatmap layer → text layer → % layer → combine → save.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ensures deterministic output.
• CQ-03: Clean Imports (2/2) — Only altair, numpy, pandas — all used.
• CQ-04: Code Elegance (2/2) — Clean, well-organized. The three-layer composition (rect + text + %) is elegant, not over-engineered.
• CQ-05: Output & API (1/1) — Saves as plot.png (scale_factor=3.0) and plot.html. Current Altair 6.0 API.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Expert Altair usage: mark_rect/mark_text with ordinal encoding and explicit sort orders, alt.condition() for conditional text color, alt.layer() composition, alt.Title with subtitle, configure_view/configure_axis for global styling.
• LM-02: Distinctive Features (3/5) — Uses alt.condition() for dynamic text color based on background intensity (distinctly Altair), built-in tooltip interactivity, HTML export, declarative layer composition pattern.

Score Caps Applied

• None — no caps triggered.

Strengths

• Custom 6-stop sequential palette with sophisticated color progression from light to dark
• Separate % symbol layer at smaller font size adds typographic polish
• Informative subtitle that communicates the key data insight
• Expert-level Altair idioms: conditional text color, layer composition, declarative encoding
• Perfect spec compliance with all required features present
• Realistic SaaS retention data with plausible decay patterns

Weaknesses

• Chart width is 1400 instead of 1600, resulting in 4200px instead of the ideal 4800px output width
• The % suffix fontSize=10 (30px at 3x) is on the small side

Issues Found

None critical — implementation meets approval threshold.

AI Feedback for Next Attempt

Strong implementation that meets the quality bar. The custom palette, thoughtful typography with the separate % layer, and informative subtitle elevate this above a standard heatmap. Consider using width=1600 for ideal canvas dimensions in future implementations.

Verdict: APPROVED