microsegments 0.1.0__tar.gz

microsegments-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,71 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/microsegments
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Sign and create GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Sign with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Upload to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: gh release upload '${{ github.ref_name }}' dist/** --repo '${{ github.repository }}' --clobber

microsegments-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest

microsegments-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+*.parquet
+!tests/fixtures/**/*.parquet
+.claude/
+src/microsegments/_version.py
+tests/regression/golden/
+examples/data/
+out/

microsegments-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaspard Merten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

microsegments-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: microsegments
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/GaspardMerten/microsegments/issues
+Author-email: Gaspard Merten <gaspard.mp.work@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: avl,bus,gtfs,gtfs-rt,hotspots,polars,tram,transit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: gtfs-parquet>=0.7
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.0
+Requires-Dist: shapely>=2.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: matplotlib>=3.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: gtfsrt
+Requires-Dist: gtfs-realtime-bindings>=1.0; extra == 'gtfsrt'
+Provides-Extra: mobilitytwin
+Requires-Dist: requests>=2.31; extra == 'mobilitytwin'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# microsegments
+
+Where do buses and trams linger? `microsegments` cuts each line into short stretches (30 m by default)
+and counts how many times a vehicle position is observed in each one, per hour and per day of the week.
+It works with GTFS plus any vehicle position feed: GTFS-RT VehiclePositions (lat/lon, as CSV, parquet or
+`.pb`) or linear-referenced AVL (last stop + distance, like STIB).
+
+![Report page: hour player, map coloured by micro-segment, hotspots, hour x micro-segment matrix](docs/report.jpg)
+
+## Install
+
+```bash
+pip install "microsegments[plot]"        # plot extra = matplotlib
+```
+
+Python ≥ 3.11. Core dependencies: polars, numpy, shapely, gtfs-parquet (no pandas).
+
+## Quick start (offline, synthetic data)
+
+```bash
+python examples/make_synth.py                     # simulated tram line S1 -> examples/data/
+microsegments run examples/synth.toml -o out/     # result.parquet, analysis.json, report.html, matrix_dir*.png
+```
+
+## Linear-referenced feeds (STIB vehicle-distance)
+
+```toml
+[input]
+paths = ["vd55/*.parquet"]           # <YYYYMMDD>.parquet (ts, dir, point, dist) + <YYYYMMDD>.snaps.parquet
+kind = "stib"                        # or "linear" for any "stop_id + dist_m" table (map columns below)
+events = "punctuality/*.parquet"     # optional stop events: passages from both sources, max taken
+
+[input.linear]
+id_normaliser = "leading_digits"     # "05766" -> "5766"
+feed_length = "auto"                 # rescale feed metres to GTFS link lengths
+
+[gtfs]
+path = "gtfs/"                       # zip, .txt directory or gtfs-parquet directory
+# dated = "gtfs/{date}"              # one feed per day instead
+
+[select]
+route = "55"
+dates = "2025-02-17..2025-05-16"
+weekdays = [0, 1, 2, 3, 4]
+```
+
+See `examples/stib55.toml` (runs on the two-day test fixture).
+
+## GTFS-RT positions as CSV (lat/lon)
+
+```toml
+[input]
+paths = ["positions/*.csv"]
+kind = "latlon"
+ts_unit = "s"                        # "s" | "ms" | "us" | "iso"
+[input.columns]                      # canonical name = your column
+ts = "timestamp"
+route_id = "route_id"
+vehicle_id = "vehicle_id"
+lat = "latitude"
+lon = "longitude"
+trip_id = "trip_id"                  # optional, helps map matching
+```
+
+Per-vehicle fixes are thinned to one per `tick_s` (20 s) so counts stay comparable with a snapshot feed.
+See `examples/gtfsrt_csv.toml` for every option.
+
+## Python
+
+```python
+import microsegments as ms
+
+res = ms.run(ms.Config.from_toml("ms.toml"))   # obs -> coverage -> network -> place -> passages
+                                                # -> segments -> count -> analyse -> hotspots
+res.result            # polars: one row per segment x hour (bands as hour -1 am, -2 pm, -3 day, -4 evening)
+res.hotspots          # ranked stretches
+ms.export(res, "report.html", lang="fr")       # standalone page (fr / en)
+ms.plot.matrix(res, direction_id=0, metric="obs_per_h", days=[0, 1, 2, 3, 4], stops=False)
+ms.plot.map(res, 0, "pm", metric="excess_per_passage")
+contract = res.contract()                      # the page JSON (also the platform's /api/analysis)
+
+pre = ms.prepare(cfg)                          # reuse placement to tune the segment length
+tr = ms.tune.segment_length(pre.placed, pre.segment_fn(), coverage=pre.coverage, passages=pre.passages,
+                            pattern_days=pre.network.pattern_days)
+ms.plot.tune_curves(tr)
+```
+
+Stages are usable on their own: `read_observations`, `build_network`, `segment`, `count`, `analyse`,
+`hotspots`, `simulate`.
+
+## CLI
+
+```bash
+microsegments run CONFIG -o OUT [--lang en] [--segment-m 20] [--dates A..B] [--source "credit"]
+microsegments tune CONFIG [--lengths 10,20,30,50] [--sensitivity] [-o OUT]
+microsegments hotspots CONFIG [-o hotspots.geojson|.csv|.parquet]
+microsegments inspect CONFIG        # coverage per day, GTFS versions, placement / drop counts
+```
+
+## What the numbers mean
+
+Every poll (about every 20 s) puts each vehicle in one micro-segment: one **observation**. One observation
+is therefore about 20 s of presence.
+
+| Metric | Definition | Read as |
+|---|---|---|
+| `obs_per_h` (default) | Σ observations / Σ covered hours | vehicles seen in the segment per hour of polling; `/len × 10` for per 10 m |
+| `obs_per_passage` | Σ observations / Σ passages | × 20 s ≈ time each vehicle spends there |
+| `excess_per_passage` | obs per passage − the same at 20–23 h, same days | extra observations (≈ seconds / 20) lost per vehicle vs free-flowing evening |
+| `excess_obs_per_h`, `log2_ratio` | see `metrics.py` | |
+
+All values are ratios of sums over the selected days (optionally post-stratified by weekday). Stop zones
+(30 m before to 60 m after each stop) can be masked to bring out signals and junctions. Colour scales are
+fixed per metric (p98 over 6–21 h), so hours and weekdays compare directly.
+
+## Missing data and GTFS versions
+
+- **Hours** with < 80 % of polls, a frozen feed (> 5 min), the line absent, or abnormal vehicle counts are
+  dropped from numerator and denominator. Polling gaps are handled by the exposure (covered hours); counts
+  are never imputed.
+- **Days** with more than 25 % of their 6–21 h dropped are excluded and listed with the reason
+  (`res.analysis.excluded_days`, coverage calendar in the page).
+- **GTFS changes**: patterns are rebuilt per service date; `link_key` / `seg_key` are stable across
+  versions. Each segment is aggregated only over the days it belongs to the day's main pattern (the
+  reference too). The page shows the most frequent version; others are selectable. A single feed whose
+  calendar does not cover some dates lends them the patterns of the same weekday.
+
+## Choosing the segment length
+
+`microsegments tune` scores L ∈ {10, 15, 20, 30, 40, 50, 75, 100} m (leave-one-day-out Poisson deviance,
+split-half reliability, hotspot localisation spread and Jaccard) and picks the smallest L with reliability
+≥ 0.8, spread ≤ 30 m and deviance within one standard error of the minimum. 30 m is a good default for
+20 s polling at urban speeds; go shorter only with dense GTFS-RT fixes and many days. `--sensitivity`
+re-runs phase offsets, gap caps, stop zones, references and passage sources.
+
+## Hotspots
+
+Stretches where the excess over the evening has a 95 % bootstrap lower bound above 2 s per vehicle, is
+positive on ≥ 60 % of days, survives Benjamini–Hochberg (q = 0.1) and lasts ≥ 2 hours or a peak band.
+Adjacent bins merge, never across a stop / running border. Classes: *infrastructure* (all day),
+*congestion* (peak only), *mixed*. Needs at least 5 included days. Export as GeoJSON with
+`microsegments hotspots CONFIG -o hotspots.geojson`.
+
+## License
+
+MIT. The bundled Leaflet CSS is BSD-2-Clause.

