feat(seaborn): implement timeseries-forecast-uncertainty

[github-actions]

Implementation: timeseries-forecast-uncertainty - python/seaborn

Implements the python/seaborn version of timeseries-forecast-uncertainty.

File: plots/timeseries-forecast-uncertainty/implementations/python/seaborn.py

Parent Issue: #3188

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot is rendered on a warm off-white #FAF8F1 background. A solid green (#009E73) line traces the historical stock price from early January 2025 through late March, showing a gentle upward trend with natural volatility (~$148–$161). A vertical dotted line marks the forecast boundary, after which a dashed orange (#D55E00) line projects the price ~4 weeks forward. Nested CI bands radiate from the forecast start: a semi-transparent orange 80% band (more opaque) and a lighter 95% outer band clearly visible against the warm background. The legend sits in the upper left with clear labels (Historical, Forecast, 80% Confidence, 95% Confidence). Title, axis labels ("Date", "Stock Price ($)"), and tick labels are all clearly readable in dark ink. Both CI bands are cleanly distinguishable from each other and from the background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on #1A1A17 near-black background. Title and all text elements flip to light ink (#F0EFE8 / #B8B7B0) — all text is clearly readable; no dark-on-dark failures. The green historical line and orange dashed forecast line are identical in color to the light render (Okabe-Ito positions 1–2 unchanged). However, the CI bands suffer a significant visibility loss: the 95% outer band (alpha=0.15, orange on near-black) blends to an extremely dark brownish tint (#362414) that is nearly imperceptible against #1A1A17. The 80% inner band (alpha=0.28) produces a dark brownish-orange (#4F2D11) that is more visible but still muddy and lacks the clean definition of the light render. The nesting distinction between the two bands is substantially reduced. The legend CI patches also appear very dark, making it harder to correlate legend to visual bands. Legibility verdict: PASS for text and lines; PARTIAL FAIL for CI bands — visible but with significantly degraded clarity in dark mode.

Score: 88/100

