feat(letsplot): implement sankey-basic

[github-actions]

Implementation: sankey-basic - python/letsplot

Implements the python/letsplot version of sankey-basic.

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

Parent Issue: #810

---

🤖 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 horizontal Sankey diagram shows energy flows from four source nodes on the left (Renewable 30 TWh, Nuclear 28 TWh, Natural Gas 75 TWh, Coal 36 TWh — listed top to bottom) to three target nodes on the right (Commercial 40 TWh, Residential 57 TWh, Industrial 72 TWh). Flow bands use the Okabe-Ito palette: Coal = #009E73 (brand green), Natural Gas = #D55E00 (orange), Nuclear = #0072B2 (blue), Renewable = #CC79A7 (reddish purple), all at alpha 0.65. Node rectangles are solid black (#1A1A17). Node labels are placed to the left/right of nodes in #4A4A44 (INK_SOFT). Title is bold at size 30. A legend at the bottom shows all four source categories. All text is clearly readable against the light background.

Dark render (plot-dark.png): Rendered on near-black #1A1A17 background. Flow colors are identical to the light render (Okabe-Ito positions 1–4 unchanged). Node rectangles flip to #F0EFE8 (INK in dark mode), appearing as light/white bars — correct theme adaptation. Node labels render in #B8B7B0 (INK_SOFT dark), clearly readable against the dark background. Title is light-colored and readable. No dark-on-dark failures observed. Legend is visible at bottom. Chrome adaptation works correctly throughout.

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

Score: 84/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	12	20
Spec Compliance	14	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	5	10
Total	84	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — Title (30pt), legend title (20pt), legend text (18pt) all explicitly set. Node labels at size=14 are slightly below the recommended 16pt minimum, though readable at render scale.
• VQ-02: No Overlap (6/6) — No text collisions. Node labels positioned cleanly to the sides of nodes.
• VQ-03: Element Visibility (6/6) — Flow bands are proportional and clearly visible; alpha 0.65 prevents occlusion on crossing flows.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is colorblind-safe. No red-green-only encoding.
• VQ-05: Layout & Canvas (3/4) — Diagram fills most of the canvas. Slight space inefficiency due to wide margins around node labels on the left.
• VQ-06: Axis Labels & Title (2/2) — Title is descriptive; axes correctly suppressed (N/A for Sankey).
• VQ-07: Palette Compliance (2/2) — First series (Coal) = #009E73 ✓; Okabe-Ito canonical order ✓; backgrounds #FAF8F1/#1A1A17 ✓; data colors identical in both renders ✓.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Above "well-configured default": smooth bezier-like curves, proper alpha blending, Okabe-Ito palette, minimal chrome. Not quite publication-ready — the crossing flows are hard to trace individually, and no additional design hierarchy distinguishes dominant from minor flows.
• DE-02: Visual Refinement (4/6) — Grid removed, axes removed, clean legend placement. Good refinement for a manually composed diagram. Could improve: node rectangles are very stark black/white against the background.
• DE-03: Data Storytelling (3/6) — Sankey inherently communicates flow direction and magnitude. The proportional bands reveal Natural Gas (75 TWh) as the dominant source and Industrial (72 TWh) as the largest consumer. Node labels add quantitative context. However, no emphasis technique highlights the dominant flow path — all flows are treated equally with no visual hierarchy.

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct Sankey diagram with proportional flow widths.
• SC-02: Required Features (4/4) — Proportional link widths ✓; distinct source colors ✓; no circular flows ✓; node labels visible ✓; link opacity applied ✓.
• SC-03: Data Mapping (3/3) — Sources (Coal, Natural Gas, Nuclear, Renewable) → Targets (Industrial, Residential, Commercial); 10 flows within the 5–50 spec range.
• SC-04: Title & Legend (2/3) — Title is Energy Flow · sankey-basic · letsplot · anyplot.ai but required format is {spec-id} · {library} · anyplot.ai = sankey-basic · letsplot · anyplot.ai. The "Energy Flow · " prefix is non-compliant. Legend labels correct ✓.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all Sankey aspects: proportional flow widths, multi-source to multi-target routing, crossing flows, varying magnitudes.
• DQ-02: Realistic Context (5/5) — Energy flow (coal/gas/nuclear/renewable → industrial/residential/commercial) is the canonical real-world Sankey example. Neutral and comprehensible.
• DQ-03: Appropriate Scale (4/4) — TWh values are proportionally plausible (Gas 75 > Coal 36 > Renewable 30 > Nuclear 28), consistent with modern mixed-energy economies.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat script: imports → data → layout computation → plot → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded data; no randomness.
• CQ-03: Clean Imports (2/2) — All 16 lets_plot imports are used; os and pd are used; no unused imports.
• CQ-04: Code Elegance (2/2) — Manual Sankey construction is appropriately complex for a library without native support. Bezier-like smoothstep computation is clean inline code.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png (scale=3 for 4800×2700px) and plot-{THEME}.html. Correct API usage.