microsegments-0.1.0/README.md

@@ -0,0 +1,146 @@
+# microsegments
+
+Where do buses and trams linger? `microsegments` cuts each line into short stretches (30 m by default)
+and counts how many times a vehicle position is observed in each one, per hour and per day of the week.
+It works with GTFS plus any vehicle position feed: GTFS-RT VehiclePositions (lat/lon, as CSV, parquet or
+`.pb`) or linear-referenced AVL (last stop + distance, like STIB).
+
+![Report page: hour player, map coloured by micro-segment, hotspots, hour x micro-segment matrix](docs/report.jpg)
+
+## Install
+
+```bash
+pip install "microsegments[plot]"        # plot extra = matplotlib
+```
+
+Python ≥ 3.11. Core dependencies: polars, numpy, shapely, gtfs-parquet (no pandas).
+
+## Quick start (offline, synthetic data)
+
+```bash
+python examples/make_synth.py                     # simulated tram line S1 -> examples/data/
+microsegments run examples/synth.toml -o out/     # result.parquet, analysis.json, report.html, matrix_dir*.png
+```
+
+## Linear-referenced feeds (STIB vehicle-distance)
+
+```toml
+[input]
+paths = ["vd55/*.parquet"]           # <YYYYMMDD>.parquet (ts, dir, point, dist) + <YYYYMMDD>.snaps.parquet
+kind = "stib"                        # or "linear" for any "stop_id + dist_m" table (map columns below)
+events = "punctuality/*.parquet"     # optional stop events: passages from both sources, max taken
+
+[input.linear]
+id_normaliser = "leading_digits"     # "05766" -> "5766"
+feed_length = "auto"                 # rescale feed metres to GTFS link lengths
+
+[gtfs]
+path = "gtfs/"                       # zip, .txt directory or gtfs-parquet directory
+# dated = "gtfs/{date}"              # one feed per day instead
+
+[select]
+route = "55"
+dates = "2025-02-17..2025-05-16"
+weekdays = [0, 1, 2, 3, 4]
+```
+
+See `examples/stib55.toml` (runs on the two-day test fixture).
+
+## GTFS-RT positions as CSV (lat/lon)
+
+```toml
+[input]
+paths = ["positions/*.csv"]
+kind = "latlon"
+ts_unit = "s"                        # "s" | "ms" | "us" | "iso"
+[input.columns]                      # canonical name = your column
+ts = "timestamp"
+route_id = "route_id"
+vehicle_id = "vehicle_id"
+lat = "latitude"
+lon = "longitude"
+trip_id = "trip_id"                  # optional, helps map matching
+```
+
+Per-vehicle fixes are thinned to one per `tick_s` (20 s) so counts stay comparable with a snapshot feed.
+See `examples/gtfsrt_csv.toml` for every option.
+
+## Python
+
+```python
+import microsegments as ms
+
+res = ms.run(ms.Config.from_toml("ms.toml"))   # obs -> coverage -> network -> place -> passages
+                                                # -> segments -> count -> analyse -> hotspots
+res.result            # polars: one row per segment x hour (bands as hour -1 am, -2 pm, -3 day, -4 evening)
+res.hotspots          # ranked stretches
+ms.export(res, "report.html", lang="fr")       # standalone page (fr / en)
+ms.plot.matrix(res, direction_id=0, metric="obs_per_h", days=[0, 1, 2, 3, 4], stops=False)
+ms.plot.map(res, 0, "pm", metric="excess_per_passage")
+contract = res.contract()                      # the page JSON (also the platform's /api/analysis)
+
+pre = ms.prepare(cfg)                          # reuse placement to tune the segment length
+tr = ms.tune.segment_length(pre.placed, pre.segment_fn(), coverage=pre.coverage, passages=pre.passages,
+                            pattern_days=pre.network.pattern_days)
+ms.plot.tune_curves(tr)
+```
+
+Stages are usable on their own: `read_observations`, `build_network`, `segment`, `count`, `analyse`,
+`hotspots`, `simulate`.
+
+## CLI
+
+```bash
+microsegments run CONFIG -o OUT [--lang en] [--segment-m 20] [--dates A..B] [--source "credit"]
+microsegments tune CONFIG [--lengths 10,20,30,50] [--sensitivity] [-o OUT]
+microsegments hotspots CONFIG [-o hotspots.geojson|.csv|.parquet]
+microsegments inspect CONFIG        # coverage per day, GTFS versions, placement / drop counts
+```
+
+## What the numbers mean
+
+Every poll (about every 20 s) puts each vehicle in one micro-segment: one **observation**. One observation
+is therefore about 20 s of presence.
+
+| Metric | Definition | Read as |
+|---|---|---|
+| `obs_per_h` (default) | Σ observations / Σ covered hours | vehicles seen in the segment per hour of polling; `/len × 10` for per 10 m |
+| `obs_per_passage` | Σ observations / Σ passages | × 20 s ≈ time each vehicle spends there |
+| `excess_per_passage` | obs per passage − the same at 20–23 h, same days | extra observations (≈ seconds / 20) lost per vehicle vs free-flowing evening |
+| `excess_obs_per_h`, `log2_ratio` | see `metrics.py` | |
+
+All values are ratios of sums over the selected days (optionally post-stratified by weekday). Stop zones
+(30 m before to 60 m after each stop) can be masked to bring out signals and junctions. Colour scales are
+fixed per metric (p98 over 6–21 h), so hours and weekdays compare directly.
+
+## Missing data and GTFS versions
+
+- **Hours** with < 80 % of polls, a frozen feed (> 5 min), the line absent, or abnormal vehicle counts are
+  dropped from numerator and denominator. Polling gaps are handled by the exposure (covered hours); counts
+  are never imputed.
+- **Days** with more than 25 % of their 6–21 h dropped are excluded and listed with the reason
+  (`res.analysis.excluded_days`, coverage calendar in the page).
+- **GTFS changes**: patterns are rebuilt per service date; `link_key` / `seg_key` are stable across
+  versions. Each segment is aggregated only over the days it belongs to the day's main pattern (the
+  reference too). The page shows the most frequent version; others are selectable. A single feed whose
+  calendar does not cover some dates lends them the patterns of the same weekday.
+
+## Choosing the segment length
+
+`microsegments tune` scores L ∈ {10, 15, 20, 30, 40, 50, 75, 100} m (leave-one-day-out Poisson deviance,
+split-half reliability, hotspot localisation spread and Jaccard) and picks the smallest L with reliability
+≥ 0.8, spread ≤ 30 m and deviance within one standard error of the minimum. 30 m is a good default for
+20 s polling at urban speeds; go shorter only with dense GTFS-RT fixes and many days. `--sensitivity`
+re-runs phase offsets, gap caps, stop zones, references and passage sources.
+
+## Hotspots
+
+Stretches where the excess over the evening has a 95 % bootstrap lower bound above 2 s per vehicle, is
+positive on ≥ 60 % of days, survives Benjamini–Hochberg (q = 0.1) and lasts ≥ 2 hours or a peak band.
+Adjacent bins merge, never across a stop / running border. Classes: *infrastructure* (all day),
+*congestion* (peak only), *mixed*. Needs at least 5 included days. Export as GeoJSON with
+`microsegments hotspots CONFIG -o hotspots.geojson`.
+
+## License
+
+MIT. The bundled Leaflet CSS is BSD-2-Clause.

