Add place_boundary(), layered close_map(), and full-attribute hover (1.4.0).

Author: Nathaniel Henry

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.4.0
+
+- `Client.place_boundary(geoid)` — the boundary polygon of a census place, as a
+  one-row GeoDataFrame. Free (no API key); handy as a `boundary` layer for
+  `close_map`.
+- `close_map` gains layered context and smarter defaults: it auto-zooms to the
+  data, shows every attribute on hover, defaults to the ColorBrewer `YlGnBu`
+  scale (blue = most accessible), and takes a `boundary` outline and
+  semi-transparent `background` layers (e.g. a city boundary, commute isochrones,
+  or a walkshed under its POIs).
+
 ## 1.3.0
 
 - `Client.place_pois(geoid, ...)` — every point of interest within a census

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "closecity"
-version = "1.3.0"
+version = "1.4.0"
 description = "Python client for the Close API (api.close.city). Travel times to points of interest for every US census block."
 readme = "README.md"
 requires-python = ">=3.9"

src/closecity/__init__.py

@@ -23,7 +23,7 @@
 from .spatial import to_geopandas
 from .tabular import to_pandas
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 
 __all__ = [
     "Client",

src/closecity/client.py

@@ -471,6 +471,17 @@ def place_pois(
             _clean({"type": type, "q": q, "limit": limit}),
         ), geometry = True, output = output)
 
