feat(matplotlib): implement line-annotated-events (#3020)

## Implementation: `line-annotated-events` - matplotlib

Implements the **matplotlib** version of `line-annotated-events`.

**File:** `plots/line-annotated-events/implementations/matplotlib.py`

**Parent Issue:** #2997

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

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/line-annotated-events/implementations/matplotlib.py

@@ -0,0 +1,71 @@
+""" pyplots.ai
+line-annotated-events: Annotated Line Plot with Event Markers
+Library: matplotlib 3.10.8 | Python 3.13.11
+Quality: 91/100 | Created: 2025-12-31
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+
+# Data
+np.random.seed(42)
+dates = pd.date_range("2024-01-01", periods=365, freq="D")
+# Generate realistic stock-like price data with trend and volatility
+base_price = 150
+returns = np.random.randn(365) * 0.015  # Daily returns ~1.5% std
+prices = base_price * np.cumprod(1 + returns)
+
+# Event dates and labels (quarterly earnings + major announcements)
+events = [
+    (pd.Timestamp("2024-02-15"), "Q4 2023\nEarnings"),
+    (pd.Timestamp("2024-05-10"), "Q1 2024\nEarnings"),
+    (pd.Timestamp("2024-07-22"), "Product\nLaunch"),
+    (pd.Timestamp("2024-08-08"), "Q2 2024\nEarnings"),
+    (pd.Timestamp("2024-11-14"), "Q3 2024\nEarnings"),
+]
+
+# Plot
+fig, ax = plt.subplots(figsize=(16, 9))
+
+# Main line
+ax.plot(dates, prices, linewidth=2.5, color="#306998", label="Stock Price", zorder=2)
+
+# Event markers with alternating heights
+event_colors = "#FFD43B"
+heights = [0.85, 0.70, 0.85, 0.70, 0.85]  # Alternating heights to avoid overlap
+
+for i, (event_date, event_label) in enumerate(events):
+    # Vertical line
+    ax.axvline(x=event_date, color=event_colors, linestyle="--", linewidth=2, alpha=0.8, zorder=1)
+    # Text annotation with alternating heights
+    y_pos = ax.get_ylim()[0] + (ax.get_ylim()[1] - ax.get_ylim()[0]) * heights[i]
+    ax.annotate(
+        event_label,
+        xy=(event_date, prices[dates.get_loc(event_date)]),
+        xytext=(event_date, y_pos),
+        fontsize=14,
+        ha="center",
+        va="bottom",
+        color="#333333",
+        bbox={"boxstyle": "round,pad=0.3", "facecolor": "white", "edgecolor": "#FFD43B", "alpha": 0.9},
+        arrowprops={"arrowstyle": "->", "color": "#FFD43B", "lw": 1.5},
+    )
+
+# Add event marker to legend
+ax.axvline(x=dates[0], color=event_colors, linestyle="--", linewidth=2, alpha=0, label="Event Marker")
+
+# Styling
+ax.set_xlabel("Date", fontsize=20)
+ax.set_ylabel("Price (USD)", fontsize=20)
+ax.set_title("line-annotated-events · matplotlib · pyplots.ai", fontsize=24)
+ax.tick_params(axis="both", labelsize=16)
+ax.grid(True, alpha=0.3, linestyle="--")
+ax.legend(fontsize=16, loc="upper left")
+
+# Format x-axis for better date readability
+fig.autofmt_xdate(rotation=30)
+
+plt.tight_layout()
+plt.savefig("plot.png", dpi=300, bbox_inches="tight")

plots/line-annotated-events/metadata/matplotlib.yaml

@@ -0,0 +1,26 @@
+library: matplotlib
+specification_id: line-annotated-events
+created: '2025-12-31T10:55:32Z'
+updated: '2025-12-31T11:04:51Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20617489492
+issue: 2997
+python_version: 3.13.11
+library_version: 3.10.8
+preview_url: https://storage.googleapis.com/pyplots-images/plots/line-annotated-events/matplotlib/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/line-annotated-events/matplotlib/plot_thumb.png
+preview_html: null
+quality_score: 91
+review:
+  strengths:
+  - Excellent implementation of the spec with clear event annotations using axvline
+    and annotate
+  - Smart use of alternating heights to prevent annotation overlap
+  - Professional styling with white background boxes and arrow connections
+  - Realistic stock price data with quarterly earnings context
+  - Clean KISS code structure with proper seed for reproducibility
+  weaknesses:
+  - Legend entry for Event Marker uses alpha=0 trick which creates an invisible line
+    in the legend - consider using a Line2D proxy artist instead
+  - Could utilize more distinctive matplotlib features like ConnectionPatch for arrows
+    or custom box styles