dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/geo.py

@@ -0,0 +1,700 @@
+"""Geographic and map chart Vega-Lite spec generators."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dataface.core.compile.chart_resolved import ResolvedChart, effective_color_field
+from dataface.core.compile.models.style.merged import MergedStyle, resolve_mark
+from dataface.core.compile.models.vega_lite.contracts import Projection
+from dataface.core.render.chart.presentation import to_plain_dict
+from dataface.core.render.chart.spec_builders import (
+    new_chart_spec,
+    set_chart_dimensions,
+    set_chart_title,
+    tooltip_entry,
+)
+from dataface.core.render.chart.type_inference import infer_vega_type_from_data
+from dataface.core.render.format_utils import resolve_format
+from dataface.core.render.text.case import format_display_text
+from dataface.core.render.utils import normalize_data_types, slug_to_text
+
+
+def _add_data_join(
+    spec: dict[str, Any],
+    data: list[dict[str, Any]],
+    geo_key: str,
+    lookup_field: str | None,
+    value_field: str | None,
+    handle_missing: bool = False,
+    default_value: Any | None = None,
+) -> dict[str, Any]:
+    """Add lookup transform to join user data to geographic features.
+
+    This function creates a Vega-Lite lookup transform that joins user data
+    to geographic features (states, countries, etc.) based on matching keys.
+
+    The geo data (from URL) becomes the primary data source, and user data
+    is joined via lookup. This ensures all geographic regions are displayed,
+    with unmatched regions showing null values.
+
+    Args:
+        spec: Vega-Lite spec to modify (will be modified in place)
+        data: User data to join to geographic features
+        geo_key: Key field in geographic data (e.g., "id" in TopoJSON)
+        lookup_field: Key field in user data to match against geo_key
+        value_field: Field in user data to use for encoding (color, etc.)
+        handle_missing: If True, add handling for missing/unmatched data
+        default_value: Default value for unmatched geographic features
+
+    Returns:
+        Modified Vega-Lite spec with lookup transform added
+
+    Example:
+        >>> spec = {"data": {"url": "us-10m.json"}}
+        >>> data = [{"state_code": "06", "population": 39500000}]
+        >>> result = _add_data_join(spec, data, "id", "state_code", "population")
+        >>> result["transform"][0]["lookup"]
+        'id'
+
+    """
+    # Return spec unchanged if no data or no lookup field
+    if not data or not lookup_field:
+        return spec
+
+    # Get all fields from data to include in lookup
+    data_fields = list(data[0].keys()) if data else []
+
+    # Create lookup transform
+    lookup_transform: dict[str, Any] = {
+        "lookup": geo_key,
+        "from": {
+            "data": {"values": data},
+            "key": lookup_field,
+            "fields": data_fields,
+        },
+    }
+
+    # Initialize transforms list if not present
+    if "transform" not in spec:
+        spec["transform"] = []
+
+    # Add the lookup transform
+    spec["transform"].insert(0, lookup_transform)
+
+    # Handle missing/unmatched data if requested
+    if handle_missing and default_value is not None and value_field:
+        # Add a calculate transform to replace nulls with default value
+        # This ensures unmatched regions show with the default value
+        calculate_transform = {
+            "calculate": f"datum.{value_field} === null ? {default_value} : datum.{value_field}",
+            "as": f"{value_field}_filled",
+        }
+        spec["transform"].append(calculate_transform)
+
+    return spec
+
+
+# ============================================================================
+# GEOGRAPHIC DATA SOURCES
+# ============================================================================
+# Built-in geographic data sources from Vega Datasets CDN
+
+GEO_SOURCES: dict[str, dict[str, Any]] = {
+    # US boundaries
+    "us-states": {
+        "url": "https://vega.github.io/vega-datasets/data/us-10m.json",
+        "format": {"type": "topojson", "feature": "states"},
+        "projection": "albersUsa",
+        "key": "id",
+    },
+    "us-counties": {
+        "url": "https://vega.github.io/vega-datasets/data/us-10m.json",
+        "format": {"type": "topojson", "feature": "counties"},
+        "projection": "albersUsa",
+        "key": "id",
+    },
+    # World boundaries
+    "world-countries": {
+        "url": "https://vega.github.io/vega-datasets/data/world-110m.json",
+        "format": {"type": "topojson", "feature": "countries"},
+        "projection": "equalEarth",
+        "key": "id",
+    },
+    "world-50m": {
+        "url": "https://vega.github.io/vega-datasets/data/world-50m.json",
+        "format": {"type": "topojson", "feature": "countries"},
+        "projection": "equalEarth",
+        "key": "id",
+    },
+    # City neighborhoods - San Francisco
+    "sf-neighborhoods": {
+        "url": "https://data.sfgov.org/api/geospatial/p5b7-5n3h?method=export&format=GeoJSON",
+        "format": {"type": "json", "property": "features"},
+        "projection": {
+            "type": "mercator",
+            "center": [-122.4194, 37.7749],
+            "scale": 80000,
+        },
+        "key": "nhood",
+    },
+    # City neighborhoods - New York City
+    "nyc-neighborhoods": {
+        "url": "https://data.cityofnewyork.us/api/geospatial/cpf4-rkhq?method=export&format=GeoJSON",
+        "format": {"type": "json", "property": "features"},
+        "projection": {
+            "type": "mercator",
+            "center": [-73.9857, 40.7484],
+            "scale": 40000,
+        },
+        "key": "ntaname",
+    },
+    # City neighborhoods - Chicago
+    "chicago-neighborhoods": {
+        "url": "https://data.cityofchicago.org/api/geospatial/bbvz-uum9?method=export&format=GeoJSON",
+        "format": {"type": "json", "property": "features"},
+        "projection": {
+            "type": "mercator",
+            "center": [-87.6298, 41.8781],
+            "scale": 50000,
+        },
+        "key": "pri_neigh",
+    },
+    # City neighborhoods - Los Angeles
+    "la-neighborhoods": {
+        "url": "https://data.lacity.org/api/geospatial/r3ta-u4d6?method=export&format=GeoJSON",
+        "format": {"type": "json", "property": "features"},
+        "projection": {
+            "type": "mercator",
+            "center": [-118.2437, 34.0522],
+            "scale": 35000,
+        },
+        "key": "name",
+    },
+}
+
+# Supported projections with their default settings
+PROJECTIONS: dict[str, dict[str, Any]] = {
+    "mercator": {"type": "mercator"},
+    "albersUsa": {"type": "albersUsa"},
+    "equalEarth": {"type": "equalEarth"},
+    "naturalEarth1": {"type": "naturalEarth1"},
+    "orthographic": {"type": "orthographic"},
+    "stereographic": {"type": "stereographic"},
+    "albers": {"type": "albers"},
+    "conicEqualArea": {"type": "conicEqualArea"},
+    "equirectangular": {"type": "equirectangular"},
+}
+
+
+def _resolve_geo_source(
+    geo_source: str | None,
+    geo_feature: str | None = None,
+) -> tuple[str, dict[str, Any], str | dict[str, Any]]:
+    """Resolve a geo source name or URL to URL, format, and default projection."""
+    if geo_source in GEO_SOURCES:
+        geo_info = GEO_SOURCES[geo_source]
+        resolved_feature = geo_feature or geo_info["format"].get("feature")
+        geo_format = dict(geo_info["format"])
+        if resolved_feature:
+            geo_format["feature"] = resolved_feature
+        return geo_info["url"], geo_format, geo_info["projection"]
+
+    return (
+        geo_source or "",
+        {"type": "topojson", "feature": geo_feature or "features"},
+        "mercator",
+    )
+
+
+def _resolve_projection(
+    projection_config: str | Projection | None,
+    default_projection: str | dict[str, Any],
+    fallback: str,
+) -> dict[str, Any]:
+    """Resolve the explicit or default projection config."""
+    if isinstance(projection_config, str):
+        return PROJECTIONS.get(projection_config, {"type": projection_config})
+    if isinstance(projection_config, Projection):
+        return to_plain_dict(projection_config)
+    if isinstance(default_projection, dict):
+        return default_projection
+    return PROJECTIONS.get(default_projection, {"type": fallback})
+
+
+def _build_point_position_encoding(
+    lat_field: str | None,
+    lng_field: str | None,
+) -> dict[str, Any]:
+    """Build latitude and longitude encodings for point maps."""
+    encoding: dict[str, Any] = {}
+    if lng_field:
+        encoding["longitude"] = {"field": lng_field, "type": "quantitative"}
+    if lat_field:
+        encoding["latitude"] = {"field": lat_field, "type": "quantitative"}
+    return encoding
+
+
+def _build_point_tooltip_fields(
+    data: list[dict[str, Any]],
+    *,
+    lat_field: str | None = None,
+    lng_field: str | None = None,
+    size_field: str | None = None,
+    color_field: str | None = None,
+    max_fields: int = 6,
+    tooltip_format: str,
+) -> list[dict[str, Any]]:
+    """Build tooltip fields for point and bubble maps."""
+    tooltip_fields: list[dict[str, Any]] = []
+
+    if lat_field:
+        tooltip_fields.append(
+            tooltip_entry(lat_field, "quantitative", title="Latitude"),
+        )
+    if lng_field:
+        tooltip_fields.append(
+            tooltip_entry(lng_field, "quantitative", title="Longitude"),
+        )
+    if size_field:
+        tooltip_fields.append(
+            tooltip_entry(
+                size_field,
+                "quantitative",
+                title=slug_to_text(size_field),
+                format=tooltip_format,
+            ),
+        )
+    if color_field:
+        tooltip_fields.append(
+            tooltip_entry(
+                color_field,
+                infer_vega_type_from_data(data, color_field),
+                title=slug_to_text(color_field),
+            ),
+        )
+
+    if data:
+        for field in data[0]:
+            if field in {lat_field, lng_field, size_field, color_field}:
+                continue
+            tooltip_fields.append(
+                tooltip_entry(
+                    field,
+                    infer_vega_type_from_data(data, field),
+                    title=slug_to_text(field),
+                ),
+            )
+            if len(tooltip_fields) >= max_fields:
+                break
+
+    return tooltip_fields
+
+
+def _generate_map_spec(
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    chart_type: str,
+    width: float | None = None,
+    height: float | None = None,
+    *,
+    board_style: MergedStyle,
+) -> dict[str, Any]:
+    """Generate geographic map specification (map, geoshape, etc.).
+
+    Creates Vega-Lite specs for geographic visualizations including:
+    - Filled-region maps (colored by data)
+    - Base geoshape maps (outline only)
+
+    Uses the _add_data_join() helper for consistent data joining across
+    all map types.
+
+    Args:
+        chart: Chart definition with geo configuration
+        data: List of data points to join to geographic features
+        chart_type: Type of map ('map', 'geoshape')
+        width: Optional explicit width in pixels
+        height: Optional explicit height in pixels
+
+    Returns:
+        Vega-Lite specification for geographic visualization
+
+    """
+    data = normalize_data_types(data)
+    map_config = chart.resolved_style.geoshape
+
+    # Get geo configuration from chart
+    geo_config = chart.geo
+    geo_source = chart.geo_source
+
+    # If geo_config is a dict, extract source
+    if isinstance(geo_config, dict):
+        geo_source = geo_config.get("source", geo_source)
+        geo_key = geo_config.get("key", "id")
+        geo_feature = geo_config.get("feature", None)
+    else:
+        geo_key = "id"
+        geo_feature = None
+
+    geo_url, geo_format, default_projection = _resolve_geo_source(
+        geo_source,
+        geo_feature,
+    )
+    projection = _resolve_projection(chart.projection, default_projection, "mercator")
+
+    color_field = effective_color_field(chart)
+    value_field: str | None = chart.value or color_field
+    lookup_field = chart.lookup
+
+    # Resolve the geoshape mark (global tier + optional family override).
+    charts = chart.resolved_style
+    geoshape_mark = resolve_mark(
+        charts.marks.geoshape,
+        map_config.marks.geoshape,
+    )
+
+    # Build the spec
+    spec = new_chart_spec(
+        data,
+        mark={
+            "type": "geoshape",
+            "stroke": geoshape_mark.stroke.color if geoshape_mark.stroke else None,
+            "strokeWidth": geoshape_mark.stroke.width if geoshape_mark.stroke else None,
+            "tooltip": True,
+        },
+    )
+    spec["data"] = {"url": geo_url, "format": geo_format}
+    spec["projection"] = projection
+    set_chart_dimensions(spec, width, height)
+
+    # If we have data to join, use the _add_data_join helper
+    if data and lookup_field and value_field:
+        # Use the data join helper for consistent joining logic
+        spec = _add_data_join(
+            spec=spec,
+            data=data,
+            geo_key=geo_key,
+            lookup_field=lookup_field,
+            value_field=value_field,
+            handle_missing=True,  # Handle missing data gracefully
+        )
+
+        # Color scheme: chart-local style.color_scheme is pre-merged into
+        # map_config.color_scheme by build_resolved_style.
+        spec["encoding"]["color"] = {
+            "field": value_field,
+            "type": "quantitative",
+            "title": format_display_text(
+                value_field, from_slug=True, font=chart.resolved_style.legend.title.font
+            ),
+            "scale": {"scheme": map_config.color_scheme},
+        }
+
+        # Build tooltip from data fields
+        data_fields = list(data[0].keys()) if data else []
+        tooltip_fields: list[dict[str, Any]] = []
+        if lookup_field in data_fields:
+            tooltip_fields.append(
+                tooltip_entry(
+                    lookup_field,
+                    "nominal",
+                    title=slug_to_text(lookup_field),
+                ),
+            )
+        if value_field and value_field != lookup_field:
+            tooltip_fields.append(
+                tooltip_entry(
+                    value_field,
+                    "quantitative",
+                    title=slug_to_text(value_field),
+                    format=resolve_format(
+                        chart.resolved_style.tooltip.format,
+                        chart.resolved_style.formats,
+                    ),
+                ),
+            )
+        if tooltip_fields:
+            spec["encoding"]["tooltip"] = tooltip_fields
+    else:
+        # No data - render the base map with a neutral fill. Prefer the
+        # theme's header background if set; otherwise fall back to the
+        # theme background (universal default has no header fill).
+        _ms = board_style
+        spec["mark"]["fill"] = _ms.charts.table.header.background or _ms.background
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+
+    return spec
+
+
+def _generate_point_map_spec(
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    chart_type: str,
+    width: float | None = None,
+    height: float | None = None,
+    *,
+    board_style: MergedStyle,
+) -> dict[str, Any]:
+    """Generate point/bubble map specification with markers at lat/lng coordinates.
+
+    Creates Vega-Lite specs for geographic point visualizations including:
+    - Point maps (markers at coordinates)
+    - Bubble maps (sized markers based on data values)
+
+    Optionally layers points over a background geoshape (state/country outlines).
+
+    Args:
+        chart: Chart definition with lat/lng configuration
+        data: List of data points with latitude/longitude fields
+        chart_type: Type of map ('point_map', 'bubble_map')
+        width: Optional explicit width in pixels
+        height: Optional explicit height in pixels
+
+    Returns:
+        Vega-Lite specification for point/bubble map
+
+    """
+    data = normalize_data_types(data)
+
+    # Get lat/lng field names
+    lat_field = chart.latitude
+    lng_field = chart.longitude
+
+    # Fallback to common field names if not specified
+    if not lat_field:
+        for field in ["latitude", "lat", "Latitude", "Lat", "y"]:
+            if data and field in data[0]:
+                lat_field = field
+                break
+    if not lng_field:
+        for field in ["longitude", "lng", "lon", "Longitude", "Lng", "Lon", "x"]:
+            if data and field in data[0]:
+                lng_field = field
+                break
+
+    size_field = chart.size
+    color_field = effective_color_field(chart)
+
+    # Get basemap (tile-layer) configuration
+    background_config: dict[str, Any] | None = chart.basemap
+    geo_source = chart.geo_source
+    _scatter = chart.resolved_style.scatter
+    point_mark = resolve_mark(
+        chart.resolved_style.marks.point,
+        _scatter.marks.point,
+    )
+
+    # Get projection configuration
+    # User-provided projection takes precedence, otherwise use geo_source default
+    default_projection: str | dict[str, Any] = "albersUsa"
+    if geo_source and geo_source in GEO_SOURCES:
+        default_projection = GEO_SOURCES[geo_source].get("projection", "albersUsa")
+    projection = _resolve_projection(chart.projection, default_projection, "albersUsa")
+
+    # Determine if we need a layered spec (background + points)
+    has_background = background_config or geo_source
+
+    if has_background:
+        # Create layered spec with background geoshape and points
+        return _generate_layered_point_map_spec(
+            chart,
+            data,
+            lat_field,
+            lng_field,
+            size_field,
+            color_field,
+            projection,
+            background_config,
+            geo_source,
+            width,
+            height,
+            board_style=board_style,
+        )
+
+    # Simple point map without background
+    mark_type = "circle"
+
+    mark_dict: dict[str, Any] = {"type": mark_type, "tooltip": True}
+    if point_mark.opacity is not None:
+        mark_dict["opacity"] = point_mark.opacity
+    spec = new_chart_spec(data, mark=mark_dict)
+    spec["projection"] = projection
+    spec["encoding"].update(_build_point_position_encoding(lat_field, lng_field))
+    set_chart_dimensions(spec, width, height)
+
+    # Size encoding for bubble maps
+    if size_field:
+        spec["encoding"]["size"] = {
+            "field": size_field,
+            "type": "quantitative",
+            "title": format_display_text(
+                size_field, from_slug=True, font=chart.resolved_style.legend.title.font
+            ),
+            "scale": {"range": [50, 1000]},
+        }
+    else:
+        spec["mark"]["size"] = point_mark.size
+
+    # Color encoding
+    if color_field:
+        # Infer type from data
+        color_type = infer_vega_type_from_data(data, color_field)
+        spec["encoding"]["color"] = {
+            "field": color_field,
+            "type": color_type,
+            "title": format_display_text(
+                color_field, from_slug=True, font=chart.resolved_style.legend.title.font
+            ),
+        }
+
+    tooltip_fields = _build_point_tooltip_fields(
+        data,
+        lat_field=lat_field,
+        lng_field=lng_field,
+        size_field=size_field,
+        color_field=color_field,
+        tooltip_format=resolve_format(
+            chart.resolved_style.tooltip.format, chart.resolved_style.formats
+        ),
+    )
+    if tooltip_fields:
+        spec["encoding"]["tooltip"] = tooltip_fields
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+
+    return spec
+
+
+def _generate_layered_point_map_spec(
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    lat_field: str | None,
+    lng_field: str | None,
+    size_field: str | None,
+    color_field: str | None,
+    projection: dict[str, Any],
+    background_config: dict[str, Any] | None,
+    geo_source: str | None,
+    width: float | None = None,
+    height: float | None = None,
+    *,
+    board_style: MergedStyle,
+) -> dict[str, Any]:
+    """Generate layered point map with background geoshape.
+
+    Creates a Vega-Lite layered spec with:
+    - Layer 1: Background geoshape (state/country outlines)
+    - Layer 2: Point/circle markers at lat/lng coordinates
+
+    Args:
+        chart: Chart definition
+        data: Point data with lat/lng
+        lat_field: Latitude field name
+        lng_field: Longitude field name
+        size_field: Optional size encoding field
+        color_field: Optional color encoding field
+        projection: Projection configuration
+        background_config: Background layer configuration
+        geo_source: Built-in geo source name
+        width: Optional width
+        height: Optional height
+
+    Returns:
+        Layered Vega-Lite specification
+
+    """
+    _ms = board_style
+    _scatter = chart.resolved_style.scatter
+    resolved_point = resolve_mark(
+        chart.resolved_style.marks.point,
+        _scatter.marks.point,
+    )
+
+    # Determine background geo source. For the fill, fall back to the theme
+    # background when the theme doesn't define a header fill (universal
+    # default is "header rule only").
+    _bg_fill_default = _ms.charts.table.header.background or _ms.background
+    if isinstance(background_config, dict):
+        bg_source = background_config.get("source", geo_source)
+        bg_fill = background_config.get("fill", _bg_fill_default)
+        bg_stroke = background_config.get("stroke", _ms.border.color)
+    else:
+        bg_source = geo_source
+        bg_fill = _bg_fill_default
+        bg_stroke = _ms.border.color
+
+    geo_url, geo_format, _ = _resolve_geo_source(bg_source)
+    spec = new_chart_spec(data, layer=True)
+    spec["projection"] = projection
+    set_chart_dimensions(spec, width, height)
+
+    # Layer 1: Background geoshape
+    background_layer: dict[str, Any] = {
+        "data": {
+            "url": geo_url,
+            "format": geo_format,
+        },
+        "mark": {
+            "type": "geoshape",
+            "fill": bg_fill,
+            "stroke": bg_stroke,
+            "strokeWidth": 0.5,
+        },
+    }
+    spec["layer"].append(background_layer)
+
+    # Layer 2: Points
+    mark_type = "circle"
+    point_mark: dict[str, Any] = {"type": mark_type, "tooltip": True}
+    if resolved_point.opacity is not None:
+        point_mark["opacity"] = resolved_point.opacity
+    point_layer: dict[str, Any] = {
+        "data": {"values": data},
+        "mark": point_mark,
+        "encoding": _build_point_position_encoding(lat_field, lng_field),
+    }
+
+    # Size encoding
+    point_size = resolved_point.size
+    if size_field:
+        point_layer["encoding"]["size"] = {
+            "field": size_field,
+            "type": "quantitative",
+            "title": format_display_text(
+                size_field, from_slug=True, font=chart.resolved_style.legend.title.font
+            ),
+            "scale": {"range": [50, 1000]},
+        }
+    else:
+        # Use point size from config (slightly larger for map overlays)
+        point_layer["mark"]["size"] = int(point_size * 1.33)
+
+    # Color encoding
+    if color_field:
+        color_type = infer_vega_type_from_data(data, color_field)
+        point_layer["encoding"]["color"] = {
+            "field": color_field,
+            "type": color_type,
+            "title": format_display_text(
+                color_field, from_slug=True, font=chart.resolved_style.legend.title.font
+            ),
+        }
+    else:
+        point_layer["mark"]["color"] = chart.resolved_style.palette[0]
+
+    tooltip_fields = _build_point_tooltip_fields(
+        data,
+        max_fields=6,
+        tooltip_format=resolve_format(
+            chart.resolved_style.tooltip.format, chart.resolved_style.formats
+        ),
+    )
+    if tooltip_fields:
+        point_layer["encoding"]["tooltip"] = tooltip_fields
+
+    spec["layer"].append(point_layer)
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+
+    return spec