feat(pygal): implement quiver-basic

[github-actions]

Implementation: quiver-basic - python/pygal

Implements the python/pygal version of quiver-basic.

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

Parent Issue: #1014

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1). Title "quiver-basic · pygal · anyplot.ai" is visible at top centre; X-axis label "Longitude (degrees)" and Y-axis label "Latitude (degrees)" are clearly readable. Five Okabe-Ito colours are used — green (#009E73), orange-red, blue, pink/purple, and yellow — representing magnitude bins labelled Calm / Light / Moderate / Fresh / Strong in the bottom legend. The data renders as connected line paths sweeping mostly horizontally across the chart in band-like groups, with small V-shaped arrowhead geometry visible at segment tips. The paths overlap, creating a visually busy pattern rather than discrete individual arrows at grid points. All text is readable against the light background — no light-on-light failures.

Dark render (plot-dark.png): Near-black background (#1A1A17). Title, axis labels, tick labels, and legend all render in light text and are clearly readable against the dark surface. Data colours are identical to the light render (Okabe-Ito positions 1–5); only the chrome flips. The same band-like sweeping paths are visible. No dark-on-dark text failures observed.

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

Score: 72/100

Category	Score	Max
Visual Quality	24	30
Design Excellence	10	20
Spec Compliance	11	15
Data Quality	12	15
Code Quality	10	10
Library Mastery	5	10
Total	72	100

Visual Quality (24/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set (title=28, labels=22, major_labels=18); all text readable in both themes
• VQ-02: No Overlap (5/6) — Tick and legend labels do not overlap
• VQ-03: Element Visibility (3/6) — Lines are visible but sweeping connected paths obscure individual arrow identity; the chart does not read as discrete arrows at grid points
• VQ-04: Color Accessibility (2/2) — Okabe-Ito palette is CVD-safe; five colours are distinguishable
• VQ-05: Layout & Canvas (3/4) — Plot fills canvas well; legend placement is clean
• VQ-06: Axis Labels & Title (2/2) — Longitude (degrees), Latitude (degrees), correct title format
• VQ-07: Palette Compliance (2/2) — First series #009E73; backgrounds #FAF8F1/#1A1A17; chrome is theme-adaptive in both renders

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Proper palette and theme tokens, but the visual confusion from connected sweeping paths undermines overall polish
• DE-02: Visual Refinement (3/6) — Background and legend are clean; but the chart body is visually noisy due to the connected-path rendering
• DE-03: Data Storytelling (3/6) — Meteorological context and wind-speed labels (Calm → Strong) are a good storytelling choice, but the circular rotation pattern is not visually legible from the rendering

Spec Compliance (11/15)

• SC-01: Plot Type (2/5) — Pygal.XY with stroke=True and None separators produces sweeping connected band paths, not discrete individual arrows at grid points; the output does not resemble a quiver plot
• SC-02: Required Features (3/4) — Direction encoding, magnitude scaling, grid-based positions, and colour-encoding of magnitude are all present
• SC-03: Data Mapping (3/3) — X=Longitude, Y=Latitude; full coordinate range visible
• SC-04: Title & Legend (3/3) — Title "quiver-basic · pygal · anyplot.ai"; legend labels Calm/Light/Moderate/Fresh/Strong

Data Quality (12/15)

• DQ-01: Feature Coverage (4/6) — Direction, magnitude variation, and colour encoding shown; data is correct but the circular pattern is not visually clear
• DQ-02: Realistic Context (5/5) — Counterclockwise wind rotation around a low-pressure centre is a real, neutral meteorological scenario
• DQ-03: Appropriate Scale (3/4) — Coordinates and vector magnitudes are plausible for a local-scale meteorological domain

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear structure; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — All imports used
• CQ-04: Code Elegance (2/2) — Reasonably clean; arrowhead geometry is appropriate
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly

Library Mastery (5/10)

• LM-01: Idiomatic Usage (3/5) — Uses pygal.XY with Style tokens and theme-adaptive chrome correctly
• LM-02: Distinctive Features (2/5) — Generates interactive HTML (pygal's key feature); but the chart approach is a generic XY line workaround, not exploiting any pygal-distinctive capability

Score Caps Applied

• None applied (DE-01=4 and DE-02=3 — "correct but boring" cap requires DE-01≤2 AND DE-02≤2, not triggered)

Strengths

• Correct Okabe-Ito palette (first series #009E73) with proper theme-adaptive style tokens; both renders pass the readability check
• Meaningful meteorological context (counterclockwise wind rotation around a low-pressure centre) with descriptive axis labels including units
• Font sizes explicitly set, producing readable text at 4800×2700 in both themes
• Smart magnitude-binned colouring with descriptive wind-speed labels (Calm → Strong)
• Perfect code quality: linear KISS structure, seed(42), clean imports, correct PNG + HTML output

Weaknesses

• Core rendering problem: grouping arrows by magnitude bin in pygal.XY with stroke=True creates sweeping connected band paths rather than discrete individual arrows at grid points — the output does not look like a quiver plot
• SC-01: the circular rotation pattern is not visually legible; a viewer cannot read individual vector directions or positions from the chart
• DE-01/DE-03 suffer because the visual confusion from connected paths undermines both aesthetic polish and data storytelling
• LM-02: no pygal-distinctive feature is exploited beyond html-export

Issues Found

1. SC-01 LOW (2/5): The fundamental approach of grouping arrows into series and adding them as connected paths does not produce individual arrows at grid points.
   • Fix: Add each individual arrow (shaft + two arrowhead legs) as separate, very short series — one series per arrow. This is verbose but ensures every arrow is visually independent. Alternatively, add each arrow's three segments (shaft, left barb, right barb) as separate (x,y) point pairs WITHOUT connecting dots between arrows, by relying solely on stroke=False and show_dots=True positioned only at tips, or by adding each component with a new chart.add() call per arrow. Another approach: render one large series per colour bin but ensure None separators work correctly (test that pygal version honours them) and avoid any SVG interpolation artefacts.
2. DE-01 / DE-03 LOW (4/8, 3/6): Visual noise from overlapping sweeping paths reduces both aesthetic quality and the ability to tell a story.
   • Fix: Once individual arrows are rendered correctly, the circular rotation pattern will be immediately visible and the storytelling will improve automatically. Additionally, consider reducing grid density or adding a subtle annotation calling out the low-pressure centre.

AI Feedback for Next Attempt

The core issue is that pygal.XY(stroke=True) with None separators groups all arrows of the same magnitude bin into one connected SVG path, producing sweeping horizontal bands instead of discrete arrows. To fix: restructure so each individual arrow is isolated — either (a) add each arrow's shaft + two arrowhead barbs as three very short separate chart.add() series (one per arrow, repeating colours from OKABE_ITO by index), or (b) use stroke=False, show_dots=True with carefully sized dot markers at arrowhead tips combined with the shaft lines to avoid connectivity artefacts. The meteorological context, palette, theme tokens, font sizes, and code structure are all good 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 renders on a warm off-white (#FAF8F1) background — correct for the light theme. Title "quiver-basic · pygal · anyplot.ai" is visible at top-center (small but legible). X-axis "Longitude (degrees)" and Y-axis "Latitude (degrees)" labels are present with tick marks at integer values from -3 to 3. Three arrow series are color-coded: green (#009E73 — Calm/Light), orange (#D55E00 — Moderate), and blue (#0072B2 — Fresh/Strong), forming a clear counterclockwise rotation pattern. Outer arrows (high magnitude) are large and clearly visible; center arrows (near-zero magnitude) are very small and barely distinguishable. Small dot markers appear at every segment endpoint along each arrow shaft and barb, adding slight visual noise. Legend sits at the bottom in three columns. All text is readable against the light background — no light-on-light failures.

Dark render (plot-dark.png): The plot renders on a near-black (#1A1A17) background — correct for the dark theme. Title and all axis/tick labels appear in light off-white (#F0EFE8), clearly readable against the dark surface — no dark-on-dark failures detected. Data colors are identical to the light render (#009E73, #D55E00, #0072B2) — only the chrome flips. Grid lines appear as subtle lighter lines on the dark background. Same arrow pattern, rotation, and center-arrow visibility issue as the light render. Both renders pass the legibility check.

Score: 77/100

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

Visual Quality (24/30)

• VQ-01: Text Legibility (6/8) — Font sizes explicitly set (28/22/18/16 px per guidelines) but render noticeably small at 4800×2700; text is readable in both themes but not prominent
• VQ-02: No Overlap (6/6) — 8×8 grid well-spaced, no text or arrow collisions
• VQ-03: Element Visibility (3/6) — Outer arrows clearly visible; center arrows (low magnitude near origin) very small and barely distinguishable
• VQ-04: Color Accessibility (2/2) — Green/orange/blue Okabe-Ito are CVD-safe with good luminance contrast
• VQ-05: Layout & Canvas (3/4) — Data spans -3 to 3 with reasonable canvas utilization; some empty margin space
• VQ-06: Axis Labels & Title (2/2) — "Longitude (degrees)" / "Latitude (degrees)" — descriptive with units
• VQ-07: Palette Compliance (2/2) — First series #009E73, second #D55E00, third #0072B2; backgrounds #FAF8F1 / #1A1A17 correct in both renders

Design Excellence (9/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured default; correct palette and layout, but dot markers at every segment endpoint add visual noise along arrow shafts and barbs, reducing polish
• DE-02: Visual Refinement (2/6) — Full x+y grid guides create a busy backdrop; dot markers at each segment point add noise; minimal refinement beyond basic color setup
• DE-03: Data Storytelling (3/6) — Magnitude binning into 3 wind-speed categories (Calm/Moderate/Fresh) adds a useful storytelling layer; rotation pattern is clearly communicated; no further focal emphasis

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Vector field arrows at grid positions — correct quiver plot
• SC-02: Required Features (4/4) — Grid positioning, direction encoding, length ∝ magnitude, uniform spacing, optional color-by-magnitude all present
• SC-03: Data Mapping (3/3) — X=Longitude, Y=Latitude; u=−y, v=x rotation correctly mapped
• SC-04: Title & Legend (3/3) — "quiver-basic · pygal · anyplot.ai"; Legend: Calm/Light, Moderate, Fresh/Strong

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows direction, magnitude variation, and grid pattern; near-zero arrows at centre excluded
• DQ-02: Realistic Context (5/5) — Wind field / counterclockwise rotation around a low-pressure centre — real meteorological scenario
• DQ-03: Appropriate Scale (4/4) — Degrees of lat/lon (−3 to 3) plausible for a local synoptic wind pattern

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) — No functions/classes; linear flow
• CQ-02: Reproducibility (2/2) — np.random.seed(42) and np.random.RandomState(42)
• CQ-03: Clean Imports (2/2) — All imports used
• CQ-04: Code Elegance (1/2) — Arrow construction is complex but necessary for pygal; shuffle logic slightly verbose
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Uses pygal.XY with allow_interruptions and Style object correctly
• LM-02: Distinctive Features (3/5) — Uses allow_interruptions for segment breaks, legend_at_bottom_columns, and HTML interactive output — pygal-specific capabilities

Score Caps Applied

• None — DE-01=4 exceeds the cap threshold of ≤2

Strengths

• Correct quiver arrow construction using pygal XY line segments with allow_interruptions, faithfully simulating shaft and barbs
• Perfect spec compliance: correct title format, descriptive axis labels with units, magnitude-binned color-coding as an additional insight layer
• Proper theme adaptation: correct #FAF8F1 / #1A1A17 backgrounds with Okabe-Ito palette, both renders pass legibility checks
• Wind field scenario (counterclockwise rotation, meteorological labels) is realistic and contextually meaningful

Weaknesses

• Dot markers at segment endpoints (show_dots=True, dot_size=4) create noise on every arrow shaft and barb — set show_dots=False so only clean arrow lines are visible
• Center arrows are too small: near-origin vectors (low magnitude) are barely distinguishable — increase arrow_scale (e.g., 0.28–0.30) or add a minimum shaft length to keep the smallest arrows legible
• Full x+y grid adds visual clutter — disable one or both axes guides (show_x_guides=False) to let arrows breathe; or leave only horizontal guides
• Font sizes appear small at 4800×2700: bump title to 36–40, axis labels to 28 for more visual weight

Issues Found

1. VQ-03 LOW: Center arrows near origin are nearly invisible due to very small magnitude
   • Fix: Increase arrow_scale to ~0.28 or enforce a minimum arrow length so all arrows remain distinguishable
2. DE-02 LOW: Dot markers at every segment endpoint and full grid create visual busyness
   • Fix: Set show_dots=False (or dot_size=0) and disable x-guides (show_x_guides=False)
3. VQ-01 MINOR: Text renders small at full canvas resolution
   • Fix: Increase title_font_size to 36–40, label_font_size to 28

AI Feedback for Next Attempt

Three targeted fixes will push this above 80: (1) set show_dots=False to remove the segment-endpoint dot noise and reveal clean arrow lines, (2) increase arrow_scale to ~0.28 or add a minimum shaft length so center arrows are legible, (3) disable x grid guides (show_x_guides=False) for a cleaner backdrop. Additionally, bump title_font_size to 36 and label_font_size to 28 for better readability at 4800×2700. The core quiver construction, palette, and theme adaptation are already correct — this is polish work only.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 2/4

Applied fixes based on AI review feedback.

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

---

🤖 impl-repair

[claude]

AI Review - Attempt 3/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white (#FAF8F1) background. It shows 64 arrows arranged in an 8×8 grid spanning approximately -3 to 3 on both axes, depicting a counterclockwise wind rotation pattern around a low-pressure centre. Arrows are colour-coded in three Okabe-Ito groups: green (#009E73) for 'Calm / Light' (small arrows near the centre), orange (#D55E00) for 'Moderate', and blue (#0072B2) for 'Fresh / Strong' (large arrows at the periphery). The title 'quiver-basic · pygal · anyplot.ai' is readable at the top in dark ink. Axis labels 'Longitude (degrees)' and 'Latitude (degrees)' are clearly visible. Tick labels (-3 to 3) are readable. A three-column legend sits at the bottom. All text is readable against the light background — legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on a near-black (#1A1A17) surface. The three data colours are identical to the light render (green, orange, blue in Okabe-Ito order — only the chrome flips). Title text and axis labels appear in light ink (#F0EFE8) against the dark background. Tick labels are light-coloured and readable. The grid lines are visible but subtle. No dark-on-dark failures observed — all text elements are clearly legible on the dark surface. Legibility verdict: PASS.

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

Score: 77/100

Category	Score	Max
Visual Quality	26	30
Design Excellence	10	20
Spec Compliance	14	15
Data Quality	13	15
Code Quality	8	10
Library Mastery	6	10
Total	77	100

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title=28, label=22, major_label=18, legend=16); all text readable in both themes. Minor deduction: legend at bottom is on the smaller end.
• VQ-02: No Overlap (5/6) — Arrows are well-spaced; no text collision. Minor deduction: peripheral arrows are denser.
• VQ-03: Element Visibility (5/6) — Arrows and barb segments clearly visible. Calm/light arrows near the origin are very small (inherent to data), which slightly reduces visibility.
• VQ-04: Color Accessibility (2/2) — First three Okabe-Ito colours used; colourblind-safe combination.
• VQ-05: Layout & Canvas (3/4) — Good canvas utilisation; legend placement works well. Minor wasted whitespace at left and right edges.
• VQ-06: Axis Labels & Title (2/2) — Both axes labelled with units ('Longitude (degrees)', 'Latitude (degrees)').
• VQ-07: Palette Compliance (2/2) — First series is #009E73, followed by #D55E00 and #0072B2 in canonical order. Light background is #FAF8F1, dark is #1A1A17. Chrome is theme-adaptive in both renders.

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Correct Okabe-Ito palette applied, custom style object with explicit sizing. Looks like a well-configured default rather than a publication-ready design.
• DE-02: Visual Refinement (3/6) — Custom background and INK_MUTED grid tone applied. Grid lines visible but not overly prominent. Pygal's frame cannot easily have spines removed. Above minimal defaults.
• DE-03: Data Storytelling (3/6) — Binning vectors into Beaufort-scale wind speed categories (Calm/Light, Moderate, Fresh/Strong) adds meteorological context. The circular rotation pattern creates a clear focal point. Above the default 'data dump' level.

Spec Compliance (14/15)

• SC-01: Plot Type (4/5) — Correct quiver/vector-field concept implemented. Pygal has no native quiver type; XY chart with segment breaks and arrowhead barbs is the correct approach. Deduction: approximation rather than native quiver API.
• SC-02: Required Features (4/4) — Grid of arrows, direction encoding, length proportional to magnitude, uniform spacing, and optional colour encoding by magnitude — all present.
• SC-03: Data Mapping (3/3) — X=longitude, Y=latitude; u=-y, v=x circular rotation correctly implemented and displayed.
• SC-04: Title & Legend (3/3) — Title is exactly 'quiver-basic · pygal · anyplot.ai'. Legend labels (Calm / Light, Moderate, Fresh / Strong) are descriptive and meaningful.

Data Quality (13/15)

• DQ-01: Feature Coverage (5/6) — Shows varying magnitudes (calm at centre, strong at periphery), circular rotation pattern, colour coding by wind speed bin, 64 arrows providing good field coverage.
• DQ-02: Realistic Context (4/5) — Wind rotation around a low-pressure centre is a genuine meteorological scenario. Beaufort-scale bin names add real-world grounding. Mathematical model (u=-y, v=x) is slightly abstract.
• DQ-03: Appropriate Scale (4/4) — Geographic range of ±3 degrees is sensible for mesoscale wind analysis; wind speed classifications align with Beaufort scale.

Code Quality (8/10)

• CQ-01: KISS Structure (2/3) — Follows Imports → Data → Plot → Save without functions/classes. Arrow-segment construction loop adds complexity; the sys.path manipulation (necessary because the file is named pygal.py) adds boilerplate.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) and np.random.RandomState(42) both set.
• CQ-03: Clean Imports (2/2) — importlib, os, sys, numpy — all used; pygal and Style imported dynamically as required.
• CQ-04: Code Elegance (1/2) — Functional but the arrow-segment construction (segment grouping, shuffle, flatten) is verbose. Necessary given pygal's lack of native quiver support, but could be condensed.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; uses current pygal API.

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Uses pygal.XY with allow_interruptions=True and None-terminated segments — the idiomatic pygal pattern for disconnected lines. Style object used correctly for all theming.
• LM-02: Distinctive Features (3/5) — Leverages allow_interruptions for segment breaks, stroke_style dict, legend_at_bottom_columns, and HTML interactive export. These are pygal-specific features that differentiate this from a generic implementation.

Score Caps Applied

• None — DE-01=4 and DE-02=3 (both above 2), so 'correct but boring' cap does not apply. No other cap conditions triggered.

Strengths

• Correct Okabe-Ito palette with #009E73 as first series; theme-adaptive chrome works in both renders
• Beaufort-scale wind speed bins add real meteorological context and create natural data storytelling
• allow_interruptions=True with None breaks is the idiomatic pygal pattern for disconnected arrow segments
• All font sizes explicitly set to style-guide values; both renders fully legible
• Title format exactly matches required pattern

Weaknesses

• Arrow-segment construction loop is verbose — the segment grouping, shuffle, and flatten steps could be condensed into a more elegant helper pattern
• Small calm/light arrows near the origin are very tiny and could benefit from a minimum length floor to improve visibility
• Design refinement is moderate — pygal's limited spine control constrains polish, but whitespace and grid subtlety could be improved

Issues Found

1. DE-01 MODERATE: Styling is correct but looks like a well-configured default rather than publication-ready design. Custom background and Okabe-Ito palette are present but no further visual hierarchy beyond colour bins.
2. CQ-01/CQ-04 MINOR: Arrow construction logic (segment grouping, shuffle, flatten) is more complex than necessary — could be streamlined while preserving correctness.

AI Feedback for Next Attempt

The wind rotation scenario and magnitude-bin storytelling are solid. To improve: (1) consider increasing dot_size or stroke width to make centre arrows more visible; (2) consolidate the arrow-segment construction into a cleaner list comprehension to reduce verbosity; (3) explore whether a wider range or fewer, bolder arrows would increase visual impact on the large canvas.

Verdict: APPROVED