🛡️ SafePath - Intelligent Street-Level Safety Prediction & Route Planning

SafePath is an AI-powered urban navigation system that predicts street-level crime risk and generates optimized safe routes for pedestrians. By combining machine learning with geospatial data analysis, SafePath helps users make informed decisions about their routes through city streets.

🎯 Features

• 🧠 ML-Powered Risk Prediction: XGBoost classifier achieving 0.726 ROC-AUC for street segment risk assessment
• 🗺️ Multi-Route Generation: Provides "Fastest", "Balanced", and "Safest" route alternatives
• 📊 Heterogeneous Data Integration: Combines NYC Crime Data, OpenStreetMap, and POI datasets
• ⚡ Fast API: RESTful API built with FastAPI for real-time route computation (<200ms response)
• 📱 Mobile Ready: Android application with interactive map visualization
• 🔄 A Pathfinding*: Modified A* algorithm with composite safety-distance cost function

📈 Performance Metrics

Model	Accuracy	F1-Macro	ROC-AUC	Training Time
XGBoost (Primary)	0.700	0.636	0.726	0.40s
Random Forest	0.688	0.623	0.703	2.07s
Decision Tree	0.704	0.633	0.681	0.09s
Logistic Regression	0.691	0.534	0.693	0.04s

🏗️ Architecture

┌─────────────────┐
│  Android App    │
│  (Mobile UI)    │
└────────┬────────┘
         │ HTTP Requests
         ▼
┌─────────────────────────────────┐
│     FastAPI Server              │
│  ┌───────────┐  ┌────────────┐  │
│  │  XGBoost  │  │  NetworkX  │  │
│  │   Model   │  │   Graph    │  │
│  └───────────┘  └────────────┘  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│        Data Layer               │
│  - Crime Data (NYC Open Data)   │
│  - OSM Street Network           │
│  - POI Features (Subway, etc)   │
└─────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Python 3.12+
• pip or conda package manager
• (Optional) Android Studio for mobile app

Installation

1. Clone the repository

git clone https://github.com/Muhammad-Waleed381/SafePath.git
cd SafePath

2. Create virtual environment

python -m venv safepath
source safepath/bin/activate  # On Windows: safepath\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

Data Setup

Note: The data/ folder is excluded from Git due to size constraints. You'll need to download and prepare the data locally.

1. Download NYC Crime Data

python src/data/ingest_crime.py

2. Extract OSM Street Network

python src/data/ingest_osm.py

3. Fetch POI Data

python src/data/ingest_pois.py

4. Process and Enrich Data

python src/data/map_crimes.py
python src/data/feature_engineering_poi.py
python src/data/finalize_dataset.py

Model Training

# Train and evaluate multiple models
python src/analysis/final_model_comparison.py

# Train the refined XGBoost model
python src/models/train_refined_model.py

The trained model will be saved to models/xgboost_refined.pkl.

Running the API

# Start the FastAPI server
bash run_app.sh

# The API will be available at http://0.0.0.0:8000
# API Documentation: http://0.0.0.0:8000/docs

📡 API Usage

Health Check

curl http://localhost:8000/

Single Route (with safety weight)

curl -X POST http://localhost:8000/route \
  -H "Content-Type: application/json" \
  -d '{
    "origin": [40.7580, -73.9855],
    "destination": [40.7489, -73.9680],
    "alpha": 10.0
  }'

Multiple Route Alternatives

curl -X POST http://localhost:8000/routes \
  -H "Content-Type: application/json" \
  -d '{
    "origin": [40.7580, -73.9855],
    "destination": [40.7489, -73.9680]
  }'

Response includes:

• 🚀 Fastest route (low safety weight)
• ⚖️ Balanced route (medium safety weight)
• 🛡️ Safest route (high safety weight)

🔬 Technical Details

Feature Engineering (16 Features)

Topological Features:

• Edge length, lanes, speed limit, one-way indicator
• Betweenness centrality

POI-Based Features (Distance + Density):

• Subway stations
• Schools
• Nightlife venues (bars/clubs)
• Police stations

Synthetic Features:

• Street light count (estimated)
• Traffic volume (estimated)
• Temporal lag crime count

Cost Function

Routes are optimized using a composite cost function:

Cost(edge) = length × (1 + α × risk_score)

where:

• length: Physical edge length in meters
• risk_score: XGBoost predicted probability [0, 1]
• α: User-defined safety weight (higher = prioritize safety)

Algorithms

• Risk Prediction: XGBoost Gradient Boosting Classifier
• Routing: Dijkstra's shortest path with composite weights
• Multi-Route: Yen's K-Shortest Paths algorithm

📂 Project Structure

SafePath/
├── data/
│   ├── raw/              # Raw downloaded data (gitignored)
│   └── processed/        # Processed features and graphs (gitignored)
├── models/
│   └── xgboost_refined.pkl
├── src/
│   ├── data/            # Data ingestion and processing scripts
│   ├── models/          # Model training scripts
│   ├── analysis/        # Evaluation and comparison scripts
│   └── api/             # FastAPI application
├── reports/             # Generated figures and CSVs
├── notebooks/           # Jupyter notebooks for exploration
├── requirements.txt
└── run_app.sh          # API startup script

🗺️ Data Sources

• NYC Crime Data: NYC Open Data - NYPD Complaint Data Historic
• Street Networks: OpenStreetMap via OSMnx
• POI Data: OpenStreetMap Overpass API

📱 Mobile Application

The Android application provides:

• Interactive map interface
• Route visualization with risk overlay
• Origin/destination selection
• Multi-route comparison UI
• Offline route caching

Building the Android App

cd src/app
# Open in Android Studio
# Build > Make Project
# Run on emulator or device

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NYC Open Data for providing comprehensive crime datasets
• OpenStreetMap contributors for detailed street network data
• OSMnx library by Geoff Boeing for geospatial network analysis
• XGBoost team for the gradient boosting framework

📧 Contact

Muhammad Waleed - Student ID: 455706

Project Link: https://github.com/Muhammad-Waleed381/SafePath

---

⚠️ Disclaimer: SafePath provides route suggestions based on historical crime data and should be used as a supplementary tool. Always remain aware of your surroundings and follow local safety guidelines.