feat(plotly): implement quiver-basic

[github-actions]

Implementation: quiver-basic - python/plotly

Implements the python/plotly version of quiver-basic.

File: plots/quiver-basic/implementations/python/plotly.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). A 15x15 grid of brand-green (#009E73) arrows forms a rotational flow pattern consistent with u=-y, v=x (a counterclockwise vortex). All arrows are rendered at a uniform length -- length does not vary with true vector magnitude. Underlying scatter markers at each arrow base use a green-to-blue sequential gradient (imprint_seq) keyed to wind speed, growing bluer toward the outer edge. Title, axis titles ("X Position (km)", "Y Position (km)"), tick labels, and the "Wind Speed (m/s)" colorbar title/ticks are all dark ink and clearly readable against the light background. All text is readable — no light-on-light issues.

Dark render (plot-dark.png): Warm near-black background (#1A1A17), not pure black. Arrow color (#009E73) and the scatter-marker green-to-blue gradient are pixel-identical to the light render — only chrome flipped, as required. Title, axis titles, tick labels, and colorbar text switch to light ink / soft light-gray tokens and remain clearly legible. All text is readable — no dark-on-dark failures detected.

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

Score: 82/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8)
• VQ-02: No Overlap (6/6)
• VQ-03: Element Visibility (5/6)
• VQ-04: Color Accessibility (2/2)
• VQ-05: Layout & Canvas (3/4)
• VQ-06: Axis Labels & Title (2/2)
• VQ-07: Palette Compliance (2/2)

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) - Above default, but the dense uniform-length arrow grid limits polish
• DE-02: Visual Refinement (4/6) - Subtle grid and default spines, colorbar margin slightly unbalances layout
• DE-03: Data Storytelling (4/6) - Color gradient from calm center to faster edge creates a clear focal point

Spec Compliance (13/15)

• SC-01: Plot Type (5/5)
• SC-02: Required Features (2/4) - Arrow length is normalized to a fixed value instead of proportional to magnitude
• SC-03: Data Mapping (3/3)
• SC-04: Title & Legend (3/3)

Data Quality (12/15)

• DQ-01: Feature Coverage (4/6) - Magnitude shown via color but not via arrow length (the primary quiver-plot encoding)
• DQ-02: Realistic Context (5/5)
• DQ-03: Appropriate Scale (3/4) - Wind speeds (0-2.83 m/s) are too gentle to read as "cyclonic"

Code Quality (10/10)

• CQ-01: KISS Structure (3/3)
• CQ-02: Reproducibility (2/2)
• CQ-03: Clean Imports (2/2)
• CQ-04: Code Elegance (2/2)
• CQ-05: Output & API (1/1)

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5)
• LM-02: Distinctive Features (3/5) - create_quiver + layered scatter-colorbar composition is plotly-specific

Score Caps Applied

• None

Strengths

• Correct plot type: ff.create_quiver renders a true quiver field with direction correctly derived from u=-y, v=x (counterclockwise rotation), matching the described cyclonic vortex.
• Theme handling is fully correct in both renders: PAGE_BG, INK, INK_SOFT, and GRID all branch on ANYPLOT_THEME and match the required #FAF8F1/#1A1A17 hex values with no dark-on-dark or light-on-light failures.
• Imprint palette compliance: arrows use brand green #009E73, and the magnitude overlay correctly uses the sequential imprint_seq colormap (green → blue) since wind speed is single-polarity data, not the diverging scale.
• Smart redundant encoding: layering a go.Scatter trace colored by magnitude on top of the quiver arrows adds a colorbar-driven magnitude read that a plain create_quiver call couldn't provide on its own.
• All font sizes are explicitly set (title, axis titles, tick labels, colorbar title/ticks) and the title fontsize scales by length via a documented ratio formula, avoiding overflow with the long mandated title.
• Clean, KISS-structured code: single top-to-bottom script, no functions/classes, deterministic data generation, only necessary imports.

Weaknesses