microsegments-0.1.0/examples/gtfsrt_csv.toml

@@ -0,0 +1,35 @@
+# GTFS-RT VehiclePositions flattened to CSV (one row per vehicle fix), matched on the GTFS shapes.
+#   microsegments run examples/gtfsrt_csv.toml -o out/bus
+
+[input]
+paths = ["positions/*.csv"]          # or *.parquet; GTFS-RT .pb files also work (format = "gtfsrt_pb")
+kind = "latlon"
+format = "auto"
+timezone = "Europe/Brussels"
+service_day_start = "04:00"          # 01:30 belongs to the previous service day
+ts_unit = "s"                        # "s" | "ms" | "us" | "iso"
+
+# canonical name = column in your file (only those that differ; unmapped well-known names are detected)
+[input.columns]
+ts = "timestamp"                     # fix time (vehicle.timestamp), epoch seconds here
+route_id = "route_id"                # must match the GTFS route_short_name (or route_id, see gtfs.route_key)
+vehicle_id = "vehicle_id"            # per-vehicle feed: fixes are thinned to one per tick_s
+trip_id = "trip_id"                  # optional, helps map matching
+direction_id = "direction_id"        # optional
+lat = "latitude"
+lon = "longitude"
+bearing = "bearing"                  # optional, degrees
+
+[gtfs]
+path = "gtfs.zip"
+route_key = "route_short_name"
+
+[select]
+route = "71"
+dates = "2025-02-17..2025-05-16"
+weekdays = [0, 1, 2, 3, 4]
+
+[params]
+segment_m = 30
+tick_s = 20                          # nominal interval: counts stay comparable with a 20 s snapshot feed
+max_lateral_m = 40                   # fixes farther from the shape are dropped

