feat(pygal): implement rug-basic

[github-actions]

Implementation: rug-basic - python/pygal

Implements the python/pygal version of rug-basic.

File: plots/rug-basic/implementations/python/pygal.py

Parent Issue: #978

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Rug plot on a warm off-white (#FAF8F1) background. Vertical tick marks span the x-axis from approximately 50ms to 450ms with clear multi-modal clustering: a sparse group at 50–100ms, a dense cluster at ~150ms, a moderately dense cluster at ~250ms, and a tighter cluster at ~400ms. The leftmost clusters render in clearly visible bright brand green (#009E73). The 400ms right cluster appears noticeably darker, almost dark-green/near-black, despite the implementation specifying colors=(BRAND,). The title "rug-basic · pygal · anyplot.ai" is legible at the top. The x-axis label "Response Time (ms)" and tick labels (100, 200, 300, 400, 500) are readable. The ticks occupy only the lower ~35% of canvas height with a large empty expanse above them. All text is readable against the light background.

Dark render (plot-dark.png): Same structure on a near-black (#1A1A17) background. Title, x-axis label, and tick labels are rendered in light text and remain legible. The left cluster (~50–200ms) and center cluster (~250ms) are clearly visible in brand green. The right cluster (~400ms) is rendered in a near-black color that is essentially invisible against the dark background — this is a dark-on-dark failure. The data colors are NOT identical to the light render for this cluster; what appeared dark-green on the light background becomes completely blended into the near-black background here. This represents a rendering failure affecting ~10% of data points. Large empty canvas space above the ticks is also present in this render.

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

Score: 78/100

Category	Score	Max
Visual Quality	22	30
Design Excellence	11	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	9	10
Library Mastery	6	10
Total	78	100

Visual Quality (22/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set (title=28px, label=22px, ticks=18px); all text readable in both themes
• VQ-02: No Overlap (6/6) — No text overlap; tick mark overlap is expected for rug plots
• VQ-03: Element Visibility (3/6) — Most ticks visible but dark theme right cluster (~400ms, ~10% of data) is near-invisible against #1A1A17 background
• VQ-04: Color Accessibility (1/2) — Brand green is CVD-safe overall, but the dark ticks in dark render create contrast failure for that subset
• VQ-05: Layout & Canvas (1/4) — Severe canvas underutilization: tick marks only occupy the lower ~35% of canvas height; top 60%+ is completely empty; overall data area is ~20% of canvas
• VQ-06: Axis Labels & Title (2/2) — "Response Time (ms)" is descriptive with units; no y-label is appropriate for a rug plot
• VQ-07: Palette Compliance (1/2) — Backgrounds correct (#FAF8F1 / #1A1A17); text is theme-adaptive; but some tick series render in near-black instead of brand green, suggesting pygal cycles beyond the single provided color

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured, clean single-color rug plot; correct brand green usage; not publication-exceptional
• DE-02: Visual Refinement (3/6) — No grid, no legend, hidden y-axis: clean choices. However the large empty canvas space above ticks hurts overall composition
• DE-03: Data Storytelling (4/6) — Multi-modal API response time distribution with clear clusters, gaps, and outlier group tells an effective story; viewer immediately sees fast/medium/slow categories

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct rug plot via pygal XY chart with vertical line segments
• SC-02: Required Features (4/4) — Tick marks present, x-axis positioning, semi-transparency (opacity=0.7), consistent height
• SC-03: Data Mapping (3/3) — Response time values correctly mapped to x-axis
• SC-04: Title & Legend (3/3) — Title "rug-basic · pygal · anyplot.ai" matches required format; no legend appropriate for single-series

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all rug plot features: clustering, gaps, sparse and dense regions, outlier cluster
• DQ-02: Realistic Context (5/5) — API response times with cache hits, typical responses, and slow outliers: realistic real-world scenario
• DQ-03: Appropriate Scale (4/4) — 50–500ms response time range is factually accurate for web APIs

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) — Imports → Data → Style → Chart → Save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — All imports used; sys path manipulation required for pygal shadowing
• CQ-04: Code Elegance (1/2) — Adding 100 individual series creates 100 pygal series which causes the color cycling bug; the sys.path manipulation is a code smell
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly for pygal

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Style object and XY chart used correctly with theme tokens; but 100 individual chart.add() calls is a non-idiomatic workaround causing the color cycling bug
• LM-02: Distinctive Features (3/5) — Saves interactive HTML where each tick tooltip shows the exact response time value; this is genuinely a pygal-specific capability

Score Caps Applied

• None

Strengths

• Excellent data quality: realistic multi-modal API response time distribution with clear clusters, gaps, and outlier group
• Perfect spec compliance: all required rug plot features implemented correctly
• Theme tokens applied correctly to all chrome elements (backgrounds, text, grid)
• Interactive HTML export leverages pygal's distinctive capability — per-tick tooltips with exact values
• Clean code structure with seed for reproducibility

Weaknesses

• Dark-on-dark rendering failure: right cluster (~400ms) ticks appear near-black and are nearly invisible on the #1A1A17 dark background — the 100-series loop causes pygal to cycle colors beyond the single provided BRAND color
• Severe canvas underutilization: tick marks only fill the lower ~35% of the 2700px canvas height; the top 60%+ is empty — reduce margins and adjust range to fill the canvas better
• Color cycling root cause: for val in values: chart.add(...) adds 100 separate series and pygal cycles its color engine past the single entry for later series — fix by passing explicit color in stroke_style or expanding the colors tuple to 100 entries

Issues Found

1. VQ-03 / VQ-07 COLOR BUG: Dark render shows near-black ticks at ~400ms cluster that are invisible on dark background. Root cause: adding 100 series with a 1-element colors tuple causes pygal to cycle colors, producing dark non-green ticks for later series.
   • Fix: Pass stroke_style={'color': BRAND, 'width': 8} explicitly in each chart.add() call, or set colors=(BRAND,) * 100 to ensure all series use brand green
2. VQ-05 CANVAS WASTE: Tick marks occupy only ~35% of canvas height. Reduce margin_top (try 80–120px), reduce range from (0, 0.2) to (0, 0.18), and increase tick_top to 0.16 to better fill the vertical canvas.

AI Feedback for Next Attempt

Fix the color cycling bug first: explicitly set stroke_style={'color': BRAND, 'width': 8} in each chart.add() call so all 100 series use brand green regardless of pygal's internal cycling. Then fix canvas utilization: reduce margin_top to ~80px and adjust the range so ticks fill at least 50% of canvas height. These two changes should bring VQ-03 from 3→6, VQ-07 from 1→2, and VQ-05 from 1→3, pushing 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): The plot uses a warm off-white background (#FAF8F1). Brand green (#009E73) vertical rug tick marks are clearly visible, drawn using pygal's XY chart with stroke mode. Three distinct density clusters are visible: a dense cluster around 150–200 ms, a medium-density cluster around 250–300 ms, and a sparse outlier cluster near 400 ms, with scattered marks between 50–100 ms (cache hits). The title "rug-basic · pygal · anyplot.ai" appears at the top in dark ink; the x-axis label "Response Time (ms)" is clearly readable; tick labels (100, 200, 300, 400, 500) are readable. The marks occupy approximately 55% of the chart area height, leaving some empty space above which is expected for a standalone rug plot design. All text is readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The plot uses a near-black background (#1A1A17). The brand green data marks are identical in color and position to the light render — only the chrome flips. Title and axis label text appear in light-colored ink; tick labels are readable against the dark background. No dark-on-dark failures are observed. Legibility verdict: PASS.

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

Score: 81/100

Category	Score	Max
Visual Quality	26	30
Design Excellence	10	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	9	10
Library Mastery	6	10
Total	81	100

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set (title 28px, labels 22px, major labels 18px); all text readable in both themes, though title appears somewhat small at full 4800×2700 resolution
• VQ-02: No Overlap (6/6) — No text overlap; data mark density overlap is expected and handled by transparency
• VQ-03: Element Visibility (5/6) — Rug marks are clearly visible with stroke_width=8 and opacity=0.7; good thickness; marks slightly tall (75% of y-range) but acceptable for standalone rug plot
• VQ-04: Color Accessibility (2/2) — Single brand green on appropriate backgrounds; high contrast; CVD-safe
• VQ-05: Layout & Canvas (2/4) — Content fills approximately 45–50% of canvas; some wasted vertical space above the marks (inherent to standalone rug plot design, but canvas still somewhat empty)
• VQ-06: Axis Labels & Title (2/2) — "Response Time (ms)" includes unit; title correct
• VQ-07: Palette Compliance (2/2) — Brand green #009E73 used correctly; warm off-white (#FAF8F1) and near-black (#1A1A17) backgrounds; both renders theme-correct

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Clean, well-configured result using brand green with custom Style tokens; minimal design is appropriate for a rug plot but does not rise above a well-configured default
• DE-02: Visual Refinement (3/6) — Active refinements present: no grid lines, no legend, no y-axis labels, custom margins, semi-transparent marks; however, default pygal chart border/frame remains and overall polish stops short of fully refined
• DE-03: Data Storytelling (3/6) — Multi-modal data is intentionally designed to reveal clustering; density patterns (fast cache hits, typical responses, slow outliers) are immediately visible; natural visual hierarchy from mark density

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct rug plot using XY chart with vertical strokes; individual data points as tick marks along x-axis
• SC-02: Required Features (4/4) — Semi-transparency (opacity=0.7) ✓; consistent tick height ✓; x-axis positioning ✓; reveals clustering and gaps ✓
• SC-03: Data Mapping (3/3) — Values mapped to x-axis correctly; all 100 observations visible; y-axis hidden (appropriate)
• SC-04: Title & Legend (3/3) — Title "rug-basic · pygal · anyplot.ai" correct; no legend appropriate for single-series plot

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Multi-modal distribution showing clustering (150ms, 250ms, 400ms clusters), gaps, sparse outliers, and dense regions — all core rug plot features demonstrated
• DQ-02: Realistic Context (5/5) — API response times are a natural, neutral, real-world scenario; values and distributions are plausible
• DQ-03: Appropriate Scale (4/4) — 30–500 ms range realistic for API calls; multi-modal shape (fast cache hits + typical + slow) is factually plausible

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → data → style → chart → loop → save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ✓
• CQ-03: Clean Imports (2/2) — All imports used; sys/os/numpy/pygal/Style all necessary
• CQ-04: Code Elegance (1/2) — The per-point series loop (100 chart.add() calls) is the only viable approach in pygal but creates 100 series, which may cause performance issues in the HTML; the sys.path manipulation pattern is explained by comment
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html ✓

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Correct use of pygal.XY with stroke=True; proper Style object for theming; the per-series approach for individual rug marks is the required pygal idiom for this type of plot
• LM-02: Distinctive Features (3/5) — HTML export is a distinctive pygal feature; each tick mark is labeled with its value ("150.3 ms") so the HTML version provides hover-over-tick interactivity showing exact response times — a genuinely useful feature that leverages pygal's interactive strength

Score Caps Applied

• None applied

Strengths

• Perfect spec compliance and data quality — multi-modal API response time data perfectly demonstrates rug plot clustering features
• Correct palette and theme implementation across both light and dark renders with no chrome failures
• Leverages pygal's interactive HTML output: each rug tick reveals its exact value on hover
• Semi-transparency with brand green creates natural density encoding

Weaknesses

• Title appears somewhat small at full 4800×2700 resolution; consider increasing title_font_size to 32–36px
• Significant empty vertical space above the rug marks; consider reducing the y-range (e.g., range=(0, 0.12)) to make the marks fill more of the chart area, or add a secondary complementary element (e.g., KDE curve overlay)
• Default pygal chart border/frame still visible; aesthetic polish could be elevated further
• DE-01 could be improved with a subtle annotation or visual callout highlighting the three performance clusters

Issues Found

1. VQ-01 MINOR: Title font size (28px) renders small at 4800×2700 resolution
   • Fix: Increase title_font_size to 32–36px for better prominence
2. VQ-05 MINOR: Empty canvas area above rug marks reduces canvas utilization
   • Fix: Tighten y-range from (0, 0.2) to (0, 0.12) so marks fill 90%+ of chart height
3. DE-02 MINOR: Default pygal chart border visible
   • Fix: Investigate pygal border/frame removal options or accept as library constraint

AI Feedback for Next Attempt

Increase title_font_size to 34px. Reduce range from (0, 0.2) to (0, 0.12) to fill the chart area more efficiently. Consider adding a faint KDE envelope or density annotation to elevate data storytelling (DE-03). The core implementation is solid — focus improvements on canvas utilization and title legibility.

Verdict: APPROVED