feat(letsplot): implement swarm-basic

[github-actions]

Implementation: swarm-basic - python/letsplot

Implements the python/letsplot version of swarm-basic.

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

Parent Issue: #974

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1). Bold dark title top-left reads "swarm-basic · python · letsplot · anyplot.ai". Dark axis titles ("Department", "Performance Score") and medium-gray tick labels are all clearly legible against the light surface. Subtle y-only horizontal gridlines are visible but not dominant; vertical gridlines are removed. A full rectangular panel border frames the plot on all four sides. Four swarm/sina clusters (Engineering, Marketing, Sales, Support) are colored green/purple/blue/ochre in canonical Imprint order, each with a black horizontal crossbar marking the group mean. All text is readable — no light-on-light issues.

Dark render (plot-dark.png): Warm near-black background (#1A1A17). Title and axis titles flip to light/off-white, tick labels to lighter gray — all clearly legible against the dark surface, no dark-on-dark failures. The crossbar mean markers correctly flip to off-white/cream instead of black. Data colors (green/purple/blue/ochre) are identical to the light render — confirms only chrome flipped, not data colors. All text is readable.

Both renders pass the theme-readability check.

Score: 88/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — font sizes explicitly set (title=16, axis_title=12, axis_text=10), readable in both themes, well-proportioned
• VQ-02: No Overlap (6/6) — no text overlap; point-touching within swarms is inherent to the sina technique, not a defect
• VQ-03: Element Visibility (6/6) — points appropriately sized for 38-52 obs/group, alpha=0.7 avoids overplotting
• VQ-04: Color Accessibility (2/2) — Imprint hues are CVD-safe and well distinguished
• VQ-05: Layout & Canvas (4/4) — plot fills a large, balanced portion of the 3200×1800 canvas
• VQ-06: Axis Labels & Title (1/2) — descriptive but "Performance Score" has no explicit unit/scale annotation
• VQ-07: Palette Compliance (2/2) — canonical Imprint order, first series #009E73, identical data colors across themes, theme-correct backgrounds

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (4/8) - Well-configured default: correct palette + mean-crossbar addition, but not yet "strong design" tier
• DE-02: Visual Refinement (3/6) - Vertical gridlines removed and y-grid subdued, but a full four-sided panel border is retained instead of removed spines
• DE-03: Data Storytelling (4/6) - Mean crossbars create a clear focal point per group, letting the viewer compare department averages at a glance

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — geom_sina is the correct swarm/beeswarm-equivalent for lets-plot's grammar-of-graphics API
• SC-02: Required Features (4/4) — consistent point sizes, mean marker per category, clear group spacing, color distinguishes categories
• SC-03: Data Mapping (3/3) — category on x, value on y, all data visible
• SC-04: Title & Legend (3/3) — title format correct; legend intentionally omitted since color is redundant with the x-axis category

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — bimodal Sales, tight Support with outliers, wide Marketing, moderate Engineering — full distribution-shape coverage
• DQ-02: Realistic Context (5/5) — employee performance scores by department, matching the spec's own application example
• DQ-03: Appropriate Scale (4/4) — scores clipped to a plausible 0-100 range with realistic per-department spread

Code Quality (10/10)

• CQ-01: KISS Structure (3/3)
• CQ-02: Reproducibility (2/2) — np.random.seed(42) + geom_sina(seed=42)
• CQ-03: Clean Imports (2/2)
• CQ-04: Code Elegance (2/2)
• CQ-05: Output & API (1/1) — saves plot-{THEME}.png (scale=4) and plot-{THEME}.html

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — expert grammar-of-graphics composition: ggplot + geom_sina + geom_crossbar + scale_manual + theme
• LM-02: Distinctive Features (4/5) - geom_sina is a lets-plot/ggplot-family-specific feature not easily replicated elsewhere; layering geom_crossbar on top strengthens the case

Score Caps Applied

• None

Strengths

• Correct Imprint palette assignment in canonical order (#009E73 Engineering, #C475FD Marketing, #4467A3 Sales, #BD8233 Support), identical across light/dark renders
• Theme-adaptive chrome correctly threaded through PAGE_BG/INK/INK_SOFT tokens — both renders pass legibility
• geom_sina + geom_crossbar is idiomatic lets-plot usage and a genuinely distinctive technique — the crossbar mean markers add real analytical value
• Full distribution-shape coverage: bimodal Sales, tight Support with outliers, wide Marketing, moderate Engineering
• Clean, reproducible KISS code with explicit theme font sizes and correct mandated title format

Weaknesses

• A full four-sided panel border/box frame is retained around the plot in both themes instead of removing the spine equivalent — a more refined look would raise Visual Refinement
• Y-axis label "Performance Score" has no explicit unit/scale context (e.g. "Performance Score (0-100)")
• Styling leans close to a well-configured library default beyond the crossbar addition — a more distinctive touch (e.g. accenting outlier points, or a light annotation calling out Sales' bimodal split) would push Aesthetic Sophistication and Data Storytelling further
• geom_sina is a good distinctive choice but could be pushed further (e.g. a faint geom_violin backdrop at low alpha) to more fully showcase lets-plot's layered grammar-of-graphics strengths

Issues Found

1. DE-02 LOW: Full panel border retained on all four sides instead of a more refined, spine-reduced look
   • Fix: Remove or lighten the panel border (e.g. panel_border=element_blank() or reduce to axis lines only) for a cleaner, more refined frame
2. VQ-06 LOW: "Performance Score" axis label lacks explicit unit/scale context
   • Fix: Add a scale hint, e.g. "Performance Score (0-100)"
3. DE-01/DE-03 MODERATE: Design reads as a well-executed default rather than a standout — the crossbar is a good start but doesn't yet fully tell a story
   • Fix: Consider a subtle accent on outlier points or a brief annotation calling out the Sales bimodal split to sharpen the storytelling

AI Feedback for Next Attempt

Solid foundation — correct palette, good data variety, idiomatic geom_sina usage. To push past 90: remove the full panel border for a cleaner frame (spines-removed look), add explicit units/scale to the "Performance Score" axis label, and consider one more distinctive design touch (accent color/size on outliers, or a subtle annotation on the Sales bimodal split) to elevate Aesthetic Sophistication and Data Storytelling beyond "well-configured default."

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). Bold dark title top-left reads "swarm-basic · python · letsplot · anyplot.ai". Dark axis titles ("Department", "Performance Score (0-100)") and medium-gray tick labels are all clearly legible against the light surface. Only left+bottom axis lines are drawn now — the full four-sided panel border from attempt 1 has been removed (panel_border=element_blank()), leaving a clean L-shaped frame. Subtle y-only horizontal gridlines. Four violin+sina clusters (Engineering, Marketing, Sales, Support) in canonical Imprint order (green/lavender/blue/ochre), each with a violin density silhouette behind the jittered points and a black horizontal crossbar marking the group mean. All text is readable — no light-on-light issues.

Dark render (plot-dark.png): Warm near-black background (#1A1A17). Title and axis titles flip to light/off-white, tick labels to lighter gray — all clearly legible against the dark surface, no dark-on-dark failures. Violin outlines remain visible against the dark background. The crossbar mean markers correctly flip to off-white/cream instead of black. Data colors (green/lavender/blue/ochre) are pixel-identical to the light render — confirms only chrome flipped, not data colors. All text is readable.

Both renders pass the theme-readability check.

Score: 93/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	9	10
Total	93	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — font sizes explicitly set (title=16, axis_title=12, axis_text=10), readable in both themes
• VQ-02: No Overlap (6/6) — no text overlap; point-touching within swarms is inherent to the sina technique, not a defect
• VQ-03: Element Visibility (6/6) — points appropriately sized for 38-52 obs/group, alpha=0.7 avoids overplotting
• VQ-04: Color Accessibility (2/2) — Imprint hues are CVD-safe and well distinguished
• VQ-05: Layout & Canvas (4/4) — canvas gate passed; balanced proportions, nothing cut off
• VQ-06: Axis Labels & Title (2/2) — Fixed: "Performance Score (0-100)" now includes explicit unit/scale
• VQ-07: Palette Compliance (2/2) — canonical Imprint order, first series #009E73, identical data colors across themes, theme-correct backgrounds

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (5/8) - Layered violin+sina+crossbar composition is a genuine step up from a bare swarm, but still lacks a truly distinctive touch (outlier accent, annotation)
• DE-02: Visual Refinement (5/6) - Fixed: full panel border removed (panel_border=element_blank()), now a clean L-shaped frame; subtle y-only grid, generous whitespace
• DE-03: Data Storytelling (5/6) - Violin backdrop plus mean crossbar now conveys shape, spread, and central tendency together; still no explicit callout of the Sales bimodal split

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — geom_sina is the correct swarm/beeswarm-equivalent for lets-plot's grammar-of-graphics API
• SC-02: Required Features (4/4) — consistent point sizes, mean marker per category, clear group spacing, color distinguishes categories
• SC-03: Data Mapping (3/3) — category on x, value on y, all data visible
• SC-04: Title & Legend (3/3) — title format correct; legend intentionally omitted since color is redundant with the x-axis category

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — bimodal Sales, tight Support with outliers, wide Marketing, moderate Engineering — full distribution-shape coverage, now visually reinforced by the violin outlines
• DQ-02: Realistic Context (5/5) — employee performance scores by department, matching the spec's own application example
• DQ-03: Appropriate Scale (4/4) — scores clipped to a plausible 0-100 range with realistic per-department spread

Code Quality (10/10)

• CQ-01: KISS Structure (3/3)
• CQ-02: Reproducibility (2/2) — np.random.seed(42) + geom_sina(seed=42)
• CQ-03: Clean Imports (2/2)
• CQ-04: Code Elegance (2/2)
• CQ-05: Output & API (1/1) — saves plot-{THEME}.png (scale=4) and plot-{THEME}.html

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — expert grammar-of-graphics composition: ggplot + geom_violin + geom_sina + geom_crossbar + scale_manual + theme
• LM-02: Distinctive Features (4/5) - geom_sina + geom_violin layering is lets-plot/ggplot-family-distinctive; one more unique touch would earn full marks

Score Caps Applied

• None

Strengths

• Panel border fixed per prior review: panel_border=element_blank() removes the four-sided box, leaving a clean L-shaped axis frame in both themes
• Y-axis label now reads "Performance Score (0-100)" with explicit unit/scale, resolving the prior VQ-06 deduction
• Added a geom_violin backdrop (alpha=0.15) behind the sina swarm, directly addressing the prior review's suggestion — the layered violin+sina+crossbar composition now shows density shape, individual observations, and group mean simultaneously
• Correct Imprint palette in canonical order (#009E73 Engineering, #C475FD Marketing, #4467A3 Sales, #BD8233 Support), identical data hues across light/dark renders
• Theme-adaptive chrome correctly threaded through PAGE_BG/INK/INK_SOFT tokens, including the crossbar mean marker flipping from black (light) to cream (dark)
• Clean, reproducible KISS code with correct mandated title format and correct output files

Weaknesses

• Design still stops short of a fully distinctive touch — no accent on outlier points (e.g. Support's 45/48/95 or Sales' bimodal tails) and no annotation calling out the Sales bimodal split, both suggested in the prior review round
• Sina point density in Sales/Support clusters creates moderate marker touching in the densest bands — a slightly lower alpha or marker size could open a touch more breathing room without losing prominence

Issues Found

1. DE-01 LOW: No distinctive accent beyond the violin+sina+crossbar layering
   • Fix: Consider a subtle accent (color/size/outline) on outlier points, or a light annotation calling out the Sales bimodal split
2. VQ-03 LOW: Minor marker touching in the densest Sales/Support bands
   • Fix: Slightly reduce alpha or marker size in the highest-density regions if further polish is desired (optional, not blocking)

AI Feedback for Next Attempt

Both prior blocking issues are resolved: the panel border is gone and the axis label now has units. The violin backdrop was a good addition per the prior suggestion. If iterating further, the highest-value next step is a distinctive storytelling touch — e.g. accenting Support's three outliers (45, 48, 95) or annotating Sales' bimodal split — to push Design Excellence past "well-executed default."

Verdict: APPROVED