Category	Score	Max
Visual Quality	27	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	8	10
Total	88	100

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title=24, labels=20, ticks=16, legend=16). Readable in both themes. Minor note: "Date" at fontsize=20 is slightly generous for a 4-letter label at this canvas size; "Stock Price ($)" is proportionally fine.
• VQ-02: No Overlap (6/6) — No overlapping text or data collisions anywhere.
• VQ-03: Element Visibility (4/6) — Lines (historical solid, forecast dashed) are sharp and well-weighted in both themes. CI bands are clear in light mode but severely degraded in dark mode: alpha=0.15 orange on #1A1A17 blends to ~#362414, nearly indistinguishable from the background; alpha=0.28 produces a muddy dark brownish. Both band widths exist but the visual hierarchy between them is largely lost in dark.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette. Green/orange combination is CVD-safe; bands use alpha-only distinction (universally readable).
• VQ-05: Layout & Canvas (4/4) — Good canvas utilization, balanced margins, legend doesn't overlap data.
• VQ-06: Axis Labels & Title (2/2) — "Date" and "Stock Price ($)" descriptive with units.
• VQ-07: Palette Compliance (2/2) — First series #009E73 ✓, second #D55E00 ✓, backgrounds #FAF8F1/#1A1A17 ✓, all chrome tokens theme-adaptive ✓.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Color semantics are intentional (green=known/history, orange=uncertain/future) and elevate the design above a generic default. Warm backgrounds, styled legend (fancybox=False, explicit edgecolor), and the solid-vs-dashed line contrast are thoughtful choices. Not publication-ready, but clearly above configured-default level.
• DE-02: Visual Refinement (4/6) — Despine applied, subtle y-grid (alpha=0.15), left/bottom spines explicitly colored with INK_SOFT, legend styled with framealpha=1.0. Good attention to detail.
• DE-03: Data Storytelling (4/6) — The plot narrates the forecasting story clearly through visual hierarchy: green = what happened, orange + widening bands = where we might go and how uncertain that is. The widening CI bands create a natural focal point at the far right. Transition is crisply marked by the vertical boundary line.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: time series with historical + forecast + nested 80%/95% CI bands + vertical transition marker.
• SC-02: Required Features (4/4) — Solid historical line, dashed forecast, 80% CI band, 95% CI band, vertical forecast-start marker, clear legend with all four labels present.
• SC-03: Data Mapping (3/3) — Date on X, Stock Price on Y, historical covers first 60 business days, forecast covers next 20.
• SC-04: Title & Legend (3/3) — timeseries-forecast-uncertainty · python · seaborn · anyplot.ai ✓. Legend labels match data series exactly.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: upward trend with sinusoidal seasonality in history, forecast extending the trend, monotonically widening 80% and 95% bands (√horizon growth), distinct CI nesting.
• DQ-02: Realistic Context (5/5) — Stock price forecasting with business-day frequency is a real, neutral, comprehensible scenario. Values (~$148–$175) are plausible.
• DQ-03: Appropriate Scale (4/4) — Stock price range realistic; √horizon uncertainty growth is the correct statistical model for a random-walk forecast; freq="B" for business days is domain-appropriate.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear imports → data → plot → save, no functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42).
• CQ-03: Clean Imports (2/2) — All imports used (Line2D, Patch for manual legend handles).
• CQ-04: Code Elegance (2/2) — Wide-form + long-form dual DataFrames are well-motivated (long-form for seaborn lineplot, wide-form for fill_between), no over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png ✓.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Expert use of seaborn's high-level API: hue + style + dashes in a single lineplot call for semantic multi-series encoding; long-form DataFrame organization; sns.set_theme(rc={...}) for full theme injection; sns.despine.
• LM-02: Distinctive Features (3/5) — The hue+style+dashes combo is distinctively seaborn (simultaneous color + linestyle mapping via one declarative call). CI bands require matplotlib fill_between fallback — unavoidable given seaborn's API, but limits library-exclusive credit.

Score Caps Applied

• None

Strengths

• Expert use of seaborn's hue+style+dashes combo in a single lineplot call — this is textbook idiomatic seaborn for multi-series with semantic style differentiation
• Color semantics (green=history, orange=forecast) create an immediately readable narrative without requiring annotations
• Full spec compliance: all required CI bands, boundary marker, and legend elements correctly implemented
• Statistically sound data: √horizon uncertainty growth, business-day date range, realistic stock prices
• All theme-adaptive chrome tokens correctly threaded throughout (title, labels, ticks, spines, grid, legend)
• Widening CI bands create a natural focal point and visual hierarchy that guides the viewer toward the forecast region

Weaknesses

• CI bands are nearly invisible in dark mode: alpha=0.15 for the 95% band blends orange with #1A1A17 to ~#362414 (dark brownish), essentially indistinguishable from the background; alpha=0.28 for the 80% band is visible but muddy. Use theme-adaptive alpha values: higher alpha in dark mode (e.g., alpha_95 = 0.15 if THEME == "light" else 0.35, alpha_80 = 0.28 if THEME == "light" else 0.50) to preserve CI band legibility across both themes.
• Canvas size deviation: figsize=(16, 9) at dpi=300 produces 4800×2700 px — the style guide and library spec call for figsize=(8, 4.5) at dpi=400 for the canonical 3200×1800 output. While the visual result is acceptable, alignment with the spec would be better.
• Design excellence ceiling: no focal-point annotation (e.g., a small label for the forecast boundary date), no subtitle or secondary descriptive element that would elevate from "strong default" to "publication-ready"

Issues Found

1. VQ-03 DEGRADED DARK: CI bands use fixed alpha values that produce near-invisible shading on #1A1A17 background.
   • Fix: Use theme-adaptive alpha — ALPHA_95 = 0.15 if THEME == "light" else 0.35 and ALPHA_80 = 0.28 if THEME == "light" else 0.50
