feat(plotnine): implement timeseries-decomposition

[github-actions]

Implementation: timeseries-decomposition - plotnine

Implements the plotnine version of timeseries-decomposition.

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

Parent Issue: #2992

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a time series decomposition with four vertically stacked panels using facet_wrap. The main title "timeseries-decomposition · plotnine · pyplots.ai" appears at the top in bold. All four panels share the same x-axis showing dates from 2012 to 2024. The color used is a blue (#306998) for all lines. Panel "1. Original" shows the raw data with upward trend and seasonal oscillation, ranging from ~200 to ~600. Panel "2. Trend" shows a smooth upward linear trend from ~250 to ~500. Panel "3. Seasonal" shows a regular sinusoidal pattern oscillating between approximately -25 and +25. Panel "4. Residual" shows random noise centered around zero. Each panel has a light gray strip header with bold labels. The y-axis is shared and labeled "Value", x-axis labeled "Date". Grid lines are subtle. The y-axis tick labels in the Original and Trend panels appear compressed/overlapping.

Quality Score: 78/100

Criteria Checklist

Visual Quality (30/40 pts)

• VQ-01: Text Legibility (7/10) - Title and axis labels are readable, but y-axis tick labels in some panels (especially Original and Residual) are severely overlapping/compressed
• VQ-02: No Overlap (4/8) - Y-axis tick labels overlap significantly in the Original panel (600, 550, 500, 450, 400...) and Residual panel (20, 10, 0, -10, -20...)
• VQ-03: Element Visibility (8/8) - Lines are clearly visible with appropriate thickness (size=1.2)
• VQ-04: Color Accessibility (5/5) - Single blue color, no colorblind issues
• VQ-05: Layout Balance (4/5) - Good use of canvas, though panels are somewhat compressed vertically with large whitespace between them
• VQ-06: Axis Labels (2/2) - Descriptive labels "Date" and "Value" present
• VQ-07: Grid & Legend (0/2) - Grid is subtle, but panel spacing creates visual gaps; no legend needed

Spec Compliance (23/25 pts)

• SC-01: Plot Type (8/8) - Correct time series decomposition with 4 stacked subplots
• SC-02: Data Mapping (5/5) - X (date) and Y (value) correctly mapped
• SC-03: Required Features (4/5) - All 4 components shown (Original, Trend, Seasonal, Residual), uses statsmodels seasonal_decompose. Component labels include numbers which is unnecessary.
• SC-04: Data Range (3/3) - All data visible, scales="free_y" properly used
• SC-05: Legend Accuracy (2/2) - No legend needed, facet labels are accurate
• SC-06: Title Format (1/2) - Uses correct format but panel labels have unnecessary "1. 2. 3. 4." prefix

Data Quality (18/20 pts)

• DQ-01: Feature Coverage (7/8) - Shows trend, seasonality, and residual well; 12 years of monthly data demonstrates patterns clearly
• DQ-02: Realistic Context (7/7) - Airline passenger data is a classic, neutral time series example
• DQ-03: Appropriate Scale (4/5) - Values are reasonable for passenger counts (200-600 range)

Code Quality (10/10 pts)

• CQ-01: KISS Structure (3/3) - Clean linear flow: imports → data → decomposition → plot → save
• CQ-02: Reproducibility (3/3) - Uses np.random.seed(42)
• CQ-03: Clean Imports (2/2) - All imports are used
• CQ-04: No Deprecated API (1/1) - Current plotnine API
• CQ-05: Output Correct (1/1) - Saves as plot.png

Library Features (4/5 pts)

• LF-01: Uses distinctive library features (4/5) - Good use of plotnine's ggplot grammar: facet_wrap with free_y scales, theme_minimal, proper theming with element_text/element_line/element_rect

Strengths

• Excellent use of statsmodels seasonal_decompose for proper time series decomposition
• Clean, readable code following KISS principles with appropriate random seed
• Good application of plotnine's grammar of graphics with facet_wrap for stacked panels
• Proper theme customization with readable font sizes and subtle grid lines
• Realistic airline passenger scenario with 12 years of monthly data showing clear patterns

Weaknesses

• Y-axis tick labels are severely overlapping/compressed in the Original and Residual panels, making values hard to read
• Excessive vertical whitespace between panels due to panel_spacing_y combined with the facet layout
• Unnecessary numbering prefix ("1. ", "2. ", etc.) in component labels adds visual clutter

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/3

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

The plot displays a time series decomposition with four vertically stacked faceted panels on a 16:9 landscape layout. The main title "timeseries-decomposition · plotnine · pyplots.ai" appears at the top in bold black text. Each panel has a gray strip header showing the component name with numbering: "1. Original", "2. Trend", "3. Seasonal", and "4. Residual". All panels use a consistent blue (#306998) line color. The x-axis shows dates from 2012 to 2024 with 2-year intervals, and a shared "Date" label appears at the bottom. A shared "Value" label appears on the left y-axis. The Original panel shows time series data ranging from ~200 to ~600 with clear upward trend and seasonal oscillation. The Trend panel shows a smooth increasing line from ~260 to ~540. The Seasonal panel shows a repeating sinusoidal pattern oscillating between approximately -25 and +25. The Residual panel shows random noise fluctuating roughly between -30 and +30. Light gray grid lines are visible in all panels. The background is minimal/white with subtle gray panel backgrounds.

Quality Score: 91/100

Criteria Checklist

Visual Quality (36/40 pts)

• VQ-01: Text Legibility (9/10) - Title is clear at 24pt, axis labels at 20pt, strip text at 16pt bold. Y-axis tick labels in the first panel are slightly compressed/overlapping due to many values.
• VQ-02: No Overlap (8/8) - No overlapping text elements; strip headers, axis labels, and tick marks are all clearly separated.
• VQ-03: Element Visibility (8/8) - Line width of 1.2 is well-suited for the data density; all four time series are clearly visible.
• VQ-04: Color Accessibility (5/5) - Single blue color (#306998) with good contrast against white background; no colorblind concerns.
• VQ-05: Layout Balance (4/5) - Good use of canvas space with four panels; however, the panels are quite short vertically leaving significant white space between them.
• VQ-06: Axis Labels (2/2) - "Date" and "Value" are descriptive axis labels.
• VQ-07: Grid & Legend (0/2) - Grid is subtle at alpha 0.5, but no legend is needed for this single-series plot. However, the grid could be slightly more subtle.

Spec Compliance (25/25 pts)

• SC-01: Plot Type (8/8) - Correct time series decomposition with four stacked subplots.
• SC-02: Data Mapping (5/5) - Date on X-axis, values on Y-axis with free_y scales for each component.
• SC-03: Required Features (5/5) - All four components present: Original, Trend, Seasonal, Residual with clear labels.
• SC-04: Data Range (3/3) - All data is visible within axes ranges.
• SC-05: Legend Accuracy (2/2) - N/A (no legend needed, components labeled via facet strips).
• SC-06: Title Format (2/2) - Correct format: "timeseries-decomposition · plotnine · pyplots.ai"

Data Quality (18/20 pts)

• DQ-01: Feature Coverage (7/8) - Shows clear trend, seasonal pattern, and residual noise; demonstrates additive decomposition well. Could show slightly more variation in seasonal amplitude.
• DQ-02: Realistic Context (7/7) - Airline passenger data context is realistic and commonly used for time series examples.
• DQ-03: Appropriate Scale (4/5) - Values in reasonable range for passenger data (200-600); 12-year span with monthly data provides good granularity.

Code Quality (9/10 pts)

• CQ-01: KISS Structure (3/3) - Clean linear structure: imports → data → decomposition → plotting → save.
• CQ-02: Reproducibility (3/3) - Uses np.random.seed(42) for deterministic results.
• CQ-03: Clean Imports (2/2) - All imports are used; statsmodels for decomposition is appropriate.
• CQ-04: No Deprecated API (1/1) - Uses current plotnine API.
• CQ-05: Output Correct (0/1) - Saves as plot.png but uses both positional (dpi=300) and keyword arguments; minor issue.

Library Features (3/5 pts)

• LF-01: Uses distinctive library features (3/5) - Good use of ggplot grammar with facet_wrap, theme customization, and scale_x_datetime. Could leverage more plotnine-specific features like annotate or custom scales.

Strengths

• Excellent use of plotnine's 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)

Verdict: APPROVED