• Spec violation (most important fix): the spec explicitly requires arrow "length proportional to its magnitude," but the implementation normalizes every vector to the exact same length (u_norm = u/magnitude*scale_factor with a fixed scale_factor=0.2). Every arrow in both renders is visually the same length regardless of true wind speed, so the primary quiver-plot encoding channel (length) carries no information — only direction and the separate scatter-marker color show magnitude. Fix by scaling arrow length by relative magnitude (e.g. u_norm = u * scale_factor / max_magnitude) so the radial gradient in speed is visible in the arrows themselves, while keeping near-center arrows still visible.
• The wind-speed values are physically very low for a "cyclonic wind vortex" — magnitude ranges only 0-2.83 m/s (light-air/light-breeze range), not the tens of m/s associated with real cyclonic wind systems. Either scale the underlying u/v field (or add a physically-motivated multiplier before computing magnitude) so speeds fall in a plausible cyclone range (roughly 5-30 m/s), or soften the "cyclonic" framing in the title/description to match a gentle eddy.
• Styling is solid but still close to a well-configured default — the 225-arrow field plus scatter dots is a little visually busy at this density; consider a lighter marker size or slightly more transparent arrows so the vortex structure reads more clearly as a focal point.
• The right margin (r=100) reserved for the colorbar makes the plot area sit slightly left-of-center within the square canvas; tightening the colorbar thickness/margin would rebalance whitespace.

Issues Found

1. SC-02 / DQ-01 HIGH: Arrow length is normalized to a constant value, so the spec's "length proportional to magnitude" requirement is not represented by the arrows.
   • Fix: Scale u_norm/v_norm by relative magnitude (divide by max(magnitude) instead of by each vector's own magnitude) so arrow length varies radially, then re-tune scale_factor for visibility.
2. DQ-03 MEDIUM: Wind speed values (0-2.83 m/s) are too gentle for a "cyclonic" scenario.
   • Fix: Multiply the u/v field by a physically-motivated factor so peak magnitude lands in a realistic cyclone range (~5-30 m/s).
3. DE-01/DE-02 LOW: Design is above-default but still fairly close to a configured default given the dense uniform grid.
   • Fix: Consider slightly smaller/more transparent scatter markers or thinner arrow lines to let the vortex structure read as a cleaner focal point.

AI Feedback for Next Attempt

Make arrow length proportional to relative magnitude instead of normalizing every vector to a fixed length — this is a direct spec requirement and currently the single biggest gap. Scale the underlying wind field so peak speeds read as a plausible cyclonic vortex (roughly 5-30 m/s) rather than a light breeze. Keep the theme handling, Imprint palette usage, and colorbar overlay exactly as-is — those are working well.

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 consistent with #FAF8F1. A 13x13 grid of brand-green (#009E73) arrows forms a counterclockwise rotational flow pattern consistent with u=-y, v=x. All arrows appear visually uniform in length — length does not vary with vector magnitude in this render. Underlying scatter markers at each arrow base use the green-to-blue sequential imprint_seq gradient keyed to wind speed; the colorbar spans only 0 to ~2.8 m/s. Title, axis titles ("X Position (km)", "Y Position (km)"), tick labels, and the "Wind Speed (m/s)" colorbar title/ticks are all dark ink and clearly readable against the light background. All text is readable — no light-on-light issues.

Dark render (plot-dark.png): Warm near-black background consistent with #1A1A17. Arrow color (#009E73) and the scatter-marker gradient are pixel-identical to the light render — only chrome flipped, as required. Title, axis titles, tick labels, and colorbar text switch to light ink / soft light-gray tokens and remain clearly legible. Same uniform-arrow-length and 0-2.8 m/s colorbar characteristics as the light render. All text is readable — no dark-on-dark failures.

Critical finding — the supplied renders are stale, not the output of the current commit. I directly executed the current committed source (plots/quiver-basic/implementations/python/plotly.py at HEAD, commit e3d18ee5b) locally with ANYPLOT_THEME=light. That run produces a colorbar spanning 0–28.3 m/s (matching WIND_SPEED_SCALE = 10.0 in the current source) and arrows whose length clearly grows from the vortex centre outward (matching the length_frac formula in the current source) — materially different from the plot-light.png/plot-dark.png attached to this PR. For comparison, I also rendered the pre-repair commit (dd432f135) locally, and it reproduces the attached plot-light.png pixel-for-pixel (same 0-2.8 m/s colorbar, same uniform arrow lengths, same marker size/opacity). This proves the images under review here are the attempt-1 (pre-repair) render, not the fix that was actually committed.

Both paragraphs above describe both renders as attached; the pipeline-mismatch note is additional diagnostic context from direct source verification.

Score: 76/100

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

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8)
• VQ-02: No Overlap (6/6)
• VQ-03: Element Visibility (4/6) - Arrows are visually uniform length in the provided render; magnitude only reads through color, not through the primary quiver encoding channel
• VQ-04: Color Accessibility (2/2)
• VQ-05: Layout & Canvas (3/4)
• VQ-06: Axis Labels & Title (2/2)
• VQ-07: Palette Compliance (2/2)

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) - Above default via the colorbar overlay composition, but the dense uniform grid in the provided render limits polish
• DE-02: Visual Refinement (4/6) - Subtle grid, reasonable margins; colorbar sizing tightened since attempt 1
• DE-03: Data Storytelling (3/6) - Color gradient creates a focal point, but no visible advancement over attempt 1 in the render under review