2. DE-01 CEILING: Design is strong but doesn't reach publication quality; no typographic hierarchy variation, no callout annotation, no focal emphasis.
   • Fix: Add a small annotation at the forecast boundary (e.g., "Forecast start" with date), or use a slightly bolder/larger title fontweight to create stronger hierarchy.

AI Feedback for Next Attempt

Primary fix: Make CI bands theme-adaptive by using significantly higher alpha values in dark mode (0.35/0.50 instead of 0.15/0.28). This is the single biggest quality gap. Secondary: consider adding a small text annotation at the forecast boundary date to push DE-01 above 6. Canvas size should align with the seaborn spec (figsize=(8,4.5) dpi=400). All other aspects — palette, data, spec compliance, code quality — are excellent and should be preserved.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/4

Applied fixes based on AI review feedback.

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

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

Light render (plot-light.png): The plot displays a time series on a warm off-white #FAF8F1 background. The historical stock price line (60 trading days, Jan–Mar 2025) renders in #009E73 (brand green) as a solid line with natural upward trend and noise. The forecast line (20 trading days, Apr–May 2025) renders in #D55E00 (vermillion) as a dashed line, connecting seamlessly from the last historical point. Two nested confidence bands fill the forecast region in the same vermillion family: a wider lighter 95% band (alpha=0.15) and a narrower darker 80% band (alpha=0.28). A subtle dotted vertical line marks the forecast boundary. The legend sits in the upper-left quadrant (no data there) and cleanly labels all four elements. Title, axis labels ("Date", "Stock Price ($)"), and tick labels are all clearly readable in dark ink against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on a warm near-black #1A1A17 background. The historical green line (#009E73) and dashed orange forecast line (#D55E00) are identical in color to the light render — only the chrome flips. Title, axis labels, and tick labels render in light text (#F0EFE8 / #B8B7B0) and are fully readable against the dark surface. The 95% CI band appears as a dark brownish-orange region and the 80% band as a brighter orange layer on top — still distinguishable, though the band contrast is slightly compressed on dark. No dark-on-dark text failures observed. The legend background uses the elevated dark token (#242420). Legibility verdict: PASS.

