feat(plotnine): implement timeseries-decomposition (#3033)

## Implementation: `timeseries-decomposition` - plotnine

Implements the **plotnine** version of `timeseries-decomposition`.

**File:** `plots/timeseries-decomposition/implementations/plotnine.py`

**Parent Issue:** #2992

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

---------

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/timeseries-decomposition/implementations/plotnine.py

@@ -0,0 +1,92 @@
+""" pyplots.ai
+timeseries-decomposition: Time Series Decomposition Plot
+Library: plotnine 0.15.2 | Python 3.13.11
+Quality: 91/100 | Created: 2025-12-31
+"""
+
+import numpy as np
+import pandas as pd
+from plotnine import (
+    aes,
+    element_blank,
+    element_line,
+    element_rect,
+    element_text,
+    facet_wrap,
+    geom_line,
+    ggplot,
+    labs,
+    scale_x_datetime,
+    theme,
+    theme_minimal,
+)
+from statsmodels.tsa.seasonal import seasonal_decompose
+
+
+# Data - Monthly airline passengers with trend and seasonality
+np.random.seed(42)
+n_months = 144  # 12 years of monthly data
+
+# Create date range
+dates = pd.date_range(start="2012-01-01", periods=n_months, freq="MS")
+
+# Generate synthetic airline passenger data with:
+# - Upward trend
+# - Strong yearly seasonality (peak in summer)
+# - Random noise
+t = np.arange(n_months)
+trend = 200 + t * 2.5  # Growing trend
+seasonal = 40 * np.sin(2 * np.pi * t / 12 - np.pi / 2)  # Peak in summer (month 7)
+residual = np.random.normal(0, 15, n_months)
+value = trend + seasonal + residual
+
+# Create DataFrame
+df = pd.DataFrame({"date": dates, "value": value})
+
+# Perform seasonal decomposition using statsmodels
+decomposition = seasonal_decompose(df["value"], model="additive", period=12)
+
+# Prepare data for plotnine with all components
+df_plot = pd.DataFrame(
+    {
+        "date": np.tile(dates, 4),
+        "value": np.concatenate(
+            [df["value"].values, decomposition.trend.values, decomposition.seasonal.values, decomposition.resid.values]
+        ),
+        "component": np.repeat(["Original", "Trend", "Seasonal", "Residual"], n_months),
+    }
+)
+
+# Remove NaN values (decomposition creates NaNs at edges)
+df_plot = df_plot.dropna()
+
+# Make component a categorical with correct order
+df_plot["component"] = pd.Categorical(
+    df_plot["component"], categories=["Original", "Trend", "Seasonal", "Residual"], ordered=True
+)
+
+# Create faceted plot with four components
+plot = (
+    ggplot(df_plot, aes(x="date", y="value"))
+    + geom_line(color="#306998", size=1.2)
+    + facet_wrap("~component", ncol=1, scales="free_y", dir="v")
+    + scale_x_datetime(date_labels="%Y", date_breaks="2 years")
+    + labs(title="timeseries-decomposition · plotnine · pyplots.ai", x="Date", y="Value")
+    + theme_minimal()
+    + theme(
+        figure_size=(16, 9),
+        plot_title=element_text(size=24, ha="center", weight="bold"),
+        axis_title_x=element_text(size=20, margin={"t": 15}),
+        axis_title_y=element_text(size=20, margin={"r": 15}),
+        axis_text_x=element_text(size=14),
+        axis_text_y=element_text(size=12),
+        strip_text=element_text(size=16, weight="bold"),
+        strip_background=element_rect(fill="#e8e8e8", color=None),
+        panel_spacing_y=0.08,
+        panel_grid_major=element_line(color="#dddddd", size=0.5, alpha=0.5),
+        panel_grid_minor=element_blank(),
+    )
+)
+
+# Save
+plot.save("plot.png", dpi=300, width=16, height=9)

plots/timeseries-decomposition/metadata/plotnine.yaml

@@ -0,0 +1,29 @@
+library: plotnine
+specification_id: timeseries-decomposition
+created: '2025-12-31T10:56:56Z'
+updated: '2025-12-31T11:15:24Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20617482775
+issue: 2992
+python_version: 3.13.11
+library_version: 0.15.2
+preview_url: https://storage.googleapis.com/pyplots-images/plots/timeseries-decomposition/plotnine/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/timeseries-decomposition/plotnine/plot_thumb.png
+preview_html: null
+quality_score: 91
+review:
+  strengths:
+  - Excellent use of plotnine facet_wrap for creating the four-panel decomposition
+    layout
+  - Clean implementation using statsmodels seasonal_decompose for proper time series
+    analysis
+  - Good color choice (#306998) that is accessible and professional
+  - Proper handling of NaN values from decomposition edges
+  - Correct categorical ordering of components using pd.Categorical
+  - Title follows the exact required format
+  - 12 years of monthly data provides meaningful decomposition
+  weaknesses:
+  - Y-axis tick labels in the Original panel appear slightly crowded with multiple
+    values stacked
+  - Panel spacing could be reduced to make better use of vertical canvas space
+  - Grid alpha at 0.5 could be more subtle (0.3 would be better)