Spec Compliance (12/15)

• SC-01: Plot Type (5/5)
• SC-02: Required Features (1/4) - Spec-mandated "length proportional to magnitude" still not visible in the provided render (all arrows uniform length), for the second consecutive review cycle — see pipeline-failure note
• SC-03: Data Mapping (3/3)
• SC-04: Title & Legend (3/3)

Data Quality (10/15)

• DQ-01: Feature Coverage (3/6) - Magnitude only encoded via color in the provided render, not via arrow length (the primary quiver-plot encoding), for the second consecutive review cycle
• DQ-02: Realistic Context (5/5)
• DQ-03: Appropriate Scale (2/4) - Wind speeds in the provided render (0-2.83 m/s) remain too gentle for a "cyclonic" vortex — see pipeline-failure note

Code Quality (10/10)

• CQ-01: KISS Structure (3/3)
• CQ-02: Reproducibility (2/2)
• CQ-03: Clean Imports (2/2)
• CQ-04: Code Elegance (2/2)
• CQ-05: Output & API (1/1)

Library Mastery (6/10)

• LM-01: Idiomatic Usage (4/5)
• LM-02: Distinctive Features (2/5) - create_quiver + layered scatter-colorbar composition is plotly-specific, but no new distinctive feature added since attempt 1

Score Caps Applied

• None (standard caps not triggered; score reflects direct deductions plus the pipeline-mismatch finding below)

Strengths

• Correct plot type: ff.create_quiver renders a true quiver field with direction correctly derived from u=-y, v=x (counterclockwise rotation), matching the described cyclonic vortex.
• Theme handling is fully correct in both provided renders: PAGE_BG, INK, INK_SOFT, and GRID all branch on ANYPLOT_THEME and match the required #FAF8F1/#1A1A17 hex values with no dark-on-dark or light-on-light failures.
• Imprint palette compliance: arrows use brand green #009E73, and the magnitude overlay correctly uses the sequential imprint_seq colormap since wind speed is single-polarity data.
• Reading the current source directly confirms both attempt-1 weaknesses were genuinely fixed in code: arrow length now scales with relative magnitude via length_frac, and WIND_SPEED_SCALE = 10.0 pushes peak wind speed into a plausible cyclone range (~28 m/s). This is correct, good engineering work by the repair step.
• Clean, KISS-structured code: single top-to-bottom script, no functions/classes, deterministic data generation, only necessary imports.

Weaknesses

