feat(matplotlib): implement heatmap-cohort-retention (#4943)

## Implementation: `heatmap-cohort-retention` - matplotlib

Implements the **matplotlib** version of `heatmap-cohort-retention`.

**File:** `plots/heatmap-cohort-retention/implementations/matplotlib.py`

**Parent Issue:** #4570

---
:robot: *[impl-generate
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/23165008020)*

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/heatmap-cohort-retention/implementations/matplotlib.py

@@ -0,0 +1,132 @@
+""" pyplots.ai
+heatmap-cohort-retention: Cohort Retention Heatmap
+Library: matplotlib 3.10.8 | Python 3.14.3
+Quality: 92/100 | Created: 2026-03-16
+"""
+
+import matplotlib.colors as mcolors
+import matplotlib.patches as mpatches
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+# Data
+np.random.seed(42)
+cohort_labels = [
+    "Jan 2024",
+    "Feb 2024",
+    "Mar 2024",
+    "Apr 2024",
+    "May 2024",
+    "Jun 2024",
+    "Jul 2024",
+    "Aug 2024",
+    "Sep 2024",
+    "Oct 2024",
+]
+cohort_sizes = [1200, 1350, 980, 1100, 1450, 1280, 1050, 1320, 1180, 1400]
+n_cohorts = len(cohort_labels)
+n_periods = n_cohorts
+
+# Generate realistic retention data with meaningful variation across cohorts
+# Some cohorts retain much better (e.g., May launch campaign), some churn faster
+retention = np.full((n_cohorts, n_periods), np.nan)
+# Per-cohort decay multipliers: <1 = better retention, >1 = worse retention
+decay_profiles = [1.0, 1.15, 1.3, 1.1, 0.55, 0.65, 1.2, 0.85, 1.05, 0.75]
+
+for i in range(n_cohorts):
+    max_periods = n_periods - i
+    retention[i, 0] = 100.0
+    for j in range(1, max_periods):
+        base_drop = (15 * np.exp(-0.25 * j) + 1.5) * decay_profiles[i]
+        noise = np.random.uniform(-2, 2)
+        retention[i, j] = max(retention[i, j - 1] - base_drop - noise, 5)
+
+# Find the best-performing cohort (highest average retention) for emphasis
+# Require at least 4 periods to qualify as "best" cohort
+avg_retention = [np.nanmean(retention[i, 1 : n_periods - i]) if n_periods - i >= 4 else 0.0 for i in range(n_cohorts)]
+best_cohort = int(np.argmax(avg_retention))
+
+# Plot
+fig, ax = plt.subplots(figsize=(16, 9))
+
+# Perceptually-uniform colormap
+cmap = plt.cm.viridis
+norm = mcolors.Normalize(vmin=0, vmax=100)
+
+# Draw heatmap cells using FancyBboxPatch for rounded corners
+for i in range(n_cohorts):
+    for j in range(n_periods):
+        if np.isnan(retention[i, j]):
+            continue
+        val = retention[i, j]
+        color = cmap(norm(val))
+        rect = mpatches.FancyBboxPatch(
+            (j - 0.47, i - 0.47),
+            0.94,
+            0.94,
+            boxstyle=mpatches.BoxStyle.Round(pad=0, rounding_size=0.08),
+            facecolor=color,
+            edgecolor="white",
+            linewidth=2.5,
+        )
+        ax.add_patch(rect)
+        # Text color: white on dark cells, dark on light cells
+        luminance = 0.299 * color[0] + 0.587 * color[1] + 0.114 * color[2]
+        text_color = "white" if luminance < 0.5 else "#1a1a2e"
+        ax.text(
+            j,
+            i,
+            f"{val:.0f}%",
+            ha="center",
+            va="center",
+            fontsize=15,
+            fontweight="bold" if i == best_cohort else "medium",
+            color=text_color,
+        )
+
+# Style
+ax.set_xlim(-0.5, n_periods - 0.5)
+ax.set_ylim(n_cohorts - 0.5, -0.5)
+ax.set_xticks(range(n_periods))
+ax.set_xticklabels([f"Month {p}" for p in range(n_periods)], fontsize=16)
+ax.set_yticks(range(n_cohorts))
+ytick_labels = []
+for idx, (label, size) in enumerate(zip(cohort_labels, cohort_sizes, strict=True)):
+    text = f"{label}  (n={size:,})"
+    if idx == best_cohort:
+        text = f"\u2605 {text}"
+    ytick_labels.append(text)
+ax.set_yticklabels(ytick_labels, fontsize=16)
+ax.set_xlabel("Months Since Signup", fontsize=20)
+ax.set_ylabel("Signup Cohort", fontsize=20)
+ax.set_title("heatmap-cohort-retention · matplotlib · pyplots.ai", fontsize=24, fontweight="medium", pad=20)
+
+# Highlight best cohort row with a subtle border
+highlight_rect = mpatches.FancyBboxPatch(
+    (-0.55, best_cohort - 0.55),
+    n_periods - best_cohort + 0.1,
+    1.1,
+    boxstyle=mpatches.BoxStyle.Round(pad=0, rounding_size=0.12),
+    facecolor="none",
+    edgecolor="#FFD700",
+    linewidth=3,
+    linestyle="--",
+    zorder=5,
+)
+ax.add_patch(highlight_rect)
+
+for spine in ax.spines.values():
+    spine.set_visible(False)
+ax.tick_params(axis="both", length=0)
+
+# Colorbar
+sm = plt.cm.ScalarMappable(cmap=cmap, norm=norm)
+sm.set_array([])
+cbar = fig.colorbar(sm, ax=ax, shrink=0.6, aspect=25, pad=0.02)
+cbar.set_label("Retention Rate (%)", fontsize=16)
+cbar.ax.tick_params(labelsize=16)
+cbar.outline.set_visible(False)
+
+plt.tight_layout()
+plt.savefig("plot.png", dpi=300, bbox_inches="tight")

plots/heatmap-cohort-retention/metadata/matplotlib.yaml

@@ -0,0 +1,235 @@
+library: matplotlib
+specification_id: heatmap-cohort-retention
+created: '2026-03-16T20:48:01Z'
+updated: '2026-03-16T21:00:45Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 23165008020
+issue: 4570
+python_version: 3.14.3
+library_version: 3.10.8
+preview_url: https://storage.googleapis.com/pyplots-images/plots/heatmap-cohort-retention/matplotlib/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/heatmap-cohort-retention/matplotlib/plot_thumb.png
+preview_html: null
+quality_score: 92
+review:
+  strengths:
+  - Rounded-corner cells via FancyBboxPatch give a modern, polished look distinct
+    from standard heatmaps
+  - Best-cohort highlighting (star icon + gold dashed border + bold text) creates
+    effective data storytelling
+  - 'Excellent spec compliance: triangular shape, cell annotations, cohort sizes,
+    colorbar all present'
+  - Clean, well-structured code with meaningful data variation across cohorts
+  weaknesses:
+  - Cell text fontsize (15) is slightly below the recommended 16pt minimum for tick-level
+    text
+  - Could explore a warmer sequential colormap that maps more intuitively to good
+    retention = green
+  image_description: 'The plot displays a triangular cohort retention heatmap with
+    10 monthly signup cohorts (Jan 2024 – Oct 2024) on the y-axis and periods (Month
+    0 – Month 9) on the x-axis. Cells use the viridis colormap — bright yellow-green
+    for high retention (100%), transitioning through teal to dark blue for low retention
+    (~33–39%). Each cell contains a bold percentage label with automatic contrast
+    (white text on dark cells, dark text on light cells). The triangular shape is
+    correctly formed: Jan 2024 has all 10 periods while Oct 2024 has only 1. Cohort
+    sizes are shown in parentheses next to each cohort label (e.g., "Jan 2024 (n=1,200)").
+    The May 2024 cohort is marked with a gold star (★) and surrounded by a gold dashed
+    border, identifying it as the best-performing cohort with retention of 74% at
+    Month 5. Cells have rounded corners with white borders, creating a clean, modern
+    appearance. A vertical colorbar on the right labeled "Retention Rate (%)" maps
+    the 0–100% range. The title reads "heatmap-cohort-retention · matplotlib · pyplots.ai".'
+  criteria_checklist:
+    visual_quality:
+      score: 29
+      max: 30
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 7
+        max: 8
+        passed: true
+        comment: All font sizes explicitly set (title 24, labels 20, ticks 16, cell
+          text 15). Cell text slightly below 16pt guideline but readable.
+      - id: VQ-02
+        name: No Overlap
+        score: 6
+        max: 6
+        passed: true
+        comment: No overlapping text anywhere. All cell values, axis labels, and tick
+          labels fully readable.
+      - id: VQ-03
+        name: Element Visibility
+        score: 6
+        max: 6
+        passed: true
+        comment: Cells well-sized with white borders and rounded corners creating
+          excellent separation.
+      - id: VQ-04
+        name: Color Accessibility
+        score: 4
+        max: 4
+        passed: true
+        comment: Viridis is perceptually-uniform and colorblind-safe.
+      - id: VQ-05
+        name: Layout & Canvas
+        score: 4
+        max: 4
+        passed: true
+        comment: Plot fills canvas well. Colorbar compact and well-positioned. Balanced
+          margins.
+      - id: VQ-06
+        name: Axis Labels & Title
+        score: 2
+        max: 2
+        passed: true
+        comment: 'Descriptive labels: Months Since Signup, Signup Cohort.'
+    design_excellence:
+      score: 16
+      max: 20
+      items:
+      - id: DE-01
+        name: Aesthetic Sophistication
+        score: 6
+        max: 8
+        passed: true
+        comment: Rounded-corner cells, white borders, gold star/border highlight,
+          luminance-based text contrast. Above defaults with intentional design.
+      - id: DE-02
+        name: Visual Refinement
+        score: 5
+        max: 6
+        passed: true
+        comment: All spines removed, tick marks hidden, colorbar outline removed,
+          generous whitespace between cells.
+      - id: DE-03
+        name: Data Storytelling
+        score: 5
+        max: 6
+        passed: true
+        comment: Best cohort highlighted with star icon and gold dashed border. Clear
+          focal point guides viewer to key insight.
+    spec_compliance:
+      score: 15
+      max: 15
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 5
+        max: 5
+        passed: true
+        comment: Correct triangular cohort retention heatmap.
+      - id: SC-02
+        name: Required Features
+        score: 4
+        max: 4
+        passed: true
+        comment: 'All spec features present: triangular shape, cell annotations, cohort
+          sizes, colorbar, period labels.'
+      - id: SC-03
+        name: Data Mapping
+        score: 3
+        max: 3
+        passed: true
+        comment: Cohorts on Y, periods on X, retention mapped to color.
+      - id: SC-04
+        name: Title & Legend
+        score: 3
+        max: 3
+        passed: true
+        comment: Title follows exact format. Colorbar serves as legend with proper
+          label.
+    data_quality:
+      score: 14
+      max: 15
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 5
+        max: 6
+        passed: true
+        comment: 'Good variation: fast-churning and high-retention cohorts shown.
+          Could show slightly more extreme variation.'
+      - id: DQ-02
+        name: Realistic Context
+        score: 5
+        max: 5
+        passed: true
+        comment: SaaS monthly cohort retention is a real, neutral business analytics
+          scenario.
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 4
+        passed: true
+        comment: 'Realistic retention values: 100% at signup, decaying to 30-40%.
+          Cohort sizes 980-1450 plausible.'
+    code_quality:
+      score: 10
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: 'Clean linear structure: imports, data, plot, style, save.'
+      - id: CQ-02
+        name: Reproducibility
+        score: 2
+        max: 2
+        passed: true
+        comment: np.random.seed(42) set at start.
+      - id: CQ-03
+        name: Clean Imports
+        score: 2
+        max: 2
+        passed: true
+        comment: 'All imports used: mcolors, mpatches, plt, np.'
+      - id: CQ-04
+        name: Code Elegance
+        score: 2
+        max: 2
+        passed: true
+        comment: Appropriate complexity. FancyBboxPatch justified for rounded-corner
+          aesthetic.
+      - id: CQ-05
+        name: Output & API
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves as plot.png with dpi=300, bbox_inches=tight. No deprecated
+          API.
+    library_mastery:
+      score: 8
+      max: 10
+      items:
+      - id: LM-01
+        name: Idiomatic Usage
+        score: 4
+        max: 5
+        passed: true
+        comment: Uses Axes methods, FancyBboxPatch, ScalarMappable, mcolors.Normalize
+          correctly. Manual heatmap for rounded corners.
+      - id: LM-02
+        name: Distinctive Features
+        score: 4
+        max: 5
+        passed: true
+        comment: FancyBboxPatch with BoxStyle.Round, luminance-based text color, ScalarMappable
+          for standalone colorbar are distinctively matplotlib.
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - colorbar
+  - annotations
+  - patches
+  - manual-ticks
+  patterns:
+  - data-generation
+  - matrix-construction
+  - iteration-over-groups
+  dataprep: []
+  styling:
+  - custom-colormap
+  - edge-highlighting