Tagline: "Quantifying Driver Competency Through Inverse Crash Modeling"
SafeDriver-IQ transforms crash data into a continuous safety score that tells drivers in real-time how close they are to crash conditions and what specific actions would make them safer, with special focus on protecting vulnerable road users (VRUs).
A deep-dive multi-dataset investigation combining CRSS (417K crashes) and Waymo Open Motion Dataset to answer 8 core research questions:
- What factors contribute to vehicle crashes?
- Which features best predict crash probability?
- How to classify driver behavior from crash and good-driving data?
- What data is most critical for VRU/pedestrian/cyclist predictions?
- What patterns can improve crash prevention model training?
- What historical crash trends are present across 2016–2023?
- What environmental conditions uniquely elevate crash risk?
- How to systematically perform root cause analysis?
Key addition — Contextual Feature Synthesis: CRSS captures crash outcomes but is silent on contextual preconditions. A new ContextualFeatureGenerator synthesises 16 research-calibrated risk dimensions (see Section 6 in notebook 04) drawn from NHTSA, FHWA-HSM, AAA Foundation, and IIHS sources, enabling richer training and what-if simulation.
Now features an autonomous decision-making system that actively prevents crashes through:
- Real-time risk assessment and autonomous interventions
- Continuous learning from driving experiences
- Multi-modal driver notifications (visual, audio, haptic)
- Transparent, explainable AI reasoning
- Learn more → | View plan →
- 7,500+ pedestrian deaths/year in the USA (40-year high)
- 1,000+ cyclist deaths/year
- Traditional systems are reactive (emergency braking) not proactive
- No system tells drivers "you're driving safely" or "improve these specific behaviors"
Instead of predicting crashes, we model the distance from crash - quantifying how "safe" a driving scenario is by measuring its statistical distance from crash-producing conditions.
This repository serves as the reference implementation and experimental foundation for the following research:
Paper Title: Real-Time Driver Safety Scoring Through Inverse Crash Probability Modeling
This research was developed in collaboration with the American Center for Mobility (ACM), a federally designated proving ground for connected and automated vehicle technology. ACM is featuring the work through its publication channels, reflecting growing industry interest in proactive safety intelligence. The paper was presented at the 2026 IEEE International Conference on Electro/Information Technology (EIT) in La Crosse, Wisconsin, and at the IEEE CTSoc Technical Talks Webinar, and is forthcoming in IEEE Xplore.
Read the paper: https://arxiv.org/abs/2603.14841
- 87% of crashes involve 2+ co-occurring risk factors
- 4.5x non-linear risk compounding over baseline
- Model performance: AP = 0.891, precision = 0.941, recall = 0.480
- SHAP-ablation correlation: r = 0.94
- Estimated 22.7% crash reduction with adoption
Phase 2 of this research, an agentic multi-model architecture for proactive safety intervention in autonomous transportation, has been accepted for presentation at the American Society of Civil Engineers (ASCE) 2027 conference. Validation artifacts are in the asce2027/ directory.
- 1,296 scenarios validated across nuScenes (10), Argoverse 2 (1,000), and Waymo WOMD (286)
- Mean safety score: 68.0/100
- 77.6% of scenarios classified as advisory
- 3.8% near-miss rate
- ~11% escalated to intervention/emergency
- Cross-dataset calibration without retraining
The SafeDriver-IQ system was designed, implemented, and validated first, and the insights, models, and experimental findings from this project directly led to the research publication.
In other words:
- ✅ This repository = working system + experiments
- ✅ The paper = formalization of methodology, results, and contributions
The research paper builds on this project and formally introduces:
- Inverse Crash Probability Modeling → foundation of the safety score
- Continuous Driver Safety Scoring (0–100) instead of binary crash prediction
- Distance-from-crash formulation using learned decision boundaries
- Integration of crash data (CRSS) + behavioral data (Waymo)
- Explainable safety feedback mechanisms for real-time systems
| Research Concept | Implementation in This Repo |
|---|---|
| Inverse crash modeling | src/safety_score.py |
| Feature engineering (120+) | src/feature_engineering.py |
| Contextual risk synthesis | src/contextual_feature_generator.py |
| Model training (RF/XGBoost) | src/models.py |
| Behavioral insights | src/driver_behavior_classifier.py |
| Explainability (SHAP) | notebooks/03_shap_analysis.ipynb |
| Real-time scoring system | src/realtime_calculator.py |
- Samaresh Kumar Singh
- Joyjit Roy
@article{safedriveriq,
author = {Roy, Joyjit and Singh, Samaresh Kumar and Das, Sushanta},
title = {Real-Time Driver Safety Scoring Through Inverse Crash Probability Modeling},
journal = {arXiv preprint arXiv:2603.14841},
year = {2026},
doi = {10.48550/arXiv.2603.14841},
url = {https://arxiv.org/abs/2603.14841},
note = {Submitted to IEEE EIT 2026, University of Wisconsin-La Crosse}
}Visual one-page summaries for each phase of the work.
Phase 1 introduces inverse crash probability modeling: a continuous 0–100 safety score derived from NHTSA CRSS crash data and Waymo driving behavior, demonstrating that 87% of crashes involve two or more co-occurring risk factors.
Phase 2 extends the foundation into an agentic multi-model architecture with environmental, trajectory, and VRU risk models fused by a DQN agent. PRISM was validated across nuScenes, Argoverse 2, and Waymo WOMD, achieving a mean safety score of 68/100 with 77.6% of scenarios classified as advisory.
| Traditional Approach | SafeDriver-IQ (Novel) |
|---|---|
| Binary crash prediction | Continuous safety score (0-100) |
| "30% crash risk" | "Safety score: 72/100 → Improve to 85+" |
| Reactive warnings | Proactive guidance with specific actions |
| General risk factors | VRU-specific safety models |
| CRSS-only training | CRSS + Waymo + synthesised contextual features |
- Inverse Safety Score Formulation - Continuous safety metric (0-100) instead of binary crash prediction
- Good Driver Profile Extraction - First empirical characterisation of safe driving from crash data + Waymo behavioural data
- VRU-Specific Safety Modeling - Dedicated models for pedestrian, cyclist, and work zone encounters
- Contextual Feature Synthesis - 16 research-calibrated risk dimensions generated from
ContextualFeatureGeneratorto fill CRSS data gaps - Multi-Method Feature Consensus - Random Forest, XGBoost, Permutation Importance, and SHAP combined into a single consensus ranking
- Real-Time Integration Architecture - Practical system design for in-vehicle deployment
CRSS (Crash Report Sampling System) — NHTSA national crash database
- 417,335 crash records (2016–2023, 8 years)
- 38,462 VRU crashes (pedestrians + cyclists)
- 1,032,571 person records
- Tables:
ACCIDENT,VEHICLE,PERSON,PBTYPE,FACTOR,DISTRACT,DRIMPAIR,WEATHER, and more
Waymo Open Motion Dataset (WOMD v1.2) — Real-world autonomous driving scenarios
- 6 splits: training (1,000 shards), training_20s, validation, validation_interactive, testing, testing_interactive
- 91 timesteps per scenario at 10 Hz (1 s context + 8 s future horizon)
- Captures: agent trajectories (vehicles, pedestrians, cyclists), road graph, traffic signals, speed limits
- Used for: Good driver profiling, near-miss detection, behavioral pattern extraction
- Stored via Git LFS in
waymo/motion_dataset/
| Paper | Dataset | Size | Type | Purpose |
|---|---|---|---|---|
| Phase 1 (EIT2026) | NHTSA CRSS 2016–2023 | 417,335 crash records | Historical crash outcomes | Train inverse crash probability model |
| Phase 2 (ASCE2027) | nuScenes mini | 10 scenarios | Autonomous driving scenes | Validate PRISM across diverse urban environments |
| Phase 2 (ASCE2027) | Argoverse 2 | 1,000 scenarios | Autonomous driving scenes | Validate PRISM across diverse urban environments |
| Phase 2 (ASCE2027) | Waymo WOMD | 286 scenarios | Autonomous driving scenes | Validate PRISM across diverse urban environments |
SafeDriver-IQ is the first-generation inverse crash modeling system. It combines national crash statistics (CRSS 2016–2023) with real-world behavioral data (Waymo WOMD) to train a binary crash classifier, then inverts its predicted probability of not crashing into a continuous 0–100 safety score. The pipeline includes data ingestion, feature engineering (120+ variables), crash pattern analysis, model training, and a real-time scoring interface that maps scores to five risk levels: Critical, High, Medium, Low, and Excellent.
PRISM (Proactive Risk Intelligence and Safety Management) extends SafeDriver-IQ into a four-layer agentic architecture:
- Layer 1 — Data Ingestion and Normalization: Converts heterogeneous AV datasets (nuScenes, Argoverse 2, Waymo WOMD) into a unified
DrivingScenerepresentation. - Layer 2 — Parallel Risk Models: Runs three independent models concurrently:
- Environmental Risk: Reuses the frozen SafeDriver-IQ random forest as a context estimator.
- Trajectory Kinematic: Evaluates speed, acceleration, and yaw-rate exceedances.
- VRU Interaction: Uses a Social Force Model + LSTM to predict ego-VRU conflicts.
- Layer 3 — Agentic Reasoning: Fuses risks via a DQN reinforcement learning agent, selects one of four intervention tiers (silent, advisory, intervention, emergency), and provides SHAP-based explanations with short-term and long-term memory.
- Layer 4 — Applications: Supports ADAS integration, fleet risk management, and infrastructure planning without dataset-specific retraining.
├── asce2027/ # ASCE2027 PRISM validation artifacts
│ ├── scripts/ # Analysis scripts (AV2, Waymo, nuScenes)
│ ├── data/ # Validation results (CSV/JSON)
│ └── figures/ # Paper figures
├── docs/
│ ├── images/ # Architecture diagrams (SafeDriver-IQ + PRISM)
│ └── flyers/ # Research flyers (Phase 1 + Phase 2)
├── CRSS_Data/ # National crash database (2016-2023)
│ ├── 2016/ # Year-wise crash data
│ ├── 2017/
│ └── ...
├── waymo/ # Waymo Open Motion Dataset (Git LFS)
│ └── motion_dataset/
│ ├── datasets_scenario/ # Scenario-format TFRecords
│ └── tf_example_datasets/# TF Example-format TFRecords
├── data/
│ ├── raw/ # Downloaded CRSS files
│ ├── processed/ # Cleaned datasets
│ └── external/ # VMT exposure data
├── notebooks/
│ ├── 01_data_exploration.ipynb
│ ├── 02_train_inverse_model.ipynb
│ ├── 03_shap_analysis.ipynb
│ └── 04_crash_factor_investigation.ipynb # 8-investigation deep-dive
├── src/
│ ├── data_loader.py # CRSS data loading
│ ├── preprocessing.py # Data cleaning
│ ├── feature_engineering.py # 120+ features
│ ├── models.py # Model training/saving
│ ├── safety_score.py # Score computation
│ ├── realtime_calculator.py # Live safety scoring
│ ├── scenario_simulator.py # What-if analysis
│ ├── contextual_feature_generator.py # synthesised contextual features
│ ├── crash_insights.py # crash investigation utilities
│ ├── driver_behavior_classifier.py # behavior clustering
│ ├── feature_importance.py # multi-method feature consensus
│ ├── waymo_data_loader.py # Waymo TFRecord loader
│ └── visualization.py # Plotting utilities
├── tests/
│ ├── test_data_loader.py
│ ├── test_feature_engineering.py
│ ├── test_models.py
│ ├── test_preprocessing.py
│ └── test_realtime_calculator.py
├── results/
│ ├── figures/ # Visualizations
│ ├── tables/ # Analysis results
│ ├── crash_investigation_feature_importance.csv
│ ├── crash_investigation_behavior_clusters.csv
│ ├── crash_investigation_rf_model.pkl
│ └── models/ # Trained models
└── app/
└── streamlit_app.py # Interactive dashboard
- Python 3.12+ installed
- CRSS data downloaded to
CRSS_Data/directory - Terminal/Command line access
# Navigate to project directory
cd safedriver-iq
# Create virtual environment
python -m venv venv
# Activate (Windows)
venv\Scripts\activate
# Activate (Linux/Mac)
# source venv/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
# Verify data loading (shows 417K+ crashes)
python test_data_loader.py
# Run COMPLETE demonstration (trains model + all features)
python run_complete_demo.py --quick
# Or run quick data demo
python demo_quick.py
# Or explore interactively
jupyter notebook notebooks/01_data_exploration.ipynb
# Launch interactive dashboard (after training model)
streamlit run app/streamlit_app.py✓ 417,335 total crashes loaded
✓ 38,462 VRU crashes identified
✓ Data from 2016-2023 successfully loaded
cd /path/to/your/workspace
git clone https://github.com/ssam18/safedriver-iq.git
cd safedriver-iqpython -m venv venv
# Activate (Windows)
venv\Scripts\activate
# Activate (Linux/Mac)
# source venv/bin/activatepip install --upgrade pip
pip install -r requirements.txtThis installs:
- Data Processing: pandas, numpy, pyarrow
- Machine Learning: scikit-learn, xgboost, lightgbm
- Visualization: matplotlib, seaborn, plotly
- Model Interpretation: shap
- Interactive: jupyter, streamlit
If data is still zipped:
cd CRSS_Data
for year in 2016 2017 2018 2019 2020 2021 2022 2023; do
unzip -o ${year}/CRSS${year}CSV.zip -d ${year}/
done
cd ..python test_data_loader.pyShould show successful loading of 417K+ crash records.
# Activate virtual environment (REQUIRED before running tests)
venv\Scripts\activate # Windows
# source venv/bin/activate # Linux/Mac
# Install test dependencies
pip install -r requirements-test.txt
# Run all tests with basic output
pytest
# Run all tests with verbose output and short traceback (recommended)
pytest tests/ -v --tb=short
# Run all tests with verbose output and one-line traceback (most concise)
pytest tests/ -v --tb=line
# Run tests without coverage calculation (faster)
pytest tests/ -v --tb=short --no-cov
# Run tests in quiet mode with one-line traceback (minimal output)
pytest tests/ -q --tb=line
# Run with coverage report (detailed analysis)
pytest --cov=src --cov-report=html
# View coverage report
open htmlcov/index.html # On Mac
# xdg-open htmlcov/index.html # On LinuxTest Output Options:
-v= verbose mode (shows each test name)-q= quiet mode (minimal output, just pass/fail counts)--tb=short= shorter traceback on failures (recommended for debugging)--tb=line= one-line traceback (most concise, good for CI/CD)--no-cov= skip coverage calculation (faster test runs)
Test Realtime Calculator (verifies condition changes affect scores):
# Run realtime calculator tests to verify model sensitivity
pytest tests/test_realtime_calculator.py -v --tb=short -sExpected: 65 tests total (53 pass + 12 realtime tests with 5 expected failures due to known model limitations)
- Load CRSS datasets (2016-2023)
- Load Waymo Open Motion Dataset (TFRecord parsing via
WaymoDataLoader) - Filter VRU crashes
- Feature engineering (120+ variables)
- Create exposure-weighted baseline
- Investigation 1 — Primary crash factors (temporal, environmental, VRU interactions)
- Investigation 2 — Feature selection via 4-method consensus (RF, XGBoost, Permutation, SHAP)
- Investigation 3 — Driver behavior classification (CRSS crash clusters + Waymo good-driver profiling)
- Investigation 4 — Critical data for crash/VRU prediction
- Investigation 5 — Crash prevention patterns and high-risk combinations
- Investigation 6 — Historical year-over-year trends (2016–2023)
- Investigation 7 — Environmental uniqueness analysis (rare high-severity conditions)
- Investigation 8 — Root cause analysis causal chain framework
- Section 6 — Contextual feature synthesis with
ContextualFeatureGenerator(16 research-calibrated risk factors)
- Clustering → Identify crash archetypes
- Association Rules → Find co-occurring risk factors
- Feature Importance → Rank risk contributors
- Train crash classifier (Random Forest / XGBoost, n_estimators=200)
- Extract decision boundaries
- Compute "distance from crash boundary" = Safety Score
- Profile "good driver" = maximises safety score (using Waymo behavioural data)
- Cross-validation metrics
- SHAP analysis for interpretability
- Dashboard for results presentation
The asce2027/ folder contains the reproducibility bundle for the ASCE2027 conference paper:
- Scripts:
compute_stats.py,check_tier_mapping.py,find_thresholds.py,sensitivity_final.py,av2_and_shap_outputs.py,fig2_score_distribution_final.py,generate_paper_outputs.py,waymo_validation.py,waymo_validation_run.py - Data:
av2_validation_1000.csv,av2_validation_by_city.csv,av2_scenario_summary.csv,scenario_summary.csv,waymo_validation_results.json,waymo_scenario_summary.csv,fig2_score_distribution_data.csv - Figures: Score distribution, tier distribution, ablation, latency, near-miss, SHAP, and VRU proximity plots
These artifacts support the paper's results: mean safety score 68/100, 77.6% advisory, 3.8% near-miss rate, and ~11% escalation to intervention/emergency.
1. Comprehensive Crash Factor Investigation (Notebook 04)
- 8 structured investigations using CRSS + Waymo datasets
- Multi-method feature importance consensus (RF + XGBoost + Permutation + SHAP)
- Driver behavior classification linking crash patterns to Waymo good-driving profiles
- Root cause analysis causal chain framework
- Results saved:
results/crash_investigation_feature_importance.csv,results/crash_investigation_rf_model.pkl
2. Contextual Feature Generator (src/contextual_feature_generator.py)
- Synthesises 16 research-backed risk dimensions missing from CRSS
- Top risk factors by weight:
| Weight | Factor | Source |
|---|---|---|
| 0.28 | DUI risk — late night + weekend + bar density | NHTSA |
| 0.24 | Black ice — temperature < 35°F + precipitation | NHTSA |
| 0.20 | Active work zone with workers on roadway | NHTSA |
| 0.18 | Rush hour — dense traffic + tailgating | FHWA-HSM |
| 0.16 | Aggressive surrounding drivers | AAA Foundation |
| 0.15 | Narrow lane (<11 ft) on horizontal curve | FHWA-HSM |
| 0.14 | Driver fatigue — 2–6 AM circadian low | NHTSA |
| 0.13 | Distracted driving (phone / in-cabin) | NHTSA/IIHS |
- Enables what-if simulation across any risk factor combination
3. Waymo Data Loader (src/waymo_data_loader.py)
- Parses Waymo Open Motion Dataset TFRecord format (v1.2)
- Extracts per-agent state (position, velocity, heading), road graph, traffic signals
- Computes crash indicators: TTC, min inter-agent distance, near-miss flags
- Supports all 6 dataset splits (training, validation, testing + interactive variants)
4. Model Training
- Complete inverse safety model training pipeline
- Three model types: Random Forest (n_estimators=200, max_depth=10), XGBoost (n_estimators=200, max_depth=6, lr=0.1), Gradient Boosting
- Automated best model selection based on performance
- Model saving/loading with feature persistence
- Automated best model selection based on performance
- Model saving/loading with feature persistence
5. Safety Score Calculation
- Continuous scores (0-100) instead of binary prediction
- Five risk levels: Critical, High, Medium, Low, Excellent
- Confidence intervals for each prediction
- Distance from crash boundary computation
6. Real-Time Calculator
- Instant safety score for any driving scenario
- Specific, actionable improvement recommendations
- Scenario comparison capabilities
- Batch analysis for multiple scenarios
7. Interactive Dashboard
- Web-based Streamlit application
- Real-time safety score calculator interface
- Scenario comparison tools
- Improvement suggestion engine
- Batch analysis with visualizations
- About page with methodology explanation
8. Scenario Simulator
- Factorial scenario generation
- Monte Carlo random sampling
- Time-series trip simulation
- Risk pattern templates (high-risk, low-risk, night, weather, speed, VRU)
- Comprehensive test suite generator
9. SHAP Interpretability
- Global feature importance analysis
- Individual prediction explanations
- Feature interaction detection
- Waterfall plots for high/medium/low safety scenarios
- Decision plots comparing multiple scenarios
- Comprehensive interpretation report
python test_data_loader.pyShows: 417K crashes, 38K VRU crashes, 8 years of national data
python demo_quick.pyShows:
- Data loading statistics
- VRU crash trends over time
- Temporal patterns (peak times, seasonal)
- Feature engineering capabilities
- Novel approach explanation
- Expected impact projections
jupyter notebook notebooks/01_data_exploration.ipynbIncludes:
- Comprehensive data quality analysis
- VRU crash distribution and trends
- Temporal pattern visualizations
- Environmental factor analysis
- Injury severity patterns
jupyter notebook notebooks/04_crash_factor_investigation.ipynbIncludes:
- 8 structured investigations with CRSS + Waymo data
- Multi-method feature importance consensus
- Driver behavior clustering
- Contextual feature synthesis (Section 6)
- What-if sensitivity analysis
- Root cause causal chain framework
Crash Patterns:
- Peak crash times: Evening rush hour (5-7 PM)
- High-risk periods: Weekend nights
- VRU crashes concentrated in urban areas
- Dark/poor lighting significantly increases risk
VRU Statistics (2023):
- 2,907 pedestrians involved in crashes
- 2,026 bicyclists involved in crashes
- Fatal injury rate: ~5-7% for VRUs (vs. ~2% vehicle occupants)
Feature Engineering:
- 120+ features created from raw data
- Temporal, environmental, location, VRU-specific categories
- Interaction features for complex scenarios
Key notebooks for demonstrations:
- 01_data_exploration.ipynb — Data quality, VRU trends, temporal patterns
- 02_train_inverse_model.ipynb — Full inverse safety model training
- 03_shap_analysis.ipynb — SHAP interpretability deep-dive
- 04_crash_factor_investigation.ipynb — 8-investigation crash factor analysis with Waymo integration
With 20% adoption, SafeDriver-IQ could prevent:
- 1,500 pedestrian deaths/year (20% reduction)
- 200 cyclist deaths/year (20% reduction)
- 170 work zone deaths/year (20% reduction)
- 30,000 VRU injuries/year (20% reduction)
Total impact: 1,870+ lives saved annually
- README.md — Project overview & setup (this file)
- PROJECT_SETUP_SUMMARY.md — Detailed setup reference
- notebooks/04_crash_factor_investigation.ipynb — Comprehensive crash factor investigation
The current trained model does not respond meaningfully to changes in road condition, VRU presence, or speed relative to limit. This is a fundamental limitation of training on crash-only data: the model never learned what "truly safe" driving looks like. It remains useful for weather, lighting, and temporal risk patterns. For test evidence, run pytest tests/test_realtime_calculator.py -v --tb=short.
The PRISM architecture (Phase 2) addresses this by adding separate trajectory-kinematic and VRU-interaction models, plus a DQN fusion agent. Validation results are in the asce2027/ directory.
This is a research project. For questions or collaboration:
- Review notebooks/04_crash_factor_investigation.ipynb for the latest investigation results
- Run
demo_quick.pyto see current capabilities - Check issues for planned features
[To be determined - typically MIT or Apache 2.0 for research code]
- American Center for Mobility (ACM) for collaboration and domain guidance as a federally designated CAV proving ground
- NHTSA for CRSS data availability
- SafeDriver-IQ novel methodology development
- Python scientific computing community (pandas, scikit-learn, etc.)