• CRITICAL — PIPELINE FAILURE, not a code defect: the plot-light.png / plot-dark.png supplied for this review do not reflect the current commit (e3d18ee5b). Evidence: (1) the colorbar in the provided renders tops out at ~2.8 m/s, but directly executing the current plots/quiver-basic/implementations/python/plotly.py locally (ANYPLOT_THEME=light) produces a colorbar spanning 0-28.3 m/s, matching WIND_SPEED_SCALE=10.0 in the current source. (2) the provided renders show every arrow at a visually uniform length, but executing the current source produces arrows whose length clearly grows from the vortex centre outward, matching the length_frac formula in the current source. (3) rendering the pre-repair commit (dd432f135) locally reproduces the provided plot-light.png pixel-for-pixel (same 0-2.8 m/s colorbar, same uniform arrow lengths, same marker size/opacity). This proves the images attached to this PR for review are the stale attempt-1 (pre-repair) render, not the output of the fix that was actually committed. Do not make further code edits to fix arrow-length-proportionality or wind-speed-realism — both are already correctly implemented in the current source. Instead, the workflow needs to re-render plot-light.png/plot-dark.png from the current HEAD commit before the next AI review, or this repair loop will keep scoring against a stale artifact and can never converge.
• As shown in the (stale) provided renders: every arrow is the same length regardless of position, so the spec's "length proportional to magnitude" requirement is not visible in what was reviewed — though understood to already be fixed in the underlying source per the note above.
• As shown in the (stale) provided renders: wind speed only reaches ~2.8 m/s (light-air range), too gentle for a "cyclonic" vortex — though understood to already be fixed in the underlying source (peak ~28 m/s) per the note above.
• Cannot fully evaluate Design Excellence / Library Mastery improvements for this attempt since the visual artifact under review is unchanged from attempt 1 — re-review once fresh renders are available.

Issues Found

1. PIPELINE CRITICAL: plot_images/plot-light.png and plot-dark.png supplied for this review are byte-for-byte reproducible from the pre-repair commit (dd432f135), not from the current HEAD (e3d18ee5b) which already fixes both previously-flagged issues.
   • Fix: Re-render both PNG/HTML artifacts from the current commit before the next AI review runs. No code change needed in plotly.py for this.
2. SC-02 / DQ-01 (as-rendered only): Arrow length appears constant in the reviewed images.
   • Fix: None needed in code — already resolved by length_frac in current source. Will self-resolve once the render is refreshed.
3. DQ-03 (as-rendered only): Wind speed range appears too gentle (0-2.83 m/s) for "cyclonic" framing in the reviewed images.
   • Fix: None needed in code — already resolved by WIND_SPEED_SCALE=10.0 in current source. Will self-resolve once the render is refreshed.

AI Feedback for Next Attempt

Do not change plotly.py further to address arrow-length-proportionality or wind-speed-realism — both are already correctly implemented in the current committed source (verified by direct local execution). The blocking issue is that the CI render step did not regenerate plot-light.png/plot-dark.png from the latest commit before this review ran. Please re-trigger the render/screenshot step against the current HEAD and re-run review before making any further code edits.

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): Warm off-white background consistent with #FAF8F1. A 13x13 grid of brand-green (#009E73) arrows forms a counterclockwise rotational flow pattern consistent with u=-y, v=x. Arrow length now clearly grows from short near the calm vortex centre to long at the outer edge, proportional to true wind-speed magnitude. Scatter markers at each arrow base use the green-to-blue imprint_seq sequential gradient keyed to the same magnitude (0 to ~28.3 m/s), growing bluer toward the edges. Title ("Cyclonic Wind Vortex · quiver-basic · python · plotly · anyplot.ai"), axis titles ("X Position (km)", "Y Position (km)"), tick labels, and the "Wind Speed (m/s)" colorbar title/ticks are all dark ink and clearly readable against the light background. All text is readable — no light-on-light issues.

Dark render (plot-dark.png): Warm near-black background consistent with #1A1A17. Arrow color (#009E73) and the scatter-marker gradient are pixel-identical to the light render — only chrome flipped, as required. Title, axis titles, tick labels, and colorbar text switch to light ink / soft light-gray tokens and remain clearly legible. Same radially-growing arrow length and same ~28.3 m/s colorbar range as the light render. All text is readable — no dark-on-dark failures detected.

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

Score: 85/100

Category	Score	Max
Visual Quality	27	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	14	15
Code Quality	9	10
Library Mastery	7	10
Total	85	100

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8)
• VQ-02: No Overlap (6/6)
• VQ-03: Element Visibility (5/6)
• VQ-04: Color Accessibility (2/2)
• VQ-05: Layout & Canvas (3/4)
• VQ-06: Axis Labels & Title (2/2)
• VQ-07: Palette Compliance (2/2)

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) - Above default via the layered quiver+colorbar composition, but short of publication-level polish
• DE-02: Visual Refinement (4/6) - Subtle grid, tightened colorbar sizing since attempt 1, reasonable margins
• DE-03: Data Storytelling (4/6) - Length AND color now both grow from the calm centre outward, reinforcing a clear visual hierarchy/focal point

