feat(plotnine): implement line-retention-cohort (#4932)

## Implementation: `line-retention-cohort` - plotnine

Implements the **plotnine** version of `line-retention-cohort`.

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

**Parent Issue:** #4572

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

---------

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/line-retention-cohort/implementations/plotnine.py

@@ -0,0 +1,155 @@
+""" pyplots.ai
+line-retention-cohort: User Retention Curve by Cohort
+Library: plotnine 0.15.3 | Python 3.14.3
+Quality: 91/100 | Created: 2026-03-16
+"""
+
+import numpy as np
+import pandas as pd
+from plotnine import (
+    aes,
+    annotate,
+    element_blank,
+    element_line,
+    element_rect,
+    element_text,
+    geom_hline,
+    geom_line,
+    geom_point,
+    geom_ribbon,
+    geom_text,
+    ggplot,
+    guide_legend,
+    guides,
+    labs,
+    scale_alpha_identity,
+    scale_color_manual,
+    scale_size_identity,
+    scale_x_continuous,
+    scale_y_continuous,
+    theme,
+    theme_minimal,
+)
+
+
+# Data
+np.random.seed(42)
+
+cohorts = {
+    "Jan 2025": {"size": 1245, "decay": 0.22, "plateau": 8},
+    "Feb 2025": {"size": 1102, "decay": 0.17, "plateau": 12},
+    "Mar 2025": {"size": 1380, "decay": 0.13, "plateau": 18},
+    "Apr 2025": {"size": 1290, "decay": 0.11, "plateau": 22},
+    "May 2025": {"size": 1455, "decay": 0.08, "plateau": 30},
+}
+
+weeks = np.arange(0, 13)
+rows = []
+
+for cohort_name, info in cohorts.items():
+    base = (100 - info["plateau"]) * np.exp(-info["decay"] * weeks) + info["plateau"]
+    noise = np.concatenate(([0], np.cumsum(np.random.normal(0, 0.6, len(weeks) - 1))))
+    retention = np.clip(base + noise, 0, 100)
+    retention[0] = 100.0
+    label = f"{cohort_name} (n={info['size']:,})"
+    for w, r in zip(weeks, retention, strict=True):
+        rows.append({"week": w, "retention": r, "cohort": label})
+
+df = pd.DataFrame(rows)
+
+cohort_labels = list(df["cohort"].unique())
+df["cohort"] = pd.Categorical(df["cohort"], categories=cohort_labels, ordered=True)
+
+# Alpha: ensure oldest is still readable
+alpha_values = [0.6, 0.7, 0.8, 0.9, 1.0]
+alpha_map = dict(zip(cohort_labels, alpha_values, strict=True))
+df["line_alpha"] = df["cohort"].map(alpha_map).astype(float)
+
+# Line width: thinner for older, bolder for newer
+size_values = [1.0, 1.2, 1.4, 1.6, 2.0]
+size_map = dict(zip(cohort_labels, size_values, strict=True))
+df["line_size"] = df["cohort"].map(size_map).astype(float)
+
+# Ribbon data: show spread between oldest and newest cohort
+oldest_label = cohort_labels[0]
+newest_label = cohort_labels[-1]
+df_oldest = df[df["cohort"] == oldest_label][["week", "retention"]].rename(columns={"retention": "ymin"})
+df_newest = df[df["cohort"] == newest_label][["week", "retention"]].rename(columns={"retention": "ymax"})
+df_ribbon = df_oldest.merge(df_newest, on="week")
+
+# Colors: refined palette with clear progression
+colors = ["#94B8D1", "#6A9EC1", "#306998", "#E07941", "#C94420"]
+
+# Endpoint labels for storytelling
+df_endpoints = df[df["week"] == 12].copy()
+df_endpoints["ret_label"] = df_endpoints["retention"].apply(lambda x: f"{x:.0f}%")
+
+# Plot
+plot = (
+    ggplot(df, aes(x="week", y="retention", color="cohort", group="cohort"))
+    + geom_ribbon(
+        aes(x="week", ymin="ymin", ymax="ymax"), data=df_ribbon, inherit_aes=False, fill="#306998", alpha=0.07
+    )
+    + geom_hline(yintercept=20, linetype="dashed", color="#AAAAAA", size=0.7)
+    + geom_line(aes(alpha="line_alpha", size="line_size"))
+    + scale_alpha_identity()
+    + scale_size_identity()
+    + geom_point(aes(alpha="line_alpha"), size=2.5, show_legend=False)
+    + geom_text(aes(label="ret_label"), data=df_endpoints, nudge_x=0.5, size=10, ha="left", show_legend=False)
+    + scale_color_manual(values=colors)
+    + scale_x_continuous(breaks=range(0, 13), labels=[str(w) for w in range(0, 13)], expand=(0.02, 0.8))
+    + scale_y_continuous(
+        limits=(0, 108), breaks=[0, 20, 40, 60, 80, 100], labels=["0%", "20%", "40%", "60%", "80%", "100%"]
+    )
+    + annotate(
+        "text",
+        x=11.8,
+        y=22.5,
+        label="20% retention threshold",
+        size=11,
+        color="#888888",
+        ha="right",
+        fontstyle="italic",
+    )
+    + annotate(
+        "label",
+        x=6,
+        y=55,
+        label="Improvement\ngap",
+        size=10,
+        color="#306998",
+        fill="#F0F4F8",
+        alpha=0.85,
+        ha="center",
+        label_size=0,
+    )
+    + labs(
+        x="Weeks Since Signup",
+        y="Retained Users",
+        color="Cohort",
+        title="line-retention-cohort · plotnine · pyplots.ai",
+    )
+    + guides(color=guide_legend(override_aes={"size": 3, "alpha": 1}))
+    + theme_minimal()
+    + theme(
+        figure_size=(16, 9),
+        text=element_text(family="sans-serif", size=14, color="#333333"),
+        plot_title=element_text(size=24, weight="bold", color="#1a1a1a"),
+        axis_title=element_text(size=20, color="#444444"),
+        axis_text=element_text(size=16, color="#555555"),
+        legend_title=element_text(size=18, weight="bold"),
+        legend_text=element_text(size=14),
+        legend_position="right",
+        legend_background=element_rect(fill="#FAFAFA", color="#E0E0E0", size=0.5),
+        legend_key=element_rect(fill="none", color="none"),
+        panel_grid_major_x=element_blank(),
+        panel_grid_minor=element_blank(),
+        panel_grid_major_y=element_line(color="#EBEBEB", size=0.4, alpha=0.6),
+        axis_line_x=element_line(color="#333333", size=0.5),
+        axis_line_y=element_line(color="#333333", size=0.5),
+        plot_margin=0.04,
+    )
+)
+
+# Save
+plot.save("plot.png", dpi=300, verbose=False)

plots/line-retention-cohort/metadata/plotnine.yaml

@@ -0,0 +1,226 @@
+library: plotnine
+specification_id: line-retention-cohort
+created: '2026-03-16T20:44:50Z'
+updated: '2026-03-16T20:57:58Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 23164943107
+issue: 4572
+python_version: 3.14.3
+library_version: 0.15.3
+preview_url: https://storage.googleapis.com/pyplots-images/plots/line-retention-cohort/plotnine/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/line-retention-cohort/plotnine/plot_thumb.png
+preview_html: null
+quality_score: 91
+review:
+  strengths:
+  - Excellent data storytelling with improvement gap ribbon, endpoint labels, and
+    20% threshold annotation
+  - Graduated alpha and line width effectively emphasize recent cohorts
+  - Custom color palette with intentional blue-to-orange progression
+  - All spec requirements fully implemented including cohort sizes in legend
+  - Expert use of plotnine grammar of graphics with identity scales
+  weaknesses:
+  - Minor overlap of endpoint labels (17% and 19%) for the two oldest cohorts at week
+    12
+  - Three blue shades for Jan/Feb/Mar cohorts could be more distinct
+  image_description: The plot displays 5 user retention curves for monthly signup
+    cohorts (Jan–May 2025), each starting at 100% and decaying over 12 weeks. Colors
+    progress from light steel blue (oldest cohort, Jan) through medium blue (Mar)
+    to dark burnt orange/red (newest, May). Lines use graduated alpha (0.6–1.0) and
+    thickness (1.0–2.0pt) to visually emphasize recent cohorts. A subtle blue-shaded
+    ribbon spans the area between the oldest and newest cohort curves, labeled "Improvement
+    gap" in a boxed annotation. A horizontal dashed gray line marks the 20% retention
+    threshold with an italic annotation. Endpoint percentage labels appear at week
+    12 for each cohort (17%, 19%, 34%, 40%, 57%). The legend on the right shows cohort
+    labels with sample sizes (e.g., "Jan 2025 (n=1,245)") inside a light gray box
+    with border. Title reads "line-retention-cohort · plotnine · pyplots.ai" in bold.
+    Y-axis labeled "Retained Users" with percentage gridlines; X-axis labeled "Weeks
+    Since Signup" with integer ticks 0–12.
+  criteria_checklist:
+    visual_quality:
+      score: 26
+      max: 30
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 8
+        max: 8
+        passed: true
+        comment: 'All font sizes explicitly set: title=24, axis_title=20, axis_text=16,
+          legend_title=18, legend_text=14'
+      - id: VQ-02
+        name: No Overlap
+        score: 4
+        max: 6
+        passed: true
+        comment: Minor overlap of 19% and 17% endpoint labels at week 12
+      - id: VQ-03
+        name: Element Visibility
+        score: 6
+        max: 6
+        passed: true
+        comment: Lines and points well-sized with graduated thickness and alpha
+      - id: VQ-04
+        name: Color Accessibility
+        score: 3
+        max: 4
+        passed: true
+        comment: Blue-to-orange progression generally colorblind-safe, three blue
+          shades could be more distinct
+      - id: VQ-05
+        name: Layout & Canvas
+        score: 3
+        max: 4
+        passed: true
+        comment: Good layout, slight crowding on right side near legend
+      - id: VQ-06
+        name: Axis Labels & Title
+        score: 2
+        max: 2
+        passed: true
+        comment: 'Descriptive labels: Weeks Since Signup, Retained Users'
+    design_excellence:
+      score: 16
+      max: 20
+      items:
+      - id: DE-01
+        name: Aesthetic Sophistication
+        score: 6
+        max: 8
+        passed: true
+        comment: Custom palette with color progression, refined typography, graduated
+          alpha/size for emphasis
+      - id: DE-02
+        name: Visual Refinement
+        score: 5
+        max: 6
+        passed: true
+        comment: X-grid removed, Y-grid subtle, legend styled, generous whitespace
+      - id: DE-03
+        name: Data Storytelling
+        score: 5
+        max: 6
+        passed: true
+        comment: Improvement gap ribbon, endpoint labels, threshold line, alpha/size
+          graduation create clear narrative
+    spec_compliance:
+      score: 15
+      max: 15
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 5
+        max: 5
+        passed: true
+        comment: Correct line chart with multiple cohort retention curves
+      - id: SC-02
+        name: Required Features
+        score: 4
+        max: 4
+        passed: true
+        comment: 'All spec features implemented: 100% start, distinct colors, legend
+          with sizes, gridlines, threshold line, emphasis'
+      - id: SC-03
+        name: Data Mapping
+        score: 3
+        max: 3
+        passed: true
+        comment: X=weeks since signup, Y=retention percentage, correctly mapped
+      - id: SC-04
+        name: Title & Legend
+        score: 3
+        max: 3
+        passed: true
+        comment: Title follows exact format, legend labels show cohort name with sample
+          size
+    data_quality:
+      score: 15
+      max: 15
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 6
+        max: 6
+        passed: true
+        comment: 5 cohorts with different decay rates, plateau levels, and sizes showing
+          clear progression
+      - id: DQ-02
+        name: Realistic Context
+        score: 5
+        max: 5
+        passed: true
+        comment: Real-world product analytics with monthly cohorts and plausible user
+          counts
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 4
+        passed: true
+        comment: Realistic exponential decay with sensible plateau levels and cohort
+          sizes
+    code_quality:
+      score: 10
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: Clean imports-data-plot-save flow, no functions or classes
+      - id: CQ-02
+        name: Reproducibility
+        score: 2
+        max: 2
+        passed: true
+        comment: np.random.seed(42) set
+      - id: CQ-03
+        name: Clean Imports
+        score: 2
+        max: 2
+        passed: true
+        comment: All imports are used
+      - id: CQ-04
+        name: Code Elegance
+        score: 2
+        max: 2
+        passed: true
+        comment: Well-organized with appropriate complexity
+      - id: CQ-05
+        name: Output & API
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves as plot.png with dpi=300, current API
+    library_mastery:
+      score: 9
+      max: 10
+      items:
+      - id: LM-01
+        name: Idiomatic Usage
+        score: 5
+        max: 5
+        passed: true
+        comment: Expert grammar of graphics usage with layered geoms, identity scales,
+          guide overrides
+      - id: LM-02
+        name: Distinctive Features
+        score: 4
+        max: 5
+        passed: true
+        comment: scale_*_identity with data-mapped columns, annotate label, geom_ribbon,
+          guide_legend override_aes
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - annotations
+  - layer-composition
+  - custom-legend
+  patterns:
+  - data-generation
+  - iteration-over-groups
+  dataprep: []
+  styling:
+  - alpha-blending
+  - grid-styling