microsegments 0.2.0__tar.gz → 0.2.1__tar.gz

{microsegments-0.2.0 → microsegments-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: microsegments
-Version: 0.2.0
+Version: 0.2.1
 Summary: Where do transit vehicles linger? Count vehicle position observations per micro-segment of a line, from GTFS + AVL / GTFS-RT positions.
 Project-URL: Homepage, https://github.com/GaspardMerten/microsegments
 Project-URL: Repository, https://github.com/GaspardMerten/microsegments

{microsegments-0.2.0 → microsegments-0.2.1}/src/microsegments/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.2.1'
+__version_tuple__ = version_tuple = (0, 2, 1)
 
 __commit_id__ = commit_id = None

{microsegments-0.2.0 → microsegments-0.2.1}/src/microsegments/io/coverage.py

@@ -5,6 +5,12 @@ non-frozen poll (the last poll covers min(tick_s, gap_cap_s)). Each frozen snaps
 [t_i, t_i + min(t_next_any - t_i, gap_cap_s)) of ``frozen_s`` (t_next_any: next snapshot of any kind).
 Intervals are split exactly at local hour boundaries and credited to the hour they fall in.
 ``coverage = covered_s / 3600`` clipped to 1. Frozen snapshots never count as polls.
+
+FROZEN flag: an hour is flagged when it overlaps a *stall*, a run of consecutive frozen snapshots
+lasting more than ``max_frozen_s`` (each covering min(next snapshot - t, gap_cap_s)). Isolated
+repeats are normal for feeds that refresh more slowly than they are polled (STIB since 2026: about
+one poll in five repeats the previous one, 300-700 s per hour in total) and do not flag the hour;
+``frozen_s`` still reports their total.
 """
 from __future__ import annotations
 
@@ -79,9 +85,22 @@ def coverage(snapshots: pl.DataFrame | pl.LazyFrame, tz: str = "Europe/Brussels"
     tf, gf = t[fr], (nxt_any - t)[fr]
     fs, fl = _split_by_hour(tf, tf + np.minimum(gf, cap), tz)
 
+    # stalls: runs of consecutive frozen snapshots longer than max_frozen_s
+    ss, sl = np.zeros(0), np.zeros(0)
+    if fr.any():
+        span = np.minimum(nxt_any - t, cap)
+        edge = np.diff(np.concatenate([[0], fr.astype(np.int8), [0]]))
+        r0, r1 = np.flatnonzero(edge == 1), np.flatnonzero(edge == -1)     # [r0, r1) frozen runs
+        csum = np.concatenate([[0.0], np.cumsum(np.where(fr, span, 0.0))])
+        dur = csum[r1] - csum[r0]
+        long = dur > max_frozen_s
+        if long.any():
+            ss, sl = _split_by_hour(t[r0[long]], t[r0[long]] + dur[long], tz)
+
     sds = service_day_start
     cov = _hour_table(ps, pl_, "covered_s", tz, sds)
     frz = _hour_table(fs, fl, "frozen_s", tz, sds)
+    stall = _hour_table(ss, sl, "stall_s", tz, sds) if ss.size else None
     nsn = _hour_table(tp, np.ones_like(tp), "n_snapshots", tz, sds)
 
     if dates is None:
@@ -96,9 +115,13 @@ def coverage(snapshots: pl.DataFrame | pl.LazyFrame, tz: str = "Europe/Brussels"
            .join(frz, on=["service_date", "hour"], how="left")
            .join(nsn, on=["service_date", "hour"], how="left")
            .with_columns(pl.col("covered_s", "frozen_s", "n_snapshots").fill_null(0.0)))
+    if stall is not None:
+        out = out.join(stall, on=["service_date", "hour"], how="left").with_columns(pl.col("stall_s").fill_null(0.0))
+    else:
+        out = out.with_columns(pl.lit(0.0).alias("stall_s"))
     c = (pl.col("covered_s") / 3600.0).clip(0.0, 1.0)
     flags = (pl.when(c < min_coverage).then(Flag.LOW_COVERAGE).otherwise(0)
-             + pl.when(pl.col("frozen_s") > max_frozen_s).then(Flag.FROZEN).otherwise(0))
+             + pl.when(pl.col("stall_s") > 0).then(Flag.FROZEN).otherwise(0))
     out = out.with_columns(c.alias("coverage"), flags.alias("flags"))
     return out.select([pl.col(k).cast(v) for k, v in COVERAGE.items()]).sort("service_date", "hour")
 

{microsegments-0.2.0 → microsegments-0.2.1}/tests/test_coverage.py

@@ -101,6 +101,27 @@ def test_frozen_not_counted():
     assert c2.filter(pl.col("hour") == 10)["covered_s"][0] == row["covered_s"]
 
 
+def test_scattered_repeats_do_not_flag_frozen():
+    """One poll in four repeating the previous one (a feed refreshed more slowly than polled) is not a
+    stall: ~900 s of frozen snapshots in the hour, no run longer than 20 s."""
+    t = _day_polls()
+    frozen = (np.arange(t.size) % 4) == 3
+    c = coverage(_snaps(t, frozen), TZ, gap_cap_s=40, max_frozen_s=300)
+    row = c.filter(pl.col("hour") == 10).row(0, named=True)
+    assert row["frozen_s"] > 300
+    assert not row["flags"] & Flag.FROZEN and not row["flags"] & Flag.LOW_COVERAGE
+
+
+def test_stall_across_hours_flags_both():
+    t = _day_polls()
+    f1, f2 = local_epoch(DAY, 10 * 3600 + 3400, TZ), local_epoch(DAY, 11 * 3600 + 200, TZ)   # 400 s stall
+    c = coverage(_snaps(t, (t >= f1) & (t < f2)), TZ, gap_cap_s=40, max_frozen_s=300)
+    fl = dict(zip(c["hour"].to_list(), c["flags"].to_list()))
+    assert fl[10] & Flag.FROZEN and fl[11] & Flag.FROZEN and not fl[12] & Flag.FROZEN
+    c = coverage(_snaps(t, (t >= f1) & (t < f1 + 200)), TZ, gap_cap_s=40, max_frozen_s=300)   # 200 s: fine
+    assert not any(f & Flag.FROZEN for f in c["flags"].to_list())
+
+
 def test_silent_hours_are_zero_rows():
     t = _day_polls()
     t = t[(t < local_epoch(DAY, 12 * 3600, TZ)) | (t >= local_epoch(DAY, 14 * 3600, TZ))]