feat(plotly): implement heatmap-cohort-retention (#4942)

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

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

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

**Parent Issue:** #4570

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

---------

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/plotly.py

@@ -0,0 +1,155 @@
+""" pyplots.ai
+heatmap-cohort-retention: Cohort Retention Heatmap
+Library: plotly 6.6.0 | Python 3.14.3
+Quality: 91/100 | Created: 2026-03-16
+"""
+
+import numpy as np
+import plotly.graph_objects as go
+
+
+# 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",
+]
+num_cohorts = len(cohort_labels)
+num_periods = num_cohorts
+cohort_sizes = [1200, 1350, 980, 1100, 1450, 1280, 1050, 1380, 1150, 900]
+
+retention = np.full((num_cohorts, num_periods), np.nan)
+for i in range(num_cohorts):
+    max_period = num_periods - i
+    retention[i, 0] = 100.0
+    for j in range(1, max_period):
+        base_drop = np.exp(-0.25 * j) * 100
+        noise = np.random.normal(0, 3)
+        trend_bonus = i * 0.8
+        retention[i, j] = np.clip(base_drop + noise + trend_bonus, 5, 100)
+
+# Build hovertext and cell annotations with conditional coloring
+hover_text = []
+cell_annotations = []
+for i in range(num_cohorts):
+    row_hover = []
+    for j in range(num_periods):
+        if np.isnan(retention[i, j]):
+            row_hover.append("")
+        else:
+            val = retention[i, j]
+            row_hover.append(
+                f"<b>{cohort_labels[i]}</b> · Month {j}<br>"
+                f"Cohort size: {cohort_sizes[i]:,} users<br>"
+                f"Retained: <b>{val:.1f}%</b>"
+            )
+            cell_annotations.append(
+                {
+                    "x": f"Month {j}",
+                    "y": f"{cohort_labels[i]}  (n={cohort_sizes[i]:,})",
+                    "text": f"<b>{val:.0f}%</b>",
+                    "showarrow": False,
+                    "font": {"size": 15, "color": "#1a2e1a" if val < 45 else "white"},
+                }
+            )
+    hover_text.append(row_hover)
+
+# Y-axis labels with cohort size
+y_labels = [f"{label}  (n={size:,})" for label, size in zip(cohort_labels, cohort_sizes, strict=False)]
+x_labels = [f"Month {i}" for i in range(num_periods)]
+
+# Custom colorscale — teal-green sequential with good perceptual uniformity
+colorscale = [
+    [0.0, "#f0f9f4"],
+    [0.15, "#c6e7d4"],
+    [0.30, "#7cc5a3"],
+    [0.50, "#3a9d6e"],
+    [0.70, "#1e7a4e"],
+    [0.85, "#135c39"],
+    [1.0, "#0a3d26"],
+]
+
+# Plot
+fig = go.Figure(
+    data=go.Heatmap(
+        z=retention,
+        x=x_labels,
+        y=y_labels,
+        showscale=True,
+        hovertext=hover_text,
+        hoverinfo="text",
+        colorscale=colorscale,
+        zmin=0,
+        zmax=100,
+        colorbar={
+            "title": {"text": "Retention Rate", "font": {"size": 18, "color": "#2d2d2d"}},
+            "tickfont": {"size": 16, "color": "#2d2d2d"},
+            "ticksuffix": "%",
+            "tickvals": [0, 20, 40, 60, 80, 100],
+            "len": 0.75,
+            "thickness": 18,
+            "outlinewidth": 0,
+            "x": 1.02,
+        },
+        xgap=3,
+        ygap=3,
+    )
+)
+
+# Add cell annotations with conditional text coloring (dark on light, white on dark)
+for ann in cell_annotations:
+    fig.add_annotation(**ann)
+
+# Add a subtle annotation highlighting the improving trend
+fig.add_annotation(
+    text="↑ Later cohorts retain better",
+    xref="paper",
+    yref="paper",
+    x=0.0,
+    y=-0.10,
+    showarrow=False,
+    font={"size": 15, "color": "#3a9d6e", "family": "Arial"},
+    xanchor="left",
+)
+
+# Style
+fig.update_layout(
+    title={
+        "text": "heatmap-cohort-retention · plotly · pyplots.ai",
+        "font": {"size": 28, "color": "#1a1a1a", "family": "Arial Black, Arial"},
+        "x": 0.5,
+        "xanchor": "center",
+        "y": 0.96,
+    },
+    xaxis={
+        "title": {"text": "Months Since Signup", "font": {"size": 22, "color": "#2d2d2d"}, "standoff": 15},
+        "tickfont": {"size": 17, "color": "#3d3d3d"},
+        "side": "bottom",
+        "dtick": 1,
+    },
+    yaxis={
+        "title": {"text": "Signup Cohort", "font": {"size": 22, "color": "#2d2d2d"}, "standoff": 20},
+        "tickfont": {"size": 16, "color": "#3d3d3d"},
+        "autorange": "reversed",
+    },
+    template="plotly_white",
+    width=1600,
+    height=900,
+    margin={"l": 195, "r": 90, "t": 75, "b": 95},
+    paper_bgcolor="#fafafa",
+    plot_bgcolor="#fafafa",
+    font={"family": "Arial, Helvetica, sans-serif"},
+)
+
+# Save
+fig.write_image("plot.png", width=1600, height=900, scale=3)
+fig.write_html("plot.html", include_plotlyjs="cdn")

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

