feat(pygal): implement bubble-map-geographic (#3637)

## Implementation: `bubble-map-geographic` - pygal

Implements the **pygal** version of `bubble-map-geographic`.

**File:** `plots/bubble-map-geographic/implementations/pygal.py`

**Parent Issue:** #3625

---
:robot: *[impl-generate
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20873960009)*

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/bubble-map-geographic/implementations/pygal.py

@@ -0,0 +1,185 @@
+""" pyplots.ai
+bubble-map-geographic: Bubble Map with Sized Geographic Markers
+Library: pygal 3.1.0 | Python 3.13.11
+Quality: 90/100 | Created: 2026-01-10
+"""
+
+# Fix module name conflict (this file is named pygal.py)
+import sys
+
+
+_cwd = sys.path[0] if sys.path and sys.path[0] else None
+if _cwd:
+    sys.path.remove(_cwd)
+
+import numpy as np  # noqa: E402
+import pygal  # noqa: E402
+from pygal.style import Style  # noqa: E402
+
+
+if _cwd:
+    sys.path.insert(0, _cwd)
+
+
+# Data - Major world cities with population data (millions)
+np.random.seed(42)
+
+cities = {
+    "Tokyo": (35.68, 139.69, 37.4),
+    "Delhi": (28.61, 77.21, 32.9),
+    "Shanghai": (31.23, 121.47, 28.5),
+    "Sao Paulo": (-23.55, -46.63, 22.4),
+    "Mexico City": (19.43, -99.13, 21.8),
+    "Cairo": (30.04, 31.24, 21.3),
+    "Mumbai": (19.08, 72.88, 20.7),
+    "Beijing": (39.90, 116.41, 20.5),
+    "New York": (40.71, -74.01, 18.8),
+    "Los Angeles": (34.05, -118.24, 12.5),
+    "Paris": (48.86, 2.35, 11.0),
+    "London": (51.51, -0.13, 9.5),
+    "Moscow": (55.76, 37.62, 12.5),
+    "Istanbul": (41.01, 28.98, 15.4),
+    "Lagos": (6.52, 3.38, 14.9),
+    "Buenos Aires": (-34.60, -58.38, 15.4),
+    "Sydney": (-33.87, 151.21, 5.4),
+    "Seoul": (37.57, 126.98, 9.8),
+    "Bangkok": (13.76, 100.50, 10.7),
+    "Jakarta": (-6.21, 106.85, 10.6),
+}
+
+# Extract data
+names = list(cities.keys())
+lats = [cities[c][0] for c in names]
+lons = [cities[c][1] for c in names]
+populations = [cities[c][2] for c in names]
+
+# Simplified world coastlines as XY series (longitude, latitude format for pygal XY)
+coastlines = [
+    # North America
+    [
+        (-125, 50),
+        (-141, 60),
+        (-165, 55),
+        (-168, 52),
+        (-148, 60),
+        (-130, 55),
+        (-120, 49),
+        (-95, 49),
+        (-80, 45),
+        (-67, 45),
+        (-75, 35),
+        (-81, 25),
+        (-90, 30),
+        (-97, 26),
+        (-110, 32),
+        (-125, 50),
+    ],
+    # Mexico/Central America
+    [(-117, 33), (-110, 25), (-97, 20), (-87, 16), (-80, 8), (-90, 22), (-110, 32), (-117, 33)],
+    # South America
+    [(-78, 10), (-60, 8), (-35, -6), (-42, -23), (-66, -55), (-72, -30), (-78, 10)],
+    # Europe/Africa
+    [(-10, 36), (10, 37), (30, 31), (42, 14), (35, -22), (17, -30), (0, 6), (-17, 14), (-10, 36)],
+    # Northern Europe
+    [(-6, 50), (5, 58), (28, 70), (24, 55), (3, 51), (-6, 50)],
+    # Asia
+    [(28, 70), (100, 77), (170, 60), (120, 32), (100, 14), (72, 25), (40, 46), (28, 70)],
+    # India/SE Asia
+    [(78, 33), (72, 8), (88, 22), (104, 2), (78, 33)],
+    # Japan
+    [(130, 32), (145, 44), (130, 32)],
+    # Australia
+    [(113, -22), (150, -23), (140, -38), (113, -22)],
+]
+
+# Bin cities by population for bubble sizing
+small_cities = []  # < 12M
+medium_cities = []  # 12-20M
+large_cities = []  # 20-30M
+mega_cities = []  # > 30M
+
+for i, name in enumerate(names):
+    lat, lon, pop = lats[i], lons[i], populations[i]
+    point = {"value": (lon, lat), "label": f"{name}: {pop}M"}
+
+    if pop < 12:
+        small_cities.append(point)
+    elif pop < 20:
+        medium_cities.append(point)
+    elif pop < 30:
+        large_cities.append(point)
+    else:
+        mega_cities.append(point)
+
+# Custom style for 4800x2700 canvas
+# Colors: 9 gray for coastlines, then 4 for population categories
+custom_style = Style(
+    background="white",
+    plot_background="#C8DDF0",  # Ocean blue background
+    foreground="#333333",
+    foreground_strong="#111111",
+    foreground_subtle="#666666",
+    guide_stroke_color="#88888866",  # Semi-transparent gray grid lines
+    guide_stroke_dasharray="5,5",  # Dashed grid lines for visibility
+    colors=(
+        # Gray for all coastlines (9 series)
+        "#999999",
+        "#999999",
+        "#999999",
+        "#999999",
+        "#999999",
+        "#999999",
+        "#999999",
+        "#999999",
+        "#999999",
+        # City bubble colors - distinct colors for population sizes
+        "#306998",  # Python Blue - small
+        "#4a8cc2",  # Light blue - medium
+        "#FFD43B",  # Python Yellow - large
+        "#E24A33",  # Red-orange - mega
+    ),
+    opacity=0.7,
+    opacity_hover=0.9,
+    title_font_size=72,
+    label_font_size=48,
+    major_label_font_size=40,
+    legend_font_size=40,
+    value_font_size=36,
+    tooltip_font_size=36,
+)
+
+# Create XY chart
+chart = pygal.XY(
+    width=4800,
+    height=2700,
+    style=custom_style,
+    title="bubble-map-geographic · pygal · pyplots.ai",
+    x_title="Longitude (°)",
+    y_title="Latitude (°)",
+    show_legend=True,
+    legend_at_bottom=True,
+    legend_at_bottom_columns=4,
+    legend_box_size=30,
+    stroke=True,
+    dots_size=3,
+    show_x_guides=True,
+    show_y_guides=True,
+    explicit_size=True,
+    print_values=False,
+    xrange=(-180, 180),
+    range=(-60, 80),
+)
+
+# Add coastlines as background (None title = no legend entry in pygal)
+for coords in coastlines:
+    chart.add(None, coords, stroke=True, dots_size=0, show_dots=False, fill=False)
+
+# Add city bubbles by population category (increased sizes for visibility)
+chart.add("Pop < 12M", small_cities, stroke=False, dots_size=28)
+chart.add("Pop 12-20M", medium_cities, stroke=False, dots_size=42)
+chart.add("Pop 20-30M", large_cities, stroke=False, dots_size=58)
+chart.add("Pop > 30M", mega_cities, stroke=False, dots_size=78)
+
+# Save outputs (PNG first as primary, then HTML for interactivity)
+chart.render_to_png("plot.png")
+chart.render_to_file("plot.html")

plots/bubble-map-geographic/metadata/pygal.yaml

@@ -0,0 +1,212 @@
+library: pygal
+specification_id: bubble-map-geographic
+created: '2026-01-10T06:14:04Z'
+updated: '2026-01-10T06:22:11Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20873960009
+issue: 3625
+python_version: 3.13.11
+library_version: 3.1.0
+preview_url: https://storage.googleapis.com/pyplots-images/plots/bubble-map-geographic/pygal/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/bubble-map-geographic/pygal/plot_thumb.png
+preview_html: https://storage.googleapis.com/pyplots-images/plots/bubble-map-geographic/pygal/plot.html
+quality_score: 90
+review:
+  strengths:
+  - Excellent visual clarity with well-sized text and clear color differentiation
+  - Effective use of custom coastline polygons to provide geographic context
+  - Good use of pygal custom Style for controlling fonts and colors at high resolution
+  - Interactive HTML output with hover tooltips showing city names and populations
+  - Clean well-structured code following KISS principles
+  weaknesses:
+  - Bubble sizes are categorical (4 fixed sizes) rather than continuously scaled proportional
+    to population values as the spec requires
+  - Grid lines are somewhat prominent compared to ideal subtle alpha 0.2-0.4
+  - Does not use pygal World map capability which could provide better geographic
+    basemap
+  image_description: 'The plot displays a geographic bubble map with 20 world cities
+    plotted on an XY coordinate system where X represents Longitude (-180 to 160°)
+    and Y represents Latitude (-60 to 80°). The background is a light blue (#C8DDF0)
+    representing oceans, with simplified gray coastline outlines for continents (North
+    America, South America, Europe, Africa, Asia, Australia). City bubbles are color-coded
+    by population category: small dark blue (Pop < 12M), medium blue (Pop 12-20M),
+    yellow (Pop 20-30M), and red-orange (Pop > 30M). Bubble sizes increase proportionally
+    with population category. The two largest red-orange bubbles represent Tokyo and
+    Delhi (>30M). The title "bubble-map-geographic · pygal · pyplots.ai" appears at
+    the top. A legend at the bottom shows the four population categories. Grid lines
+    are subtle dashed gray lines.'
+  criteria_checklist:
+    visual_quality:
+      score: 36
+      max: 40
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 10
+        max: 10
+        passed: true
+        comment: 'All text clearly readable: title at 72pt, axis labels at 48pt, tick
+          labels at 40pt, legend at 40pt'
+      - id: VQ-02
+        name: No Overlap
+        score: 8
+        max: 8
+        passed: true
+        comment: No overlapping text or elements
+      - id: VQ-03
+        name: Element Visibility
+        score: 6
+        max: 8
+        passed: true
+        comment: Bubbles are well-sized and visible; however size variation within
+          each category is not shown
+      - id: VQ-04
+        name: Color Accessibility
+        score: 5
+        max: 5
+        passed: true
+        comment: Blue/yellow/red color scheme is colorblind-safe and provides good
+          contrast
+      - id: VQ-05
+        name: Layout Balance
+        score: 5
+        max: 5
+        passed: true
+        comment: Good use of canvas with balanced margins, plot fills appropriate
+          area
+      - id: VQ-06
+        name: Axis Labels
+        score: 2
+        max: 2
+        passed: true
+        comment: Longitude (°) and Latitude (°) with units
+      - id: VQ-07
+        name: Grid & Legend
+        score: 0
+        max: 2
+        passed: false
+        comment: Grid lines are quite visible/prominent, not subtle alpha 0.2-0.4
+    spec_compliance:
+      score: 23
+      max: 25
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 8
+        max: 8
+        passed: true
+        comment: Correct bubble map implementation using XY scatter with sized markers
+      - id: SC-02
+        name: Data Mapping
+        score: 5
+        max: 5
+        passed: true
+        comment: Longitude on X, Latitude on Y, population controlling size category
+      - id: SC-03
+        name: Required Features
+        score: 3
+        max: 5
+        passed: false
+        comment: 'Has sized bubbles, geographic context, transparency, tooltips. Missing:
+          continuous size scaling'
+      - id: SC-04
+        name: Data Range
+        score: 3
+        max: 3
+        passed: true
+        comment: All data visible within range
+      - id: SC-05
+        name: Legend Accuracy
+        score: 2
+        max: 2
+        passed: true
+        comment: Legend correctly shows all four population categories
+      - id: SC-06
+        name: Title Format
+        score: 2
+        max: 2
+        passed: true
+        comment: 'Correct format: bubble-map-geographic · pygal · pyplots.ai'
+    data_quality:
+      score: 18
+      max: 20
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 6
+        max: 8
+        passed: true
+        comment: Shows range of populations, good geographic spread. Categorical binning
+          reduces continuous size variation demo
+      - id: DQ-02
+        name: Realistic Context
+        score: 7
+        max: 7
+        passed: true
+        comment: Real-world city population data, accurate locations, plausible values
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 5
+        max: 5
+        passed: true
+        comment: Population values are realistic and well-documented (in millions)
+    code_quality:
+      score: 10
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: 'Simple linear flow: imports → data → coastlines → chart → save'
+      - id: CQ-02
+        name: Reproducibility
+        score: 3
+        max: 3
+        passed: true
+        comment: Uses np.random.seed(42)
+      - id: CQ-03
+        name: Clean Imports
+        score: 2
+        max: 2
+        passed: true
+        comment: Only necessary imports
+      - id: CQ-04
+        name: No Deprecated API
+        score: 1
+        max: 1
+        passed: true
+        comment: Uses current pygal API
+      - id: CQ-05
+        name: Output Correct
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves as plot.png and plot.html
+    library_features:
+      score: 3
+      max: 5
+      items:
+      - id: LF-01
+        name: Distinctive Features
+        score: 3
+        max: 5
+        passed: true
+        comment: Good use of XY chart, custom Style, interactive HTML output. Does
+          not use pygal World map charts
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - hover-tooltips
+  - html-export
+  - custom-legend
+  patterns:
+  - data-generation
+  - iteration-over-groups
+  dataprep:
+  - binning
+  styling:
+  - alpha-blending
+  - grid-styling