feat(seaborn): implement sankey-basic

[github-actions]

Implementation: sankey-basic - python/seaborn

Implements the python/seaborn version of sankey-basic.

File: plots/sankey-basic/implementations/python/seaborn.py

Parent Issue: #810

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1). Title "sankey-basic · seaborn · anyplot.ai" in dark text at the top — clearly readable. Three source nodes on the left (Gas in #009E73 green, Coal in #D55E00 orange, Nuclear in #0072B2 blue) and three destination nodes on the right (Residential in #CC79A7 pink, Industrial in #E69F00 gold, Commercial in #56B4E9 sky blue), each labelled in bold dark text with name and TWh value. Smooth Bezier flow bands connect sources to targets, color-coded by source with alpha=0.55. All node labels (18pt bold) and the title (24pt) are readable against the light background. No text legibility issues. Significant empty space in the lower quarter of the canvas.

Dark render (plot-dark.png): Dark near-black background (~#1A1A17). Title in light text, clearly readable. Node labels are white/light-colored and fully readable against the dark background — no dark-on-dark failures. Data colors are identical to the light render: Gas=green, Coal=orange, Nuclear=blue on the source side; Residential=pink, Industrial=gold, Commercial=sky-blue on the target side. The alpha-blended flow bands appear darker (less translucent feel) on the dark surface but remain distinguishable. Brand green #009E73 is clearly visible. Chrome (title, node labels) correctly adapts to the dark theme. Legibility verdict: PASS for both renders.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 82/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	12	20
Spec Compliance	15	15
Data Quality	13	15
Code Quality	10	10
Library Mastery	4	10
Total	82	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — Title 24pt ✓, node labels 18pt bold (explicitly set but below 20pt axis-label guideline)
• VQ-02: No Overlap (6/6) — All labels and nodes are spatially separated; no text collisions
• VQ-03: Element Visibility (6/6) — Node sizes proportional to flow, flows clearly visible with alpha=0.55; thin flows (10 TWh) still distinguishable
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is CVD-safe; source and target colors differ sufficiently
• VQ-05: Layout & Canvas (3/4) — Diagram fills ~65% of canvas; noticeable empty space in the lower 20-25% of the image
• VQ-06: Axis Labels & Title (2/2) — Title is correct format; node labels embed TWh values as effective axis context
• VQ-07: Palette Compliance (2/2) — First source (#009E73) is brand green; Okabe-Ito order maintained for all 6 nodes; backgrounds are theme-correct; chrome adapts correctly between themes

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Custom Sankey from scratch with smooth Bezier curves, rounded nodes (FancyBboxPatch), and intentional Okabe-Ito coloring. Polished and above defaults, but not FiveThirtyEight-level — no typographic hierarchy beyond bold labels, no title subtitle or annotation layer
• DE-02: Visual Refinement (4/6) — Axis fully removed (appropriate), alpha blending well-chosen, PAGE_BG node edges provide clean separation. Some canvas imbalance (empty bottom) and no intentional use of whitespace as a design element
• DE-03: Data Storytelling (3/6) — Color-coded flows by source enable path-tracing, and TWh values in labels provide immediate quantitative context. However no visual emphasis on the dominant story (Gas is the largest source, flowing broadly). All flows treated equally — no focal point or hierarchy to guide the viewer

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Custom Sankey diagram with proportional link widths and source-to-target node structure
• SC-02: Required Features (4/4) — Proportional flow widths, distinct source colors, link opacity, node labels, no circular flows
• SC-03: Data Mapping (3/3) — Energy sources (Gas/Coal/Nuclear) → end-use sectors (Residential/Industrial/Commercial) with TWh values
• SC-04: Title & Legend (3/3) — Title "sankey-basic · seaborn · anyplot.ai" ✓; nodes self-label with name + value, appropriate for Sankey

Data Quality (13/15)

• DQ-01: Feature Coverage (5/6) — All 9 source-target combinations present; varied magnitudes (10–50 TWh); shows full distribution from 3 sources. Minor: all sources connect to all targets (no selective flow), which is valid but limits structural contrast
• DQ-02: Realistic Context (5/5) — Energy flow (Gas/Coal/Nuclear → Residential/Industrial/Commercial) is a canonical Sankey use case; neutral, real-world domain
• DQ-03: Appropriate Scale (3/4) — Values plausible; Gas dominance is realistic. Nuclear's share (45 TWh vs Gas's 120) could be more realistically differentiated for some country profiles, and Coal→Residential flow is higher than expected in modern grids

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → tokens → data → layout calc → figure → draw → save; no functions or classes
• CQ-02: Reproducibility (2/2) — Data is fully deterministic; no random elements
• CQ-03: Clean Imports (2/2) — All 6 imports are used (os, mpatches, plt, np, pd, sns)
• CQ-04: Code Elegance (2/2) — Smoothstep interpolation, Bezier curve computation, and layout normalization are appropriate complexity; no over-engineering
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png, no deprecated functions

Library Mastery (4/10)

• LM-01: Idiomatic Usage (3/5) — sns.set_theme() used correctly for consistent chrome styling; the bulk of rendering is matplotlib primitives (necessary since seaborn has no Sankey API)
• LM-02: Distinctive Features (1/5) — seaborn's contribution is limited to set_theme() for styling; all chart logic is matplotlib. Seaborn has no native Sankey capability, so this is an inherent limitation

Score Caps Applied

• None applied — all category triggers are above threshold

Strengths

• Excellent spec compliance (15/15) with correct Sankey structure, proportional flows, and all spec requirements met
• Perfect code quality (10/10): clean, linear structure with deterministic data and all imports used
• Correct Okabe-Ito palette across both themes with proper chrome adaptation — no theme-readability failures
• Smooth Bezier flow bands with smoothstep interpolation and sorted flow order to minimize visual crossings
• Rounded FancyBboxPatch nodes with PAGE_BG edge separation add professional polish

Weaknesses

• DE-03 LOW: No focal point or visual storytelling emphasis — Gas is the dominant source (120 TWh) but treated identically to Nuclear (45 TWh). Consider making the dominant source node or its flows slightly more prominent (thicker stroke on Gas node border, or a subtitle annotation like "Gas supplies 49% of all energy")
• DE-01 MODERATE: No typographic hierarchy beyond bold node labels — title and labels are the same visual weight. A subtitle or brief annotation layer would add depth
• VQ-05 MINOR: Lower ~20-25% of canvas is empty. Adjust Y_START/TOTAL_H to better center the diagram vertically or add a small explanatory note in the empty space
• LM-02 LOW: Inherent to Sankey in seaborn; not fixable without switching chart type
• VQ-01 MINOR: Node labels at 18pt — bump to 20pt to match axis-label guideline

Issues Found

1. DE-03 LOW: No visual hierarchy — all flows and nodes styled uniformly regardless of magnitude
   • Fix: Add a title annotation or subtitle highlighting the key insight (e.g., "Gas is the primary energy source"); OR increase Gas node border thickness to emphasize dominance; OR use slightly higher alpha (0.65–0.70) for the dominant Gas flows to make them visually heavier
2. VQ-05 MINOR: Bottom 20% of canvas is unused whitespace
   • Fix: Adjust Y_START = 0.85 and TOTAL_H = 0.72 to center the diagram, or add a data source footnote in the empty space
3. VQ-01 MINOR: Node label fontsize=18 is below the ≥20pt guideline for axis-equivalent labels
   • Fix: Change fontsize=18 to fontsize=20 in both node label blocks

AI Feedback for Next Attempt

Improve data storytelling: add a brief subtitle or annotation identifying the dominant flow path (Gas is 49% of total energy). Increase node label fontsize from 18 to 20. Adjust layout parameters to eliminate the empty bottom quarter (try Y_START=0.85, TOTAL_H=0.72). Consider slightly boosting the alpha on Gas flows (from 0.55 to 0.65) so the largest source reads as visually heavier. These targeted changes to DE-03 and VQ-05 should push the score above 90.

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): Warm off-white (#FAF8F1) background with a custom-drawn Sankey diagram. Three source nodes on the left — Gas (#009E73, brand green), Coal (#D55E00, vermillion), Nuclear (#0072B2, blue) — with rounded rectangle styling and background-colored borders. Three target nodes on the right — Residential (#CC79A7, reddish purple), Industrial (#E69F00, orange), Commercial (#56B4E9, sky blue). Flows are rendered as smooth cubic Bezier curves with alpha=0.68 for Gas (visual emphasis) and alpha=0.44 for Coal and Nuclear. Node labels in bold dark ink (fontsize=20) show names and values in TWh. Title "sankey-basic · seaborn · anyplot.ai" is clearly readable at fontsize=24. An italic green subtitle above the Sankey signals the Gas dominance story, though it appears in a narrow strip and is subtle at fontsize=16. All text readable against the light background.

Dark render (plot-dark.png): Near-black (#1A1A17) background. Data colors are identical to the light render (Gas=green, Coal=orange, Nuclear=blue; target nodes same). Node labels use the INK token (#F0EFE8) and appear in near-white — clearly readable against the dark background. Title text is white and legible. The low-alpha Coal and Nuclear flows (0.44) become somewhat muted against the dark background in crossing areas but remain distinguishable. No dark-on-dark failures. Chrome correctly flips while data colors stay constant.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 88/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — Title 24pt, node labels 20pt bold, subtitle 16pt; all explicitly set and clearly readable in both themes
• VQ-02: No Overlap (6/6) — No text collisions; node labels positioned cleanly left/right of Sankey
• VQ-03: Element Visibility (5/6) — Flows are visible; Gas flows prominent at alpha=0.68; Coal/Nuclear at alpha=0.44 become somewhat muted in dark crossing areas
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette, CVD-safe, sufficient luminance variation between all 6 node colors
• VQ-05: Layout & Canvas (4/4) — Sankey fills ~70% of canvas, margins are balanced, nothing cut off
• VQ-06: Axis Labels & Title (2/2) — Node labels include units (TWh); title is descriptive; axis off (appropriate for Sankey)
• VQ-07: Palette Compliance (2/2) — Gas (first source) = #009E73; full Okabe-Ito order for both sources and targets; backgrounds #FAF8F1/#1A1A17; INK token adapts text colors correctly

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: hand-crafted Bezier curves, rounded FancyBboxPatch nodes with background-colored borders, differential alpha for visual emphasis on Gas — clearly above library defaults
• DE-02: Visual Refinement (5/6) — axis('off') for minimal chrome, smoothstep Bezier for ultra-smooth flows, no grid, rounded corners, node-edge styling; very polished
• DE-03: Data Storytelling (4/6) — Gas flow rendered at higher alpha (0.68 vs 0.44) for visual hierarchy; italic subtitle explicitly names the key insight; Gas node at top draws the eye first

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct Sankey diagram with source→target flows, widths proportional to values
• SC-02: Required Features (4/4) — 9 flows (within 5-50), no circular flows, node labels visible, distinct source colors, link opacity implemented
• SC-03: Data Mapping (3/3) — Sources left, targets right, node heights and flow widths proportional to values
• SC-04: Title & Legend (3/3) — Title format "sankey-basic · seaborn · anyplot.ai" correct; node placement serves as implicit legend (no separate legend needed)

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — All sources connect to all targets (9 flows), varied magnitudes, flow crossings demonstrate Sankey's full capability
• DQ-02: Realistic Context (5/5) — Energy flow scenario (Gas/Coal/Nuclear → Residential/Industrial/Commercial) is a classic, neutral, real-world example
• DQ-03: Appropriate Scale (4/4) — Gas 120 TWh (49%), Coal 80 TWh (33%), Nuclear 45 TWh (18%); proportions plausible for a mixed-grid energy system

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → tokens → data → layout geometry → figure → draw flows → draw nodes → save; no functions or classes
• CQ-02: Reproducibility (2/2) — Fully deterministic (no random values); hardcoded data
• CQ-03: Clean Imports (2/2) — All 6 imports used: os (THEME env), mpatches (FancyBboxPatch), plt (figure/save), np (linspace/arrays), pd (DataFrame/groupby), sns (set_theme)
• CQ-04: Code Elegance (2/2) — Pythonic, appropriate complexity for a custom Sankey; smoothstep formula is a recognized technique; no over-engineering or fake UI
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png; current matplotlib/seaborn API throughout

Library Mastery (4/10)

• LM-01: Idiomatic Usage (3/5) — seaborn used correctly for theming (sns.set_theme); however the Sankey itself is entirely matplotlib primitives; seaborn's statistical plot API is unused
• LM-02: Distinctive Features (1/5) — seaborn used only for sns.set_theme(); nothing seaborn-specific in the visualization itself; could be replicated with plain matplotlib

Score Caps Applied

• None

Strengths

• Perfect spec compliance and data quality — energy flow scenario is ideal for a Sankey
• Custom bezier-curve Sankey from first principles, with smoothstep interpolation and rounded nodes, is visually polished
• Okabe-Ito palette applied correctly to both source and target node groups
• Theme-adaptive chrome works correctly in both renders — INK token controls all text colors
• Differential alpha (Gas=0.68 vs others=0.44) creates genuine visual hierarchy highlighting the dominant source
• Code is clean, deterministic, and well-structured for a complex custom diagram

Weaknesses

• Library Mastery is minimal — seaborn is used only for sns.set_theme(); the entire visualization is matplotlib; no seaborn statistical API leveraged
• Subtitle text at y=0.93 data coords is in a very narrow strip and appears small/subtle; storytelling impact is reduced
• Low-alpha flows (0.44) become somewhat muted in the dark render's crossing areas, slightly reducing flow distinguishability

Issues Found

1. LM-02 LOW: seaborn's unique capabilities (statistical plots, FacetGrid, color palette utilities) are not used — only sns.set_theme() is called
   • Fix: Consider using seaborn's color utilities or a seaborn-native chart component where applicable
2. Subtitle Visibility: Italic subtitle at fontsize=16 in a narrow data-coordinate strip above the Sankey is subtle; increases fontsize or repositions for better storytelling impact

AI Feedback for Next Attempt

This is a high-quality implementation at 88/100, APPROVED for attempt 2. The main drag is Library Mastery (4/10) — seaborn is used only for theming. If regeneration is needed, consider leveraging seaborn color utilities (e.g., sns.color_palette()) or using seaborn's axes-level functions for any supplementary plot elements. The subtitle at y=0.93 in data coordinates is well-intentioned but appears in a very narrow strip; increasing fontsize to 20 or repositioning as an axes title alternative would improve DE-03.

Verdict: APPROVED