Library Mastery (5/10)

• LM-01: Idiomatic Usage (3/5) — Uses ggplot grammar correctly with layered geoms and theme composition. Manual Sankey construction with geom_polygon/geom_rect/geom_text is an appropriate ggplot approach. Not quite expert-level — same pattern works identically in plotnine.
• LM-02: Distinctive Features (2/5) — The multi-layer composition to build a custom diagram type is somewhat creative, but no feature unique to lets-plot is leveraged (e.g., lets-plot's built-in interactivity hooks, geom_livemap, or tooltip customization). The HTML export is lets-plot-specific but underused.

Score Caps Applied

• None — all caps checked; no cap triggers (VQ-02=6, VQ-03=6, SC-01=5, DQ-02=5, DE-01=5>2, DE-02=4>2, CQ-04=2>0).

Strengths

• Perfect Okabe-Ito compliance with Coal as #009E73 (brand green first)
• Correct theme-adaptive chrome in both renders — no dark-on-dark failures
• Smooth bezier-like flow curves built with geom_polygon smoothstep interpolation
• Complete data quality: realistic energy domain, plausible TWh values, all Sankey features demonstrated
• Perfect code quality: flat KISS structure, deterministic, clean imports

Weaknesses

• Title format incorrect: has Energy Flow · sankey-basic · letsplot · anyplot.ai — should be sankey-basic · letsplot · anyplot.ai (remove the "Energy Flow · " prefix)
• Node label size=14 is below the 16pt minimum guideline; should be at least 16
• DE-03 low: no emphasis on dominant flow path (Natural Gas → Industrial is the largest single flow but is visually equal to all others)
• DE-01 not exceptional: stark black/white node rectangles are visually blunt; slightly rounded or colored nodes could improve sophistication
• LM-02 low: no lets-plot-specific feature used (interactive tooltip customization, HTML interactivity, or geom_livemap)

Issues Found

1. SC-04 PARTIAL: Title prefix non-compliant
   • Fix: Change title to labs(title="sankey-basic · letsplot · anyplot.ai")
2. VQ-01 MINOR: Node label size below guideline
   • Fix: Increase geom_text(..., size=16) for node labels
3. DE-03 LOW: No visual hierarchy on dominant flows
   • Fix: Optionally increase alpha or add subtle annotation on the Natural Gas → Industrial flow (the largest single flow at 22 TWh) to create a focal point
4. DE-01 MODERATE: Node rectangles too blunt
   • Fix: Consider using fill=INK_SOFT instead of INK for nodes, or add a thin border with color=PAGE_BG to soften their appearance

AI Feedback for Next Attempt

Fix title format to sankey-basic · letsplot · anyplot.ai. Increase node label size from 14 to 16+. To push DE-01 and DE-03 higher: use INK_SOFT for node fills (softer than stark INK), and add a subtle visual cue — e.g., slightly higher alpha or a thin annotation — on the dominant Natural Gas flows to create hierarchy. Consider leveraging lets-plot's HTML interactivity with custom tooltips showing exact flow values for LM-02 improvement.

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 background (#FAF8F1) — correct theme surface. Title visible in bold dark INK text at top-left. Node labels on the left (Renewable 30 TWh, Nuclear 28 TWh, Natural Gas 75 TWh, Coal 36 TWh) and right (Commercial 40 TWh, Residential 57 TWh, Industrial 72 TWh) are rendered in INK_SOFT — all clearly readable. Legend at bottom shows "Energy Source" with four correctly colored swatches. No axis text (correctly blanked for Sankey). Flow bands show Coal in #009E73 (green, first/correct), Natural Gas in #D55E00 (orange), Nuclear in #0072B2 (blue), Renewable in #CC79A7 (reddish purple) — correct Okabe-Ito canonical order. Smooth bezier-like curves connect source to target nodes at alpha=0.65. Black node rectangles clearly visible. All text is readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): Warm near-black background (#1A1A17) — correct dark surface. Title rendered in light INK (#F0EFE8) text — clearly readable. Node labels in INK_SOFT (#B8B7B0) — readable against the dark background; no dark-on-dark failure detected. Legend text is appropriately light-colored. Flow band colors are identical to the light render — Coal #009E73, Natural Gas #D55E00, Nuclear #0072B2, Renewable #CC79A7 — only chrome flips, data colors stay constant. Node rectangles adapt to light INK color in dark theme. Legibility verdict: PASS.

Score: 85/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	12	20
Spec Compliance	14	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	5	10
Total	85	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — Title size=30 and legend 18/20 explicitly set; node labels size=14 is slightly below the recommended 16pt minimum for secondary text — all readable but marginal
• VQ-02: No Overlap (6/6) — No text or element overlap; source and target labels well-separated from flow bands
• VQ-03: Element Visibility (6/6) — Flow bands at alpha=0.65 clearly visible; node rectangles prominent; all elements distinguishable
• VQ-04: Color Accessibility (2/2) — Okabe-Ito is CVD-safe; adequate luminance differences between all four flow colors
• VQ-05: Layout & Canvas (4/4) — Sankey fills canvas well; nodes at x=0.18/0.82 with y spanning ~0.05–0.95; good 16:9 proportions
• VQ-06: Axis Labels & Title (2/2) — No traditional axis labels (correct for Sankey); node labels with TWh values serve as data labels; title present
• VQ-07: Palette Compliance (2/2) — First series (Coal) = #009E73 correct; Okabe-Ito canonical order maintained; backgrounds #FAF8F1 / #1A1A17 correct; chrome adaptive in both themes

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Well above defaults: custom-built Sankey with smooth bezier-like curves, professional Okabe-Ito palette, clean typography; not quite publication-ready polish but clearly intentional design
• DE-02: Visual Refinement (4/6) — Grid removed, axes blanked, warm theme-appropriate background; legend border adds minor chrome; generous whitespace around nodes
• DE-03: Data Storytelling (3/6) — Flow proportions convey magnitude (Natural Gas 75 TWh is visually dominant), but no explicit visual hierarchy or annotation highlights the key insight; viewer must read labels to find the story

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct Sankey diagram with proportional flow widths, source/target nodes, and multi-to-multi connections
• SC-02: Required Features (4/4) — Source/target/value mapped; node labels visible with totals; distinct colors per source; link opacity (alpha=0.65); no circular flows
• SC-03: Data Mapping (3/3) — All 10 flows correctly rendered with widths proportional to TWh values
• SC-04: Title & Legend (2/3) — Code has title="Energy Flow · sankey-basic · letsplot · anyplot.ai" — extra "Energy Flow ·" prefix deviates from required format {spec-id} · {library} · anyplot.ai; legend correctly shows Energy Source with four labeled colors

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows 4 sources, 3 targets, 10 flows, varying magnitudes (6–35 TWh); all inter-connections and flow crossing patterns represented
• DQ-02: Realistic Context (5/5) — Realistic energy sector scenario (Coal/Gas/Nuclear/Renewable → Industrial/Residential/Commercial) — neutral and real-world
• DQ-03: Appropriate Scale (4/4) — TWh values are plausible for national-scale energy distribution; relative proportions (Gas > Coal > Nuclear > Renewable) are realistic

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → tokens → data → layout → plot → save; no functions or classes despite inherent complexity
• CQ-02: Reproducibility (2/2) — Fully deterministic; all data hardcoded, no random generation needed
• CQ-03: Clean Imports (2/2) — All imported symbols used; no unused imports
• CQ-04: Code Elegance (2/2) — Appropriate complexity for building a Sankey from primitives; smooth curve computation is clear
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png (scale=3) and plot-{THEME}.html correctly

Library Mastery (5/10)

• LM-01: Idiomatic Usage (3/5) — Correct ggplot grammar with layer composition, scale_fill_manual, full theme system, labs — idiomatic but necessarily at the primitive geom level
• LM-02: Distinctive Features (2/5) — HTML export via ggsave is letsplot-distinctive; the Sankey construction uses generic primitives that could be replicated in plotnine with minor syntax changes

Score Caps Applied

• None — DE-01=5 > 2 and DE-02=4 > 2, so the "generic + no visual refinement" cap does not apply; no other caps triggered

Strengths

• Full Sankey built from scratch using letsplot primitives (geom_polygon + geom_rect + geom_text) — correct approach given no native Sankey geom; smooth bezier-like curves (smoothstep interpolation) produce polished ribbon shapes
• Okabe-Ito palette in correct canonical order: Coal=#009E73 (first), Natural Gas=#D55E00, Nuclear=#0072B2, Renewable=#CC79A7
• Theme-adaptive chrome correctly implemented throughout: PAGE_BG, ELEVATED_BG, INK, INK_SOFT all flip correctly; both renders pass readability check
• Realistic energy flow domain with sensible TWh values; node labels include totals aiding direct interpretation
• Perfect Data Quality (15/15) and Code Quality (10/10)

Weaknesses

• Title in code is "Energy Flow · sankey-basic · letsplot · anyplot.ai" — remove "Energy Flow · " prefix so title exactly matches sankey-basic · letsplot · anyplot.ai
• Node label text size=14 is slightly below the 16pt recommended minimum — increase to size=16 or size=18 for better legibility at 4800×2700px
• No visual hierarchy for data storytelling — consider adding labs(subtitle="Largest flow: Natural Gas → Residential (35 TWh)") or slightly increasing alpha on the dominant Natural Gas flow to create a visual focal point

Issues Found

1. SC-04 MINOR: Title has extra prefix "Energy Flow · " not required by spec
   • Fix: Change to labs(title="sankey-basic · letsplot · anyplot.ai"); optionally add subtitle="Largest flow: Natural Gas → Residential (35 TWh)" for storytelling
2. VQ-01 MINOR: Node label size=14 below 16pt minimum
   • Fix: Change size=14 to size=16 in both geom_text calls
3. DE-03 LOW: No explicit visual hierarchy or storytelling annotation
   • Fix: Add a subtitle in labs() highlighting the dominant flow, or increase alpha slightly on Natural Gas flows

AI Feedback for Next Attempt

Fix title to exact format sankey-basic · letsplot · anyplot.ai (remove "Energy Flow ·" prefix). Increase node label text size from 14 to 16 or 18. Add labs(subtitle="Largest flow: Natural Gas → Residential (35 TWh)") to provide a storytelling element — this single change improves DE-03 from 3 to 4 with minimal code change. These are all minor fixes; the overall implementation quality is high.

Verdict: APPROVED