microsegments 0.1.0__py3-none-any.whl

microsegments/__init__.py

@@ -0,0 +1,42 @@
+"""microsegments: count where transit vehicles are observed along a line, per micro-segment.
+
+Quick start::
+
+    import microsegments as ms
+    res = ms.run(ms.Config.from_toml("ms.toml"))
+    ms.export(res, "report.html")
+    ms.plot.matrix(res, direction_id=0)
+"""
+from __future__ import annotations
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+from .aggregate import count
+from .config import Config
+from .hotspots import hotspots
+from .html import export
+from .io import read_observations
+from .metrics import Analysis, analyse
+from .network import build_network
+from .pipeline import RunResult, prepare, run
+from .report import to_contract
+from .schema import Flag
+from .segments import segment
+from .simulate import simulate
+from . import tune
+
+__all__ = ["Analysis", "Config", "Flag", "RunResult", "__version__", "analyse", "build_network", "count", "export",
+           "hotspots", "plot", "prepare", "read_observations", "run", "segment", "simulate", "to_contract", "tune"]
+
+
+def __getattr__(name: str):
+    # matplotlib is optional: import the plot module on first use
+    if name == "plot":
+        import importlib
+        mod = importlib.import_module(".plot", __name__)
+        globals()["plot"] = mod
+        return mod
+    raise AttributeError(f"module 'microsegments' has no attribute {name!r}")

microsegments/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

microsegments/aggregate.py

