feat(matplotlib): implement scatter-lag (#5270)

## Implementation: `scatter-lag` - matplotlib

Implements the **matplotlib** version of `scatter-lag`.

**File:** `plots/scatter-lag/implementations/matplotlib.py`

**Parent Issue:** #5251

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

---------

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/scatter-lag/implementations/matplotlib.py

@@ -0,0 +1,77 @@
+""" pyplots.ai
+scatter-lag: Lag Plot for Time Series Autocorrelation Diagnosis
+Library: matplotlib 3.10.8 | Python 3.14.3
+Quality: 85/100 | Created: 2026-04-12
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+# Data — synthetic AR(1) process with strong positive autocorrelation
+np.random.seed(42)
+n_observations = 500
+phi = 0.85
+noise = np.random.normal(0, 1, n_observations)
+series = np.zeros(n_observations)
+series[0] = noise[0]
+for i in range(1, n_observations):
+    series[i] = phi * series[i - 1] + noise[i]
+
+lag = 1
+y_t = series[:-lag]
+y_t_lag = series[lag:]
+time_index = np.arange(len(y_t))
+
+# Correlation
+r_value = np.corrcoef(y_t, y_t_lag)[0, 1]
+
+# Plot
+fig, ax = plt.subplots(figsize=(16, 9))
+
+scatter = ax.scatter(
+    y_t, y_t_lag, c=time_index, cmap="viridis", s=120, alpha=0.65, edgecolors="white", linewidth=0.5, zorder=2
+)
+
+# Diagonal reference line (y = x)
+data_min = min(y_t.min(), y_t_lag.min())
+data_max = max(y_t.max(), y_t_lag.max())
+margin = (data_max - data_min) * 0.05
+ax.plot(
+    [data_min - margin, data_max + margin],
+    [data_min - margin, data_max + margin],
+    color="#AAAAAA",
+    linewidth=2,
+    linestyle="--",
+    alpha=0.6,
+    zorder=1,
+)
+
+# Colorbar
+cbar = fig.colorbar(scatter, ax=ax, pad=0.02, aspect=30)
+cbar.set_label("Time Index", fontsize=18)
+cbar.ax.tick_params(labelsize=14)
+
+# Correlation annotation
+ax.text(
+    0.04,
+    0.96,
+    f"r = {r_value:.3f}",
+    transform=ax.transAxes,
+    fontsize=20,
+    verticalalignment="top",
+    fontweight="medium",
+    color="#333333",
+)
+
+# Style
+ax.set_xlabel("y(t)", fontsize=20)
+ax.set_ylabel(f"y(t + {lag})", fontsize=20)
+ax.set_title("AR(1) Autocorrelation · scatter-lag · matplotlib · pyplots.ai", fontsize=24, fontweight="medium")
+ax.tick_params(axis="both", labelsize=16)
+ax.spines["top"].set_visible(False)
+ax.spines["right"].set_visible(False)
+ax.grid(True, alpha=0.2, linewidth=0.8)
+
+plt.tight_layout()
+plt.savefig("plot.png", dpi=300, bbox_inches="tight")

plots/scatter-lag/metadata/matplotlib.yaml

@@ -0,0 +1,231 @@
+library: matplotlib
+specification_id: scatter-lag
+created: '2026-04-12T18:10:35Z'
+updated: '2026-04-12T18:25:18Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 24313009889
+issue: 5251
+python_version: 3.14.3
+library_version: 3.10.8
+preview_url: https://storage.googleapis.com/pyplots-images/plots/scatter-lag/matplotlib/plot.png
+preview_html: null
+quality_score: 85
+review:
+  strengths:
+  - 'Perfect code quality: clean KISS structure, seed set, correct API throughout'
+  - Temporal color encoding via viridis clearly reveals time structure in the scatter
+  - r=0.834 annotation with ax.transAxes relative positioning is well-executed
+  - 'All required spec features implemented: diagonal reference line, time-index color,
+    r-value annotation'
+  - Font sizes explicitly set at all levels for high-res output
+  weaknesses:
+  - Marker size s=120 too large for 499 data points causing dense overlap; reduce
+    to s=50-60, alpha=0.45-0.55
+  - Title format deviates from spec-id · library · pyplots.ai — has extra AR(1) Autocorrelation
+    prefix
+  - Full x+y gridlines instead of preferred y-axis-only grid
+  - Generic annotation box style; needs subtle white background bbox with no border
+    edge
+  image_description: The plot shows a scatter plot of an AR(1) time series against
+    its lag-1 version. The x-axis is labeled "y(t)" and the y-axis "y(t + 1)", with
+    values ranging roughly from -4.5 to 5.5 on both axes. Approximately 499 data points
+    are colored using the viridis colormap, transitioning from dark purple (time index
+    0) to bright yellow (time index ~499), with a colorbar on the right labeled "Time
+    Index". A dashed diagonal reference line (y = x) runs from lower-left to upper-right
+    in light gray. The data forms a strong linear cluster along the diagonal, visually
+    confirming high positive autocorrelation. An annotation in the upper-left corner
+    shows "r = 0.834" in bold. The title reads "AR(1) Autocorrelation · scatter-lag
+    · matplotlib · pyplots.ai". Top and right spines are removed; a subtle grid (alpha=0.2)
+    is visible. The overall layout is clean and professional on a light background
+    with a 16:9 aspect ratio.
+  criteria_checklist:
+    visual_quality:
+      score: 28
+      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, colorbar
+          label=18, colorbar ticks=14, annotation=20'
+      - id: VQ-02
+        name: No Overlap
+        score: 6
+        max: 6
+        passed: true
+        comment: No overlapping text or elements
+      - id: VQ-03
+        name: Element Visibility
+        score: 4
+        max: 6
+        passed: true
+        comment: s=120, alpha=0.65 for 499 points is too large per guideline (s=20-50
+          for 300+); visible crowding in dense center
+      - id: VQ-04
+        name: Color Accessibility
+        score: 4
+        max: 4
+        passed: true
+        comment: Viridis colormap is perceptually uniform and colorblind-safe
+      - id: VQ-05
+        name: Layout & Canvas
+        score: 4
+        max: 4
+        passed: true
+        comment: Good canvas utilization, balanced margins, colorbar well-positioned
+      - id: VQ-06
+        name: Axis Labels & Title
+        score: 2
+        max: 2
+        passed: true
+        comment: y(t) and y(t+1) are standard notation for lag plots; appropriate
+          and descriptive
+    design_excellence:
+      score: 12
+      max: 20
+      items:
+      - id: DE-01
+        name: Aesthetic Sophistication
+        score: 4
+        max: 8
+        passed: true
+        comment: Clean functional design; viridis and spine removal add polish but
+          overall is a well-configured library default
+      - id: DE-02
+        name: Visual Refinement
+        score: 4
+        max: 6
+        passed: true
+        comment: Spines removed, subtle grid (alpha=0.2), tight_layout; deducted for
+          full x+y grid instead of preferred y-axis-only
+      - id: DE-03
+        name: Data Storytelling
+        score: 4
+        max: 6
+        passed: true
+        comment: Temporal color encoding reveals time structure, r annotation quantifies
+          the pattern, diagonal line guides interpretation
+    spec_compliance:
+      score: 14
+      max: 15
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 5
+        max: 5
+        passed: true
+        comment: 'Correct lag plot: scatter of y(t) vs y(t+k)'
+      - id: SC-02
+        name: Required Features
+        score: 4
+        max: 4
+        passed: true
+        comment: Diagonal y=x reference line, time-index color encoding, r-value annotation,
+          configurable lag all present
+      - id: SC-03
+        name: Data Mapping
+        score: 3
+        max: 3
+        passed: true
+        comment: x=y(t), y=y(t+1), correct per spec
+      - id: SC-04
+        name: Title & Legend
+        score: 2
+        max: 3
+        passed: false
+        comment: Title has extra 'AR(1) Autocorrelation · ' prefix before spec-id;
+          should start with scatter-lag · matplotlib · pyplots.ai
+    data_quality:
+      score: 14
+      max: 15
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 5
+        max: 6
+        passed: true
+        comment: Strong autocorrelation case clearly demonstrated; missing contrast
+          with random/uncorrelated case which spec explicitly describes
+      - id: DQ-02
+        name: Realistic Context
+        score: 5
+        max: 5
+        passed: true
+        comment: AR(1) synthetic process is explicitly listed in spec; neutral and
+          scientifically appropriate
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 4
+        passed: true
+        comment: Values -4.5 to 5.5 are realistic for zero-mean AR(1) with Gaussian
+          noise std=1
+    code_quality:
+      score: 10
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: Imports → Data → Plot → Save, 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: Only matplotlib.pyplot and numpy, both used
+      - id: CQ-04
+        name: Code Elegance
+        score: 2
+        max: 2
+        passed: true
+        comment: Clean, Pythonic, appropriate complexity for AR(1) generation
+      - id: CQ-05
+        name: Output & API
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves as plot.png, dpi=300, bbox_inches='tight', no deprecated functions
+    library_mastery:
+      score: 7
+      max: 10
+      items:
+      - id: LM-01
+        name: Idiomatic Usage
+        score: 4
+        max: 5
+        passed: true
+        comment: Uses ax.scatter with c= colormap, fig.colorbar(), ax methods throughout;
+          correct but no advanced matplotlib patterns
+      - id: LM-02
+        name: Distinctive Features
+        score: 3
+        max: 5
+        passed: true
+        comment: c= parameter with colormap + colorbar on scatter is distinctive matplotlib;
+          ax.transAxes for relative text placement is a nice touch
+  verdict: REJECTED
+impl_tags:
+  dependencies: []
+  techniques:
+  - annotations
+  - colorbar
+  patterns:
+  - data-generation
+  - explicit-figure
+  dataprep: []
+  styling:
+  - alpha-blending
+  - custom-colormap
+  - edge-highlighting
+  - grid-styling