feat: add gps coverage chart (#1678)

Author: arielvino

src/locale/en.json

@@ -31,6 +31,16 @@
   "singleline_map_page_description": "Display of bus route on map by user-given bus operator, vehicle number, route number, route, date & time",
   "singleline_map_page_route": "By Route",
   "singleline_map_page_vehicle_id": "By Vehicle ID",
+  "gps_coverage_title": "GPS coverage over time",
+  "gps_coverage_description": "Density of GPS reports over time. Each column is the gap between two consecutive reports.",
+  "gps_coverage_tooltip_duration": "{{duration}}",
+  "gps_coverage_tooltip_distance": "{{distance}} apart",
+  "gps_coverage_unit_meter": "m",
+  "gps_coverage_unit_km": "km",
+  "gps_coverage_tooltip_focus_start": "Last reported position",
+  "gps_coverage_vehicle_label": "Vehicle:",
+  "gps_coverage_no_pings": "No GPS reports received for this vehicle",
+  "gps_coverage_one_ping": "Only one GPS report received for this vehicle",
   "bus_tooltip_footer_previous_location": "Previous location",
   "bus_tooltip_footer_next_location": "Next location",
   "bus_icon_alt": "Bus icon",

src/locale/he.json

@@ -31,6 +31,16 @@
   "singleline_map_page_description": "תצוגה של מסלול קו על מפה ע\"פ נתוני חברת אוטובוסים, מספר רכב, קו, מסלול, תאריך ושעה",
   "singleline_map_page_route": "לפי מסלול",
   "singleline_map_page_vehicle_id": "לפי מספר רכב",
+  "gps_coverage_title": "כיסוי GPS לאורך זמן",
+  "gps_coverage_description": "צפיפות דיווחי GPS לאורך זמן. כל עמודה מייצגת מרווח בין 2 דיווחים עוקבים.",
+  "gps_coverage_tooltip_duration": "{{duration}}",
+  "gps_coverage_tooltip_distance": "{{distance}} הפרש",
+  "gps_coverage_unit_meter": "מטר",
+  "gps_coverage_unit_km": "קילומטר",
+  "gps_coverage_tooltip_focus_start": "המיקום האחרון שדווח",
+  "gps_coverage_vehicle_label": "רכב:",
+  "gps_coverage_no_pings": "לא התקבלו דיווחי GPS עבור רכב זה",
+  "gps_coverage_one_ping": "התקבל דיווח GPS אחד בלבד עבור רכב זה",
   "bus_tooltip_footer_previous_location": "המיקום הקודם",
   "bus_tooltip_footer_next_location": "המיקום הבא",
   "bus_icon_alt": "סמל אוטובוס",

src/pages/components/map-related/MapContent.tsx

@@ -22,13 +22,26 @@ export const plannedRouteLineColor = 'black'
 export const plannedRouteStopMarkerPath = `${import.meta.env.BASE_URL}marker-bus-stop.png`
 export const plannedRouteStopMarker = getIcon(plannedRouteStopMarkerPath, 20, 25)
 
-export function MapContent({ positionGroups, plannedRouteStops, showNavigationButtons }: MapProps) {
+export function MapContent({
+  positionGroups,
+  plannedRouteStops,
+  showNavigationButtons,
+  focusTarget,
+}: MapProps) {
   const [tileUrl, setTileUrl] = useState('https://tile-a.openstreetmap.fr/hot/{z}/{x}/{y}.png')
   const map = useMap()
   const { i18n } = useTranslation()
 
   useRecenterOnDataChange({ positionGroups, plannedRouteStops })
 
+  // Fly to (and scroll into view) an externally requested location — e.g. clicking a
+  // coverage-gap's geomarker focuses the last-seen ping before the bus went dark.
+  useEffect(() => {
+    if (!map || !focusTarget) return
+    map.flyTo(focusTarget.loc, Math.max(map.getZoom(), 16))
+    map.getContainer().scrollIntoView({ behavior: 'smooth', block: 'center' })
+  }, [map, focusTarget])
+
   useEffect(() => {
     const handleLanguageChange = (lng: string) => {
       const newUrl =

src/pages/components/map-related/MapWithLocationsAndPath.tsx

@@ -13,6 +13,7 @@ export function MapWithLocationsAndPath({
   positionGroups,
   plannedRouteStops,
   showNavigationButtons,
+  focusTarget,
 }: MapProps) {
   return (
     <MapShell
@@ -26,6 +27,7 @@ export function MapWithLocationsAndPath({
         positionGroups={positionGroups}
         plannedRouteStops={plannedRouteStops}
         showNavigationButtons={showNavigationButtons}
+        focusTarget={focusTarget}
       />
     </MapShell>
   )

src/pages/components/map-related/map-types.ts

@@ -27,10 +27,19 @@ export interface Path {
   vehicleRef: string
 }
 
+/** A request to fly the map to a location; `seq` bumps so repeated requests for the same
+ * location still re-trigger the fly-to (clicking the same ping twice). */
+export interface FocusTarget {
+  loc: [number, number]
+  seq: number
+}
+
 export interface MapProps {
   positionGroups: PositionGroup[]
   plannedRouteStops?: BusStop[]
   showNavigationButtons?: boolean
+  /** When set/changed, the map flies to this location (e.g. a coverage-gap ping). */
+  focusTarget?: FocusTarget | null
 }
 
 export function toPoint(location: SiriVehicleLocationWithRelatedPydanticModel): Point {

src/pages/components/utils/gpsCoverage.test.ts

@@ -0,0 +1,179 @@
+import { Point } from 'src/pages/components/map-related/map-types'
+import {
+  classifyGap,
+  distanceMeters,
+  gapSeverity,
+  medianPingInterval,
+  pingGaps,
+} from './gpsCoverage'
+
+/**
+ * Unit tests for the per-ride GPS coverage measure used by the SingleLineMap strip.
+ * The strip is built from the elapsed time *between consecutive pings* (not fixed
+ * clock buckets), so a bus that stops reporting surfaces as one long gap. The gap
+ * extraction and the median-relative classification are locked here.
+ */
+
+// Minimal Point factory — only recordedAtTime matters for coverage.
+const ping = (recordedAtTime: number): Point => ({
+  loc: [0, 0],
+  color: 0,
+  recordedAtTime,
+})
+
+const MIN = 60_000
+const base = 1_000_000
+
+describe('pingGaps', () => {
+  it('returns no gaps for fewer than two pings', () => {
+    expect(pingGaps([])).toEqual([])
+    expect(pingGaps([ping(base)])).toEqual([])
+  })
+
+  it('ignores pings without a valid timestamp', () => {
+    expect(pingGaps([ping(base), { loc: [0, 0], color: 0 }])).toEqual([])
+  })
+
+  it('produces one gap per consecutive pair, spanning the whole ride contiguously', () => {
+    const gaps = pingGaps([ping(base), ping(base + 10_000), ping(base + 30_000)])
+    expect(gaps).toEqual([
+      { startMs: base, endMs: base + 10_000, gapMs: 10_000, startLoc: [0, 0], endLoc: [0, 0] },
+      {
+        startMs: base + 10_000,
+        endMs: base + 30_000,
+        gapMs: 20_000,
+        startLoc: [0, 0],
+        endLoc: [0, 0],
+      },
+    ])
+    // contiguous: each gap starts where the previous ended
+    for (let i = 1; i < gaps.length; i++) {
+      expect(gaps[i].startMs).toBe(gaps[i - 1].endMs)
+    }
+  })
+
+  it('sorts out-of-order pings before computing gaps', () => {
+    const gaps = pingGaps([ping(base + 30_000), ping(base), ping(base + 10_000)])
+    expect(gaps.map((g) => g.gapMs)).toEqual([10_000, 20_000])
+  })
+
+  it('surfaces a long dropout as a single wide gap', () => {
+    const gaps = pingGaps([ping(base), ping(base + 15_000), ping(base + 15_000 + 5 * MIN)])
+    expect(gaps.map((g) => g.gapMs)).toEqual([15_000, 5 * MIN])
+  })
+
+  it('collapses pings that share a recordedAtTime (SIRI re-ingestion duplicates)', () => {
+    // base appears twice (same instant, same place) — the duplicate must not create a
+    // zero-length gap or a second gap starting at the same startMs.
+    const gaps = pingGaps([ping(base), ping(base), ping(base + 10_000)])
+    expect(gaps).toEqual([
+      { startMs: base, endMs: base + 10_000, gapMs: 10_000, startLoc: [0, 0], endLoc: [0, 0] },
+    ])
+  })
+
+  it('keeps every gap startMs unique even with duplicate timestamps', () => {
+    const gaps = pingGaps([ping(base), ping(base), ping(base + 10_000), ping(base + 10_000)])
+    const starts = gaps.map((g) => g.startMs)
+    expect(new Set(starts).size).toBe(starts.length)
+  })
+
+  it('carries each bounding ping location onto the gap', () => {
+    const a: Point = { loc: [32.1, 34.8], color: 0, recordedAtTime: base }
+    const b: Point = { loc: [32.2, 34.9], color: 0, recordedAtTime: base + 10_000 }
+    const [gap] = pingGaps([a, b])
+    expect(gap.startLoc).toEqual([32.1, 34.8])
+    expect(gap.endLoc).toEqual([32.2, 34.9])
+  })
+})
+
+describe('distanceMeters', () => {
+  // Thin [lat, lon]-tuple adapter over geolib.getDistance; these pin the tuple order, not geolib.
+  it('is 0 for identical points', () => {
+    expect(distanceMeters([32, 34], [32, 34])).toBe(0)
+  })
+
+  it('measures ~111 km per degree of latitude', () => {
+    const d = distanceMeters([0, 0], [1, 0])
+    expect(d).toBeGreaterThan(111_000)
+    expect(d).toBeLessThan(111_400)
+  })
+
+  it('reads the tuple as [lat, lon] (not [lon, lat])', () => {
+    // At latitude 32°, a degree of longitude is much shorter than a degree of latitude;
+    // a swapped adapter would make these equal.
+    const oneLat = distanceMeters([32, 34], [33, 34])
+    const oneLon = distanceMeters([32, 34], [32, 35])
+    expect(oneLon).toBeLessThan(oneLat)
+  })
+})
+
+describe('medianPingInterval', () => {
+  it('is 0 with fewer than two pings', () => {
+    expect(medianPingInterval([])).toBe(0)
+    expect(medianPingInterval([ping(base)])).toBe(0)
+  })
+
+  it('computes the median gap between consecutive pings', () => {
+    // gaps: 10s, 10s, 30s -> median 10s
+    expect(
+      medianPingInterval([
+        ping(base),
+        ping(base + 10_000),
+        ping(base + 20_000),
+        ping(base + 50_000),
+      ]),
+    ).toBe(10_000)
+  })
+
+  it('averages the two middle gaps for an even count', () => {
+    // gaps: 10s, 20s -> median (10+20)/2 = 15s
+    expect(medianPingInterval([ping(base), ping(base + 10_000), ping(base + 30_000)])).toBe(15_000)
+  })
+})
+
+describe('classifyGap', () => {
+  // 15s cadence; bands break at the sparse threshold (2× = 30s) and dropout (4× = 60s).
+  const median = 15_000
+
+  it('treats everything as ok when there is no baseline', () => {
+    expect(classifyGap(10 * MIN, 0)).toBe('ok')
+  })
+
+  it('flags a near-cadence gap as ok up to the sparse threshold', () => {
+    expect(classifyGap(median, median)).toBe('ok')
+    expect(classifyGap(30_000, median)).toBe('ok') // exactly 2×
+  })
+
+  it('flags a moderately stretched gap as sparse', () => {
+    expect(classifyGap(30_001, median)).toBe('sparse') // just past 2×
+    expect(classifyGap(60_000, median)).toBe('sparse') // exactly 4×
+  })
+
+  it('flags a long gap as a dropout', () => {
+    expect(classifyGap(60_001, median)).toBe('gap') // just past 4×
+    expect(classifyGap(5 * MIN, median)).toBe('gap')
+  })
+})
+
+describe('gapSeverity', () => {
+  // 15s cadence; severity ramps 0 at 1× to 1 at the 4× dropout threshold (60s).
+  const median = 15_000
+
+  it('is 0 when there is no baseline', () => {
+    expect(gapSeverity(10 * MIN, 0)).toBe(0)
+  })
+
+  it('is 0 at or below the median cadence', () => {
+    expect(gapSeverity(median, median)).toBe(0)
+    expect(gapSeverity(median / 2, median)).toBe(0)
+  })
+
+  it('reaches 1 at (and clamps above) the dropout threshold', () => {
+    expect(gapSeverity(60_000, median)).toBe(1) // exactly 4×
+    expect(gapSeverity(10 * MIN, median)).toBe(1) // far beyond
+  })
+
+  it('ramps linearly between the median and the dropout threshold', () => {
+    expect(gapSeverity(37_500, median)).toBeCloseTo(0.5) // ratio 2.5, halfway from 1× to 4×
+  })
+})

src/pages/components/utils/gpsCoverage.ts

@@ -0,0 +1,114 @@
+import { getDistance } from 'geolib'
+import { Point } from 'src/pages/components/map-related/map-types'
+
+/**
+ * A gap up to this multiple of the ride's median interval is normal jitter (`ok`).
+ * Between this and {@link GAP_FACTOR} the coverage is `sparse`; above it, a `gap`.
+ */
+export const SPARSE_FACTOR = 2
+export const GAP_FACTOR = 4
+
+export interface PingGap {
+  /** recordedAtTime of the earlier ping, epoch ms. */
+  startMs: number
+  /** recordedAtTime of the later ping, epoch ms. */
+  endMs: number
+  /** Elapsed time between the two consecutive pings (endMs - startMs). */
+  gapMs: number
+  /** [lat, lon] of the earlier ping — the last known position before the gap. */
+  startLoc: [number, number]
+  /** [lat, lon] of the later ping — the first position after the gap. */
+  endLoc: [number, number]
+}
+
+export type Density = 'gap' | 'sparse' | 'ok'
+
+/**
+ * Sorted, valid (positive-timestamp) pings for a ride, collapsing pings that share a
+ * `recordedAtTime`. The SIRI pipeline re-ingests the same observation across snapshots, so a
+ * ride routinely carries rows with identical `recordedAtTime` (and lat/lon) but distinct ids
+ * that survive the upstream `uniqBy(id)`. Same time means same position, so keeping the first
+ * row per timestamp is lossless and avoids meaningless zero-length gaps.
+ */
+function sortedTimedPings(positions: Point[]): { t: number; loc: [number, number] }[] {
+  const sorted = positions
+    .filter((p) => (p.recordedAtTime ?? 0) > 0)
+    .map((p) => ({ t: p.recordedAtTime as number, loc: p.loc }))
+    .sort((a, b) => a.t - b.t)
+  // Equal timestamps are now adjacent — drop every ping whose time matches its predecessor.
+  return sorted.filter((p, i) => i === 0 || p.t !== sorted[i - 1].t)
+}
+
+/**
+ * The elapsed time between each pair of consecutive pings across the ride. Each gap also
+ * carries its two bounding ping locations (for the strip's distance readout and map focus).
+ * Returns [] for fewer than two valid pings.
+ */
+export function pingGaps(positions: Point[]): PingGap[] {
+  const pings = sortedTimedPings(positions)
+  const gaps: PingGap[] = []
+  for (let i = 1; i < pings.length; i++) {
+    gaps.push({
+      startMs: pings[i - 1].t,
+      endMs: pings[i].t,
+      gapMs: pings[i].t - pings[i - 1].t,
+      startLoc: pings[i - 1].loc,
+      endLoc: pings[i].loc,
+    })
+  }
+  return gaps
+}
+
+/**
+ * Number of valid, distinct-time pings for a ride — i.e. how many points remain after
+ * dropping zero-timestamp rows and collapsing duplicate `recorded_at_time`s. A strip needs
+ * at least two (one gap); below that the caller can tell "reported nothing" (0) from
+ * "reported once" (1) to show a specific notice instead of a blank strip.
+ */
+export function distinctPingCount(positions: Point[]): number {
+  return sortedTimedPings(positions).length
+}
+
+/**
+ * Median gap (ms) between consecutive pings — the ride's natural reporting cadence,
+ * used as the baseline every gap is judged against. Returns 0 with fewer than two pings.
+ */
+export function medianPingInterval(positions: Point[]): number {
+  const gaps = pingGaps(positions).map((g) => g.gapMs)
+  if (gaps.length === 0) return 0
+  gaps.sort((a, b) => a - b)
+  const mid = Math.floor(gaps.length / 2)
+  return gaps.length % 2 === 0 ? (gaps[mid - 1] + gaps[mid]) / 2 : gaps[mid]
+}
+
+/** Great-circle distance between two [lat, lon] points, in meters (via geolib). */
+export function distanceMeters(a: [number, number], b: [number, number]): number {
+  return getDistance({ latitude: a[0], longitude: a[1] }, { latitude: b[0], longitude: b[1] })
+}
+
+/**
+ * Classify a single inter-ping gap relative to the ride's median cadence:
+ *  - `ok`     — within {@link SPARSE_FACTOR}× the median (normal jitter)
+ *  - `sparse` — between {@link SPARSE_FACTOR}× and {@link GAP_FACTOR}× (degraded)
+ *  - `gap`    — beyond {@link GAP_FACTOR}× (the bus effectively stopped reporting)
+ *
+ * With no usable baseline (median <= 0, e.g. a single ping) everything is `ok`.
+ */
+export function classifyGap(gapMs: number, medianMs: number): Density {
+  if (medianMs <= 0) return 'ok'
+  if (gapMs > medianMs * GAP_FACTOR) return 'gap'
+  if (gapMs > medianMs * SPARSE_FACTOR) return 'sparse'
+  return 'ok'
+}
+
+/**
+ * Continuous severity of a gap on a 0–1 scale, for coloring the strip with a smooth
+ * gradient instead of the three discrete {@link classifyGap} bands: 0 when the gap is at
+ * (or below) the median cadence, ramping linearly to 1 once it reaches the
+ * {@link GAP_FACTOR}× dropout threshold. With no usable baseline (median <= 0) it is 0.
+ */
+export function gapSeverity(gapMs: number, medianMs: number): number {
+  if (medianMs <= 0) return 0
+  const ratio = gapMs / medianMs
+  return Math.min(1, Math.max(0, (ratio - 1) / (GAP_FACTOR - 1)))
+}