@@ -0,0 +1,232 @@
+library: plotly
+specification_id: heatmap-cohort-retention
+created: '2026-03-16T20:47:33Z'
+updated: '2026-03-16T20:59:38Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 23165008247
+issue: 4570
+python_version: 3.14.3
+library_version: 6.6.0
+preview_url: https://storage.googleapis.com/pyplots-images/plots/heatmap-cohort-retention/plotly/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/heatmap-cohort-retention/plotly/plot_thumb.png
+preview_html: https://storage.googleapis.com/pyplots-images/plots/heatmap-cohort-retention/plotly/plot.html
+quality_score: 91
+review:
+  strengths:
+  - Excellent triangular shape implementation with NaN masking for unavailable periods
+  - Custom 7-stop teal-green colorscale with good perceptual uniformity
+  - Smart conditional text coloring (dark on light cells, white on dark cells) for
+    universal readability
+  - Rich HTML hover tooltips showing cohort name, period, size, and retention — leveraging
+    Plotly interactivity
+  - Storytelling annotation guides viewer interpretation with improving trend across
+    cohorts
+  - Data shows realistic retention decay with plausible SaaS cohort sizes
+  weaknesses:
+  - Cell annotation font size (15) could be slightly larger for improved readability
+    at full resolution
+  - LM-01 could reach 5 by using plotly.express or more advanced Plotly patterns
+  image_description: 'The plot displays a triangular cohort retention heatmap with
+    10 monthly cohorts (Jan 2024 – Oct 2024) on the y-axis and Months 0–9 on the x-axis.
+    A custom teal-green sequential colorscale runs from very light green (low retention,
+    ~9%) to deep forest green (100% retention). Each cell contains a bold percentage
+    annotation with conditional text coloring — white text on dark cells, dark green
+    text on light cells. The y-axis labels include cohort sizes in parentheses (e.g.,
+    "Jan 2024 (n=1,200)"). The triangular shape is clearly visible: Jan 2024 spans
+    all 10 months while Oct 2024 has only Month 0. A colorbar on the right displays
+    "Retention Rate" with percentage ticks from 0–100%. A subtle green annotation
+    at the bottom reads "↑ Later cohorts retain better". The background is a soft
+    off-white (#fafafa) with the plotly_white template providing clean minimal chrome.
+    Cell gaps of 3px create clear visual separation between cells.'
+  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 28, axes 22, ticks 16-17, cell
+          text 15, colorbar 18/16). Cell annotation font slightly small.
+      - id: VQ-02
+        name: No Overlap
+        score: 6
+        max: 6
+        passed: true
+        comment: No overlapping text. Cell gaps and margins prevent collisions.
+      - id: VQ-03
+        name: Element Visibility
+        score: 6
+        max: 6
+        passed: true
+        comment: Heatmap cells well-sized with 3px gaps for clear separation.
+      - id: VQ-04
+        name: Color Accessibility
+        score: 4
+        max: 4
+        passed: true
+        comment: Green sequential colorscale is colorblind-safe. Conditional text
+          coloring ensures readability.
+      - id: VQ-05
+        name: Layout & Canvas
+        score: 4
+        max: 4
+        passed: true
+        comment: Plot fills canvas well with balanced margins. Triangular white space
+          is inherent to data.
+      - id: VQ-06
+        name: Axis Labels & Title
+        score: 2
+        max: 2
+        passed: true
+        comment: 'Descriptive labels: Months Since Signup, Signup Cohort.'
+    design_excellence:
+      score: 14
+      max: 20
+      items:
+      - id: DE-01
+        name: Aesthetic Sophistication
+        score: 6
+        max: 8
+        passed: true
+        comment: Custom 7-stop teal-green colorscale, conditional text coloring, off-white
+          background, cell gaps. Clearly above defaults.
+      - id: DE-02
+        name: Visual Refinement
+        score: 4
+        max: 6
+        passed: true
+        comment: plotly_white template, 3px cell gaps, generous whitespace, custom
+          background color.
+      - id: DE-03
+        name: Data Storytelling
+        score: 4
+        max: 6
+        passed: true
+        comment: Storytelling annotation guides interpretation. Improving trend across
+          cohorts creates a clear narrative.
+    spec_compliance:
+      score: 15
+      max: 15
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 5
+        max: 5
+        passed: true
+        comment: Correct triangular heatmap with NaN masking.
+      - id: SC-02
+        name: Required Features
+        score: 4
+        max: 4
+        passed: true
+        comment: 'All spec features present: triangular shape, 100% at period 0, cell
+          text, cohort sizes, colorbar, green colorscale.'
+      - id: SC-03
+        name: Data Mapping
+        score: 3
+        max: 3
+        passed: true
+        comment: X=months since signup, Y=cohorts (reversed), Z=retention rate.
+      - id: SC-04
+        name: Title & Legend
+        score: 3
+        max: 3
+        passed: true
+        comment: Title matches required format. Colorbar serves as legend with Retention
+          Rate label.
+    data_quality:
+      score: 15
+      max: 15
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 6
+        max: 6
+        passed: true
+        comment: Shows retention decay, triangular shape, cohort size variation, improving
+          trend, full range 9-100%.
+      - id: DQ-02
+        name: Realistic Context
+        score: 5
+        max: 5
+        passed: true
+        comment: SaaS monthly cohort retention is a classic neutral business analytics
+          scenario.
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 4
+        passed: true
+        comment: Realistic exponential decay, plausible cohort sizes (900-1450).
+    code_quality:
+      score: 10
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: 'Clean linear flow: imports, data, hover/annotations, plot, style,
+          save.'
+      - id: CQ-02
+        name: Reproducibility
+        score: 2
+        max: 2
+        passed: true
+        comment: np.random.seed(42) ensures deterministic output.
+      - id: CQ-03
+        name: Clean Imports
+        score: 2
+        max: 2
+        passed: true
+        comment: Only numpy and plotly.graph_objects, both fully utilized.
+      - id: CQ-04
+        name: Code Elegance
+        score: 2
+        max: 2
+        passed: true
+        comment: Appropriate complexity. No fake UI or over-engineering.
+      - id: CQ-05
+        name: Output & API
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves plot.png at 4800x2700 (1600x900 scale=3). Also exports HTML.
+    library_mastery:
+      score: 8
+      max: 10
+      items:
+      - id: LM-01
+        name: Idiomatic Usage
+        score: 4
+        max: 5
+        passed: true
+        comment: Good use of go.Heatmap with proper parameters, fig.add_annotation,
+          update_layout.
+      - id: LM-02
+        name: Distinctive Features
+        score: 4
+        max: 5
+        passed: true
+        comment: Rich HTML hover tooltips, HTML export, colorbar customization — distinctly
+          Plotly capabilities.
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - annotations
+  - colorbar
+  - hover-tooltips
+  - html-export
+  patterns:
+  - data-generation
+  - matrix-construction
+  - iteration-over-groups
+  dataprep: []
+  styling:
+  - custom-colormap
+  - edge-highlighting