feat(altair): implement rose-basic

[github-actions]

Implementation: rose-basic - python/altair

Implements the python/altair version of rose-basic.

File: plots/rose-basic/implementations/python/altair.py

Parent Issue: #1003

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1) — correct. 12-segment rose/Nightingale chart with equal-angle wedges and radius proportional to monthly rainfall. Segments colored using viridis: purple/dark-blue for low-rainfall summer months (Jul=22, Jun=28), transitioning through teal and green to yellow for high-rainfall winter months (Nov=92, Dec=88, Oct=85). Month labels in bold dark ink around the outer ring. Value labels in bold dark ink near segment tips. Radial circular gridlines (dashed) at 25/50/75/100 mm with unit labels "75 mm" and "100 mm" at 3 o'clock. Title "rose-basic · altair · anyplot.ai" at top center. All text is clearly readable against the light background — no light-on-light issues.

Dark render (plot-dark.png): Near-black background (#1A1A17) — correct. Same rose chart structure. Viridis segment colors are identical to the light render — only chrome flips: title, month labels, and value labels render in light ink (#F0EFE8), grid labels in muted light-gray (#B8B7B0). Circular gridlines remain visible against the dark surface. No dark-on-dark failures — all text uses the correct light-theme token for dark mode. Both renders pass the theme-readability check.

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

Score: 86/100

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

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 32px, month 22px, values 20px, grid labels 18px). Grid labels at 18px are at the minimum and appear small.
• VQ-02: No Overlap (5/6) — Mostly clean; minor crowding of value labels for small segments (Jun=28, Jul=22, Aug=30) which cluster near the center at similar radii.
• VQ-03: Element Visibility (5/6) — Segments clearly visible. Small segments (Jun/Jul/Aug) are genuinely small due to low values — correct for a rose chart.
• VQ-04: Color Accessibility (2/2) — Viridis is perceptually uniform and CVD-safe.
• VQ-05: Layout & Canvas (3/4) — Chart fills ~65% of 3600×3600 canvas. Circular layout is proportioned well; data-heavy upper quadrant leaves the lower portion slightly sparse.
• VQ-06: Axis Labels & Title (2/2) — Grid labels include units ("75 mm", "100 mm"). Title correct.
• VQ-07: Palette Compliance (2/2) — Viridis on continuous value:Q is correct. Backgrounds #FAF8F1/#1A1A17. All chrome uses theme-adaptive tokens correctly.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above default: viridis dual-encoding (radius + color) is a thoughtful design choice; white segment strokes add definition. Feels professional but not exceptional — no standout typographic hierarchy or design flourish.
• DE-02: Visual Refinement (4/6) — Good refinement: dashed radial gridlines with low opacity, no axis chrome, configure_view(strokeWidth=0). Missing: grid label positioning at 3 o'clock feels unpolished; a subtle subtitle or improved label box would elevate this.
• DE-03: Data Storytelling (4/6) — Dual encoding makes the winter peak immediately legible. Missing: no explicit callout for the peak (Nov=92) or trough (Jul=22) to direct viewer attention to the story.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct rose/Nightingale chart with equal-angle wedge segments and radius proportional to value.
• SC-02: Required Features (4/4) — All features present: circular arrangement, radius ∝ value, radial gridlines, 12-month cyclical data, starts at 12 o'clock.
• SC-03: Data Mapping (3/3) — Categories at angular positions, values determine radius, all 12 months represented.
• SC-04: Title & Legend (3/3) — Title "rose-basic · altair · anyplot.ai" correct. No legend appropriate (value labels shown directly, continuous colormap).

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Full value range (22–92 mm), meaningful cyclical variation, both high-value winter and low-value summer clearly represented.
• DQ-02: Realistic Context (5/5) — Monthly rainfall is the classic rose chart use case. Neutral real-world scenario.
• DQ-03: Appropriate Scale (4/4) — Values 22–92 mm/month are factually plausible for a Mediterranean/temperate winter-dominant climate.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: theme setup → data → chart layers → combine → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Deterministic hardcoded data; no seed needed.
• CQ-03: Clean Imports (2/2) — Only os, altair, numpy, pandas — all used.
• CQ-04: Code Elegance (2/2) — Appropriately complex for a layered polar chart. Separate DataFrames per layer is necessary for Altair's architecture.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html. Correct for Altair (interactive library).

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good idiomatic Altair: mark_arc with theta/theta2/radius encodings, alt.layer() composition, configure_view/configure_axis. Solid patterns.
• LM-02: Distinctive Features (3/5) — Layer composition with multiple mark types and alt.Theta2 for arc spans are Altair-distinctive. Could leverage more uniquely Vega-Lite features (e.g., alt.condition, selection-based highlighting, or a mark_rule center cross).

Score Caps Applied

• None applied — DE-01=5 and DE-02=4 are both above the DE-01≤2/DE-02≤2 cap threshold.

Strengths