Score: 90/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	8	10
Total	90	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title=24, labels=20, ticks=16). Well-proportioned for the 4800×2700 canvas. Minor: axis label fontsize=20 is slightly generous for short labels "Date" and "Stock Price ($)".
• VQ-02: No Overlap (6/6) — Legend cleanly placed in empty upper-left quadrant, no text/data collisions in either render.
• VQ-03: Element Visibility (6/6) — Historical solid line and forecast dashed line both prominent; CI bands appropriately semi-transparent (alpha 0.15 / 0.28) with good density for 20-point forecast.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito green/vermillion pair is CVD-safe and high contrast; shapes also distinguished by line style (solid vs dashed).
• VQ-05: Layout & Canvas (4/4) — Plot fills canvas well, generous but balanced whitespace, tight_layout() + bbox_inches='tight' applied correctly.
• VQ-06: Axis Labels & Title (2/2) — Y-axis has units ("Stock Price ($)"), X-axis label is "Date", both appropriately descriptive.
• VQ-07: Palette Compliance (2/2) — First series is #009E73 ✓; second is #D55E00 (Okabe-Ito position 2) ✓; backgrounds are #FAF8F1 (light) / #1A1A17 (dark) ✓; all chrome tokens are theme-adaptive ✓.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above defaults: intentional two-color scheme (historical/forecast distinction), solid vs dashed line styling, nested CI bands, vertical boundary marker, fancybox=False clean legend. Not yet publication-ready — the CI band differentiation is slightly weak in the dark render.
• DE-02: Visual Refinement (4/6) — Spines despined (top/right removed), subtle y-axis-only grid (alpha=0.15), elevated legend background, no tick marks clutter. Clean and polished.
• DE-03: Data Storytelling (4/6) — The growing uncertainty bands over the forecast horizon communicate the key insight naturally. Vertical divider clearly demarcates known vs projected. Color + linestyle reinforcement of historical/forecast makes the narrative immediately readable.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct time-series-with-forecast-uncertainty chart; historical line, forecast line, dual CI bands all present.
• SC-02: Required Features (4/4) — Solid historical line ✓, dashed forecast line ✓, 80% and 95% CI bands ✓, vertical forecast boundary marker ✓, semi-transparent fills (alpha 0.15/0.28) ✓, comprehensive legend ✓.
• SC-03: Data Mapping (3/3) — Date on x-axis, stock price on y-axis, both historical and forecast periods fully visible.
• SC-04: Title & Legend (3/3) — Title is exactly timeseries-forecast-uncertainty · python · seaborn · anyplot.ai ✓; legend labels "Historical", "Forecast", "80% Confidence", "95% Confidence" ✓.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: trending historical data with realistic noise, forecast continuation, widening CI bands over horizon (both 80% and 95%), clear historical-to-forecast transition.
• DQ-02: Realistic Context (5/5) — Stock price forecasting is a neutral, comprehensible real-world scenario; no controversial topics.
• DQ-03: Appropriate Scale (4/4) — ~$150 stock with gentle upward trend and proportionally growing CI bands (±1.96σ√t). Values, trend, and uncertainty widths are all factually plausible.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → tokens → data → theme → plot → style → legend → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ✓.
• CQ-03: Clean Imports (2/2) — All seven imports are used (os, plt, np, pd, sns, Line2D, Patch).
• CQ-04: Code Elegance (2/2) — Clean, Pythonic. Wide-form for CI bands, long-form for seaborn lineplot — sensible separation. No over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png ✓; current seaborn/matplotlib API throughout ✓.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Exemplary seaborn: long-form data with hue + style + dashes dict for per-series styling; sns.set_theme() with rc customization; sns.despine(). Fully leverages seaborn's high-level multi-series API.
• LM-02: Distinctive Features (3/5) — Uses seaborn-distinctive dashes parameter for per-hue line styles and the theme/rc system. CI bands use matplotlib fill_between directly (seaborn's built-in CI is for statistical aggregates, so this is the correct approach), which limits the "only in seaborn" score slightly.

Score Caps Applied

• None

Strengths

• Idiomatic seaborn long-form API with hue+style+dashes for clean multi-series styling
• Full theme-adaptive chrome: all tokens correctly set for both light and dark renders
• All spec requirements met: dual CI bands, forecast boundary, legend, line styles
• Realistic, self-contained data generation with widening CI bands over forecast horizon
• Clean code structure with proper seed and all imports used

Weaknesses

• Axis label fontsize=20 is slightly disproportionate for short labels "Date" / "Stock Price ($)" on the large 4800×2700 canvas — scale to ~14pt
• CI band visual separation is slightly compressed in the dark render (both bands appear dark brownish) — consider bumping the 95% alpha to 0.20 and 80% to 0.35 for better dark-theme differentiation
• Canvas is 4800×2700 (dpi=300, figsize=(16,9)) — exceeds the standard 3200×1800 target; use dpi=200 or figsize=(10.67, 6) to match standard

Issues Found

1. VQ-01 MINOR: Axis labels "Date" and "Stock Price ($)" use fontsize=20 on a large canvas — proportionally slightly large for short labels.
   • Fix: Reduce to fontsize=14 (or scale relative to canvas size)
2. DE-01 ROOM: CI band differentiation slightly weak in dark render.
   • Fix: Increase alphas slightly (95%: 0.20, 80%: 0.35) for better contrast distinction in dark mode

AI Feedback for Next Attempt

Plot is approved at 90/100. For future iterations: reduce axis label fontsize for short labels to maintain visual balance, and consider slightly higher alpha values for CI bands to improve dark-theme differentiation between the 80% and 95% intervals.

Verdict: APPROVED