@@ -0,0 +1,101 @@
+"""Placed observations -> Cube: how many times a vehicle was observed in each micro-segment.
+
+Only rows with ``count`` True (or null) are counted. A row is assigned to the segment whose
+link-relative interval ``(offset_m, offset_m + len_m]`` contains its ``pos_m`` (lower bound open,
+upper bound closed, as in the prototype: a vehicle standing at stop B is at the end of link A->B).
+A row at ``pos_m <= 0`` of link i > 0 goes to the last segment of link i - 1, i.e. the end of the
+link arriving at that stop. Positions beyond the link end are clipped to its last segment.
+
+Per-vehicle feeds (GTFS-RT with irregular / dense fixes) are thinned to at most one observation
+per ``(track_id, floor(ts / tick_s))`` (the last fix of each tick), so counts stay comparable with
+a snapshot feed polled every ``tick_s``.
+"""
+from __future__ import annotations
+
+import numpy as np
+import polars as pl
+
+from .schema import CUBE, conform
+
+_SCALE = 1e7  # metres; composite sort key = group * _SCALE + position (links are far shorter)
+
+
+def thin(placed: pl.DataFrame, tick_s: float = 20.0) -> pl.DataFrame:
+    """Keep the last fix per (track_id, tick bucket). Rows without track_id are kept as they are."""
+    tick_ms = max(int(round(tick_s * 1000)), 1)
+    df = placed.with_columns((pl.col("ts").dt.epoch("ms") // tick_ms).alias("_tick"))
+    has = df.filter(pl.col("track_id").is_not_null())
+    none = df.filter(pl.col("track_id").is_null())
+    has = has.sort("ts", maintain_order=True).unique(subset=["track_id", "_tick"], keep="last", maintain_order=True)
+    return pl.concat([has, none], how="vertical").drop("_tick")
+
+
+def assign(placed: pl.DataFrame, segments: pl.DataFrame) -> pl.DataFrame:
+    """Add ``seg_idx`` and ``seg_key`` to placed rows (null when the row's link has no segment).
+
+    Vectorised: one searchsorted over all (pattern, link) groups at once."""
+    seg = (segments.select("pattern_uid", "link_idx", "seg_idx", "seg_key", "offset_m", "len_m")
+           .with_columns(pl.col("link_idx").cast(pl.Int16))
+           .sort("pattern_uid", "link_idx", "offset_m"))
+    groups = (seg.group_by("pattern_uid", "link_idx", maintain_order=True)
+              .agg(pl.len().alias("_n"))
+              .with_row_index("_gid"))
+    gn = groups["_n"].to_numpy().astype(np.int64)
+    g_last = np.cumsum(gn) - 1
+    g_first = g_last - gn + 1
+    seg = seg.join(groups.select("pattern_uid", "link_idx", "_gid"), on=["pattern_uid", "link_idx"], how="left")
+    seg_comp = seg["_gid"].to_numpy().astype(np.float64) * _SCALE + (seg["offset_m"] + seg["len_m"]).to_numpy()
+
+    # pos <= 0 on link i > 0 belongs to the end of link i - 1.
+    back = (pl.col("pos_m") <= 0) & (pl.col("link_idx") > 0)
+    df = placed.with_columns(
+        pl.when(back).then(pl.col("link_idx") - 1).otherwise(pl.col("link_idx")).cast(pl.Int16).alias("_li"),
+        pl.when(back).then(pl.lit(np.inf)).otherwise(pl.col("pos_m").cast(pl.Float64)).alias("_pos"),
+    )
+    df = df.join(groups.select(pl.col("pattern_uid"), pl.col("link_idx").alias("_li"), "_gid"),
+                 on=["pattern_uid", "_li"], how="left", maintain_order="left")
+    ok = df["_gid"].is_not_null().to_numpy()
+    gid = df["_gid"].fill_null(0).to_numpy().astype(np.int64)
+    pos = df["_pos"].fill_null(0.0).to_numpy().astype(np.float64)
+    pos = np.clip(np.nan_to_num(pos, nan=0.0, posinf=_SCALE / 2), -1.0, _SCALE / 2)
+    n = len(df)
+    if len(seg_comp) == 0:
+        ok = np.zeros(n, bool)
+        idx = np.zeros(n, np.int64)
+    else:
+        idx = np.searchsorted(seg_comp, gid * _SCALE + pos, side="left")
+        idx = np.clip(idx, g_first[gid], g_last[gid])
+    seg_idx = seg["seg_idx"].to_numpy()[idx] if len(seg_comp) else np.zeros(n, np.int32)
+    seg_key = seg["seg_key"].gather(idx) if len(seg_comp) else pl.Series([None] * n, dtype=pl.Utf8)
+    ok_s = pl.Series(ok)
+    return df.drop("_li", "_pos", "_gid").with_columns(
+        pl.when(ok_s).then(pl.Series(seg_idx, dtype=pl.Int32)).otherwise(None).alias("seg_idx"),
+        pl.when(ok_s).then(seg_key).otherwise(None).alias("seg_key"),
+    )
+
+
+def count(placed: pl.DataFrame, segments: pl.DataFrame, tick_s: float = 20.0,
+          per_vehicle: bool = False) -> pl.DataFrame:
+    """Placed -> Cube (service_date, hour, pattern_uid, seg_key, obs).
+
+    Σ obs equals the number of counted (and, for per-vehicle feeds, thinned) rows whose link has
+    segments."""
+    df = placed.filter(pl.col("count").fill_null(True))
+    if per_vehicle:
+        df = thin(df, tick_s)
+    df = assign(df.select("ts", "service_date", "hour", "pattern_uid", "link_idx", "pos_m", "track_id"), segments)
+    cube = (df.filter(pl.col("seg_key").is_not_null())
+            .group_by("service_date", "hour", "pattern_uid", "seg_key")
+            .agg(pl.len().alias("obs"))
+            .sort("service_date", "hour", "pattern_uid", "seg_key"))
+    return conform(cube, CUBE)
+
+
+def link_totals(cube: pl.DataFrame, segments: pl.DataFrame,
+                by: tuple[str, ...] = ("service_date", "hour")) -> pl.DataFrame:
+    """Sum the cube per link: (pattern_uid, link_key, *by, obs). Invariant to segment length and phase."""
+    keys = segments.select("pattern_uid", "seg_key", "link_key").unique(["pattern_uid", "seg_key"])
+    return (cube.join(keys, on=["pattern_uid", "seg_key"], how="left")
+            .group_by("pattern_uid", "link_key", *by)
+            .agg(pl.col("obs").sum().cast(pl.UInt64))
+            .sort("pattern_uid", "link_key", *by))

microsegments/cli.py

@@ -0,0 +1,201 @@
+"""Command line: ``microsegments run | tune | hotspots | inspect CONFIG``."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+import polars as pl
+
+from .config import Config
+
+
+def _cfg(args) -> Config:
+    cfg = Config.from_toml(args.config)
+    if getattr(args, "segment_m", None):
+        cfg.params = replace(cfg.params, segment_m=float(args.segment_m))
+    if getattr(args, "dates", None):
+        cfg.select = replace(cfg.select, dates=args.dates)
+    return cfg
+
+
+def _log(args):
+    return (lambda s: print(s, file=sys.stderr)) if not getattr(args, "quiet", False) else None
+
+
+def _hotspot_table(hs: pl.DataFrame, tick_s: float) -> pl.DataFrame:
+    if hs is None or hs.height == 0:
+        return pl.DataFrame()
+    return hs.select(
+        "direction_id", "rank",
+        pl.concat_str([pl.col("from_stop_name"), pl.lit(" -> "), pl.col("to_stop_name")]).alias("stretch"),
+        pl.col("x0_m").round(0), pl.col("x1_m").round(0), "zone", "kind",
+        pl.col("hours").cast(pl.List(pl.Utf8)).list.join(",").alias("hours"),
+        pl.col("excess_per_passage").round(2).alias("excess_obs_per_veh"),
+        (pl.col("excess_per_passage") * tick_s).round(0).alias("approx_s_per_veh"),
+        pl.col("persistence").round(2))
+
+
+def cmd_run(args) -> int:
+    from .pipeline import run
+    cfg = _cfg(args)
+    res = run(cfg, log=_log(args), hotspots=not args.no_hotspots)
+    paths = res.save(args.out, html=not args.no_html, png=not args.no_png, lang=args.lang, title=args.title,
+                     source=args.source)
+    for name, p in paths.items():
+        print(p)
+    if not args.quiet:
+        t = " ".join(f"{k} {v:.1f}s" for k, v in res.timings.items())
+        print(f"done: {len(res.analysis.days)} days, {res.segments.height} segments, "
+              f"{0 if res.hotspots is None else res.hotspots.height} hotspots ({t})", file=sys.stderr)
+    return 0
+
+
+def cmd_hotspots(args) -> int:
+    from .pipeline import run
+    cfg = _cfg(args)
+    res = run(cfg, log=_log(args))
+    t = _hotspot_table(res.hotspots, cfg.params.tick_s)
+    if t.height == 0:
+        print("no hotspot")
+        return 0
+    with pl.Config(tbl_rows=200, tbl_cols=20, fmt_str_lengths=60, tbl_width_chars=200):
+        print(t)
+    if args.out:
+        out = Path(args.out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if out.suffix == ".geojson":
+            from .hotspots import to_geojson
+            out.write_text(json.dumps(to_geojson(res.hotspots, res.segments), default=str))
+        elif out.suffix == ".csv":
+            t.write_csv(out)
+        else:
+            res.hotspots.write_parquet(out)
+        print(out)
+    return 0
+
+
+def cmd_tune(args) -> int:
+    from . import tune
+    from .pipeline import prepare
+    cfg = _cfg(args)
+    pre = prepare(cfg, log=_log(args))
+    lengths = [float(x) for x in args.lengths.split(",")]
+    kw = dict(coverage=pre.coverage, passages=pre.passages, pattern_days=pre.network.pattern_days,
+              select=cfg.select, params=cfg.params, quality=cfg.quality, per_vehicle=pre.per_vehicle)
+    tr = tune.segment_length(pre.placed, pre.segment_fn(), lengths, B=args.bootstrap, **kw)
+    with pl.Config(tbl_rows=50, tbl_cols=20, tbl_width_chars=200, float_precision=3):
+        print(tr.table)
+    print(f"recommended L = {tr.recommended:g} m ({tr.rule})")
+    out = Path(args.out) if args.out else None
+    if out:
+        out.mkdir(parents=True, exist_ok=True)
+        tr.table.write_parquet(out / "tune.parquet")
+    sr = None
+    if args.sensitivity:
+        sr = tune.sensitivity(pre.placed, pre.segment_fn(), tr.recommended, B=args.bootstrap, **kw)
+        with pl.Config(tbl_rows=50, tbl_cols=20, tbl_width_chars=200, float_precision=3):
+            print(sr.summary)
+            print(sr.hotspots)
+        print("stable" if sr.stable else "NOT stable")
+        if out:
+            sr.table.write_parquet(out / "sensitivity_profiles.parquet")
+            sr.summary.write_parquet(out / "sensitivity.parquet")
+    if out:
+        try:
+            import matplotlib
+            matplotlib.use("Agg")
+            from . import plot
+            plot.save(plot.tune_curves(tr), out / "tune.png")
+            if sr is not None:
+                plot.save(plot.sensitivity(sr), out / "sensitivity.png")
+        except ImportError:
+            pass
+        print(out)
+    return 0
+
+
+def cmd_inspect(args) -> int:
+    from .pipeline import prepare
+    cfg = _cfg(args)
+    pre = prepare(cfg, log=_log(args))
+    cov = pre.coverage
+    q = cfg.quality
+    print(f"route {cfg.select.route}: {pre.observations.height:,} observations, {pre.snapshots.height:,} polls")
+    day = (cov.filter(pl.col("hour").is_between(6, 20))
+           .group_by("service_date").agg(pl.col("coverage").mean().alias("mean_cov"),
+                                         (pl.col("coverage") < q.min_hour_coverage).sum().alias("low_hours"),
+                                         (pl.col("frozen_s") > 0).sum().alias("frozen_hours"))
+           .sort("service_date"))
+    print("\ncoverage per service date (hours 6-20):")
+    with pl.Config(tbl_rows=400, float_precision=2):
+        print(day)
+    print("\nGTFS versions (main pattern runs):")
+    with pl.Config(tbl_rows=50, tbl_cols=12, fmt_str_lengths=40, tbl_width_chars=200):
+        print(pre.network.versions().with_columns(pl.col("links_added").list.len(), pl.col("links_removed").list.len()))
+    if pre.network.missing_dates:
+        print("dates without GTFS service:", ", ".join(d.isoformat() for d in pre.network.missing_dates))
+    print("\nplacement:")
+    for k, v in (pre.place_report or {}).items():
+        print(f"  {k:<36} {v:>12,}" if isinstance(v, (int, float)) else f"  {k:<36} {v}")
+    from .schema import Flag
+    if "flags" in pre.placed.columns and pre.placed.height:
+        fl = pre.placed["flags"].fill_null(0).to_numpy()
+        for name in ("LAYOVER", "SHORT_WORKING", "OFF_PATTERN", "AMBIGUOUS", "AT_STOP"):
+            n = int(((fl & getattr(Flag, name)) != 0).sum())
+            if n:
+                print(f"  flag {name.lower():<31} {n:>12,}")
+        print(f"  counted rows                         {int(pre.placed['count'].fill_null(True).sum()):>12,}")
+    if pre.passages is not None and pre.passages.height:
+        p = pre.passages
+        print(f"\npassages: {p['n'].sum():,.0f} link passages"
+              + (f" (feed {p['n_feed'].sum():,.0f}, events {p['n_events'].sum():,.0f})" if p["n_events"].null_count() < p.height else ""))
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="microsegments", description="Vehicle observations per micro-segment of a transit line.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def common(p):
+        p.add_argument("config", help="TOML configuration")
+        p.add_argument("--segment-m", type=float, help="override params.segment_m")
+        p.add_argument("--dates", help="override select.dates (YYYY-MM-DD..YYYY-MM-DD)")
+        p.add_argument("-q", "--quiet", action="store_true")
+
+    p = sub.add_parser("run", help="full pipeline: parquet + JSON + HTML report + PNG matrices")
+    common(p)
+    p.add_argument("-o", "--out", default="out", help="output directory (default: out)")
+    p.add_argument("--lang", default="fr", choices=["fr", "en"])
+    p.add_argument("--title")
+    p.add_argument("--source", help="data credit shown in the page footer")
+    p.add_argument("--no-html", action="store_true")
+    p.add_argument("--no-png", action="store_true")
+    p.add_argument("--no-hotspots", action="store_true")
+    p.set_defaults(fn=cmd_run)
+
+    p = sub.add_parser("tune", help="choose the segment length (and optionally run the sensitivity suite)")
+    common(p)
+    p.add_argument("--lengths", default="10,15,20,30,40,50,75,100")
+    p.add_argument("--bootstrap", type=int, default=100)
+    p.add_argument("--sensitivity", action="store_true")
+    p.add_argument("-o", "--out", help="directory for tune.parquet / tune.png")
+    p.set_defaults(fn=cmd_tune)
+
+    p = sub.add_parser("hotspots", help="print the hotspot table")
+    common(p)
+    p.add_argument("-o", "--out", help="write .parquet, .csv or .geojson")
+    p.set_defaults(fn=cmd_hotspots)
+
+    p = sub.add_parser("inspect", help="coverage, GTFS versions, placement / drop counts")
+    common(p)
+    p.set_defaults(fn=cmd_inspect)
+
+    args = ap.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

microsegments/config.py

@@ -0,0 +1,142 @@
+"""Run configuration: where the data is, how its columns map to ``schema.OBSERVATION``, what to select
+and the method parameters. Load from TOML (``Config.from_toml``) or build in Python.
+
+Example (lat/lon GTFS-RT positions exported to CSV)::
+
+    [input]
+    paths = ["positions/*.csv"]
+    kind = "latlon"
+    [input.columns]
+    ts = "timestamp"
+    route_id = "route_id"
+    vehicle_id = "vehicle_id"
+    lat = "latitude"
+    lon = "longitude"
+    [gtfs]
+    path = "gtfs.zip"
+    [select]
+    route = "55"
+    dates = "2025-02-17..2025-05-16"
+    weekdays = [0, 1, 2, 3, 4]
+"""
+from __future__ import annotations
+
+import datetime as dt
+import tomllib
+from dataclasses import dataclass, field, fields, is_dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass
+class LinearInput:
+    """Linear-referenced feeds: 'last stop passed + metres since' (STIB vehicle-distance)."""
+    direction_kind: Literal["terminus_stop", "direction_id"] = "terminus_stop"
+    id_normaliser: str = "leading_digits"     # "none" | "leading_digits" | a regex with one group
+    feed_length: Literal["auto", "gtfs"] = "auto"   # auto: rescale feed metres to GTFS link length (p99.5)
+    terminus_aliases: dict[str, str] = field(default_factory=dict)   # code -> stop_id, else learned
+
+
+@dataclass
+class Input:
+    paths: list[str] = field(default_factory=list)   # csv / parquet / json globs
+    kind: Literal["latlon", "linear", "stib"] = "latlon"
+    format: Literal["auto", "csv", "parquet", "stib_json", "gtfsrt_pb"] = "auto"
+    timezone: str = "Europe/Brussels"
+    service_day_start: str = "04:00"
+    ts_unit: Literal["s", "ms", "us", "iso"] = "s"
+    # canonical name -> source column name (only the ones that differ / exist)
+    columns: dict[str, str] = field(default_factory=dict)
+    linear: LinearInput = field(default_factory=LinearInput)
+    snapshots: str | None = None              # optional path(s) to a Snapshot table
+    events: str | None = None                 # optional stop events (StopEvent schema or STIB punctuality)
+
+
+@dataclass
+class Gtfs:
+    path: str | None = None                   # zip / directory / gtfs-parquet directory
+    dated: str | None = None                  # template with {date} (YYYY-MM-DD) for one feed per day
+    route_key: Literal["route_short_name", "route_id"] = "route_short_name"
+
+
+@dataclass
+class Select:
+    route: str | None = None
+    dates: str | None = None                  # "YYYY-MM-DD..YYYY-MM-DD"
+    weekdays: list[int] = field(default_factory=lambda: [0, 1, 2, 3, 4])
+    exclude_dates: list[str] = field(default_factory=list)
+    hours: tuple[int, int] = (5, 24)          # [start, end)
+    directions: list[int] | None = None
+
+    def date_range(self) -> tuple[dt.date, dt.date] | None:
+        if not self.dates:
+            return None
+        a, b = self.dates.split("..")
+        return dt.date.fromisoformat(a), dt.date.fromisoformat(b)
+
+
+@dataclass
+class Params:
+    segment_m: float = 30.0
+    phase_m: float = 0.0
+    grid: Literal["equal", "fixed"] = "equal"  # equal: L' = len/round(len/L) per link; fixed: L with a short last bin
+    tick_s: float = 20.0                     # nominal poll interval; per-vehicle feeds are thinned to 1 obs / tick
+    gap_cap_s: float = 40.0                  # a poll covers at most this long
+    stop_zone: tuple[float, float] = (30.0, 60.0)   # metres before / after a stop masked as "stop" zone
+    reference_hours: tuple[int, int] = (20, 23)     # [start, end) "normal" evening reference
+    reference: Literal["evening", "freeflow"] = "evening"
+    layover_m: float = 10.0                  # at the first stop of a pattern closer than this = terminus layover
+    max_lateral_m: float = 40.0              # map matching: reject fixes farther from the shape
+    bootstrap: int = 200
+
+
+@dataclass
+class Quality:
+    min_hour_coverage: float = 0.8
+    min_day_coverage: float = 0.75           # share of 6-21 h day-hours that must pass
+    max_frozen_s: float = 300.0
+    vehicle_ratio: tuple[float, float] = (0.7, 1.3)
+    max_off_pattern: float = 0.2
+    min_days: int = 5
+    min_passages_per_day: float = 0.5
+
+
+@dataclass
+class Config:
+    input: Input = field(default_factory=Input)
+    gtfs: Gtfs = field(default_factory=Gtfs)
+    select: Select = field(default_factory=Select)
+    params: Params = field(default_factory=Params)
+    quality: Quality = field(default_factory=Quality)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Config":
+        return _build(cls, d)
+
+    @classmethod
+    def from_toml(cls, path: str | Path) -> "Config":
+        path = Path(path)
+        cfg = cls.from_dict(tomllib.loads(path.read_text()))
+        base = path.parent
+        cfg.input.paths = [p if Path(p).is_absolute() else str(base / p) for p in cfg.input.paths]
+        for obj, attr in ((cfg.gtfs, "path"), (cfg.gtfs, "dated"), (cfg.input, "snapshots"), (cfg.input, "events")):
+            v = getattr(obj, attr)
+            if v and not Path(v).is_absolute():
+                setattr(obj, attr, str(base / v))
+        return cfg
+
+
+def _build(cls, d: dict[str, Any]):
+    kw = {}
+    names = {f.name: f for f in fields(cls)}
+    for k, v in (d or {}).items():
+        if k not in names:
+            raise ValueError(f"unknown config key {cls.__name__}.{k}")
+        f = names[k]
+        default = f.default_factory() if callable(f.default_factory) else f.default  # type: ignore[misc]
+        if is_dataclass(default) and isinstance(v, dict):
+            v = _build(type(default), v)
+        elif isinstance(default, tuple) and isinstance(v, list):
+            v = tuple(v)
+        kw[k] = v
+    return cls(**kw)

microsegments/contract.py

@@ -0,0 +1,42 @@
+"""JSON exchanged with the HTML page (``html.export``) and the platform (``GET /api/analysis``).
+
+Totals are kept per weekday so the page can recombine any set of weekdays client-side
+(sum the selected rows, then divide). Nothing is pre-divided except geometry.
+
+    {
+      "v": 1,
+      "line": "55", "route_id": "...", "mode": "tram",
+      "params": {segment_m, phase_m, grid, tick_s, gap_cap_s, stop_zone: [up, down], reference_hours: [a, b]},
+      "period": {"first": "2025-02-17", "last": "2025-05-16",
+                 "days": 60,                      # included service days
+                 "per_dow": [11, 12, 13, 12, 12, 0, 0],
+                 "excluded": [{"date": "2025-03-04", "reason": "low_coverage"}]},
+      "hours": [5, ..., 23],                      # hour index h used below
+      "coverage": {"dates": ["2025-02-17", ...], "c": [[0.98, ...] per date][per hour]},
+      "versions": [{"dir": 0, "pattern_uid": "...", "first": "...", "last": "...", "n_days": 54,
+                    "links_added": [...], "links_removed": [...], "display": true}],
+      "dirs": [{
+        "dir": 0, "pattern_uid": "...", "from": "Da Vinci", "to": "Rogier",
+        "stops": [{"id": "...", "name": "...", "ll": [lon, lat], "x": 0.0}],
+        "links": [{"key": "...", "from": "...", "to": "...", "len": 252.7, "n_days": 60, "flags": 0}],
+        "seg": {"key": [...], "link": [...], "x0": [...], "len": [...], "zone": ["stop"|"running"],
+                "c": [[[lon, lat], ...] per segment], "flags": [...]},
+        "wk": {"obs":  [dow][h][seg]  int   observation counts,
+               "cov":  [dow][h][link] float covered hours (sum of coverage over included days where the link is valid),
+               "p":    [dow][h][link] float passages,
+               "days": [dow][link]    int   included days where the link is valid}
+      }],
+      "hotspots": [HOTSPOT rows as dicts],
+      "ctx": [[[lon, lat], ...]]                  # optional background polylines
+    }
+
+Client-side metrics for a weekday set W and hour h, segment s in link l:
+    obs_per_h       = sum_W obs / sum_W cov
+    obs_per_passage = sum_W obs / sum_W p
+    ref             = sum_{W, h in ref} obs / sum_{W, h in ref} p
+    excess          = obs_per_passage - ref
+"""
+from __future__ import annotations
+
+CONTRACT_VERSION = 1
+DOW_FR = ["Lu", "Ma", "Me", "Je", "Ve", "Sa", "Di"]