pyssms 0.1.0__tar.gz

pyssms-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy
+      - run: pytest   # data/network tests are excluded by default (no microdata in CI)

pyssms-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: release
+# Publishes to PyPI with Trusted Publishing (OIDC): no token or password is stored anywhere.
+# One-time setup on pypi.org (account > Publishing > "Add a new pending publisher"):
+#   project name pyssms | owner sabernaseralavi-60 | repository pyssms | workflow release.yml | environment pypi
+# Trigger: publishing a GitHub release, or running the workflow by hand (workflow_dispatch).
+# A published version number can never be reused: bump the version before every release.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pyssms-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# data and caches: never commit microdata or third-party copyrighted PDFs
+local_data/
+data_raw/
+*.csv
+*.parquet
+*.feather
+*.arrow
+*.zip
+*.sas7bdat
+*.xpt
+*.dbf
+*.RData
+*.rds
+lit/*.pdf
+.cache/
+# python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+
+# local figures made from datasets without a declared licence
+figures_local/
+paper/manuscript.html
+paper/manuscript_fa.html
+
+# per-recording run files (aggregates, resumable runs)
+runs_local/
+
+# logs of long runs
+runs_*.log
+.venv310/
+
+# paper_softwarex build leftovers
+paper_softwarex/latex/*.aux
+paper_softwarex/latex/*.log
+paper_softwarex/latex/*.out
+paper_softwarex/latex/*.synctex.gz
+paper_softwarex/__pycache__/
+paper_softwarex/listing_test.log
+paper_softwarex/latex/*.spl

pyssms-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-11-08): initial release
+
+* `timetime`: one conflict polygon K in the plane of the two predicted arrival times gives TTC (state A), Time Advantage, T2 and Time Gap (state B) and
+  the no-overlap state C, for two convex translating bodies at any approach angle; vectorised; 8-row and 12-row forms of K for rectangles.
+* `reference.laureshyn2010`: independent implementation of Appendix A of Laureshyn et al. (2010) (32 corner-side combinations); equivalence
+  report (`docs/equivalence.md`) and benchmark (`docs/benchmark.md`).
+* `ssm1d`: the ten car-following measures of the 2025 framework (TTC1, TTC2, TTC3, TTCD, DRAC, MDRAC, DCIA, PSD, MPSD, SDI), tested against
+  simulations of their motion stories.
+* `contact`, `escape`, `stories`, `margins`, `disturbance`, `severity` (Delta-V, Extended Delta-V, injury-risk curves).
+* Trajectory input and processing: `io` (SSAM, SUMO FCD, VISSIM, LevelX, NGSIM, generic table), `preprocessing`, `process`, `calibration`,
+  `hierarchy`, `scenario`, `bank` and `datasets` (synthetic scenarios, a bank of NGSIM conflict windows under the FHWA licence text, aggregated
+  counts and scales of the five LevelX data sets; no LevelX trajectories), `viz`.
+* Tests: pytest suite in `tests/`; continuous integration on Linux and Windows with Python 3.10 and 3.13.
+* Article: `paper_softwarex/` holds the sources, the number-injection scripts and the figures of the accompanying software article.
+
+Everything reported by the tools is descriptive; no indicator is validated against observed outcomes in this release.

pyssms-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use pyssms, please cite it as below."
+title: "pyssms: surrogate safety indicators for road-user encounters on a time-time conflict polygon"
+version: 0.1.0
+date-released: 2026-11-08
+license: BSD-3-Clause
+repository-code: "https://github.com/sabernaseralavi-60/pyssms"
+authors:
+  - family-names: Naseralavi
+    given-names: Seyed Saber
+    orcid: "https://orcid.org/0000-0002-5392-910X"
+    affiliation: "Department of Civil Engineering, Shahid Bahonar University of Kerman, Kerman, Iran"
+  - family-names: Mazaheri
+    given-names: Akram
+    affiliation: "Department of Civil and Environmental Engineering, Tarbiat Modares University, Tehran, Iran"
+keywords:
+  - surrogate safety measures
+  - time to collision
+  - post-encroachment time
+  - traffic conflict
+  - road safety
+  - trajectory data
+abstract: >-
+  Continuous surrogate safety indicators for road-user encounters: TTC, Time Advantage, T2 and Time Gap for arbitrary approach angles, computed exactly on a time-time conflict polygon.
+# After the first release: archive it on Zenodo (GitHub integration) and add the DOI here:
+# doi: 10.5281/zenodo.XXXXXXX

pyssms-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+1. **Set up:** `uv venv && uv pip install -e ".[dev]"`.
+2. **Checks before a pull request:** `ruff check src tests`, `mypy`, `pytest`. Run `mypy` and `pytest` in a
+   fresh Python 3.10 environment too: CI installs newer type stubs than a long-lived dev environment.
+3. **Never commit data** or third-party PDFs (`.gitignore` already excludes them).
+4. **Do not tune the library to match a published figure.** If a figure does not reproduce, record it
+   with a note in `src/pyssms/validation/data/*.yaml` and set its `expected` status honestly.
+5. Regenerate `docs/validation.md` after any change that can move an estimate.
+6. Releases: bump the version in `pyproject.toml` and `src/pyssms/__init__.py`, update `CHANGELOG.md`,
+   tag `vX.Y.Z` and publish a GitHub release; the `release` workflow uploads to PyPI.

pyssms-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Seyed Saber Naseralavi
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pyssms-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: pyssms
+Version: 0.1.0
+Summary: Continuous surrogate safety indicators for road-user encounters: TTC, Time Advantage, T2 and Time Gap for arbitrary approach angles, computed exactly on a time-time conflict polygon.
+Project-URL: Homepage, https://github.com/sabernaseralavi-60/pyssms
+Project-URL: Issues, https://github.com/sabernaseralavi-60/pyssms/issues
+Project-URL: Changelog, https://github.com/sabernaseralavi-60/pyssms/blob/main/CHANGELOG.md
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: NGSIM,highD,post-encroachment time,road safety,surrogate safety measures,time to collision,traffic conflict,trajectory data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# pyssms
+
+![status](https://img.shields.io/badge/status-alpha-orange)
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+![license](https://img.shields.io/badge/license-BSD--3--Clause-green)
+
+Continuous surrogate safety indicators for road-user encounters: Time-to-Collision (TTC), Time
+Advantage (TAdv, a predicted PET), T2 and Time Gap (TG) as defined by Laureshyn, Svensson and
+Hydén (2010), for any approach angle and any convex body shape, computed exactly on one
+time-time conflict polygon.
+
+> **Status.** Version 0.1.0 is the initial release of the package. It covers the four indicators of the 2010 framework for
+> constant-velocity prediction of two translating convex bodies (verified against an independent implementation of the
+> paper's Appendix A and a brute-force grid oracle: [docs/equivalence.md](docs/equivalence.md)), the ten car-following
+> measures of the 2025 framework, trajectory readers for SSAM, SUMO, VISSIM, LevelX and NGSIM, and a bank of NGSIM
+> conflict windows. All statistics produced by the tools are descriptive: the indicators are not validated against observed
+> outcomes here. Install from the repository (not yet on PyPI):
+> `pip install git+https://github.com/sabernaseralavi-60/pyssms`. The accompanying article is in [paper_softwarex/](paper_softwarex/).
+
+## What it does
+
+```python
+import numpy as np
+from pyssms import indicators_rect
+
+# car 1 at (-20, 0) heading east at 10 m/s; car 2 at (0, -30) heading north at 10 m/s; 4.5 x 1.8 m
+k = indicators_rect(-20, 0, 0, 10, 0, 4.5, 1.8,  0, -30, np.pi / 2, 0, 10, 4.5, 1.8)
+k.state, k.ttc, k.tadv, k.t2, k.tg   # ['B'], [nan], [0.37], [2.685], [2.685]  (crossing course)
+```
+
+All inputs may be arrays of encounters; computation is vectorised.
+
+## Coverage (what exists today)
+
+| Measure | Module | Status |
+|---|---|---|
+| TTC, TAdv, T2, TG, state A/B/C (Laureshyn et al. 2010), any angle, any convex shape | `timetime` | verified against Appendix A (1e6 encounters) |
+| Injury risk curves for pedestrians, cyclists, motorcyclists, car drivers (Lubbe et al. 2022) | `severity` | safe speeds of the paper reproduced within coefficient rounding |
+| Disturbance set D, signed margin beta, Time Advantage and lateral margin as its axis readings | `disturbance` | consistent with `timetime` and `margins`; brute-force membership check; scales are inputs |
+| Smallest braking that avoids a contact (shape-aware DRAC relative) | `escape` | braking curve vs conflict polygon and vs `stories`; analytic stopping case |
+| Delta-V, Extended Delta-V (Laureshyn et al. 2017) | `severity` | 18 of 20 printed Table 1 rows reproduced; 2 documented gaps |
+| TTC1, TTC2, TTC3, TTCD, DRAC, MDRAC, DCIA, PSD, MPSD, SDI (Naseralavi et al. 2025), car following | `ssm1d` | tested against simulations of their stories; printed-form differences in `docs/ssm1d_notes.md` |
+| Motion stories (constant speed, acceleration, jerk) and first contact on straight paths | `stories` | equals `timetime` for constant speed; brute-force check for braking |
+| Time margin (TAdv) and lateral margin | `timetime`, `margins` | lateral margin checked against the independent polygon code |
+| Trajectory readers: SSAM `.trj` (read and write), LevelX (inD, rounD, exiD, uniD, highD), SUMO FCD, VISSIM `.fzp`, generic table | `io` | round trips on synthetic files; the LevelX readers were run on real recordings of the five LevelX data sets ([docs/io_and_scenarios.md](docs/io_and_scenarios.md)) |
+| Encounter series, observed PET, TET/TIT, braking onset and (TA, v_conf), scale calibration, severity hierarchy, scenario summary and comparison, synthetic scenarios | `process`, `calibration`, `hierarchy`, `scenario`, `datasets` | unit tests on constructed cases; definitions stated in the docstrings; hierarchy and prediction-error scales computed on all recordings of inD, rounD, uniD, exiD and highD (`docs/diamond_*.md`, descriptive, nothing validated); Hyden's (1987) severity zones are approximate (see the docstrings) |
+| Which face and corner touch first on a collision course, and which would touch if the road user ahead were delayed by TAdv (crossing course) | `contact` | time-stepped search; the ten corner-side configurations of Jimenez et al. (2013) come out as classes |
+| NGSIM reader (US-101, I-80, Lankershim, Peachtree; feet to metres, front centre to body centre) | `io.read_ngsim` | run on all ten periods; units checked against the data set's own columns ([docs/ngsim_notes.md](docs/ngsim_notes.md)) |
+| Causal or centred smoothing of trajectories | `preprocessing` | unit tests (causality, noise reduction, lag); not tuned to a data set |
+| Conflict windows: `extract_conflicts`, and a bank of windows around the most severe encounters of NGSIM that ships with the package (`datasets.load_conflict_bank("ngsim")`), plus counts and scales of the five LevelX data sets (`datasets.load_summary()`) | `bank`, `datasets` | the windows are chosen by the package's own indicators: examples and test material, **not a sample** |
+| Plots of the polygon K, the disturbance set D with the signed margin, the indicator profile of an encounter, the hierarchy (needs matplotlib) | `viz` | smoke tests |
+| Statistically scaled margin (beta), collision physics beyond point masses, 2-D versions of the ten car-following measures, native Aimsun input | - | **not implemented** |
+
+## The idea in one paragraph
+
+Give each road user its own predicted arrival time at the conflict. The pairs of arrival times at which the two bodies overlap
+form a convex polygon `K` (an affine preimage of the Minkowski difference of the bodies).
+Undisturbed motion is the diagonal. TTC is where the diagonal enters `K`; TAdv is the distance
+of `K` from the diagonal (the delay that would produce a collision); T2 and TG are the earliest
+second arrivals. The 32 corner-side combinations of the 2010 appendix become one polygon, and
+parallel paths, standing road users and overlapping bodies need no special cases. See
+[docs/methods.md](docs/methods.md).
+
+## Development
+
+```
+uv venv && uv pip install -e ".[dev]"
+pytest
+python tools/equivalence.py --n 1000000   # writes docs/equivalence.md
+python tools/benchmark.py                 # writes docs/benchmark.md
+```
+
+## Citation
+
+See [CITATION.cff](CITATION.cff). License of the code: BSD-3-Clause.
+
+**Data shipped inside the package** (`src/pyssms/data/`): the windows in `conflict_bank_ngsim.npz` come
+from the FHWA NGSIM trajectories, licensed by the Federal Highway Administration under a modified
+Creative Commons Attribution 2.0 licence (not public domain). Credit FHWA and the Next Generation
+Simulation (NGSIM) program; any reuse of those data is subject to that licence
+(`NGSIM_LICENSE.txt`, `NGSIM_CC-BY-2.0_legalcode.html`); the data are provided as is. Nothing from the
+LevelX data sets (inD, rounD, uniD, exiD, highD) is shipped except aggregated counts and scales.

pyssms-0.1.0/README.md

@@ -0,0 +1,82 @@
+# pyssms
+
+![status](https://img.shields.io/badge/status-alpha-orange)
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+![license](https://img.shields.io/badge/license-BSD--3--Clause-green)
+
+Continuous surrogate safety indicators for road-user encounters: Time-to-Collision (TTC), Time
+Advantage (TAdv, a predicted PET), T2 and Time Gap (TG) as defined by Laureshyn, Svensson and
+Hydén (2010), for any approach angle and any convex body shape, computed exactly on one
+time-time conflict polygon.
+
+> **Status.** Version 0.1.0 is the initial release of the package. It covers the four indicators of the 2010 framework for
+> constant-velocity prediction of two translating convex bodies (verified against an independent implementation of the
+> paper's Appendix A and a brute-force grid oracle: [docs/equivalence.md](docs/equivalence.md)), the ten car-following
+> measures of the 2025 framework, trajectory readers for SSAM, SUMO, VISSIM, LevelX and NGSIM, and a bank of NGSIM
+> conflict windows. All statistics produced by the tools are descriptive: the indicators are not validated against observed
+> outcomes here. Install from the repository (not yet on PyPI):
+> `pip install git+https://github.com/sabernaseralavi-60/pyssms`. The accompanying article is in [paper_softwarex/](paper_softwarex/).
+
+## What it does
+
+```python
+import numpy as np
+from pyssms import indicators_rect
+
+# car 1 at (-20, 0) heading east at 10 m/s; car 2 at (0, -30) heading north at 10 m/s; 4.5 x 1.8 m
+k = indicators_rect(-20, 0, 0, 10, 0, 4.5, 1.8,  0, -30, np.pi / 2, 0, 10, 4.5, 1.8)
+k.state, k.ttc, k.tadv, k.t2, k.tg   # ['B'], [nan], [0.37], [2.685], [2.685]  (crossing course)
+```
+
+All inputs may be arrays of encounters; computation is vectorised.
+
+## Coverage (what exists today)
+
+| Measure | Module | Status |
+|---|---|---|
+| TTC, TAdv, T2, TG, state A/B/C (Laureshyn et al. 2010), any angle, any convex shape | `timetime` | verified against Appendix A (1e6 encounters) |
+| Injury risk curves for pedestrians, cyclists, motorcyclists, car drivers (Lubbe et al. 2022) | `severity` | safe speeds of the paper reproduced within coefficient rounding |
+| Disturbance set D, signed margin beta, Time Advantage and lateral margin as its axis readings | `disturbance` | consistent with `timetime` and `margins`; brute-force membership check; scales are inputs |
+| Smallest braking that avoids a contact (shape-aware DRAC relative) | `escape` | braking curve vs conflict polygon and vs `stories`; analytic stopping case |
+| Delta-V, Extended Delta-V (Laureshyn et al. 2017) | `severity` | 18 of 20 printed Table 1 rows reproduced; 2 documented gaps |
+| TTC1, TTC2, TTC3, TTCD, DRAC, MDRAC, DCIA, PSD, MPSD, SDI (Naseralavi et al. 2025), car following | `ssm1d` | tested against simulations of their stories; printed-form differences in `docs/ssm1d_notes.md` |
+| Motion stories (constant speed, acceleration, jerk) and first contact on straight paths | `stories` | equals `timetime` for constant speed; brute-force check for braking |
+| Time margin (TAdv) and lateral margin | `timetime`, `margins` | lateral margin checked against the independent polygon code |
+| Trajectory readers: SSAM `.trj` (read and write), LevelX (inD, rounD, exiD, uniD, highD), SUMO FCD, VISSIM `.fzp`, generic table | `io` | round trips on synthetic files; the LevelX readers were run on real recordings of the five LevelX data sets ([docs/io_and_scenarios.md](docs/io_and_scenarios.md)) |
+| Encounter series, observed PET, TET/TIT, braking onset and (TA, v_conf), scale calibration, severity hierarchy, scenario summary and comparison, synthetic scenarios | `process`, `calibration`, `hierarchy`, `scenario`, `datasets` | unit tests on constructed cases; definitions stated in the docstrings; hierarchy and prediction-error scales computed on all recordings of inD, rounD, uniD, exiD and highD (`docs/diamond_*.md`, descriptive, nothing validated); Hyden's (1987) severity zones are approximate (see the docstrings) |
+| Which face and corner touch first on a collision course, and which would touch if the road user ahead were delayed by TAdv (crossing course) | `contact` | time-stepped search; the ten corner-side configurations of Jimenez et al. (2013) come out as classes |
+| NGSIM reader (US-101, I-80, Lankershim, Peachtree; feet to metres, front centre to body centre) | `io.read_ngsim` | run on all ten periods; units checked against the data set's own columns ([docs/ngsim_notes.md](docs/ngsim_notes.md)) |
+| Causal or centred smoothing of trajectories | `preprocessing` | unit tests (causality, noise reduction, lag); not tuned to a data set |
+| Conflict windows: `extract_conflicts`, and a bank of windows around the most severe encounters of NGSIM that ships with the package (`datasets.load_conflict_bank("ngsim")`), plus counts and scales of the five LevelX data sets (`datasets.load_summary()`) | `bank`, `datasets` | the windows are chosen by the package's own indicators: examples and test material, **not a sample** |
+| Plots of the polygon K, the disturbance set D with the signed margin, the indicator profile of an encounter, the hierarchy (needs matplotlib) | `viz` | smoke tests |
+| Statistically scaled margin (beta), collision physics beyond point masses, 2-D versions of the ten car-following measures, native Aimsun input | - | **not implemented** |
+
+## The idea in one paragraph
+
+Give each road user its own predicted arrival time at the conflict. The pairs of arrival times at which the two bodies overlap
+form a convex polygon `K` (an affine preimage of the Minkowski difference of the bodies).
+Undisturbed motion is the diagonal. TTC is where the diagonal enters `K`; TAdv is the distance
+of `K` from the diagonal (the delay that would produce a collision); T2 and TG are the earliest
+second arrivals. The 32 corner-side combinations of the 2010 appendix become one polygon, and
+parallel paths, standing road users and overlapping bodies need no special cases. See
+[docs/methods.md](docs/methods.md).
+
+## Development
+
+```
+uv venv && uv pip install -e ".[dev]"
+pytest
+python tools/equivalence.py --n 1000000   # writes docs/equivalence.md
+python tools/benchmark.py                 # writes docs/benchmark.md
+```
+
+## Citation
+
+See [CITATION.cff](CITATION.cff). License of the code: BSD-3-Clause.
+
+**Data shipped inside the package** (`src/pyssms/data/`): the windows in `conflict_bank_ngsim.npz` come
+from the FHWA NGSIM trajectories, licensed by the Federal Highway Administration under a modified
+Creative Commons Attribution 2.0 licence (not public domain). Credit FHWA and the Next Generation
+Simulation (NGSIM) program; any reuse of those data is subject to that licence
+(`NGSIM_LICENSE.txt`, `NGSIM_CC-BY-2.0_legalcode.html`); the data are provided as is. Nothing from the
+LevelX data sets (inD, rounD, uniD, exiD, highD) is shipped except aggregated counts and scales.

pyssms-0.1.0/docs/benchmark.md

@@ -0,0 +1,23 @@
+# Benchmark
+
+*Generated by `tools/benchmark.py`; do not edit by hand.* pyssms 0.1.0, Python 3.13.5, NumPy 2.5.4, Intel64 Family 6 Model 151 Stepping 5, GenuineIntel; single process, best of 3 (best-of-3 also at 10^6; absolute times vary by up to a factor of two between runs).
+
+All four indicators (TTC, TAdv, T2, TG) per encounter.
+
+| encounters | time-time polygon (s) | 32 combinations, vectorised (s) | polygon us/encounter |
+|---|---|---|---|
+| 10,000 | 0.05 | 0.03 | 5.4 |
+| 100,000 | 0.56 | 0.40 | 5.6 |
+| 1,000,000 | 4.34 | 4.13 | 4.3 |
+
+The polygon column uses the 8-row form of K that applies when both rectangles move along their length (side faces parallel to the axes of the time-time plane; all encounters of this benchmark). The general 12-row form, which any convex shape and any velocity direction uses, takes:
+
+| encounters | general 12-row form (s) | 8-row form (s) | ratio |
+|---|---|---|---|
+| 10,000 | 0.10 | 0.05 | 1.93 |
+| 100,000 | 0.94 | 0.56 | 1.67 |
+| 1,000,000 | 9.48 | 4.34 | 2.18 |
+
+A per-encounter Python loop over the 32 combinations takes 5449 us per encounter.
+
+Both columns use the block size that was fastest for them (polygon: the default, 500 encounters; reference: all at once, 20,000, 5,000 or 2,000). At 10^6 encounters the polygon takes 1.05 times the time of the vectorised combinations. Its value is exactness in the cases the appendix does not cover (parallel paths, standing road users, overlapping bodies) and one code path for any convex shape.

pyssms-0.1.0/docs/beta_proposal.md

@@ -0,0 +1,48 @@
+# Margin beta: what is decided and what is not (2026-11-01)
+
+Status: **not implemented.** The 2010 paper only says that a near miss "has less of a safety margin
+to endure an additional unlucky factor" (Section 2). Turning that sentence into a number needs a
+disturbance model, which is a scientific decision. Facts that constrain it, read from the papers:
+
+* The 2017 paper (Section 5.2) lists what a disturbance model must not ignore: braking force
+  depends on friction and vehicle; cyclists swerve and pedestrians can jump back; four masses only;
+  the collision is a completely inelastic point-mass collision.
+* Prior art on disturbance-based margins exists (Astarita & Giofre 2019; Kuang et al. 2015; Xie et
+  al. 2019 for TTCD in the 2025 paper), so novelty must come from the formulation, not the idea.
+
+Candidate definitions, from simplest to richest (none validated):
+
+1. **Time margin** = TAdv (already implemented): the smallest delay of one road user that creates a
+   collision course. No new parameter.
+2. **Lateral margin** (needed for state C): the smallest sideways shift of one path that makes the
+   bodies overlap at the same time; exact on the overlap polygon R for straight paths.
+3. **Combined margin**: smallest norm of (delay, lateral shift) after scaling each by a standard
+   deviation estimated from undisturbed passages at the same site (a Hasofer-Lind style distance).
+   Scales are data, not constants; the choice of norm and of the scales is the open decision.
+
+## Update 2026-11-01: option 3 as a geometric object (implemented, scales still open)
+
+`pyssms.disturbance` computes the disturbance set D in the plane of the clock shift delta (s) and a
+sideways shift eps (m) of one path: the pairs for which the disturbed straight-line encounter
+overlaps within the horizon. D is a convex polygon (projection of a convex polytope; exact
+Fourier-Motzkin elimination). Then:
+
+* the undisturbed encounter is the origin; it lies in D exactly on a collision course (state A);
+* Time Advantage (option 1) and the lateral margin (option 2) are the shortest distances to D along
+  the two axes (checked against `pyssms.timetime` and `pyssms.margins`);
+* the signed distance `beta` from the origin to D in the scaled coordinates
+  `(delta/sigma_delta, eps/sigma_eps)` is continuous through A, B and C; `Phi(-beta)` is the
+  Hasofer-Lind approximation of a collision-course probability (exact for a half-plane D).
+
+What this does not settle: (a) `sigma_delta` and `sigma_eps` (data, not constants; the error of a
+constant-velocity prediction grows with the horizon), (b) whether a shift of the clock is the right
+disturbance for a braking road user (braking is not a time shift), (c) at a perpendicular crossing
+the lateral margin of the second road user equals `|v1| * TAdv`, so it adds no information there;
+it matters for diverging or parallel paths, (d) when a passage is over (D empty) `beta` is
+undefined. Prior art for the idea of a margin: Hyden (1987) hypothesises a safety margin used by
+road users when judging whether they are on a collision course (as cited in the 2010 thesis,
+Section 4.1); Svensson (1998) discusses enlarging the road users' footprints so that near misses register as collision courses (read in her thesis, Section 4 and the closing chapter: discussed, not applied)
+(same source; neither read in the original); Astarita & Giofre (2019) and Kuang et al. (2015) are in
+`literature_step0.md`. The contribution to claim is the formulation and its checks, not the idea.
+
+Question for the 2010 paper's authors: which of these matches the intuition in Section 2?

pyssms-0.1.0/docs/data_notes.md

@@ -0,0 +1,11 @@
+# Pitfalls found while building pyssms
+
+* Implementing Appendix A of Laureshyn et al. (2010) from the journal's "article in press" PDF
+  gives a wrong sign: Eqs. (8) and (9) lack the leading minus sign there and return minus the
+  crossing time. The author's 2010 thesis (Appendix, printed p. 138) prints the minus sign, so the
+  equations themselves are correct. Eq. (10) has `x2`, `y2` where `x_ln2`, `y_ln2` are meant (thesis
+  and preprint alike), and a literal implementation needs a tolerance for sides parallel to an axis.
+  Evidence and counts: [equivalence.md](equivalence.md); derivation: [methods.md](methods.md).
+* The appendix does not cover parallel paths, standing road users or bodies that already overlap.
+* Any comparison of two implementations must use the same prediction horizon (an oracle with a
+  shorter horizon produced a false 2.6 s disagreement during development).

pyssms-0.1.0/docs/data_sources.md

@@ -0,0 +1,35 @@
+# Data sources (not redistributed)
+
+| Dataset | Source | Retrieved | Notes |
+|---|---|---|---|
+| DUT vehicle-crowd interaction (filtered trajectories and ratios) | https://github.com/dongfang-steven-yang/vci-dataset-dut, commit `80b8c746833664cd1e5244fccad79c7f2a7cbe31` | 2026-11-01 | Stored in `data_raw/dut/` (git-ignored). **The repository declares no licence**: do not redistribute; ask the authors before publishing derived figures. Cite Yang et al., arXiv:1902.00487 (not yet read in full; verify the reference before citing). Per-file SHA-256 list: `data_raw/SHA256SUMS_dut.txt` (84 files; SHA-256 of that list begins `c1f53915d9b77d6b`). Columns of vehicle files: `id, frame, label, x_est, y_est, psi_est, vel_est`; pedestrians: `id, frame, label, x_est, y_est, vx_est, vy_est`. |
+| SinD sample record Tianjin 8_2_1 (Tsinghua University) | https://github.com/SOTIF-AVLab/SinD, `Data/Tianjin/8_2_1/` (Git LFS objects fetched from media.githubusercontent.com) | 2026-11-02 | Stored in `data_raw/sind_tianjin/` (git-ignored; SHA-256 list `data_raw/SHA256SUMS_sind_tianjin.txt`, `Veh_smoothed_tracks.csv` begins `c377452a22ad0d57`). **Licence is not clear:** the repository `LICENSE` file is the CC0 text, but the README badge and text state a non-commercial *dataset* licence and give full access by request to an educational e-mail address. Treated as non-commercial research use, not redistributed, aggregates only; ask the authors before publishing any derived figure. Cars and bicycles have measured `length`/`width`; pedestrians have none. Cite Xu et al. (2022), IEEE ITSC (not yet read; verify before citing). |
+| FLUID (Figshare, doi 10.6084/m9.figshare.29974954; Scientific Data, doi 10.1038/s41597-026-07110-9) | placed by the user in `data_raw/FLUID/` (browser download), 2026-11-02 | 2026-11-02 | Licence CC BY 4.0 (read from the Figshare record). Files and SHA-256 prefixes: `Conflict.zip` a654792d6756c209, `FI-derived_data.zip` 271be0412b6ad56d, `FIDRT-derived_data.zip` b59703fdec881c28, `TI-derived_data.zip` e73ed4a0f2f400d4, `README.md` 4c8eed3aaea9f14f, article PDF 682d4748fcbd0bcc. **The conflict lists are not human labels:** the paper defines a conflict by thresholds on the authors' own TTC (0 to 2 s) and DGT (0 to 4 s) for pairs of motor vehicles; using them as an outcome for TTC-type indicators would be circular. Analysed from 2026-11-02 with `tools/fluid_pilot.py` (scene TI videos 1-3 exploratory; scenes FI and FIDRT as a pre-declared confirmation, `docs/prereg_fluid_confirmation.md`); the conflict lists are not used. |
+| NGSIM (FHWA Next Generation Simulation): US-101, I-80, Lankershim Boulevard, Peachtree Street | placed by the user at `D:\ReproducibleResearch_R_Projects\NGSIM\10-02-2026\data_raw\NGSIM DATA` (four archives); unpacked 2026-11-07 into `data_raw/ngsim/` | 2026-11-07 | **Licence read from `ngsim-license.htm` of the archives: modified Creative Commons Attribution 2.0, Licensor FHWA; credit FHWA and NGSIM, and any reuse must state it is subject to the licence. Not public domain, not CC0.** Redistribution of derived windows is allowed under those conditions (shipped in `src/pyssms/data/` with the licence text). SHA-256 prefixes of the archives and of the ten trajectory files: `data_raw/SHA256SUMS_ngsim_prefix.txt` (archives: I 80.rar 48f113fc6795984f, Lankershim d615aae87efe0b84, Peachtree d25a34bc64761318, US-101 480b460615482e0d). Used: hierarchy and scales (`docs/diamond_NGSIM.md`), ten measures on the freeway files, conflict bank. Details: `docs/ngsim_notes.md`. |
+| DLR Urban Traffic dataset v1.3.1 (Zenodo) | placed by the user in `data_raw/dlr_ut/`, 2026-11-02 | 2026-11-02 | Licence CC BY-NC-SA 4.0 (from the dataset README). `DLR-Urban-Traffic-dataset_v1-3-1.zip` f13b10fdba5675ca (463 MB), documentation PDF 94fd9ebd32d04a9c. One day at the AIM Research Intersection in Braunschweig. Not analysed yet. The dataset paper (Schicktanz et al., IEEE IV 2025; placed by the user in `data_raw/dlr_ut/`, SHA-256 prefix 56cdefef7609ee54) gives 10 Hz trajectories of 32,296 road users of one day. |
+| Svensson (1998) thesis | placed by the user in `lit/Svensson1998.pdf`, 2026-11-02 | 2026-11-02 | SHA-256 prefix c0d9dce7149e943c; 176 pages; read only in the passages on footprint enlargement and safety margins. |
+| highD copy in a third-party GitHub repository (`HighD_Preprocessing`) | not downloaded | 2026-11-02 | highD is distributed on request; a third-party copy has no declared licence, so it was not fetched. Use the official request. |
+| LevelX family: inD, highD, rounD, exiD, uniD (RWTH Aachen / fka) | requests reported approved by the user on 2026-11-03 (relayed in chat; the approval e-mails were not seen by me) | not downloaded | **Files not yet in `data_raw/` on 2026-11-03.** Licence terms are those of the approval e-mails (scientific, non-commercial use as relayed); do not redistribute, do not commit, no derived figure without checking the terms. Cite inD as Bock, Krajewski, Moers, Runde, Vater and Eckstein (2020), 2020 IEEE Intelligent Vehicles Symposium, pp. 1929-1934, doi:10.1109/IV47402.2020.9304839 (checked with Crossref 2026-11-03; the other data sets have their own preferred references on the providers' websites, not yet recorded here). Present on 2026-11-03: `data_raw/inD-dataset-v1.1` (33 recordings), `round-dataset-v1.1` (24), `uniD-dataset-v1.1` (13), `exiD-dataset-v2.1` (93), `highD-dataset-v1.0` (60 recordings, 4.5 GB). |
+
+Papers fetched on 2026-11-01 into `lit/` (outside the repository; open access, normal download, no
+paywall bypassed). SHA-256 in parentheses:
+
+| File | Source | SHA-256 |
+|---|---|---|
+| `Lubbe2022_safe_speeds.pdf` | https://doi.org/10.55329/vfma7555 (Traffic Safety Research 2, 000006, CC-BY) via https://tsr.international/TSR/article/download/23823/21217 | `32318eaf90f9d5b2` |
+| `Johnsson_Laureshyn2022_evasive.pdf` | https://doi.org/10.55329/erqd8683 (Traffic Safety Research 3, 000012) via https://tsr.international/TSR/article/download/23755/21648 | `f1681103dc3206c0` |
+| `Tefft2011_PedestrianRiskVsSpeed.pdf` | https://aaafoundation.org/wp-content/uploads/2026/02/2011PedestrianRiskVsSpeedReport.pdf | `3deef7f75204089b` |
+| `Hyden1987_thesis.pdf` | https://www.ictct.net/wp-content/uploads/SMoS_Library/LIB_Hyden_1987.pdf (link published in the SMoS library cited by Johnsson and Laureshyn 2022) | `78cd77939702c27e` |
+| `Aliaksei_Laureshyn.pdf` | Lund University portal copy of the 2010 thesis (supplied by the user; download date printed in the file: 2026-11-01) | not computed |
+| `Zanardi2023_arXiv2308.01050.pdf` | https://arxiv.org/pdf/2308.01050 (arXiv preprint; downloaded 2026-11-02; methods read) | `d73feeae0a6409b0` |
+| `2013_An Improved Method to Calculate the Time-to-Collision of Two Vehicles.pdf` | placed by the user in `lit/` on 2026-11-03 (paywalled at the publisher; not downloaded by me). Jimenez, Naranjo, Garcia, Int. J. Intell. Transp. Syst. Res. 11(1):34-42, doi:10.1007/s13177-012-0054-4 (Crossref: online 2012-11-28, volume 11 issue 1 pages 34-42). Read: sections 2 to 5 (pages 2 to 7) | `9fdf8a616ed7dfcf` |
+| `SSAM_File_Format_v1.04.pdf` | https://raw.githubusercontent.com/OSADP/SSAM/master/Documentation/SSAM%20File%20Format%20v1.04.pdf (downloaded 2026-11-03) | `11e62f3b7e9d5b9a` |
+| `SSAM_File_Format_v3.0.pdf` | https://raw.githubusercontent.com/OSADP/SSAM/master/Documentation/Open%20Source%20SSAM%20File%20Format%20v3.0.pdf (downloaded 2026-11-03) | `15c5068489101deb` |
+| `ika_drone_dataset_tools_tracks_import.py` | https://raw.githubusercontent.com/ika-rwth-aachen/drone-dataset-tools/master/src/tracks_import.py (downloaded 2026-11-03; reference loader of the LevelX data provider, read for column names) | `317c2fb8b74d40a7` |
+| `sumo_sumolib_convert_trj.py` | https://raw.githubusercontent.com/eclipse-sumo/sumo/main/tools/sumolib/output/convert/trj.py (downloaded 2026-11-03; SUMO's `.trj` writer, EPL-2.0 or GPL-2.0+, read for the byte layout) | `f17c59157ac6e95d` |
+| `Cheng2026_arXiv2604.17841.pdf` | https://arxiv.org/pdf/2604.17841 (arXiv preprint; downloaded 2026-11-02; methods read) | `2531e0dfff77b65d` |
+
+Svensson (1998), https://portal.research.lu.se/files/4456913/1653512.pdf, returned a
+Cloudflare challenge page (HTTP 403) and was not fetched; it needs to be placed in `lit/` by hand.
+Hyden (1987) was fetched but not yet read. Papers in `lit/` are git-ignored. Open-access copy of Laureshyn et al. (2017, Extended Delta-V) could
+not be fetched (publisher 403, university server down for maintenance); place it in `lit/` by hand.