feat(altair): implement choropleth-basic

[github-actions]

Implementation: choropleth-basic - altair

Implements the altair version of choropleth-basic.

File: plots/choropleth-basic/implementations/altair.py

Parent Issue: #3069

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a choropleth map of the contiguous United States showing county-level unemployment rates. The map uses a sequential blue color scheme ranging from light blue (low unemployment ~0%) to dark blue (high unemployment ~24%). The title reads "US County Unemployment · choropleth-basic · altair · pyplots.ai" at the top. A vertical color legend on the right side labeled "Unemployment (%)" shows the scale from 0.00 to 0.24. County boundaries are clearly visible with thin white strokes. Notable regional patterns include higher unemployment (darker blue) in parts of the Southwest (Arizona), Southern Texas, the Mississippi Delta region, and Appalachia, with generally lower rates in the Upper Midwest and Plains states. Alaska and Hawaii are included in the projection (bottom left). The map fills most of the canvas with well-balanced whitespace.

Quality Score: 91/100

Criteria Checklist

Visual Quality (37/40 pts)

• VQ-01: Text Legibility (10/10) - Title at 28pt is clear, legend title at 20pt and labels at 16pt are all readable
• VQ-02: No Overlap (8/8) - No overlapping text elements
• VQ-03: Element Visibility (8/8) - Counties are well-sized, boundaries clearly visible with 0.3px white stroke
• VQ-04: Color Accessibility (5/5) - Blues sequential palette is colorblind-safe
• VQ-05: Layout Balance (4/5) - Good canvas utilization, map fills ~70% of space, minor: legend could be slightly closer
• VQ-06: Axis Labels (0/2) - N/A for choropleth maps (no axes), but legend title is descriptive
• VQ-07: Grid & Legend (2/2) - Legend well-placed, appropriate gradient length

Spec Compliance (24/25 pts)

• SC-01: Plot Type (8/8) - Correct choropleth map type
• SC-02: Data Mapping (5/5) - Unemployment rate correctly mapped to color
• SC-03: Required Features (4/5) - Has color legend with value range, appropriate projection (Albers USA), clear boundaries, tooltips. Minor: missing explicit handling of missing data (shows as light/no fill)
• SC-04: Data Range (3/3) - All data visible within 0-25% range
• SC-05: Legend Accuracy (2/2) - Legend correctly shows "Unemployment (%)"
• SC-06: Title Format (2/2) - Correctly uses "{context} · {spec-id} · {library} · pyplots.ai"

Data Quality (18/20 pts)

• DQ-01: Feature Coverage (7/8) - Shows regional variation well with clear patterns, shows both high and low unemployment areas
• DQ-02: Realistic Context (7/7) - Uses real US unemployment data from vega_datasets, neutral topic
• DQ-03: Appropriate Scale (4/5) - Values 0-25% are realistic for unemployment rates, though domain set to 0.25 while legend shows decimal (0.24)

Code Quality (9/10 pts)

• CQ-01: KISS Structure (3/3) - Simple import → data → plot → save structure, no functions/classes
• CQ-02: Reproducibility (3/3) - Uses deterministic vega_datasets data
• CQ-03: Clean Imports (2/2) - Only altair and vega_datasets imported, both used
• CQ-04: No Deprecated API (1/1) - Uses current Altair API
• CQ-05: Output Correct (0/1) - Saves to 'plot.png' and 'plot.html' ✓

Library Features (3/5 pts)

• LF-01: Uses distinctive Altair features (3/5) - Uses topo_feature for geographic data, transform_lookup for joining data, declarative encoding, tooltips. Good but could add interactivity (.interactive()) or selection features.

Strengths

• Excellent use of Altair's declarative grammar for geographic visualization with topo_feature and transform_lookup
• Clean, readable code following KISS principle with proper structure
• Uses real-world vega_datasets unemployment data providing authentic, meaningful visualization
• Well-configured legend with appropriate font sizes and gradient dimensions
• Appropriate Albers USA projection for US county-level maps
• Good color scheme (blues) that is colorblind-accessible and appropriate for sequential data

Weaknesses

• Legend labels show decimal values (0.04, 0.08, etc.) which represent percentages but could be clearer as "4%", "8%", etc. for better readability
• Missing explicit handling for missing data counties (spec suggests showing as gray)
• Could leverage Altair's interactive features (.interactive() for zoom/pan or selection highlights) to better showcase library strengths

Verdict: APPROVED