Spec Compliance (15/15)

• SC-01: Plot Type (5/5)
• SC-02: Required Features (4/4) - Arrow length is now proportional to magnitude (previously the key gap, now fixed)
• SC-03: Data Mapping (3/3)
• SC-04: Title & Legend (3/3)

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6)
• DQ-02: Realistic Context (5/5)
• DQ-03: Appropriate Scale (4/4) - Peak wind speed ~28.3 m/s is now a plausible severe-storm range, fixing the previous "too gentle" issue

Code Quality (9/10)

• CQ-01: KISS Structure (3/3)
• CQ-02: Reproducibility (2/2)
• CQ-03: Clean Imports (2/2)
• CQ-04: Code Elegance (1/2) - np.random.seed(42) is set but never used (no np.random calls exist anywhere in the script) — harmless but misleading dead code
• CQ-05: Output & API (1/1)

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5)
• LM-02: Distinctive Features (3/5) - create_quiver + a layered go.Scatter colorbar overlay is a plotly-specific composition

Score Caps Applied

• None

Strengths

• Both previously-flagged blockers are now genuinely fixed and visible in the fresh renders: arrow length grows radially from the calm vortex centre outward (length_frac formula), and peak wind speed now reaches ~28.3 m/s (WIND_SPEED_SCALE=10.0), a plausible severe-storm range instead of a light breeze.
• Direction correctly derived from u=-y, v=x, producing a clean counterclockwise cyclonic rotation that matches the spec's example field.
• Smart redundant encoding: a go.Scatter layer colored by true wind-speed magnitude (imprint_seq colorscale + colorbar) sits on top of ff.create_quiver, giving a second, more precise magnitude read that plain create_quiver can't provide on its own.
• Theme handling is fully correct in both renders: PAGE_BG/INK/INK_SOFT/GRID all branch on ANYPLOT_THEME and match the required #FAF8F1/#1A1A17 hex values with no dark-on-dark or light-on-light failures.
• Imprint palette compliance: arrows use brand green #009E73, and the single-polarity magnitude field correctly uses imprint_seq rather than a diverging or forbidden colormap.
• All font sizes explicitly set (title, axis titles, tick labels, colorbar title/ticks), with the title fontsize dynamically scaled by a documented length ratio so the long mandated title never clips.

Weaknesses

• np.random.seed(42) is set but never used — all data (grid, u, v) is generated deterministically via np.linspace/meshgrid with no calls into np.random. This is harmless dead code but misleadingly implies a stochastic data-generation step that doesn't exist; remove the seed line or use it if randomness is ever added.
• Design Excellence is solid but not exceptional: the 169-arrow grid plus overlaid scatter dots is still fairly close to a well-composed default rather than a distinctively art-directed chart. Consider a slightly more restrained marker opacity/size or thinner arrow lines near the dense outer rings to let the vortex structure read even more cleanly as a focal point.
• The colorbar's reserved right-hand margin makes the square plot area sit marginally left-of-center; tightening the colorbar thickness/length slightly further would perfect the whitespace balance (currently good, not perfect).
• Outer-ring arrowheads sit close to their neighbors given the grid spacing versus max arrow length (~0.32 vs ~0.33 spacing) — not true overlap, but there is little breathing room; a slightly lower scale_factor would give more visual air without losing the magnitude signal.

Issues Found

1. CQ-04 LOW: np.random.seed(42) is dead code — no np.random calls exist in the script.
   • Fix: Remove the unused seed line (data generation is already fully deterministic without it).
2. DE-01/DE-02 LOW: Design is above-default but still fairly close to a well-composed default given the dense uniform grid.
   • Fix: Consider a slightly lower marker opacity/size or thinner arrow lines in the dense outer rings to sharpen the focal point.

AI Feedback for Next Attempt

This implementation is approved. If revisited in the future, the highest-value remaining polish is: (1) drop the unused np.random.seed(42) line, and (2) further refine Design Excellence — slightly lighter markers/arrows in the dense outer rings and a touch more colorbar-margin tightening would push this toward publication quality. The core spec-compliance fixes (magnitude-proportional arrow length, realistic wind-speed scale) are correct and should not be touched again.

Verdict: APPROVED