feat(altair): implement timeseries-decomposition

[github-actions]

Implementation: timeseries-decomposition - altair

Implements the altair version of timeseries-decomposition.

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

Parent Issue: #2992

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a time series decomposition visualization with four vertically stacked line charts sharing a common x-axis (Date, spanning 2018-2025). Each subplot shows a distinct component: Original (blue line) shows the raw time series data with visible trend and seasonal fluctuations ranging from ~75 to ~200; Trend (red line) displays a smooth upward linear trend from ~100 to ~170; Seasonal (teal line) shows a perfect repeating annual sinusoidal pattern oscillating between approximately -30 and +30; Residual (purple line) shows random noise fluctuating around 0 within a range of roughly -20 to +20. The title "timeseries-decomposition · altair · pyplots.ai" appears at the top. Component names are displayed as bold labels on the left side of each subplot. Font sizes appear adequate for readability.

Quality Score: 91/100

Criteria Checklist

Visual Quality (36/40 pts)

• VQ-01: Text Legibility (9/10) - Title at 28pt, axis labels at 16-20pt are readable; tick labels could be slightly larger but acceptable
• VQ-02: No Overlap (8/8) - No overlapping text elements; x-axis labels angled at -45° prevent overlap
• VQ-03: Element Visibility (8/8) - Line thickness of 2.5 is optimal for the data density; all components clearly visible
• VQ-04: Color Accessibility (5/5) - Four distinct colors (blue, red, teal, purple) are colorblind-safe and have good contrast
• VQ-05: Layout Balance (4/5) - Good use of canvas with faceted layout; slight excessive whitespace between subplots
• VQ-06: Axis Labels (1/2) - "Date" and "Value" are descriptive but lack units
• VQ-07: Grid & Legend (1/2) - No visible grid lines (spec requested light grid); legend appropriately hidden since component names are facet labels

Spec Compliance (23/25 pts)

• SC-01: Plot Type (8/8) - Correct time series decomposition with 4 vertically stacked subplots
• SC-02: Data Mapping (5/5) - Date on x-axis, values on y-axis, correctly mapped for all components
• SC-03: Required Features (4/5) - All four components displayed; missing light grid lines as specified
• SC-04: Data Range (3/3) - All data visible with independent y-scales per subplot
• SC-05: Legend Accuracy (2/2) - Component names clearly labeled via facet headers
• SC-06: Title Format (1/2) - Uses correct format but middle dot separator could be more prominent

Data Quality (19/20 pts)

• DQ-01: Feature Coverage (7/8) - Shows trend, seasonality, and noise effectively; 96 monthly points (8 years) covers multiple cycles; decomposition shows characteristic patterns
• DQ-02: Realistic Context (7/7) - Airline passengers scenario is a classic, neutral, and realistic time series example
• DQ-03: Appropriate Scale (5/5) - Values 100-200 for passengers are realistic; seasonal amplitude and residual scale are sensible

Code Quality (10/10 pts)

• CQ-01: KISS Structure (3/3) - Linear flow: imports → data → decomposition → plot → save
• CQ-02: Reproducibility (3/3) - Uses np.random.seed(42) for consistent results
• CQ-03: Clean Imports (2/2) - All imports used: altair, numpy, pandas, statsmodels
• CQ-04: No Deprecated API (1/1) - Uses current Altair API
• CQ-05: Output Correct (1/1) - Saves as plot.png and plot.html

Library Features (3/5 pts)

• LF-01: Uses Altair distinctive features (3/5) - Good use of faceting with row= encoding, declarative color mapping, and independent y-scales via resolve_scale. Could have added interactivity with .interactive() or tooltips.

Strengths

• Excellent use of Altair's declarative faceting to create vertically stacked subplots with independent y-scales
• Clean, professional color scheme with distinct colors for each component that are colorblind-accessible
• Proper use of statsmodels seasonal_decompose for authentic decomposition (not just manual construction)
• Component labels are prominently displayed using facet headers with good font styling
• Appropriate data: 96 monthly points covering 8 years provides sufficient data for meaningful decomposition
• Code follows KISS principles with clear linear flow

Weaknesses

• Missing light grid lines that the specification explicitly requests ("Include light grid lines to aid reading values across time")
• Y-axis labels all say generic "Value" rather than being more specific (e.g., "Passengers" for Original, "Trend Component", etc.)
• Could leverage Altair's interactivity features (.interactive() or tooltips) which are a key library strength

Verdict: APPROVED