feat(plotly): implement bubble-map-geographic (#3634)

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

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

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

**Parent Issue:** #3625

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

---------

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

Author: github-actions[bot]

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

@@ -0,0 +1,162 @@
+""" pyplots.ai
+bubble-map-geographic: Bubble Map with Sized Geographic Markers
+Library: plotly 6.5.1 | Python 3.13.11
+Quality: 91/100 | Created: 2026-01-10
+"""
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+
+
+# Data: Major world cities with population (in millions)
+np.random.seed(42)
+
+cities = [
+    {"city": "Tokyo", "lat": 35.6762, "lon": 139.6503, "pop": 37.4, "region": "Asia"},
+    {"city": "Delhi", "lat": 28.7041, "lon": 77.1025, "pop": 31.2, "region": "Asia"},
+    {"city": "Shanghai", "lat": 31.2304, "lon": 121.4737, "pop": 27.8, "region": "Asia"},
+    {"city": "São Paulo", "lat": -23.5505, "lon": -46.6333, "pop": 22.4, "region": "South America"},
+    {"city": "Mexico City", "lat": 19.4326, "lon": -99.1332, "pop": 21.9, "region": "North America"},
+    {"city": "Cairo", "lat": 30.0444, "lon": 31.2357, "pop": 21.3, "region": "Africa"},
+    {"city": "Mumbai", "lat": 19.0760, "lon": 72.8777, "pop": 20.7, "region": "Asia"},
+    {"city": "Beijing", "lat": 39.9042, "lon": 116.4074, "pop": 20.5, "region": "Asia"},
+    {"city": "Dhaka", "lat": 23.8103, "lon": 90.4125, "pop": 22.5, "region": "Asia"},
+    {"city": "Osaka", "lat": 34.6937, "lon": 135.5023, "pop": 19.2, "region": "Asia"},
+    {"city": "New York", "lat": 40.7128, "lon": -74.0060, "pop": 18.8, "region": "North America"},
+    {"city": "Karachi", "lat": 24.8607, "lon": 67.0011, "pop": 16.5, "region": "Asia"},
+    {"city": "Buenos Aires", "lat": -34.6037, "lon": -58.3816, "pop": 15.2, "region": "South America"},
+    {"city": "Istanbul", "lat": 41.0082, "lon": 28.9784, "pop": 15.4, "region": "Europe"},
+    {"city": "Lagos", "lat": 6.5244, "lon": 3.3792, "pop": 14.9, "region": "Africa"},
+    {"city": "Manila", "lat": 14.5995, "lon": 120.9842, "pop": 14.4, "region": "Asia"},
+    {"city": "Rio de Janeiro", "lat": -22.9068, "lon": -43.1729, "pop": 13.5, "region": "South America"},
+    {"city": "Los Angeles", "lat": 34.0522, "lon": -118.2437, "pop": 12.5, "region": "North America"},
+    {"city": "Moscow", "lat": 55.7558, "lon": 37.6173, "pop": 12.5, "region": "Europe"},
+    {"city": "Paris", "lat": 48.8566, "lon": 2.3522, "pop": 11.1, "region": "Europe"},
+    {"city": "London", "lat": 51.5074, "lon": -0.1278, "pop": 9.5, "region": "Europe"},
+    {"city": "Lima", "lat": -12.0464, "lon": -77.0428, "pop": 10.9, "region": "South America"},
+    {"city": "Bangkok", "lat": 13.7563, "lon": 100.5018, "pop": 10.7, "region": "Asia"},
+    {"city": "Jakarta", "lat": -6.2088, "lon": 106.8456, "pop": 10.6, "region": "Asia"},
+    {"city": "Seoul", "lat": 37.5665, "lon": 126.9780, "pop": 9.9, "region": "Asia"},
+    {"city": "Sydney", "lat": -33.8688, "lon": 151.2093, "pop": 5.4, "region": "Oceania"},
+    {"city": "Melbourne", "lat": -37.8136, "lon": 144.9631, "pop": 5.0, "region": "Oceania"},
+    {"city": "Toronto", "lat": 43.6532, "lon": -79.3832, "pop": 6.3, "region": "North America"},
+    {"city": "Chicago", "lat": 41.8781, "lon": -87.6298, "pop": 8.9, "region": "North America"},
+    {"city": "Singapore", "lat": 1.3521, "lon": 103.8198, "pop": 5.9, "region": "Asia"},
+]
+
+df = pd.DataFrame(cities)
+
+# Scale bubble sizes: area proportional to population
+# Using sqrt to make area proportional (since marker size is diameter)
+min_size = 15
+max_size = 70
+df["marker_size"] = min_size + (max_size - min_size) * np.sqrt(
+    (df["pop"] - df["pop"].min()) / (df["pop"].max() - df["pop"].min())
+)
+
+# Color palette for regions (colorblind-safe)
+region_colors = {
+    "Asia": "#306998",  # Python Blue
+    "Europe": "#FFD43B",  # Python Yellow
+    "North America": "#2ca02c",  # Green
+    "South America": "#ff7f0e",  # Orange
+    "Africa": "#9467bd",  # Purple
+    "Oceania": "#17becf",  # Cyan
+}
+
+# Create figure with geo map
+fig = go.Figure()
+
+# Add traces for each region to create proper legend
+for region in df["region"].unique():
+    region_df = df[df["region"] == region]
+    fig.add_trace(
+        go.Scattergeo(
+            lon=region_df["lon"],
+            lat=region_df["lat"],
+            text=region_df.apply(lambda x: f"{x['city']}<br>Population: {x['pop']:.1f}M", axis=1),
+            marker={
+                "size": region_df["marker_size"],
+                "color": region_colors[region],
+                "opacity": 0.65,
+                "line": {"width": 1.5, "color": "white"},
+                "sizemode": "diameter",
+            },
+            name=region,
+            hovertemplate="%{text}<extra></extra>",
+        )
+    )
+
+# Update layout for 4800x2700
+fig.update_layout(
+    title={
+        "text": "World City Populations · bubble-map-geographic · plotly · pyplots.ai",
+        "font": {"size": 32, "color": "#333333"},
+        "x": 0.5,
+        "xanchor": "center",
+    },
+    geo={
+        "showland": True,
+        "landcolor": "rgb(243, 243, 243)",
+        "showocean": True,
+        "oceancolor": "rgb(230, 240, 250)",
+        "showcoastlines": True,
+        "coastlinecolor": "rgb(150, 150, 150)",
+        "coastlinewidth": 1,
+        "showframe": True,
+        "framecolor": "rgb(100, 100, 100)",
+        "framewidth": 1,
+        "showcountries": True,
+        "countrycolor": "rgb(200, 200, 200)",
+        "countrywidth": 0.5,
+        "projection_type": "natural earth",
+        "lataxis": {"range": [-60, 75]},
+        "lonaxis": {"range": [-140, 180]},
+    },
+    legend={
+        "title": {"text": "Region", "font": {"size": 20}},
+        "font": {"size": 18},
+        "itemsizing": "constant",
+        "x": 0.02,
+        "y": 0.35,
+        "bgcolor": "rgba(255,255,255,0.85)",
+        "bordercolor": "rgba(0,0,0,0.2)",
+        "borderwidth": 1,
+    },
+    margin={"l": 20, "r": 20, "t": 80, "b": 20},
+    template="plotly_white",
+)
+
+# Add size legend annotation
+fig.add_annotation(
+    text="Bubble size = Population (millions)",
+    xref="paper",
+    yref="paper",
+    x=0.02,
+    y=0.15,
+    showarrow=False,
+    font={"size": 16, "color": "#555555"},
+    align="left",
+)
+
+# Example size indicators
+size_examples = [5, 20, 35]
+for i, pop_val in enumerate(size_examples):
+    size = min_size + (max_size - min_size) * np.sqrt((pop_val - df["pop"].min()) / (df["pop"].max() - df["pop"].min()))
+    fig.add_annotation(
+        text=f"  {pop_val}M",
+        xref="paper",
+        yref="paper",
+        x=0.065,
+        y=0.09 - i * 0.028,
+        showarrow=False,
+        font={"size": 14, "color": "#666666"},
+        align="left",
+    )
+
+# Save as PNG (4800x2700)
+fig.write_image("plot.png", width=1600, height=900, scale=3)
+
+# Save as HTML for interactivity
+fig.write_html("plot.html", include_plotlyjs="cdn")

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

@@ -0,0 +1,218 @@
+library: plotly
+specification_id: bubble-map-geographic
+created: '2026-01-10T06:09:27Z'
+updated: '2026-01-10T06:13:11Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20873955145
+issue: 3625
+python_version: 3.13.11
+library_version: 6.5.1
+preview_url: https://storage.googleapis.com/pyplots-images/plots/bubble-map-geographic/plotly/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/bubble-map-geographic/plotly/plot_thumb.png
+preview_html: https://storage.googleapis.com/pyplots-images/plots/bubble-map-geographic/plotly/plot.html
+quality_score: 91
+review:
+  strengths:
+  - Excellent geographic visualization using Plotly's native Scattergeo with Natural
+    Earth projection
+  - Proper area scaling using sqrt transform for perceptually accurate bubble sizes
+  - Well-designed colorblind-safe palette for 6 distinct regions
+  - Comprehensive hover tooltips showing city name and population
+  - Clean code structure with clear data preparation
+  - Both PNG and interactive HTML outputs generated
+  weaknesses:
+  - Size legend shows text labels (5M, 20M, 35M) but lacks corresponding visual bubble
+    indicators to demonstrate the actual sizes
+  - Could leverage more Plotly-specific features like linked hover highlighting or
+    custom zoom controls
+  image_description: 'The plot displays a world map using the Natural Earth projection
+    with a light gray landmass and pale blue ocean. Thirty major world cities are
+    represented as bubbles sized proportionally to their population (in millions).
+    The bubbles are color-coded by region using a 6-color palette: blue for Asia,
+    orange for South America, green for North America, purple for Africa, yellow for
+    Europe, and cyan for Oceania. The largest bubbles (Tokyo, Delhi, Shanghai) are
+    clearly visible in Asia. A region legend is positioned in the lower-left corner
+    with a white semi-transparent background. Below the legend, a size legend annotation
+    explains "Bubble size = Population (millions)" with example sizes for 5M, 20M,
+    and 35M. The title at the top follows the required format. Country boundaries
+    are shown as subtle gray lines, and the map uses appropriate latitude/longitude
+    constraints to show all populated continents.'
+  criteria_checklist:
+    visual_quality:
+      score: 36
+      max: 40
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 9
+        max: 10
+        passed: true
+        comment: Title at 32pt is excellent, legend text at 18-20pt is good. Size
+          legend text at 14-16pt is slightly small but readable.
+      - id: VQ-02
+        name: No Overlap
+        score: 8
+        max: 8
+        passed: true
+        comment: No overlapping text elements. Bubbles intentionally overlap in dense
+          areas but handled well with transparency.
+      - id: VQ-03
+        name: Element Visibility
+        score: 7
+        max: 8
+        passed: true
+        comment: Marker sizes scale well from small to large cities. Some smaller
+          cities could be slightly more visible.
+      - id: VQ-04
+        name: Color Accessibility
+        score: 5
+        max: 5
+        passed: true
+        comment: Six-color palette is colorblind-safe with good distinction between
+          all colors.
+      - id: VQ-05
+        name: Layout Balance
+        score: 5
+        max: 5
+        passed: true
+        comment: Map fills canvas well, balanced margins, legend positioned appropriately.
+      - id: VQ-06
+        name: Axis Labels
+        score: 2
+        max: 2
+        passed: true
+        comment: N/A for geographic maps - no traditional axis labels needed.
+      - id: VQ-07
+        name: Grid & Legend
+        score: 2
+        max: 2
+        passed: true
+        comment: Region legend well-formatted with semi-transparent background. Size
+          legend provides helpful context.
+    spec_compliance:
+      score: 25
+      max: 25
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 8
+        max: 8
+        passed: true
+        comment: Correctly implements geographic bubble map with Scattergeo.
+      - id: SC-02
+        name: Data Mapping
+        score: 5
+        max: 5
+        passed: true
+        comment: Latitude/longitude correctly mapped, population correctly encoded
+          as bubble size.
+      - id: SC-03
+        name: Required Features
+        score: 5
+        max: 5
+        passed: true
+        comment: 'All spec requirements met: size legend, transparency, geographic
+          context, hover tooltips.'
+      - id: SC-04
+        name: Data Range
+        score: 3
+        max: 3
+        passed: true
+        comment: Map shows all data points with appropriate lat/lon range.
+      - id: SC-05
+        name: Legend Accuracy
+        score: 2
+        max: 2
+        passed: true
+        comment: Region legend is accurate; size legend explains the scaling.
+      - id: SC-06
+        name: Title Format
+        score: 2
+        max: 2
+        passed: true
+        comment: Uses correct format with spec-id, library, and pyplots.ai.
+    data_quality:
+      score: 18
+      max: 20
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 7
+        max: 8
+        passed: true
+        comment: Shows good range of populations across 6 regions. Could include more
+          small cities.
+      - id: DQ-02
+        name: Realistic Context
+        score: 7
+        max: 7
+        passed: true
+        comment: Real-world city population data with accurate coordinates.
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 5
+        passed: true
+        comment: Population values are realistic and current.
+    code_quality:
+      score: 9
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: 'Clean linear structure: imports, data, size calculation, figure,
+          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 numpy, pandas, and plotly.graph_objects imported.
+      - id: CQ-04
+        name: No Deprecated API
+        score: 1
+        max: 1
+        passed: true
+        comment: Uses current Plotly API.
+      - id: CQ-05
+        name: Output Correct
+        score: 0
+        max: 1
+        passed: false
+        comment: Size legend text labels lack corresponding visual bubble indicators.
+    library_features:
+      score: 3
+      max: 5
+      items:
+      - id: LF-01
+        name: Distinctive Features
+        score: 3
+        max: 5
+        passed: true
+        comment: Uses Scattergeo and generates interactive HTML with hover tooltips.
+          Could leverage more Plotly features.
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - annotations
+  - hover-tooltips
+  - html-export
+  - iteration-over-groups
+  patterns:
+  - data-generation
+  - iteration-over-groups
+  dataprep:
+  - normalization
+  styling:
+  - alpha-blending
+  - edge-highlighting