microsegments-0.1.0/examples/make_synth.py

@@ -0,0 +1,29 @@
+"""Generate the synthetic example data (offline) into examples/data/:
+
+    python examples/make_synth.py
+    microsegments run examples/synth.toml -o out/
+
+A simulated tram line "S1" (two directions, 8 links), 3 weeks of STIB-like positions every ~20 s
+with outages and a frozen feed, a GTFS change after two thirds of the period (the last two stops are cut), and three
+injected hotspots (a signal, a peak-hour queue, an evening holding stop). See microsegments.simulate.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from microsegments.simulate import simulate
+
+HERE = Path(__file__).resolve().parent
+
+
+def main(out: Path = HERE / "data", days: int = 21, seed: int = 0) -> Path:
+    sim = simulate(seed=seed, days=days, start="2025-03-03", mode="stib", out_dir=out / "gtfs", change_day=days * 2 // 3)
+    sim.write_stib(out / "vd")
+    sim.stop_events.write_parquet(out / "events.parquet")
+    print(f"{len(sim.observations):,} positions, {len(sim.dates)} days -> {out}")
+    return out
+
+
+if __name__ == "__main__":
+    main(Path(sys.argv[1]) if len(sys.argv) > 1 else HERE / "data")

microsegments-0.1.0/examples/stib55.toml

@@ -0,0 +1,29 @@
+# STIB tram 55, two days of vehicle-distance positions (the test fixture), linear referencing.
+#   microsegments run examples/stib55.toml -o out/stib55
+# Real use: point `paths` at the compact daily parquet files of a longer period (MobilityTwin
+# stib/vehicle-distance), and `gtfs.dated` at one GTFS snapshot per day.
+
+[input]
+paths = ["../tests/fixtures/stib55/vd55/*.parquet"]   # <YYYYMMDD>.parquet (ts, dir, point, dist) + .snaps.parquet
+kind = "stib"
+events = "../tests/fixtures/stib55/punctuality/route55.parquet"   # STIB punctuality: passages from stop events
+
+[input.linear]
+direction_kind = "terminus_stop"     # STIB directionId = destination stop code
+id_normaliser = "leading_digits"
+feed_length = "auto"                 # rescale feed metres to the GTFS link length (p99.5 per link)
+
+[gtfs]
+path = "../tests/fixtures/stib55/gtfs"    # gtfs-parquet directory
+# dated = "gtfs/{date}"                   # or one feed per day
+
+[select]
+route = "55"
+dates = "2025-03-18..2025-03-19"
+weekdays = [0, 1, 2, 3, 4]
+
+[params]
+segment_m = 30
+
+[quality]
+min_days = 2                         # only two days in the fixture

microsegments-0.1.0/examples/synth.toml

@@ -0,0 +1,27 @@
+# Synthetic tram line S1 (generate the data first: python examples/make_synth.py)
+#   microsegments run examples/synth.toml -o out/
+
+[input]
+paths = ["data/vd/*.parquet"]        # compact STIB-like files: <YYYYMMDD>.parquet + .snaps.parquet
+kind = "stib"                        # linear referencing: last stop passed + metres since
+timezone = "Europe/Brussels"
+events = "data/events.parquet"       # stop events (arrival / departure per trip and stop), optional
+
+[input.linear]
+id_normaliser = "leading_digits"     # "01003" -> "1003"
+
+[gtfs]
+path = "data/gtfs"                   # GTFS directory (.txt), zip or gtfs-parquet directory
+route_key = "route_short_name"
+
+[select]
+route = "S1"
+dates = "2025-03-03..2025-03-23"
+weekdays = [0, 1, 2, 3, 4]
+hours = [5, 24]
+
+[params]
+segment_m = 30
+stop_zone = [30, 60]                 # metres before / after a stop masked as "stop zone"
+reference_hours = [20, 23]
+bootstrap = 200

microsegments-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "microsegments"
+dynamic = ["version"]
+description = "Where do transit vehicles linger? Count vehicle position observations per micro-segment of a line, from GTFS + AVL / GTFS-RT positions."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Gaspard Merten", email = "gaspard.mp.work@gmail.com" },
+]
+keywords = ["gtfs", "gtfs-rt", "avl", "transit", "bus", "tram", "hotspots", "polars"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Typing :: Typed",
+]
+dependencies = [
+    "polars>=1.0",
+    "numpy>=1.26",
+    "shapely>=2.0",
+    "gtfs-parquet>=0.7",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.8"]
+mobilitytwin = ["requests>=2.31"]
+gtfsrt = ["gtfs-realtime-bindings>=1.0"]
+dev = ["pytest>=8.0", "hypothesis>=6.0", "matplotlib>=3.8"]
+
+[project.scripts]
+microsegments = "microsegments.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/GaspardMerten/microsegments"
+Repository = "https://github.com/GaspardMerten/microsegments"
+Issues = "https://github.com/GaspardMerten/microsegments/issues"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/microsegments/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/microsegments"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["regression: needs the local BrusselsTransitStuck prototype data (MS_PROTOTYPE_DATA)"]
+addopts = "-m 'not regression'"