feat(altair): implement bubble-map-geographic

[github-actions]

Implementation: bubble-map-geographic - altair

Implements the altair version of bubble-map-geographic.

File: plots/bubble-map-geographic/implementations/altair.py

Parent Issue: #3625

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a world map with an equirectangular projection showing major city populations as sized circular markers. The base map shows country boundaries in light gray (#E8E8E0) with subtle borders. Bubbles are positioned at city locations with size proportional to population (5-40 million range). Colors encode regions: blue for Asia, yellow for Europe, green for North America, red/coral for South America, purple for Africa, and cyan for Oceania. Tokyo appears as the largest bubble in Asia. A size legend on the bottom-left shows the population scale (5-40 million), and a color legend on the bottom-right identifies regions. The title "World City Populations · bubble-map-geographic · altair · pyplots.ai" is displayed at the top center. White stroke outlines on bubbles (1.5px) provide separation, and 70% opacity enables viewing of overlapping markers in dense areas like East Asia.

Quality Score: 93/100

Criteria Checklist

Visual Quality (37/40 pts)

• VQ-01: Text Legibility (10/10) - Title at 28pt, legend titles at 16pt, labels at 14pt - all readable at full resolution
• VQ-02: No Overlap (8/8) - No text overlap; bubble overlap is intentional and handled well with alpha
• VQ-03: Element Visibility (7/8) - Bubbles well-sized for data density; white strokes help distinguish overlapping markers; minor deduction for some smaller markers being slightly less prominent
• VQ-04: Color Accessibility (5/5) - Six distinct colors for regions are colorblind-safe; blue/yellow/green/red/purple/cyan palette provides good differentiation
• VQ-05: Layout Balance (4/5) - Good use of canvas; map is centered; slight imbalance with legends on bottom corners leaving some empty space on sides
• VQ-06: Axis Labels (2/2) - N/A for geographic maps, but legends are well-labeled with "Population (millions)" and "Region"
• VQ-07: Grid & Legend (1/2) - Size legend uses consistent symbol color (#306998) rather than showing the actual varied colors; legends well-positioned but size legend could show actual size variation more clearly

Spec Compliance (25/25 pts)

• SC-01: Plot Type (8/8) - Correct bubble map with geographic projection
• SC-02: Data Mapping (5/5) - Latitude/longitude correctly mapped to positions; population to size; region to color
• SC-03: Required Features (5/5) - All spec features present: size encoding, color categories, transparency, basemap, tooltips, size legend
• SC-04: Data Range (3/3) - All 30 cities visible within map bounds
• SC-05: Legend Accuracy (2/2) - Both legends accurate and descriptive
• SC-06: Title Format (2/2) - Correct format "World City Populations · bubble-map-geographic · altair · pyplots.ai"

Data Quality (18/20 pts)

• DQ-01: Feature Coverage (7/8) - Shows good range of populations (5.4M to 37.4M), multiple regions, various geographic distributions; minor deduction for Africa having only 2 cities
• DQ-02: Realistic Context (7/7) - Real world cities with accurate populations and coordinates; neutral educational topic
• DQ-03: Appropriate Scale (4/5) - Population values are realistic; coordinates accurate; minor issue with some population values slightly dated

Code Quality (8/10 pts)

• CQ-01: KISS Structure (3/3) - Clean linear flow: imports → data → map → bubbles → combine → save
• CQ-02: Reproducibility (1/3) - No random seed needed (deterministic data), but hardcoded data could benefit from source comment
• CQ-03: Clean Imports (2/2) - Only altair and pandas imported
• CQ-04: No Deprecated API (1/1) - Uses current Altair API
• CQ-05: Output Correct (1/1) - Saves as plot.png and plot.html

Library Features (5/5 pts)

• LF-01: Uses distinctive library features (5/5) - Excellent use of Altair features: declarative encoding, topo_feature for basemap, layered composition, interactive tooltips, vega-datasets URL loading

Strengths

• Excellent use of Altair's declarative grammar for geographic visualization
• Proper layering of basemap and bubble overlay with matching projections
• Good use of tooltips showing city, population, region, and coordinates
• Clean code structure with well-organized data definition
• Appropriate bubble sizing with scale domain matching data range
• White stroke outlines improve bubble distinction
• Both PNG and HTML outputs for static and interactive viewing

Weaknesses

• Size legend uses single color (#306998) rather than showing how colors vary by region in the actual bubbles
• Code lacks a reproducibility comment about data source (e.g., UN population estimates year)

Verdict: APPROVED