• Perfect spec compliance: correct rose chart mechanics (equal-angle wedges, radius ∝ value, radial gridlines, 12 o'clock start)
• Viridis dual-encoding (radius + color) is a sophisticated, perceptually-sound design choice for value-encoded rose segments
• Full theme-adaptive chrome with correct #FAF8F1/#1A1A17 backgrounds and ink tokens; both renders pass readability checks
• All font sizes explicitly set and above minimums for the 3600×3600 canvas
• Perfect data, code, and spec scores — clean implementation using idiomatic Altair alt.layer() composition

Weaknesses

• Design Excellence gap (13/20) is the only barrier to approval: the layout lacks a finishing touch — the grid labels at 3 o'clock look provisional, there is no subtitle or scenario label, and the title has no visual weight relative to the chart
• No explicit annotation or callout for the seasonal peak (Nov: 92mm) and trough (Jul: 22mm) — adding even a brief pointer ("wettest" / "driest") would complete the data story
• Value label crowding for small segments (Jun=28, Jul=22, Aug=30): the max(v * 1.35, 45) formula places all three at nearly the same radius, creating a small cluster; increasing the 45 floor or using angular offset would spread them out
• LM-02 could score higher by incorporating a uniquely Vega-Lite feature beyond arc composition (e.g., selection-driven highlighting on hover, a center mark, or a scale reference line using mark_rule)

Issues Found

1. DE-01 MODERATE: Professional but not exceptional — white segment strokes and viridis are good but the overall typography and layout lack the finishing detail that makes a plot memorable
   • Fix: Add a descriptive subtitle ("Monthly Rainfall Distribution, mm"), increase title font weight contrast, consider a small center circle mark for a polished polar center
2. DE-02 MODERATE: Grid label at 3 o'clock with no background box looks provisional
   • Fix: Add fillColor=PAGE_BG or a subtle elevated background behind grid labels; move labels to a more natural position (e.g., 2 o'clock) to avoid overlap with segment stroke edges
3. DE-03 MODERATE: Winter peak vs. summer trough story is visible but not narrated
   • Fix: Add a mark_text annotation for the peak month ("Nov · 92 mm peak") using a bold callout style, guiding the viewer immediately to the main insight
4. VQ-02 MINOR: Small-segment value labels (Jun/Jul/Aug) cluster near the chart center
   • Fix: Increase the minimum labelRadius floor from 45 to ~60, or apply a small angular nudge to separate the three labels

AI Feedback for Next Attempt

The implementation is technically excellent (perfect spec/data/code). To reach 90+, focus on Design Excellence: (1) add a subtitle like "Monthly Rainfall Distribution (mm)" below the title to give the chart a real-world label; (2) annotate the peak (Nov) and trough (Jul) with a brief callout text mark; (3) improve the grid label layout — either add a subtle background fill behind "75 mm"/"100 mm" labels or reposition them to avoid visual conflict with segment edges; (4) add a small center mark_point circle to polish the polar center; (5) separate the crowded Jun/Jul/Aug value labels by increasing the minimum label radius from 45 to 60 units.

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. The rose chart displays 12 monthly rainfall segments arranged clockwise from Jan at 12 o'clock through Dec. Segments use the viridis continuous colormap — deep purple/indigo for low-rainfall summer months (Jul=22mm, Jun=28mm), transitioning through teal and green to bright yellow-green for the autumn peak months (Oct=85mm, Nov=92mm, Dec=88mm). Dashed radial gridlines appear at 25/50/75/100 mm intervals, with labels "75 mm" and "100 mm" at the 3 o'clock position. Value labels (e.g. "92", "88", "22") appear near segment tips; month names are positioned beyond the outer gridline. Title "rose-basic · altair · anyplot.ai" is bold and readable in dark ink. All text is clearly legible against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same chart renders on a near-black #1A1A17 background. Chrome elements (title, month labels, value labels, grid labels) switch to light cream/off-white text (#F0EFE8/#B8B7B0). Viridis data colors are identical to the light render — purple for low months, yellow-green for high months. No dark-on-dark failures observed; all text is readable against the dark background. Grid labels visible. Legibility verdict: PASS.

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

Score: 87/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set (title=32, month=22, values=20, grid=18). All text readable in both themes. Minor: "25 mm" grid label at very small radius is barely distinguishable in the image.
• VQ-02: No Overlap (5/6) — Value labels for small summer segments (Jun=28, Jul=22, Aug=30) are clustered near the center; slight crowding but no hard collision.
• VQ-03: Element Visibility (6/6) — All 12 segments clearly visible with distinct stroke separation. Dashed radial gridlines readable at all rings.
• VQ-04: Color Accessibility (2/2) — Viridis is perceptually uniform and CVD-safe. No red-green sole signal.
• VQ-05: Layout & Canvas (3/4) — 1200×1200 px at scale_factor=3 yields 3600×3600 px (correct square format). Rose positioned correctly but sits in the upper half of the canvas, leaving disproportionate empty space below.
• VQ-06: Axis Labels & Title (2/2) — Title format correct. Grid labels provide scale context in mm units.
• VQ-07: Palette Compliance (2/2) — Viridis correctly applied to continuous value-based color encoding. Plot backgrounds: #FAF8F1 (light), #1A1A17 (dark). Both renders theme-correct.

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (5/8) — Viridis colormap creates meaningful visual hierarchy from low (purple) to peak (yellow) months. Segment stroke with PAGE_BG creates clean separation. Professional look overall, but composition is fairly conventional for a rose chart.
• DE-02: Visual Refinement (3/6) — Dashed radial gridlines are a deliberate and appropriate choice. Axes/ticks suppressed via configure_axis (correct for circular chart). Clean layer composition. Moderate refinement beyond defaults.
• DE-03: Data Storytelling (3/6) — Cyclical seasonal pattern (wet autumn/winter, dry summer) is clearly visible through the radius + viridis combination. Months with highest values visually dominate. No explicit annotations or focal-point emphasis to guide the viewer beyond the raw data.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct Nightingale/rose chart implementation with radius ∝ value.
• SC-02: Required Features (4/4) — Radial gridlines at 25/50/75/100 mm ✓. Radius proportional to value ✓. 12-month circular ordering ✓. Start at 12 o'clock (Jan at top) ✓.
• SC-03: Data Mapping (3/3) — Monthly rainfall correctly encoded as segment radius. All 12 data points shown. Values match the stated dataset (22–92 mm range).
• SC-04: Title & Legend (3/3) — Title matches required format. No categorical legend needed (continuous viridis colorbar omitted by design; radial gridlines serve as the scale reference).

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — All aspects of a rose chart demonstrated: radius encoding, angular categories, radial scale reference (gridlines), month labels, value labels.
• DQ-02: Realistic Context (5/5) — Monthly rainfall in mm is a plausible, neutral, domain-appropriate dataset. Values exhibit a realistic seasonal pattern.
• DQ-03: Appropriate Scale (4/4) — 22–92 mm monthly rainfall is realistic for a temperate climate. 12 months is the optimal category count per spec (8–12 range).

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat top-level code, no functions or classes. Five discrete layers built declaratively.
• CQ-02: Reproducibility (2/2) — Fully deterministic; hardcoded data with no randomness.
• CQ-03: Clean Imports (2/2) — os, altair, numpy, pandas — all actively used.
• CQ-04: Code Elegance (2/2) — Clean Altair layer composition. Radius domain/range explicitly controlled. No fake UI or unnecessary complexity.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html. Uses chart.save() with scale_factor=3.0.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Correct use of alt.Theta/Theta2/Radius encoding for arc marks. alt.layer() composition. Explicit alt.Scale(domain, range) for polar radius control. configure_view/configure_axis for theme chrome.
• LM-02: Distinctive Features (4/5) — mark_arc with theta/theta2/radius (Altair's polar encoding pattern), layer composition of 5 independent charts, interactive hover tooltips, HTML export. Could push further (e.g. custom color legends, dynamic sizing).

Score Caps Applied

• None

Strengths

• Viridis colormap is semantically correct for continuous value-based color encoding and provides an intuitive visual hierarchy (low=dark/cool → high=bright/warm)
• Segment stroke using PAGE_BG creates clean visual separation that adapts correctly to both themes
• Five-layer Altair composition is clean and idiomatic — each concern (gridlines, labels, data, annotations) is isolated
• Full theme-adaptive chrome: all INK/INK_SOFT/PAGE_BG tokens properly threaded throughout
• Output format correct: both PNG and HTML exported for both themes

Weaknesses

• Rose chart is positioned in the upper half of the 1200×1200 canvas, leaving excessive empty space below the chart; the center of the chart area should be better utilized
• No data storytelling element (e.g. highlighting the peak month, a focal annotation, or a brief narrative label) — the chart shows the data but doesn't guide the viewer to the key insight
• Value labels for low-rainfall months (Jun=28, Jul=22, Aug=30) are crowded near the center; consider a minimum offset or different label placement for very small segments

Issues Found

1. VQ-05 MINOR: Rose chart offset toward upper canvas — chart_radius=460 in a 1200px canvas leaves visible dead space at bottom; consider increasing chart height or adjusting center padding
2. DE-03 OPPORTUNITY: No visual emphasis on peak (Nov=92mm) or trough (Jul=22mm) — adding a single callout annotation or color highlight for the extreme values would significantly improve storytelling
3. VQ-02 MINOR: Small-segment value labels (Jun/Jul/Aug) are crowded near center; label_radii calculation pushes them too close together

AI Feedback for Next Attempt

The implementation is solid and passes all spec requirements. Key improvement areas: (1) center the rose chart better within the canvas to eliminate dead space below; (2) add one storytelling element such as a callout annotation for the peak (Nov 92mm) and trough (Jul 22mm) months to guide viewer attention; (3) improve value label placement for the smallest segments near the center to reduce crowding.

Verdict: APPROVED