feat(seaborn): implement heatmap-cohort-retention

[github-actions]

Implementation: heatmap-cohort-retention - seaborn

Implements the seaborn version of heatmap-cohort-retention.

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

Parent Issue: #4570

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/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 periods (Month 0 through Month 9) on the x-axis positioned at the top. Each cell contains the retention percentage as white text. The colormap is YlGnBu — dark teal/blue for high retention (100%) transitioning to pale yellow for low values (single digits). Cohort sizes are shown in parentheses next to each cohort label (e.g., "Jan 2024 (n=1,926)"). The triangular shape is correctly formed, with each subsequent cohort having one fewer period column. White gridlines (linewidth=2) separate cells cleanly. A vertical colorbar on the right shows the "Retention %" scale from 0 to 100. The title reads "heatmap-cohort-retention · seaborn · pyplots.ai" in medium-weight font at the top.

Score: 86/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 24, labels 20, annotations 13, colorbar 16). Tick labels set to 14pt, slightly below the 16pt guideline but still readable.
• VQ-02: No Overlap (6/6) — No overlapping text anywhere; cells are spacious.
• VQ-03: Element Visibility (6/6) — Cells well-sized with white linewidths creating clear separation; annotation text is clearly visible against all background colors.
• VQ-04: Color Accessibility (4/4) — YlGnBu is a perceptually uniform, colorblind-safe sequential colormap.
• VQ-05: Layout & Canvas (4/4) — Plot fills the canvas well with tight_layout; balanced margins.
• VQ-06: Axis Labels & Title (2/2) — "Periods Since Signup" and "Signup Cohort" are descriptive.

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (5/8) — YlGnBu is a strong colormap choice, white gridlines look clean, and moving x-axis to top is a thoughtful design decision for cohort heatmaps. However, the overall look is a well-configured seaborn default rather than a custom publication-quality design.
• DE-02: Visual Refinement (3/6) — White cell separators and top-positioned x-axis show some refinement. However, default matplotlib spines are still visible and the background is not customized. No spine removal or grid styling applied.
• DE-03: Data Storytelling (3/6) — The triangular shape naturally conveys cohort aging, and the color gradient clearly shows retention decay over time. Cohort variation is visible (May 2024 retains better). However, there is no explicit focal point, no highlight of best/worst cohorts, and no visual emphasis guiding the viewer to key insights.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct triangular cohort retention heatmap.
• SC-02: Required Features (4/4) — All spec features present: triangular shape, retention % in cells, cohort sizes next to labels, sequential colormap, colorbar legend, "Month X" period labels.
• SC-03: Data Mapping (3/3) — Cohorts on Y, periods on X, period 0 always 100%.
• SC-04: Title & Legend (3/3) — Title follows exact format "heatmap-cohort-retention · seaborn · pyplots.ai". Colorbar serves as legend with "Retention %" label.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows full range: 100% at period 0 decaying to single digits, varying cohort sizes (921–2,438), different retention curves across cohorts, proper triangular shape.
• DQ-02: Realistic Context (5/5) — Monthly SaaS signup cohorts with realistic retention decay patterns; neutral business analytics domain.
• DQ-03: Appropriate Scale (4/4) — Retention values are realistic (100% → ~6% over 9 months), cohort sizes of 800–2,500 are plausible for a mid-size SaaS product.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data generation → plot → styling → save.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All four imports (matplotlib, numpy, pandas, seaborn) are used.
• CQ-04: Code Elegance (2/2) — Appropriate complexity; data generation loop is straightforward, no over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot.png with dpi=300, bbox_inches='tight'. Current API used.

Library Mastery (6/10)

• LM-01: Idiomatic Usage (4/5) — Good use of sns.heatmap with mask, annot, fmt, cmap, cbar_kws, and linewidths. This is the idiomatic seaborn approach for masked heatmaps.
• LM-02: Distinctive Features (2/5) — The mask parameter for triangular shape and built-in annotation/colorbar integration are seaborn features, but this is a fairly standard sns.heatmap usage pattern. Could leverage seaborn's styling ecosystem more (sns.set_context, sns.set_style, sns.despine).

Score Caps Applied

• None

Strengths

• Perfect spec compliance — all required features implemented correctly (triangular shape, cell annotations, cohort sizes, colorbar)
• Excellent data quality with realistic SaaS retention patterns and appropriate variation across cohorts
• Clean, well-structured code following KISS principles
• Smart design choice placing x-axis at top for easier reading of cohort data

Weaknesses

• Default matplotlib spines still visible — should use sns.despine() or manual spine removal
• No visual hierarchy or emphasis to guide the viewer to key insights (e.g., highlighting best/worst retaining cohorts)
• Tick label font sizes (14pt) slightly below the recommended 16pt threshold
• Could leverage more seaborn-specific styling (sns.set_context, sns.set_style)

Issues Found

1. DE-02 LOW: Default spines and background still visible, minimal visual refinement
   • Fix: Use sns.despine() or remove spines manually; consider a cleaner background style
2. DE-01 MODERATE: Well-configured default but not publication-quality design
   • Fix: Consider a more refined color palette, adjust typography hierarchy, add subtle design touches
3. DE-03 LOW: No visual emphasis or focal point guiding the viewer
   • Fix: Use color contrast or annotation to highlight key retention insights (e.g., best-performing cohort, critical drop-off points)
