v2x-risk 0.1.0__tar.gz

v2x_risk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Quito
+
+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.

v2x_risk-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: v2x-risk
+Version: 0.1.0
+Summary: Reproducible LSTM-GAT model for V2X traffic anomaly and collision-risk classification
+Author: Benjamin Quito
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/benjaminquito/V2X
+Project-URL: Repository, https://github.com/benjaminquito/V2X
+Project-URL: Paper, https://doi.org/10.4236/ojsst.2026.163010
+Project-URL: Issues, https://github.com/benjaminquito/V2X/issues
+Keywords: v2x,traffic-anomaly-detection,collision-risk,lstm,graph-attention-network,reproducible-research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: openpyxl<4,>=3.1
+Requires-Dist: pandas<3,>=2.1
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: scikit-learn<2,>=1.3
+Requires-Dist: torch<3,>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.9; extra == "dev"
+Dynamic: license-file
+
+# V2X Traffic Anomaly and Collision-Risk Model
+
+[![CI](https://github.com/benjaminquito/V2X/actions/workflows/ci.yml/badge.svg)](https://github.com/benjaminquito/V2X/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/v2x-risk.svg)](https://pypi.org/project/v2x-risk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+This repository is a reproducible implementation of the revised model associated with
+*Predicting Traffic Anomalies and Collision Risks in V2X Systems: A Deep Learning Approach
+Using LSTM and GNN*. It implements the later reviewer-response design:
+
+- a two-layer LSTM for 15-step vehicle histories;
+- a two-layer, multi-head Graph Attention Network (GAT) for per-frame vehicle interactions;
+- directed proximity edges between vehicles less than 20 m apart;
+- a trainable softmax attention module that fuses temporal and spatial representations; and
+- three-class prediction: Low (0), Medium (1), and High (2) risk.
+
+No trained weights or real-data results are claimed by this repository. The NGSIM data is not
+redistributed. Figures stated in the manuscript or later development chat are historical claims and
+must not be treated as results reproduced by this code.
+
+## Why this implementation differs from the uploaded manuscript
+
+The uploaded manuscript describes an earlier model in several places: 50-step, three-feature
+sequences; two GCN layers; continuous risk scores; and fixed 0.6/0.4 fusion. The later revision
+changed these to 15-step, four-feature inputs; GAT; three-class outputs; and learned attention
+fusion. This repository implements the later design requested for the reviewer response while
+preserving the original claims as historical metadata only. See
+[`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) for the complete reconciliation.
+
+The earlier chat evaluation paired LSTM samples and graphs by truncating both collections to the
+same length. That does not establish that the two inputs describe the same vehicle and frame. Here,
+each graph node is built only when that exact vehicle has a valid history ending at the graph's
+frame. Both branches therefore operate on an explicitly aligned sample.
+
+The later chat's 99.90% accuracy and 1.00 weighted-F1 claim is not a repository baseline: the shared
+evaluation snippet did not demonstrate trained fusion weights or key-based modality alignment. It
+is mentioned only to prevent accidental reuse as a regenerated result.
+
+## Repository layout
+
+```text
+configs/                 Full-data and smoke-test configurations
+data/                    Raw/processed placeholders (generated data is ignored)
+docs/                    Data, methodology, and reproducibility notes
+results/                 Historical claims and regenerated-output placeholder
+src/v2x_risk/            Preprocessing, model, training, and evaluation code
+tests/                   Unit and end-to-end smoke tests
+```
+
+## Installation
+
+Python 3.10 or newer is required.
+
+Install the published package:
+
+```bash
+python -m pip install v2x-risk
+```
+
+For repository development, create an isolated environment and install the editable package:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+To reproduce the exact dependency versions used for the repository smoke test, install
+`requirements-lock.txt` before the editable package:
+
+```bash
+python -m pip install -r requirements-lock.txt
+python -m pip install --no-deps -e .
+```
+
+PyTorch is the only deep-learning dependency. The GAT layer uses native PyTorch scatter operations,
+so no separately compiled graph library is required.
+
+## Quick execution check
+
+The smoke run creates a small synthetic, NGSIM-shaped dataset, preprocesses it, trains one epoch,
+evaluates all three branches, and writes a visual report:
+
+```bash
+python -m v2x_risk.smoke --config configs/smoke.yaml
+```
+
+Smoke metrics only verify that the pipeline executes. They are not research results and must not be
+compared with the paper.
+
+Open `results/regenerated/smoke/run_report.html` after the command completes to inspect the visual
+pipeline summary.
+
+## Reproduce with NGSIM
+
+1. Obtain an NGSIM trajectory CSV from the
+   [U.S. DOT NGSIM Open Data portal](https://data.transportation.gov/stories/s/Next-Generation-Simulation-NGSIM-Open-Data/i5zb-xe34/)
+   and place it at `data/raw/NGSIM.csv`.
+2. Review [`configs/default.yaml`](configs/default.yaml), especially the coordinate conversion and
+   risk-label assumptions.
+3. Run the complete pipeline:
+
+```bash
+python -m v2x_risk.preprocess --config configs/default.yaml
+python -m v2x_risk.train --config configs/default.yaml
+python -m v2x_risk.evaluate --config configs/default.yaml --split test
+```
+
+Or use:
+
+```bash
+./scripts/reproduce.sh configs/default.yaml
+```
+
+The loader detects CSV and Excel OOXML content from the file signature. This means an uploaded
+workbook can still be read if it was accidentally named `NGSIM.csv`, although using the correct
+`.xlsx` suffix is recommended.
+
+Generated files include:
+
+- `data/processed/ngsim_aligned_graph_windows.npz`: aligned graph/history samples;
+- `data/processed/scaler.json`: train-only min-max parameters;
+- `data/processed/manifest.json`: source hash, counts, split sizes, and preprocessing metadata;
+- `results/regenerated/best_model.pt`: best checkpoint by validation macro F1;
+- `results/regenerated/metrics.json`: training history and branch-level results;
+- `results/regenerated/test_metrics.json`: independently regenerated test metrics; and
+- `results/regenerated/test_predictions.csv`: per-frame predictions and learned fusion weights;
+- `results/regenerated/run_summary.txt`: a plain-language completion summary; and
+- `results/regenerated/run_report.html`: a visual completion and results dashboard.
+
+At the end of `scripts/reproduce.sh`, the terminal prints `V2X RUN COMPLETED SUCCESSFULLY` followed
+by the main dataset counts, held-out metrics, and output locations. Open `run_report.html` in a web
+browser to verify the completed run visually.
+
+The default configuration follows the paper's 70/15/15 proportions and five training epochs. The
+split is chronological and inserts a 14-frame gap at boundaries to reduce leakage from overlapping
+15-step windows. Min-max scaling is fit on the training split only.
+
+## Required CSV columns
+
+Core inputs are `Vehicle_ID`, `Frame_ID`, `Local_X`, and `Local_Y`. The preferred input also has
+`v_Vel` and `v_Acc`. When either kinematic field is absent, preprocessing derives it from
+longitudinal position and elapsed time using the explicit settings under `data.kinematics`.
+Existing kinematic columns are never replaced. If the CSV already contains `Risk_Class`, it is used
+after validation. Otherwise, `Time_Headway` and `Space_Headway` are also required and labels are
+generated from the explicit thresholds in the configuration. The manuscript did not state the
+numerical labeling thresholds, so the supplied values are transparent repository assumptions that
+researchers should review or replace.
+
+Combined files should include `Location`. Preprocessing keeps locations separate, segments reused
+vehicle IDs into contiguous frame runs, and keys graph snapshots by location and timestamp. This
+prevents observations from separate roads or recording sessions from entering the same trajectory
+or proximity graph.
+
+Derived speed and acceleration are a transparent compatibility fallback. Report their use and do
+not treat results based on derived kinematics as directly comparable to experiments that used the
+original NGSIM `v_Vel` and `v_Acc` measurements.
+
+See [`docs/DATA.md`](docs/DATA.md) before combining NGSIM sites or changing units.
+
+## Tests
+
+```bash
+pytest
+ruff check .
+```
+
+The test suite checks class encoding, radius-graph construction, split gaps, tensor shapes, fusion
+weight normalization, and an end-to-end synthetic run.
+
+## Result-reporting rule
+
+Only files produced under `results/regenerated/` by a completed run may be described as regenerated
+results. Report the raw-data SHA-256 hash, configuration, seed, split policy, and checkpoint with
+every result. Do not copy the 99.90% accuracy or 1.00 F1 claim into a new report unless this aligned
+pipeline independently produces it on the intended held-out data.

v2x_risk-0.1.0/README.md

@@ -0,0 +1,177 @@
+# V2X Traffic Anomaly and Collision-Risk Model
+
+[![CI](https://github.com/benjaminquito/V2X/actions/workflows/ci.yml/badge.svg)](https://github.com/benjaminquito/V2X/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/v2x-risk.svg)](https://pypi.org/project/v2x-risk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+This repository is a reproducible implementation of the revised model associated with
+*Predicting Traffic Anomalies and Collision Risks in V2X Systems: A Deep Learning Approach
+Using LSTM and GNN*. It implements the later reviewer-response design:
+
+- a two-layer LSTM for 15-step vehicle histories;
+- a two-layer, multi-head Graph Attention Network (GAT) for per-frame vehicle interactions;
+- directed proximity edges between vehicles less than 20 m apart;
+- a trainable softmax attention module that fuses temporal and spatial representations; and
+- three-class prediction: Low (0), Medium (1), and High (2) risk.
+
+No trained weights or real-data results are claimed by this repository. The NGSIM data is not
+redistributed. Figures stated in the manuscript or later development chat are historical claims and
+must not be treated as results reproduced by this code.
+
+## Why this implementation differs from the uploaded manuscript
+
+The uploaded manuscript describes an earlier model in several places: 50-step, three-feature
+sequences; two GCN layers; continuous risk scores; and fixed 0.6/0.4 fusion. The later revision
+changed these to 15-step, four-feature inputs; GAT; three-class outputs; and learned attention
+fusion. This repository implements the later design requested for the reviewer response while
+preserving the original claims as historical metadata only. See
+[`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) for the complete reconciliation.
+
+The earlier chat evaluation paired LSTM samples and graphs by truncating both collections to the
+same length. That does not establish that the two inputs describe the same vehicle and frame. Here,
+each graph node is built only when that exact vehicle has a valid history ending at the graph's
+frame. Both branches therefore operate on an explicitly aligned sample.
+
+The later chat's 99.90% accuracy and 1.00 weighted-F1 claim is not a repository baseline: the shared
+evaluation snippet did not demonstrate trained fusion weights or key-based modality alignment. It
+is mentioned only to prevent accidental reuse as a regenerated result.
+
+## Repository layout
+
+```text
+configs/                 Full-data and smoke-test configurations
+data/                    Raw/processed placeholders (generated data is ignored)
+docs/                    Data, methodology, and reproducibility notes
+results/                 Historical claims and regenerated-output placeholder
+src/v2x_risk/            Preprocessing, model, training, and evaluation code
+tests/                   Unit and end-to-end smoke tests
+```
+
+## Installation
+
+Python 3.10 or newer is required.
+
+Install the published package:
+
+```bash
+python -m pip install v2x-risk
+```
+
+For repository development, create an isolated environment and install the editable package:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+To reproduce the exact dependency versions used for the repository smoke test, install
+`requirements-lock.txt` before the editable package:
+
+```bash
+python -m pip install -r requirements-lock.txt
+python -m pip install --no-deps -e .
+```
+
+PyTorch is the only deep-learning dependency. The GAT layer uses native PyTorch scatter operations,
+so no separately compiled graph library is required.
+
+## Quick execution check
+
+The smoke run creates a small synthetic, NGSIM-shaped dataset, preprocesses it, trains one epoch,
+evaluates all three branches, and writes a visual report:
+
+```bash
+python -m v2x_risk.smoke --config configs/smoke.yaml
+```
+
+Smoke metrics only verify that the pipeline executes. They are not research results and must not be
+compared with the paper.
+
+Open `results/regenerated/smoke/run_report.html` after the command completes to inspect the visual
+pipeline summary.
+
+## Reproduce with NGSIM
+
+1. Obtain an NGSIM trajectory CSV from the
+   [U.S. DOT NGSIM Open Data portal](https://data.transportation.gov/stories/s/Next-Generation-Simulation-NGSIM-Open-Data/i5zb-xe34/)
+   and place it at `data/raw/NGSIM.csv`.
+2. Review [`configs/default.yaml`](configs/default.yaml), especially the coordinate conversion and
+   risk-label assumptions.
+3. Run the complete pipeline:
+
+```bash
+python -m v2x_risk.preprocess --config configs/default.yaml
+python -m v2x_risk.train --config configs/default.yaml
+python -m v2x_risk.evaluate --config configs/default.yaml --split test
+```
+
+Or use:
+
+```bash
+./scripts/reproduce.sh configs/default.yaml
+```
+
+The loader detects CSV and Excel OOXML content from the file signature. This means an uploaded
+workbook can still be read if it was accidentally named `NGSIM.csv`, although using the correct
+`.xlsx` suffix is recommended.
+
+Generated files include:
+
+- `data/processed/ngsim_aligned_graph_windows.npz`: aligned graph/history samples;
+- `data/processed/scaler.json`: train-only min-max parameters;
+- `data/processed/manifest.json`: source hash, counts, split sizes, and preprocessing metadata;
+- `results/regenerated/best_model.pt`: best checkpoint by validation macro F1;
+- `results/regenerated/metrics.json`: training history and branch-level results;
+- `results/regenerated/test_metrics.json`: independently regenerated test metrics; and
+- `results/regenerated/test_predictions.csv`: per-frame predictions and learned fusion weights;
+- `results/regenerated/run_summary.txt`: a plain-language completion summary; and
+- `results/regenerated/run_report.html`: a visual completion and results dashboard.
+
+At the end of `scripts/reproduce.sh`, the terminal prints `V2X RUN COMPLETED SUCCESSFULLY` followed
+by the main dataset counts, held-out metrics, and output locations. Open `run_report.html` in a web
+browser to verify the completed run visually.
+
+The default configuration follows the paper's 70/15/15 proportions and five training epochs. The
+split is chronological and inserts a 14-frame gap at boundaries to reduce leakage from overlapping
+15-step windows. Min-max scaling is fit on the training split only.
+
+## Required CSV columns
+
+Core inputs are `Vehicle_ID`, `Frame_ID`, `Local_X`, and `Local_Y`. The preferred input also has
+`v_Vel` and `v_Acc`. When either kinematic field is absent, preprocessing derives it from
+longitudinal position and elapsed time using the explicit settings under `data.kinematics`.
+Existing kinematic columns are never replaced. If the CSV already contains `Risk_Class`, it is used
+after validation. Otherwise, `Time_Headway` and `Space_Headway` are also required and labels are
+generated from the explicit thresholds in the configuration. The manuscript did not state the
+numerical labeling thresholds, so the supplied values are transparent repository assumptions that
+researchers should review or replace.
+
+Combined files should include `Location`. Preprocessing keeps locations separate, segments reused
+vehicle IDs into contiguous frame runs, and keys graph snapshots by location and timestamp. This
+prevents observations from separate roads or recording sessions from entering the same trajectory
+or proximity graph.
+
+Derived speed and acceleration are a transparent compatibility fallback. Report their use and do
+not treat results based on derived kinematics as directly comparable to experiments that used the
+original NGSIM `v_Vel` and `v_Acc` measurements.
+
+See [`docs/DATA.md`](docs/DATA.md) before combining NGSIM sites or changing units.
+
+## Tests
+
+```bash
+pytest
+ruff check .
+```
+
+The test suite checks class encoding, radius-graph construction, split gaps, tensor shapes, fusion
+weight normalization, and an end-to-end synthetic run.
+
+## Result-reporting rule
+
+Only files produced under `results/regenerated/` by a completed run may be described as regenerated
+results. Report the raw-data SHA-256 hash, configuration, seed, split policy, and checkpoint with
+every result. Do not copy the 99.90% accuracy or 1.00 F1 claim into a new report unless this aligned
+pipeline independently produces it on the intended held-out data.

v2x_risk-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "v2x-risk"
+version = "0.1.0"
+description = "Reproducible LSTM-GAT model for V2X traffic anomaly and collision-risk classification"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "Benjamin Quito"}]
+license = "MIT"
+keywords = [
+  "v2x",
+  "traffic-anomaly-detection",
+  "collision-risk",
+  "lstm",
+  "graph-attention-network",
+  "reproducible-research",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Education",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "numpy>=1.26,<3",
+  "openpyxl>=3.1,<4",
+  "pandas>=2.1,<3",
+  "PyYAML>=6,<7",
+  "scikit-learn>=1.3,<2",
+  "torch>=2.2,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<9",
+  "ruff>=0.9,<1",
+]
+
+[project.scripts]
+v2x-preprocess = "v2x_risk.preprocess:main"
+v2x-train = "v2x_risk.train:main"
+v2x-evaluate = "v2x_risk.evaluate:main"
+v2x-report = "v2x_risk.report:main"
+v2x-smoke = "v2x_risk.smoke:main"
+
+[project.urls]
+Homepage = "https://github.com/benjaminquito/V2X"
+Repository = "https://github.com/benjaminquito/V2X"
+Paper = "https://doi.org/10.4236/ojsst.2026.163010"
+Issues = "https://github.com/benjaminquito/V2X/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

v2x_risk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

v2x_risk-0.1.0/src/v2x_risk/__init__.py

@@ -0,0 +1,3 @@
+"""Reproducible V2X spatiotemporal risk classification."""
+
+__version__ = "0.1.0"

v2x_risk-0.1.0/src/v2x_risk/config.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ConfigError(ValueError):
+    """Raised when a configuration is incomplete or internally inconsistent."""
+
+
+def load_config(path: str | Path) -> dict[str, Any]:
+    config_path = Path(path)
+    with config_path.open("r", encoding="utf-8") as handle:
+        config = yaml.safe_load(handle)
+    if not isinstance(config, dict):
+        raise ConfigError(f"Configuration must be a mapping: {config_path}")
+    validate_config(config)
+    return config
+
+
+def validate_config(config: dict[str, Any]) -> None:
+    for section in ("data", "model", "training"):
+        if section not in config:
+            raise ConfigError(f"Missing required configuration section: {section}")
+
+    data = config["data"]
+    model = config["model"]
+    split = data.get("split", {})
+    ratios = [float(split.get(name, -1)) for name in ("train", "validation", "test")]
+    if any(value <= 0 for value in ratios) or abs(sum(ratios) - 1.0) > 1e-9:
+        raise ConfigError("data.split train/validation/test values must be positive and sum to 1")
+    if int(data.get("sequence_length", 0)) < 2:
+        raise ConfigError("data.sequence_length must be at least 2")
+    if float(data.get("graph_radius_m", 0)) <= 0:
+        raise ConfigError("data.graph_radius_m must be positive")
+    if len(data.get("feature_columns", [])) != int(model.get("input_dim", -1)):
+        raise ConfigError("model.input_dim must match the number of data.feature_columns")
+    if int(model.get("num_classes", 0)) != 3:
+        raise ConfigError("This implementation requires exactly three risk classes")
+
+
+def with_overrides(config: dict[str, Any], overrides: dict[str, Any]) -> dict[str, Any]:
+    """Return a deep copy with recursively merged overrides."""
+
+    merged = deepcopy(config)
+
+    def merge(target: dict[str, Any], source: dict[str, Any]) -> None:
+        for key, value in source.items():
+            if isinstance(value, dict) and isinstance(target.get(key), dict):
+                merge(target[key], value)
+            else:
+                target[key] = value
+
+    merge(merged, overrides)
+    validate_config(merged)
+    return merged