feat(plotnine): implement heatmap-cohort-retention (#10309)

## Implementation: `heatmap-cohort-retention` - python/plotnine

Implements the **python/plotnine** version of
`heatmap-cohort-retention`.

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

**Parent Issue:** #4570

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

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com>

Author: github-actions[bot]

plots/heatmap-cohort-retention/implementations/python/plotnine.py

@@ -1,30 +1,44 @@
-""" pyplots.ai
+""" anyplot.ai
 heatmap-cohort-retention: Cohort Retention Heatmap
-Library: plotnine 0.15.3 | Python 3.14.3
-Quality: 90/100 | Created: 2026-03-16
+Library: plotnine 0.15.8 | Python 3.13.15
+Quality: 95/100 | Updated: 2026-08-17
 """
 
+import os
+
 import numpy as np
 import pandas as pd
+from matplotlib.patches import FancyBboxPatch
 from plotnine import (
     aes,
-    annotate,
     element_blank,
     element_rect,
     element_text,
     geom_text,
     geom_tile,
     ggplot,
     labs,
-    scale_color_identity,
-    scale_fill_gradientn,
+    scale_fill_gradient,
     scale_x_continuous,
     scale_y_discrete,
     theme,
     theme_minimal,
 )
 
 
+# Theme-adaptive chrome
+THEME = os.getenv("ANYPLOT_THEME", "light")
+PAGE_BG = "#FAF8F1" if THEME == "light" else "#1A1A17"
+ELEVATED_BG = "#FFFDF6" if THEME == "light" else "#242420"
+INK = "#1A1A17" if THEME == "light" else "#F0EFE8"
+INK_SOFT = "#4A4A44" if THEME == "light" else "#B8B7B0"
+RULE = (26 / 255, 26 / 255, 23 / 255, 0.15) if THEME == "light" else (240 / 255, 239 / 255, 232 / 255, 0.15)
+
+# Imprint sequential colormap (brand green -> blue) for single-polarity continuous data
+# Green (brand) reads as "good" -> high retention; blue anchors low retention
+SEQ_HIGH_RETENTION = "#009E73"
+SEQ_LOW_RETENTION = "#4467A3"
+
 # Data
 np.random.seed(42)
 cohorts = [
@@ -41,6 +55,8 @@
 ]
 n_cohorts = len(cohorts)
 cohort_sizes = [1200, 1350, 980, 1100, 1450, 1280, 1050, 1380, 1150, 1020]
+# Mar 2024 (index 2) suffered a pricing-change churn spike -> visibly worse retention
+churn_event_idx = 2
 
 rows = []
 for i, cohort in enumerate(cohorts):
@@ -49,79 +65,105 @@
         if period == 0:
             retention = 100.0
         else:
-            base_decay = 100 * np.exp(-0.25 * period)
+            base_decay = 100 * np.exp(-0.22 * period)
             noise = np.random.uniform(-3, 3)
-            trend_bonus = i * 1.5
-            retention = np.clip(base_decay + noise + trend_bonus, 5, 100)
+            trend_bonus = i * 2.2  # onboarding steadily improves for later cohorts
+            churn_penalty = 14 if i == churn_event_idx else 0
+            retention = np.clip(base_decay + noise + trend_bonus - churn_penalty, 5, 100)
         rows.append(
             {"cohort": cohort, "period": period, "retention_rate": round(retention, 1), "cohort_size": cohort_sizes[i]}
         )
 
 df = pd.DataFrame(rows)
 
-# Create y-axis labels with cohort size
+# Y-axis labels carry cohort size; reversed order puts Jan 2024 at the top, Oct 2024 at the bottom
 df["cohort_label"] = df.apply(lambda r: f"{r['cohort']} (n={r['cohort_size']:,})", axis=1)
-
-# Preserve ordering
 cohort_labels = [f"{c} (n={s:,})" for c, s in zip(cohorts, cohort_sizes, strict=True)]
 df["cohort_label"] = pd.Categorical(df["cohort_label"], categories=cohort_labels[::-1], ordered=True)
 
-# Text color: white on dark cells (viridis dark end), dark on light cells
-df["text_color"] = df["retention_rate"].apply(lambda v: "#ffffff" if v < 60 else "#1a1a2e")
-
-# Format retention text
 df["label"] = df["retention_rate"].apply(lambda v: f"{v:.0f}%")
 
-# Compare earliest vs latest cohort at same period for storytelling
+# Compare an early vs. a later cohort at the same period for storytelling
 compare_period = 4
-earliest = df[(df["cohort"] == "Jan 2024") & (df["period"] == compare_period)]["retention_rate"].values[0]
-latest = df[(df["cohort"] == "Jun 2024") & (df["period"] == compare_period)]["retention_rate"].values[0]
-improvement = latest - earliest
-
-# Perceptually uniform sequential palette (viridis-inspired: dark purple → teal → yellow)
-colors = ["#440154", "#31688e", "#35b779", "#fde725"]
+early_val = df[(df["cohort"] == "Jan 2024") & (df["period"] == compare_period)]["retention_rate"].values[0]
+later_val = df[(df["cohort"] == "Jun 2024") & (df["period"] == compare_period)]["retention_rate"].values[0]
+improvement = later_val - early_val
+cohort_trend_pp = 2.2  # per-cohort onboarding bonus baked into the synthetic retention formula above
 
 # Plot
 plot = (
     ggplot(df, aes(x="period", y="cohort_label", fill="retention_rate"))
-    + geom_tile(color="#f8f9fa", size=0.6)
-    + geom_text(aes(label="label", color="text_color"), size=13, fontweight="bold")
-    + scale_fill_gradientn(colors=colors, limits=(0, 100), name="Retention %")
-    + scale_color_identity()
-    + scale_x_continuous(breaks=range(n_cohorts), labels=[f"M{i}" for i in range(n_cohorts)])
-    + scale_y_discrete(expand=(0.05, 0))
-    + annotate(
-        "text",
-        x=n_cohorts - 2,
-        y=3,
-        label=f"Month {compare_period} retention improved\n+{improvement:.0f}pp from Jan→Jun 2024",
-        size=11,
-        color="#2d2d2d",
-        ha="center",
-        fontweight="bold",
-    )
+    + geom_tile(color=PAGE_BG, size=0.8)
+    + geom_text(aes(label="label"), size=3.1, color="#FFFFFF", fontweight="bold")
+    + scale_fill_gradient(low=SEQ_LOW_RETENTION, high=SEQ_HIGH_RETENTION, limits=(0, 100), name="Retention %")
+    + scale_x_continuous(breaks=range(n_cohorts), labels=[f"Month {i}" for i in range(n_cohorts)])
+    + scale_y_discrete(expand=(0.06, 0))
     + labs(
         x="Months Since Signup",
         y="",
-        title="heatmap-cohort-retention · plotnine · pyplots.ai",
-        subtitle="Monthly cohort retention — newer cohorts retain significantly better over time",
+        title="heatmap-cohort-retention · python · plotnine · anyplot.ai",
+        subtitle="Monthly cohort retention — newer cohorts retain better; Mar 2024 shows a pricing-change churn spike",
     )
     + theme_minimal()
     + theme(
-        figure_size=(16, 9),
-        plot_title=element_text(size=26, ha="center", weight="bold", color="#0d1b2a"),
-        plot_subtitle=element_text(size=18, ha="center", color="#555555", style="italic"),
-        axis_title_x=element_text(size=20, color="#333333"),
-        axis_text_x=element_text(size=16, color="#444444"),
-        axis_text_y=element_text(size=16, color="#444444"),
-        legend_title=element_text(size=16, weight="bold"),
-        legend_text=element_text(size=14),
+        figure_size=(6, 6),
+        plot_title=element_text(size=12, ha="center", weight="bold", color=INK),
+        plot_subtitle=element_text(size=8, ha="center", color=INK_SOFT, style="italic"),
+        axis_title_x=element_text(size=10, color=INK),
+        axis_text_x=element_text(size=8, color=INK_SOFT, angle=45, ha="right"),
+        axis_text_y=element_text(size=8, color=INK_SOFT),
+        legend_title=element_text(size=9, weight="bold", color=INK),
+        legend_text=element_text(size=8, color=INK_SOFT),
+        legend_background=element_rect(fill=ELEVATED_BG, color=None),
         panel_grid_major=element_blank(),
         panel_grid_minor=element_blank(),
-        plot_background=element_rect(fill="#fafafa", color="none"),
-        panel_background=element_rect(fill="#fafafa", color="none"),
+        panel_border=element_rect(color=RULE, fill=None, size=0.5),
+        plot_background=element_rect(fill=PAGE_BG, color=PAGE_BG),
+        panel_background=element_rect(fill=PAGE_BG, color=PAGE_BG),
     )
 )
 
+# Render, then drop into the underlying matplotlib Figure/Axes (a capability
+# unique to plotnine's matplotlib backend, unlike R ggplot2's grid graphics) to
+# draw a rounded-corner callout that fills the empty triangle beneath the data
+# and carries two data-backed insights instead of leaving that panel space bare.
+fig = plot.draw()
+ax = fig.axes[0]
+callout_box = FancyBboxPatch(
+    (3.6, 0.6),
+    9.6 - 3.6,
+    4.4 - 0.6,
+    transform=ax.transData,
+    boxstyle="round,pad=0,rounding_size=0.25",
+    facecolor=ELEVATED_BG,
+    edgecolor=RULE,
+    linewidth=1.0,
+    zorder=5,
+)
+ax.add_patch(callout_box)
+ax.text(
+    6.6,
+    3.3,
+    f"Month {compare_period} retention improved\n+{improvement:.0f}pp from Jan → Jun 2024",
+    transform=ax.transData,
+    ha="center",
+    va="center",
+    fontsize=9,
+    color=INK,
+    fontweight="bold",
+    zorder=6,
+)
+ax.text(
+    6.6,
+    1.7,
+    f"Each newer cohort trends ~+{cohort_trend_pp:.1f}pp per\nMonth vs. the prior cohort (onboarding gains)",
+    transform=ax.transData,
+    ha="center",
+    va="center",
+    fontsize=7.5,
+    color=INK_SOFT,
+    zorder=6,
+)
+
 # Save
-plot.save("plot.png", dpi=300, width=16, height=9)
+fig.savefig(f"plot-{THEME}.png", dpi=400)