feat(matplotlib): implement line-retention-cohort (#4927)

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

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

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

**Parent Issue:** #4572

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

---------

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

Author: github-actions[bot]

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

@@ -0,0 +1,98 @@
+""" pyplots.ai
+line-retention-cohort: User Retention Curve by Cohort
+Library: matplotlib 3.10.8 | Python 3.14.3
+Quality: 91/100 | Created: 2026-03-16
+"""
+
+import matplotlib.patheffects as pe
+import matplotlib.pyplot as plt
+import matplotlib.ticker as mticker
+import numpy as np
+
+
+# Data
+np.random.seed(42)
+
+cohorts = {
+    "Jan 2025": {"size": 1245, "base_rate": 0.82, "plateau": 8},
+    "Feb 2025": {"size": 1102, "base_rate": 0.80, "plateau": 12},
+    "Mar 2025": {"size": 1380, "base_rate": 0.78, "plateau": 15},
+    "Apr 2025": {"size": 1510, "base_rate": 0.85, "plateau": 22},
+    "May 2025": {"size": 1423, "base_rate": 0.88, "plateau": 30},
+}
+
+weeks = np.arange(0, 13)
+
+retention_data = {}
+for cohort, info in cohorts.items():
+    retention = [100.0]
+    for week in weeks[1:]:
+        decay = info["base_rate"] ** week * 100
+        plateau = info["plateau"]
+        value = max(decay, plateau) + np.random.normal(0, 1.0)
+        value = max(value, plateau - 2)
+        retention.append(round(value, 1))
+    retention_data[cohort] = retention
+
+# Plot
+fig, ax = plt.subplots(figsize=(16, 9))
+
+colors = ["#4e79a7", "#a0cbe8", "#306998", "#59a14f", "#1a6b4a"]
+linewidths = [2.0, 2.2, 2.5, 2.8, 3.2]
+alphas = [0.6, 0.65, 0.75, 0.88, 1.0]
+marker_sizes = [5, 5.5, 6, 6.5, 7]
+
+for i, (cohort, retention) in enumerate(retention_data.items()):
+    size = cohorts[cohort]["size"]
+    label = f"{cohort} (n={size:,})"
+    ax.plot(
+        weeks,
+        retention,
+        color=colors[i],
+        linewidth=linewidths[i],
+        alpha=alphas[i],
+        marker="o",
+        markersize=marker_sizes[i],
+        markeredgecolor="white",
+        markeredgewidth=0.8,
+        label=label,
+        zorder=2 + i,
+        path_effects=[pe.Stroke(linewidth=linewidths[i] + 1.5, foreground="white"), pe.Normal()],
+    )
+
+# Reference line
+ax.axhline(y=20, color="#aaaaaa", linestyle="--", linewidth=1.2, alpha=0.7, zorder=1)
+ax.annotate(
+    "20% retention target",
+    xy=(12, 20),
+    xytext=(10.5, 24),
+    fontsize=13,
+    color="#888888",
+    fontstyle="italic",
+    arrowprops={"arrowstyle": "-", "color": "#aaaaaa", "lw": 0.8},
+)
+
+# Y-axis percentage formatter
+ax.yaxis.set_major_formatter(mticker.FuncFormatter(lambda x, _: f"{int(x)}%"))
+
+# Style
+ax.set_xlabel("Weeks Since Signup", fontsize=20)
+ax.set_ylabel("Retained Users", fontsize=20)
+ax.set_title("line-retention-cohort · matplotlib · pyplots.ai", fontsize=24, fontweight="medium", pad=16)
+ax.tick_params(axis="both", labelsize=16)
+
+ax.set_xlim(-0.3, 12.5)
+ax.set_ylim(0, 105)
+ax.set_xticks(weeks)
+ax.set_yticks([0, 20, 40, 60, 80, 100])
+
+ax.spines["top"].set_visible(False)
+ax.spines["right"].set_visible(False)
+ax.spines["left"].set_color("#cccccc")
+ax.spines["bottom"].set_color("#cccccc")
+ax.yaxis.grid(True, alpha=0.15, linewidth=0.8, color="#888888")
+
+ax.legend(fontsize=16, loc="upper right", framealpha=0.92, edgecolor="#dddddd", fancybox=False)
+
+plt.tight_layout()
+plt.savefig("plot.png", dpi=300, bbox_inches="tight")

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

@@ -0,0 +1,221 @@
+library: matplotlib
+specification_id: line-retention-cohort
+created: '2026-03-16T20:43:57Z'
+updated: '2026-03-16T20:54:59Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 23164943198
+issue: 4572
+python_version: 3.14.3
+library_version: 3.10.8
+preview_url: https://storage.googleapis.com/pyplots-images/plots/line-retention-cohort/matplotlib/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/line-retention-cohort/matplotlib/plot_thumb.png
+preview_html: null
+quality_score: 91
+review:
+  strengths:
+  - Excellent visual hierarchy with graduated line width, opacity, and color from
+    older to newer cohorts
+  - Path effects (white stroke) elegantly separate overlapping curves — distinctive
+    matplotlib technique
+  - Complete spec compliance with all required features including reference line,
+    cohort sizes, opacity variation
+  - Realistic, well-calibrated data with meaningful variation across cohorts
+  weaknesses:
+  - The three blue shades (Jan/Feb/Mar) are somewhat close in hue; wider separation
+    would improve distinguishability
+  image_description: The plot displays 5 user retention curves (Jan–May 2025 cohorts)
+    on a 16:9 canvas. Colors transition from light blue (Jan 2025) through medium
+    blue (Feb, Mar) to green shades (Apr, May), with line width and opacity increasing
+    for newer cohorts. All curves start at 100% at week 0 and exhibit exponential
+    decay. A dashed gray horizontal reference line at 20% is labeled "20% retention
+    target" in italic. The Y-axis shows percentages from 0% to 100% with gridlines;
+    the X-axis shows weeks 0–12. The legend in the upper right lists each cohort with
+    sample size (e.g., "Jan 2025 (n=1,245)"). Top and right spines are removed; left/bottom
+    spines are subtle gray. White stroke path effects separate overlapping lines.
+    Newer cohorts (Apr, May) clearly retain better, plateauing around 20–30%, while
+    older cohorts (Jan, Feb) drop below 15%.
+  criteria_checklist:
+    visual_quality:
+      score: 29
+      max: 30
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 8
+        max: 8
+        passed: true
+        comment: 'All font sizes explicitly set: title=24, labels=20, ticks=16, legend=16,
+          annotation=13'
+      - id: VQ-02
+        name: No Overlap
+        score: 6
+        max: 6
+        passed: true
+        comment: No text collisions; legend positioned clear of data
+      - id: VQ-03
+        name: Element Visibility
+        score: 6
+        max: 6
+        passed: true
+        comment: Lines well-sized with markers and path effects for separation
+      - id: VQ-04
+        name: Color Accessibility
+        score: 3
+        max: 4
+        passed: true
+        comment: Blue-to-green gradient is colorblind-safe but three blue shades are
+          somewhat close
+      - id: VQ-05
+        name: Layout & Canvas
+        score: 4
+        max: 4
+        passed: true
+        comment: 16:9 figsize with tight_layout, good canvas utilization
+      - id: VQ-06
+        name: Axis Labels & Title
+        score: 2
+        max: 2
+        passed: true
+        comment: Descriptive labels with % formatter on Y-axis
+    design_excellence:
+      score: 15
+      max: 20
+      items:
+      - id: DE-01
+        name: Aesthetic Sophistication
+        score: 6
+        max: 8
+        passed: true
+        comment: Cohesive blue-to-green palette, path effects, graduated opacity/width
+          — above defaults
+      - id: DE-02
+        name: Visual Refinement
+        score: 5
+        max: 6
+        passed: true
+        comment: Spines removed, subtle grid, generous whitespace, polished details
+      - id: DE-03
+        name: Data Storytelling
+        score: 4
+        max: 6
+        passed: true
+        comment: Visual hierarchy through line weight/opacity emphasizes newer cohorts;
+          20% target provides context
+    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 retention curves
+      - id: SC-02
+        name: Required Features
+        score: 4
+        max: 4
+        passed: true
+        comment: 'All spec features present: 100% start, distinct colors, legend with
+          sizes, reference line, opacity variation'
+      - 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: Correct title format and legend labels with cohort sizes
+    data_quality:
+      score: 15
+      max: 15
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 6
+        max: 6
+        passed: true
+        comment: 5 cohorts with distinct decay rates and plateau levels showing improvement
+          trend
+      - id: DQ-02
+        name: Realistic Context
+        score: 5
+        max: 5
+        passed: true
+        comment: Monthly SaaS signup cohorts — realistic, neutral business analytics
+          scenario
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 4
+        passed: true
+        comment: Cohort sizes 1100-1510, retention 8-100% over 12 weeks — plausible
+          values
+    code_quality:
+      score: 10
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: 'Linear flow: imports, data, plot, style, save'
+      - 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 used
+      - id: CQ-04
+        name: Code Elegance
+        score: 2
+        max: 2
+        passed: true
+        comment: Clean parallel lists for per-cohort styling, appropriate complexity
+      - id: CQ-05
+        name: Output & API
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves plot.png with dpi=300
+    library_mastery:
+      score: 7
+      max: 10
+      items:
+      - id: LM-01
+        name: Idiomatic Usage
+        score: 4
+        max: 5
+        passed: true
+        comment: Proper Axes methods, FuncFormatter, path_effects, spine control
+      - id: LM-02
+        name: Distinctive Features
+        score: 3
+        max: 5
+        passed: true
+        comment: path_effects with Stroke+Normal for white halo is matplotlib-specific
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - annotations
+  - manual-ticks
+  patterns:
+  - data-generation
+  - iteration-over-groups
+  dataprep: []
+  styling:
+  - alpha-blending
+  - edge-highlighting
+  - grid-styling