+    def place_boundary(self, geoid: str, *, output: str | None = None):
+        """The boundary polygon of a census place (city or town), by place GEOID.
+        Handy as a `boundary` layer for `close_map` when mapping a city's blocks
+        or POIs. Free (no API key). A one-row polygon GeoDataFrame (a `Reply`
+        under `output="raw"`)."""
+        reply = self._get(f"/v1/places/{geoid}/boundary")
+        if self._resolve_output(output) == "raw":
+            return reply
+        from . import spatial
+        return spatial.to_geopandas(reply)
+
     # -- isochrone ----------------------------------------------------------
 
     def isochrone(

src/closecity/map.py

@@ -2,40 +2,130 @@
 
 Built on plotly over a CARTO Positron basemap: points become bright hoverable
 markers, block polygons are filled and can highlight the features meeting a
-criterion. plotly is GDAL-free (unlike leaflet/mapgl in R), and geopandas emits
+criterion. The view auto-zooms to the data, hover shows every attribute, and a
+city ``boundary`` outline or semi-transparent ``background`` layers can sit
+underneath. plotly is GDAL-free (unlike leaflet/mapgl in R), and geopandas emits
 the GeoJSON directly, so no extra system dependency.
 """
 
 from __future__ import annotations
 
+import math
 from typing import Any
 
 
+def _rgba(hexcolor: str, alpha: float) -> str:
+    h = hexcolor.lstrip("#")
+    r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+    return f"rgba({r}, {g}, {b}, {alpha})"
+
+
+def _as_layer(obj):
+    """Normalise a boundary/background argument to a GeoDataFrame, accepting a
+    GeoDataFrame, a GeoSeries, or a bare shapely geometry (assumed WGS84)."""
+    import geopandas as gpd
+
+    if isinstance(obj, gpd.GeoDataFrame):
+        return obj
+    if isinstance(obj, gpd.GeoSeries):
+        return gpd.GeoDataFrame(geometry = obj)
+    return gpd.GeoDataFrame(geometry = [obj], crs = "EPSG:4326")
+
+
+def _bounds(g):
+    minx, miny, maxx, maxy = g.total_bounds
+    return [minx, miny, maxx, maxy]
+
+
+def _center_zoom(bounds_list, buffer):
+    """A CARTO-Positron centre and zoom that frame every layer, plus a margin."""
+    minx = min(b[0] for b in bounds_list)
+    miny = min(b[1] for b in bounds_list)
+    maxx = max(b[2] for b in bounds_list)
+    maxy = max(b[3] for b in bounds_list)
+    center = {"lon": (minx + maxx) / 2, "lat": (miny + maxy) / 2}
+    span = max(maxx - minx, maxy - miny, 0.005) * (1 + 2 * buffer)
+    zoom = max(1.0, min(16.0, math.log2(360 / span) - 0.5))
+    return center, zoom
+
+
+def _polygon_lines(g):
+    """Exterior rings of every (multi)polygon as one lon/lat path, ``None``-split."""
+    lons: list = []
+    lats: list = []
+    for geom in g.geometry:
+        if geom is None or geom.is_empty:
+            continue
+        polys = list(geom.geoms) if geom.geom_type.startswith("Multi") else [geom]
+        for poly in polys:
+            x, y = poly.exterior.xy
+            lons += list(x) + [None]
+            lats += list(y) + [None]
+    return lons, lats
+
+
+def _fmt(v):
+    if isinstance(v, float):
+        return f"{v:.5f}".rstrip("0").rstrip(".")
+    if isinstance(v, dict):
+        return ", ".join(str(x) for x in v.values() if x is not None)
+    if isinstance(v, (list, tuple)):
+        return ", ".join(str(x) for x in v)
+    return str(v)
+
+
+def _hover(g, label):
+    """One hover string per row: every non-geometry attribute, ``label`` first."""
+    cols = [c for c in g.columns if c != g.geometry.name]
+    lead = [label] if label and label in cols else []
+    ordered = lead + [c for c in cols if c not in lead]
+    out = []
+    for _, row in g.iterrows():
+        parts = [
+            (f"<b>{_fmt(row[c])}</b>" if c == label else f"{c}: {_fmt(row[c])}")
+            for c in ordered
+        ]
+        out.append("<br>".join(parts))
+    return out
+
+
 def close_map(
     gdf,
     *,
     color: str = "#e8590c",
     highlight: Any = None,
     fill: Any = None,
-    palette: str = "Viridis",
-    reverse: bool = True,
-    label: str = "name",
+    palette: str = "YlGnBu",
+    reverse: bool = False,
+    label: str | None = None,
     size: int = 9,
-    zoom: float = 10,
     opacity: float = 0.65,
+    boundary=None,
+    background=None,
+    background_color: Any = "#3b6fb0",
+    background_opacity: float = 0.3,
+    buffer: float = 0.15,
 ):
     """Draw a :class:`geopandas.GeoDataFrame` from a client method as an
     interactive map on a CARTO Positron basemap.
 
     Points (POIs, places) render as bright hoverable markers; polygons (census
     blocks) are filled, optionally greying the features that do not meet
-    ``highlight`` so the ones that matter stand out.
+    ``highlight`` so the ones that matter stand out. The view auto-zooms to fit
+    every layer with a ``buffer`` margin, and hover shows all attributes.
+
+    ``highlight`` is a boolean sequence or the name of a boolean/0-1 column.
+    ``fill`` is the name of a numeric column to shade features by, on a
+    continuous ColorBrewer scale with a legend (use it OR ``highlight``);
+    ``palette`` (default ``"YlGnBu"``) and ``reverse`` control that scale.
+    ``reverse=False`` puts the blue end at the high values; pass ``reverse=True``
+    when high values mean *less* access, e.g. travel time.
 
-    ``highlight`` is either a boolean sequence (length ``len(gdf)``) or the name
-    of a boolean/0-1 column. ``fill`` is the name of a numeric column to shade
-    features by, on a continuous scale with a legend (use it OR ``highlight``);
-    ``palette`` and ``reverse`` control that scale. ``label`` names the hover
-    column. Returns a plotly ``Figure``.
+    ``boundary`` is a polygon GeoDataFrame drawn as a grey outline underneath
+    (e.g. a city boundary from ``place_boundary``). ``background`` is one polygon
+    GeoDataFrame, or a list of them, drawn as semi-transparent fills underneath
+    (e.g. commute isochrones or a walkshed); ``background_color`` recycles across
+    them. Returns a plotly ``Figure``.
     """
     try:
         import plotly.graph_objects as go
@@ -45,6 +135,39 @@ def close_map(
         ) from exc
 
     g = gdf.to_crs(4326)
+    traces = []
+    bounds = [_bounds(g)]
+
+    # Semi-transparent background fills, drawn first (underneath everything).
+    if background is not None:
+        layers = background if isinstance(background, (list, tuple)) else [background]
+        colors = (background_color if isinstance(background_color, (list, tuple))
+                  else [background_color])
+        for i, layer in enumerate(layers):
+            lg = _as_layer(layer).to_crs(4326)
+            bounds.append(_bounds(lg))
+            lons, lats = _polygon_lines(lg)
+            col = colors[i % len(colors)]
+            traces.append(go.Scattermapbox(
+                lon=lons, lat=lats, mode="lines", fill="toself",
+                fillcolor=_rgba(col, background_opacity),
+                line={"color": _rgba(col, min(1.0, background_opacity + 0.3)),
+                      "width": 1},
+                hoverinfo="skip", showlegend=False,
+            ))
+
+    # City-boundary outline (no fill), above the background fills.
+    if boundary is not None:
+        bg = _as_layer(boundary).to_crs(4326)
+        bounds.append(_bounds(bg))
+        lons, lats = _polygon_lines(bg)
+        traces.append(go.Scattermapbox(
+            lon=lons, lat=lats, mode="lines",
+            line={"color": "#666666", "width": 1.5},
+            hoverinfo="skip", showlegend=False,
+        ))
+
+    hover = _hover(g, label)
     hl = None
     if highlight is not None:
         col = g[highlight] if isinstance(highlight, str) else highlight
@@ -53,11 +176,7 @@ def close_map(
     if fill is not None and isinstance(fill, str) and fill in g.columns:
         fv = g[fill].astype(float).tolist()
 
-    minx, miny, maxx, maxy = g.total_bounds
-    center = {"lon": (minx + maxx) / 2, "lat": (miny + maxy) / 2}
-    hover = g[label].astype(str).tolist() if label in g.columns else None
     geom_type = g.geom_type.iloc[0] if len(g) else "Point"
-
     if "Point" in geom_type:
         if fv is not None:
             marker = {"size": size, "color": fv, "colorscale": palette,
@@ -68,37 +187,39 @@ def close_map(
                 color if h else "#888888" for h in hl
             ]
             marker = {"size": size, "color": marker_color}
-        fig = go.Figure(go.Scattermapbox(
-            lat = g.geometry.y.tolist(), lon = g.geometry.x.tolist(),
-            mode = "markers", marker = marker,
-            text = hover, hoverinfo = "text" if hover else "none",
+        traces.append(go.Scattermapbox(
+            lat=g.geometry.y.tolist(), lon=g.geometry.x.tolist(),
+            mode="markers", marker=marker,
+            text=hover, hoverinfo="text", showlegend=False,
         ))
     else:
         import json
 
-        g = g.reset_index(drop = True)
+        g = g.reset_index(drop=True)
         g["_id"] = [str(i) for i in range(len(g))]
         geojson = json.loads(g[["_id", "geometry"]].to_json())
         common = {
             "geojson": geojson, "locations": g["_id"].tolist(),
             "featureidkey": "properties._id",
             "marker": {"opacity": opacity, "line": {"width": 0}},
-            "text": hover, "hoverinfo": "text" if hover else "none",
+            "text": hover, "hoverinfo": "text", "showlegend": False,
         }
         if fv is not None:
             trace = go.Choroplethmapbox(
-                z = fv, colorscale = palette, reversescale = reverse,
-                showscale = True, colorbar = {"title": fill}, **common)
+                z=fv, colorscale=palette, reversescale=reverse,
+                showscale=True, colorbar={"title": fill}, **common)
         else:
             z = [1] * len(g) if hl is None else [int(h) for h in hl]
             colorscale = ([[0, color], [1, color]] if hl is None
                           else [[0, "#888888"], [1, color]])
             trace = go.Choroplethmapbox(
-                z = z, colorscale = colorscale, showscale = False, **common)
-        fig = go.Figure(trace)
+                z=z, colorscale=colorscale, showscale=False, **common)
+        traces.append(trace)
 
+    center, zoom = _center_zoom(bounds, buffer)
+    fig = go.Figure(traces)
     fig.update_layout(
-        mapbox = {"style": "carto-positron", "zoom": zoom, "center": center},
-        margin = {"l": 0, "r": 0, "t": 0, "b": 0},
+        mapbox={"style": "carto-positron", "zoom": zoom, "center": center},
+        margin={"l": 0, "r": 0, "t": 0, "b": 0},
     )
     return fig

src/closecity/spatial.py

@@ -41,6 +41,13 @@ def _isochrone_gdf(data: dict, gpd, shape, crs):
     return gpd.GeoDataFrame(records, geometry = geoms, crs = crs)
 
 
+def _feature_gdf(data: dict, gpd, shape, crs):
+    """A single GeoJSON Feature (e.g. a place boundary) as a one-row GeoDataFrame,
+    its ``properties`` folded into columns."""
+    props = dict(data.get("properties") or {})
+    return gpd.GeoDataFrame([props], geometry = [shape(data["geometry"])], crs = crs)
+
+
 def _points_gdf(rows: list[dict], gpd, Point, crs):
     geoms = [
         Point(r["lon"], r["lat"])
@@ -120,6 +127,11 @@ def to_geopandas(
         tabular._stamp_attrs(gdf, data, meta)
         return gdf
 
+    if isinstance(data, dict) and data.get("type") == "Feature" and data.get("geometry"):
+        gdf = _feature_gdf(data, gpd, shape, crs)
+        tabular._stamp_attrs(gdf, data, meta)
+        return gdf
+
     rows, envelope = tabular._rows_and_envelope(data)
     first = rows[0] if rows else None
     if first is not None and "lat" in first and "lon" in first:

tests/test_map.py

@@ -37,3 +37,22 @@ def test_close_map_polygons_with_highlight():
     import plotly.graph_objects as go
     fig = close_map(_polys(), color = "#2f9e44", highlight = "near")
     assert isinstance(fig, go.Figure)
+
+
+def test_close_map_shades_by_fill():
+    import plotly.graph_objects as go
+    polys = _polys()
+    polys["score"] = [2, 5]
+    fig = close_map(polys, fill = "score", palette = "YlGnBu")
+    assert isinstance(fig, go.Figure)
+
+
+def test_close_map_boundary_and_background_layers():
+    import plotly.graph_objects as go
+    polys = _polys()
+    boundary = polys.geometry.union_all()   # a bare shapely geometry
+    fig = close_map(_points(), boundary = boundary,
+                    background = [polys], background_color = "#3b6fb0")
+    # one background fill + one boundary outline + the point layer
+    assert isinstance(fig, go.Figure)
+    assert len(fig.data) == 3