4. LM-02 LOW: Generic sns.heatmap usage without leveraging seaborn's styling ecosystem
   • Fix: Use sns.set_context("talk"), sns.set_style(), sns.despine() to demonstrate seaborn mastery

AI Feedback for Next Attempt

Focus on Design Excellence: (1) Remove spines with sns.despine() and use sns.set_style("white") or similar for a cleaner look. (2) Increase tick label font sizes to 16pt. (3) Create visual hierarchy — consider using a diverging annotation color (white on dark cells, dark on light cells) and highlighting key retention insights. (4) Leverage seaborn's styling functions (sns.set_context, sns.set_style) to demonstrate library mastery. The spec compliance, data quality, and code quality are all excellent — keep those unchanged.

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 – Oct 2024) on the y-axis and 10 periods (Month 0 – Month 9) on the x-axis positioned at the top. Each cell shows bold retention percentages with a "%" suffix. The color scheme transitions from light tan/peach (low retention) through medium green to dark forest green (high retention), using a custom colormap. Cohort sizes (n=921 to n=2,438) are shown in parentheses next to each cohort label. The triangular shape is correctly formed — earlier cohorts have more columns. The background is light gray (#fafafa), all spines are removed, tick marks are hidden, and the colorbar on the right displays "Retention %" from 0–100 with its outline removed. The title reads "heatmap-cohort-retention · seaborn · pyplots.ai" in medium weight.

Score: 90/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	15	20
Spec Compliance	15	15
Data Quality	14	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 24pt, labels 20pt, ticks 16pt, annotations 13pt). Annotations slightly small but still readable.
• VQ-02: No Overlap (6/6) - No overlapping text anywhere. Clean cell spacing with linewidths=2.5.
• VQ-03: Element Visibility (6/6) - Heatmap cells well-sized, clear separation, good contrast between cells.
• VQ-04: Color Accessibility (3/4) - Custom tan-to-green palette avoids red-green issues but is not perceptually uniform. Some mid-range values may be harder to distinguish.
• VQ-05: Layout & Canvas (4/4) - Plot fills canvas well, colorbar appropriately sized and positioned, balanced margins.
• VQ-06: Axis Labels & Title (2/2) - "Periods Since Signup" and "Signup Cohort" are descriptive and contextually appropriate.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) - Custom colormap with warm-to-green transition, custom background color, styled colorbar with outline removed, bold annotations — clearly above defaults with intentional design choices.
• DE-02: Visual Refinement (5/6) - All spines removed via sns.despine, tick marks hidden, custom background (#fafafa), generous cell spacing, colorbar outline removed. Nearly all details polished.
• DE-03: Data Storytelling (4/6) - The triangular shape naturally communicates the cohort narrative. Color intensity effectively shows retention decay. Varied cohort sizes and retention rates enable cross-cohort comparison.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct triangular cohort retention heatmap.
• SC-02: Required Features (4/4) - All spec features present: triangular shape, Period 0 = 100%, sequential colormap, retention % text in cells, cohort sizes in y-labels, "Month N" x-labels, colorbar legend.
• SC-03: Data Mapping (3/3) - Cohorts on Y-axis, periods on X-axis, retention as color intensity. Correct.
• SC-04: Title & Legend (3/3) - Title format "heatmap-cohort-retention · seaborn · pyplots.ai" correct. Colorbar serves as legend.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Shows varying decay rates across cohorts, different cohort sizes, full triangular pattern. Some cohorts have similar decay profiles.
• DQ-02: Realistic Context (5/5) - Monthly SaaS cohort retention — a real-world, neutral business analytics scenario.
• DQ-03: Appropriate Scale (4/4) - Retention values realistic: 100% at signup, decaying to single digits for longest cohorts. Cohort sizes 921–2,438 are plausible.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear flow: imports → styling → data generation → plot → save. No functions or classes.
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) - All imports used: mcolors, plt, np, pd, sns.
• CQ-04: Code Elegance (2/2) - Clean and Pythonic. The .map() for annotation formatting is elegant. No over-engineering.
• CQ-05: Output & API (1/1) - Saves as plot.png with dpi=300. No deprecated API usage.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) - Expert use of sns.heatmap with mask, annot, fmt, cbar_kws. Uses sns.set_context, sns.set_style, and sns.despine idiomatically.
• LM-02: Distinctive Features (3/5) - Leverages seaborn-specific features: heatmap mask parameter for triangular shape, built-in annotation support, cbar_kws integration, sns.despine convenience function.

Score Caps Applied

• None

Strengths

• Excellent spec compliance — all required features implemented correctly
• Custom colormap with warm-to-green transition creates a distinctive, professional look
• Clean visual refinement: all spines removed, tick marks hidden, custom background, styled colorbar
• Idiomatic seaborn usage with mask, annotations, and context/style configuration
• Well-structured, readable code with proper reproducibility

Weaknesses

• Annotation font size (13pt) could be slightly larger for better readability at full resolution
• Color palette is not perceptually uniform — mid-range retention values may be harder to distinguish
• Some cohorts show very similar decay patterns, limiting cross-cohort comparison insight

Issues Found

None critical — implementation meets quality threshold.

AI Feedback for Next Attempt

Implementation is polished and meets the quality bar. Minor improvements could include bumping annotation font size to 14-15pt and considering a perceptually uniform base for the custom colormap.

Verdict: APPROVED