Give maps a legend and a dark basemap

Both map cards colored their routes by elapsed time with nothing to say so
— a reader could see two marks differ but not by how much or which way,
which makes the gradient decoration rather than encoding. The source
notebooks had this (branca's colormap.caption); the port had dropped it.

Adds GeoLegend to the contract and a `legend=` param to geo(): an ordered
low→high color ramp with min/max labels, plus free-form swatch items for
things a ramp can't express. schedule-adherence-map uses those items for
its dashed "Planned (GTFS)" vs solid "Measured (GPS average)" distinction,
which previously only existed in prose under the chart.

Also swaps the basemap to CARTO's dark tiles when the page is in dark
mode, tracked via a MutationObserver on the theme attribute plus the
prefers-color-scheme media query. A blinding white map inside a dark card
was the one part of the dashboard that ignored the theme. CSS-inverting
the tiles was the alternative and is worse — it makes the map's own
labels unreadable.

Verified in a real browser, light and dark: legend text correct on both
map cards, and the tile host actually switches
(tile.openstreetmap.org → basemaps.cartocdn.com).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: NoamGaash

analyses/gps_trace_map.py

@@ -9,18 +9,17 @@
 rather than raw HTTP calls.
 
 The companion notebooks that overlay a *planned* route on the same map
-("load gtfs timetable...ipynb", "compare gtfs planned vs siri actual.ipynb") need
-per-stop GTFS shape coordinates, which openbus_hack.stride doesn't wrap yet (only
-noamf2001's bus_times package fetches that, via /route_timetable/list) — left as
-a follow-up rather than rushed.
+("load gtfs timetable...ipynb", "compare gtfs planned vs siri actual.ipynb") are
+covered by ``analyses/schedule_adherence_average.py``'s map card, which draws the
+GTFS plan dashed against a GPS-derived measured route.
 """
 
 from __future__ import annotations
 
 import datetime
 from zoneinfo import ZoneInfo
 
-from openbus_hack import AnalysisRequest, analysis, geo, metrics, stride
+from openbus_hack import AnalysisRequest, GeoLegend, analysis, geo, metrics, stride
 
 ISRAEL_TZ = ZoneInfo("Asia/Jerusalem")
 _CREDIT = "Analysis by yuvalko1 (github.com/yuvalko1/talpiot-hackathon-public-transportation)."
@@ -114,6 +113,12 @@ def run(req: AnalysisRequest):
     return geo(
         features,
         title="One bus, actual GPS trace",
+        legend=GeoLegend(
+            label="minutes into the ride",
+            colors=_GRADIENT,
+            min_label=t_start.tz_convert(ISRAEL_TZ).strftime("%H:%M"),
+            max_label=t_end.tz_convert(ISRAEL_TZ).strftime("%H:%M"),
+        ),
         subtitle=(f"Line {line} ({operator}) · ride {int(ride_id)} · "
                   f"{t_start.tz_convert(ISRAEL_TZ).strftime('%Y-%m-%d %H:%M')} "
                   f"Israel time · {len(trace)} pings"),

analyses/schedule_adherence_average.py

@@ -46,6 +46,7 @@
     OptionSpec,
     Point,
     Series,
+    GeoLegend,
     analysis,
     bar_chart,
     geo,
@@ -385,6 +386,16 @@ def wmean(vals, w):
     return geo(
         features,
         title="Planned route vs. where buses actually were",
+        legend=GeoLegend(
+            label="minutes since departure",
+            colors=_GRADIENT,
+            min_label="0",
+            max_label=f"{vmax:.0f}",
+            items=[
+                {"label": "Planned (GTFS)", "color": "#666", "dashed": True},
+                {"label": "Measured (GPS average)", "color": "#666", "dashed": False},
+            ],
+        ),
         subtitle=(f"{data['label']} · {data['time_of_day']} departure · "
                   f"{len(per_day)} days · {int(n_pings.sum())} matched pings"),
         notes=[

frontend/src/GeoMap.tsx

@@ -7,14 +7,14 @@
 // Leaflet's default marker image paths break under bundlers unless you copy
 // its asset files by hand, and a colored dot fits this data better anyway.
 
-import { useEffect } from 'react'
+import { useEffect, useState } from 'react'
 import { GeoJSON, MapContainer, TileLayer, useMap } from 'react-leaflet'
 import type { GeoJsonObject } from 'geojson'
 import type { LatLngBoundsExpression, PathOptions } from 'leaflet'
 import * as L from 'leaflet'
 import 'leaflet/dist/leaflet.css'
 
-import type { AnalysisResult } from './api'
+import type { AnalysisResult, GeoLegendData } from './api'
 
 const DEFAULT_COLOR = '#2a78d6'
 
@@ -48,20 +48,57 @@ function FitBounds({ data }: { data: GeoJsonObject }) {
   return null
 }
 
+/** Tracks the page's light/dark state so the basemap doesn't stay blinding
+    white inside a dark card. The toggle stamps data-theme on <html>. */
+function useIsDark(): boolean {
+  const read = () => {
+    const attr = document.documentElement.dataset.theme
+    if (attr === 'dark') return true
+    if (attr === 'light') return false
+    return window.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false
+  }
+  const [dark, setDark] = useState(read)
+  useEffect(() => {
+    const obs = new MutationObserver(() => setDark(read()))
+    obs.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] })
+    const mq = window.matchMedia?.('(prefers-color-scheme: dark)')
+    const onMq = () => setDark(read())
+    mq?.addEventListener('change', onMq)
+    return () => {
+      obs.disconnect()
+      mq?.removeEventListener('change', onMq)
+    }
+  }, [])
+  return dark
+}
+
 export function GeoMap({ result }: { result: AnalysisResult }) {
   const data = result.geojson as GeoJsonObject | null
+  const isDark = useIsDark()
   if (!data) return <p className="muted">No map data.</p>
 
   return (
+    <div style={{ minWidth: 0 }}>
     <MapContainer
       center={[32.08, 34.78]}
       zoom={13}
       style={{ height: 420, width: '100%', borderRadius: 8, minWidth: 0 }}
       scrollWheelZoom={false}
     >
+      {/* CARTO's basemaps ship a matching dark variant; plain OSM has none, and
+          CSS-inverting tiles turns the map's own labels unreadable. */}
       <TileLayer
-        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
-        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+        key={isDark ? 'dark' : 'light'}
+        attribution={
+          isDark
+            ? '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors &copy; <a href="https://carto.com/attributions">CARTO</a>'
+            : '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
+        }
+        url={
+          isDark
+            ? 'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png'
+            : 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
+        }
       />
       <GeoJSON
         data={data}
@@ -84,5 +121,53 @@ export function GeoMap({ result }: { result: AnalysisResult }) {
       />
       <FitBounds data={data} />
     </MapContainer>
+    {result.geo_legend && <GeoLegend legend={result.geo_legend} />}
+    </div>
+  )
+}
+
+function GeoLegend({ legend }: { legend: GeoLegendData }) {
+  return (
+    <div className="legend" style={{ marginTop: 10, alignItems: 'center' }}>
+      {legend.colors.length > 0 && (
+        <>
+          <span className="muted" style={{ fontSize: 11 }}>
+            {legend.min_label ?? ''}
+          </span>
+          <span
+            aria-label={legend.label}
+            style={{
+              width: 120,
+              height: 12,
+              borderRadius: 2,
+              background: `linear-gradient(to right, ${legend.colors.join(', ')})`,
+            }}
+          />
+          <span className="muted" style={{ fontSize: 11 }}>
+            {legend.max_label ?? ''}
+          </span>
+          <span className="muted" style={{ fontSize: 11 }}>
+            {legend.label}
+          </span>
+        </>
+      )}
+      {legend.items.map((it, i) => (
+        <span key={i} className="legend-item">
+          {/* Dashed entries get a line, not a block — the distinction the
+              swatch is there to make is the stroke style itself. */}
+          <i
+            className="swatch"
+            style={{
+              width: 18,
+              height: it.dashed ? 0 : 10,
+              borderRadius: 2,
+              background: it.dashed ? 'transparent' : (it.color ?? 'var(--ink-2)'),
+              borderTop: it.dashed ? `2px dashed ${it.color ?? 'var(--ink-2)'}` : undefined,
+            }}
+          />
+          {it.label}
+        </span>
+      ))}
+    </div>
   )
 }

frontend/src/api.ts

@@ -55,6 +55,16 @@ export interface Table {
   rows: unknown[][]
 }
 
+export interface GeoLegendData {
+  label: string
+  /** Ordered low→high; painted as a continuous ramp. */
+  colors: string[]
+  min_label: string | null
+  max_label: string | null
+  /** Extra swatches the ramp doesn't cover, e.g. dashed "planned" vs solid. */
+  items: { label?: string; color?: string; dashed?: boolean }[]
+}
+
 export interface HeatmapCell {
   row: number
   col: number
@@ -98,6 +108,7 @@ export interface AnalysisResult {
   image_alt: string | null
   heatmap: HeatmapData | null
   geojson: unknown | null
+  geo_legend: GeoLegendData | null
   notes: string[]
   error_message: string | null
   error_traceback: string | null

openbus_hack/__init__.py

@@ -11,6 +11,7 @@
 from .contract import (
     AnalysisRequest,
     AnalysisResult,
+    GeoLegend,
     Heatmap,
     HeatmapCell,
     Metric,
@@ -48,6 +49,7 @@
     "Series",
     "Point",
     "Table",
+    "GeoLegend",
     "Heatmap",
     "HeatmapCell",
     # data access

openbus_hack/contract.py

@@ -26,6 +26,7 @@ def run(req: AnalysisRequest) -> AnalysisResult:
 __all__ = [
     "AnalysisRequest",
     "AnalysisResult",
+    "GeoLegend",
     "Heatmap",
     "HeatmapCell",
     "Metric",
@@ -158,6 +159,20 @@ class HeatmapCell(BaseModel):
     weak: bool = False
 
 
+class GeoLegend(BaseModel):
+    """What a map's colors mean. Without this a gradient is decoration — the
+    reader can see two marks differ but not by how much, or in which direction."""
+
+    label: str
+    # Ordered low→high; the frontend paints them as a continuous ramp.
+    colors: list[str] = Field(default_factory=list)
+    min_label: str | None = None
+    max_label: str | None = None
+    # Extra swatches for things the ramp doesn't cover — e.g. a dashed
+    # "planned" line vs. a solid measured one.
+    items: list[dict[str, Any]] = Field(default_factory=list)
+
+
 class Heatmap(BaseModel):
     """A labelled grid of values — segment × hour, stop × day, and so on.
 
@@ -223,8 +238,9 @@ class AnalysisResult(BaseModel):
     # kind="heatmap" — raw grid, rendered client-side (interactive, small payload)
     heatmap: Heatmap | None = None
 
-    # kind="geo" — a GeoJSON FeatureCollection
+    # kind="geo" — a GeoJSON FeatureCollection, plus what its colors mean
     geojson: dict[str, Any] | None = None
+    geo_legend: GeoLegend | None = None
 
     # Free-text caveats shown under the chart. Use these! "only 3 days of SIRI
     # data available" belongs here, not in a print().
@@ -460,14 +476,18 @@ def image(fig: Any = None, *, title: str | None = None, subtitle: str | None = N
 
 
 def geo(features: list[dict[str, Any]], *, title: str | None = None,
-        subtitle: str | None = None, notes: list[str] | None = None) -> AnalysisResult:
+        subtitle: str | None = None, legend: GeoLegend | None = None,
+        notes: list[str] | None = None) -> AnalysisResult:
     """A map, from a list of GeoJSON Feature dicts (LineString/Point geometries).
 
     Per-feature styling is read from ``properties``: ``color`` (any CSS color),
     ``weight`` (line width / marker radius), ``dashed`` (bool), and ``popup``
     (text shown on click). The frontend auto-fits the map to the data — no
     center/zoom to pass in.
 
+    Pass ``legend`` whenever color carries meaning: a gradient nobody can read
+    is decoration, not encoding.
+
     >>> geo([
     ...     {"type": "Feature", "geometry": {"type": "LineString", "coordinates": [[lon1, lat1], [lon2, lat2]]},
     ...      "properties": {"color": "#31688e", "weight": 4}},
@@ -476,6 +496,7 @@ def geo(features: list[dict[str, Any]], *, title: str | None = None,
     return AnalysisResult(
         kind="geo", title=title, subtitle=subtitle, notes=notes or [],
         geojson={"type": "FeatureCollection", "features": features},
+        geo_legend=legend,
     )