An AI-powered predictive crime analysis tool that leverages Python, Folium, Gradio, and the Ministral AI model (via Ollama) to analyze historical crime data and predict future crime trends. Features an enterprise-grade dark-themed web interface for uploading data, running predictive analysis, and visualizing results on an interactive map.
- Professional Dark Theme - Modern, enterprise-grade UI with carefully designed aesthetics
- Drag-and-Drop Upload - Easy CSV/Excel file import with automatic column detection
- Smart Column Mapping - Auto-detects latitude, longitude, crime type, date, and time columns
- Real-time Progress - Visual progress indicators during analysis
- Statistical Preprocessing - Computes crime distribution, geographic hotspots, and patterns
- Intelligent Predictions - Uses Ministral-3:3b model for context-aware crime prediction
- Prophet Forecasting - Time-series prediction of future crime counts with confidence intervals
- DBSCAN Hotspot Detection - Identifies natural crime clusters using density-based spatial clustering
- Seasonal Intelligence - AI considers holiday effects, payday patterns, and seasonal trends
- Crime-Type Intelligence - AI learns when specific crime types typically occur for targeted predictions
- Validation - Ensures predictions are geographically plausible
- Time-of-Day Patterns - Identifies peak crime hours (morning, afternoon, evening, night)
- Day-of-Week Analysis - Detects which days have the highest crime activity
- Trend Detection - Determines if crime is rising, falling, or stable over time
- Per-Hotspot Timing - Each hotspot shows its own peak hours and days
- Crime-Specific Patterns - Analyzes when each crime type typically occurs (e.g., thefts peak at 2 PM on Fridays)
- Exponential Decay - Recent crimes weighted more heavily than older data (30-day half-life)
- Emerging Hotspots - Automatically flags areas with recent activity spikes
- Recency Score - Visual indicator showing how recent your data is (0-100 scale)
- Smart Ranking - Hotspots ranked by recency-weighted activity, not just raw counts
- Trend Analysis - Each hotspot classified as Growing, Shrinking, Stable, or New
- Historical Comparison - Compares first-half vs second-half incident counts to detect momentum
- Visual Indicators - Clear trend labels (📈 Growing, 📉 Shrinking, ➡️ Stable, 🆕 New)
- LLM Context - Trend data fed to AI for smarter, momentum-aware predictions
- Monthly Trends - Identifies which months have the highest crime activity
- Seasonal Breakdown - Compares crime rates across Winter, Spring, Summer, and Fall
- Holiday Effect Detection - Analyzes if crime increases or decreases near major US holidays
- Payday Pattern Analysis - Detects if crimes spike around 1st/15th of month (payday effect)
- Year-over-Year Trends - Tracks if crime is increasing or decreasing over time
- Density-Based Hotspots - Uses DBSCAN algorithm to detect natural crime clusters
- Irregular Shapes - Identifies hotspots of any shape, not just grid squares
- Cluster Radius - Each hotspot reports its geographic extent in kilometers
- Noise Filtering - Automatically excludes isolated incidents as noise
- Haversine Distance - Uses accurate geographic distance calculations
- Time-Series Prediction - Uses Facebook Prophet to forecast future crime counts
- 14-Day Forecast - Predicts daily crime counts for the next two weeks
- Confidence Intervals - Each prediction includes upper/lower bounds (80% confidence)
- Peak Day Detection - Identifies which future days will have the highest crime
- Trend Analysis - Compares forecast to historical average (increasing/decreasing/stable)
- Per-Crime-Type Forecast - Breaks down predictions by crime category
- Holiday Awareness - Prophet automatically adjusts for US holidays
- Visual Chart - Interactive bar chart showing daily forecast
- Embedded Map View - Interactive Folium map displayed directly in the UI
- Heatmap Layer - Crime density visualization with gradient coloring
- Risk-Coded Markers - Predictions colored by likelihood (red=high, orange=medium, green=low)
- Marker Clustering - Groups nearby markers for better performance
- Legend - Clear identification of actual vs. predicted crimes
- Statistics Tab - Crime distribution, temporal patterns, seasonal patterns, forecast chart, and recency indicators
- Predictions Tab - Scrollable table with location, type, risk levels, and full analysis
- Full Report Tab - Complete analysis summary with temporal, seasonal, forecast insights, and AI output
- Export Options - Download interactive map (HTML) and full report (TXT)
- Python 3.8 or higher
- Ollama installed and running
git clone https://github.com/ericmaddox/crime-analyst-ai.git
cd crime-analyst-aipython3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activatepip install -r requirements.txtOr install as a package:
pip install -e .-
Download and Install Ollama from ollama.ai
-
Pull the AI Model:
ollama pull ministral-3:3b
-
Verify Installation:
ollama list
# Activate virtual environment
source venv/bin/activate
# Launch the application (opens browser automatically)
python run.pyThe application will automatically open in your default browser at http://localhost:7860.
python run.pyOptions:
--port 8080- Use a different port--no-browser- Don't auto-open browser--cli- Run in command-line mode
python run.py --cliThis expects data/sample_crime_data.csv to exist.
Your crime data file should include these columns:
| Column | Required | Description |
|---|---|---|
| Latitude | Yes | Geographic latitude (decimal degrees) |
| Longitude | Yes | Geographic longitude (decimal degrees) |
| CrimeType | Yes | Category of crime (e.g., Theft, Assault) |
| Date | Recommended | Date of incident (enables temporal analysis & recency weighting) |
| Time | Recommended | Time of incident (enables time-of-day pattern detection) |
| Address | No | Street address |
Tip: Including Date and Time columns significantly improves prediction accuracy. The system uses temporal patterns (peak hours, day-of-week trends) and recency weighting (recent crimes weighted higher) to generate smarter predictions.
A sample data file is included at data/sample_crime_data.csv.
crime-analyst-ai/
├── .github/ # GitHub templates
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ └── feature_request.md
│ └── PULL_REQUEST_TEMPLATE.md
├── data/ # Sample and user data
│ └── sample_crime_data.csv
├── media/ # Project images
│ ├── crime_analyst_ai.JPEG
│ └── crime_analyst_ai_v2.png
├── output/ # Generated files (gitignored)
├── src/
│ └── crime_analyst_ai/ # Main package
│ ├── __init__.py
│ ├── app.py # Gradio web interface
│ └── core.py # Analysis engine
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── pyproject.toml # Package configuration
├── README.md
├── requirements.txt
└── run.py # Application launcher
Edit src/crime_analyst_ai/core.py:
OLLAMA_MODEL = "your-preferred-model"- Prophet Forecasting: Modify
periods(default: 14 days) incompute_crime_forecast() - DBSCAN Clustering: Modify
eps_km(default: 0.5km) andmin_samples(default: 3) indetect_hotspots() - Seasonal Patterns: Adjust
compute_seasonal_patterns()for holiday proximity and payday analysis - Trend Detection: Customize hotspot trend thresholds in
detect_hotspots()(growth/shrinkage sensitivity) - Crime-Type Patterns: Adjust
compute_crime_type_patterns()for per-type temporal analysis - LLM Prompt: Customize
build_analysis_prompt()incore.py - Map Styling: Edit
create_crime_map()incore.py - Recency Half-Life: Change the
half_life_daysparameter incompute_recency_weights()(default: 30 days)
The system uses exponential decay to weight recent crimes more heavily:
weight = 0.5^(days_ago / half_life_days)
| Days Ago | Weight (30-day half-life) |
|---|---|
| 0 (today) | 1.00 |
| 30 days | 0.50 |
| 60 days | 0.25 |
| 90 days | 0.125 |
Adjust half_life_days in compute_recency_weights() to change decay rate.
The system uses DBSCAN (Density-Based Spatial Clustering of Applications with Noise) for hotspot detection:
| Parameter | Default | Description |
|---|---|---|
eps_km |
0.5 | Cluster radius in kilometers |
min_samples |
3 | Minimum incidents to form a cluster |
Adjust these in detect_hotspots() to change sensitivity:
- Smaller
eps_km: More, smaller clusters (finer detail) - Larger
eps_km: Fewer, larger clusters (broader areas) - Higher
min_samples: Only significant clusters (fewer false positives)
The system analyzes several calendar-based patterns:
| Pattern | Detection Method |
|---|---|
| Holiday Effect | Compares crimes within 3 days of US holidays vs normal days |
| Payday Effect | Compares crimes on 1st/2nd/15th/16th vs other days of month |
| Seasonal | Winter (Dec-Feb), Spring (Mar-May), Summer (Jun-Aug), Fall (Sep-Nov) |
| Year-over-Year | Compares first year vs last year if multi-year data |
Holiday proximity is calculated for: New Year's Day, MLK Day, Presidents Day, Memorial Day, July 4th, Labor Day, Columbus Day, Veterans Day, Thanksgiving, Christmas, and New Year's Eve.
The system uses Facebook Prophet for time-series crime forecasting:
| Parameter | Default | Description |
|---|---|---|
periods |
14 | Number of days to forecast ahead |
yearly_seasonality |
Auto | Enabled if 365+ days of data |
weekly_seasonality |
True | Detects day-of-week patterns |
interval_width |
0.80 | Confidence interval (80%) |
Minimum data requirements:
- At least 14 days of historical data
- Date column must be present and parseable
- More data = better seasonality detection
Forecast outputs:
- Daily crime count predictions with confidence intervals
- Peak/low day identification
- Trend comparison vs historical average
- Per-crime-type breakdown
The system analyzes incident patterns over time to classify each hotspot's momentum:
| Trend | Condition | Meaning |
|---|---|---|
| 📈 Growing | Second-half incidents > first-half by 20%+ | Crime increasing in this area |
| 📉 Shrinking | Second-half incidents < first-half by 20%+ | Crime decreasing in this area |
| ➡️ Stable | Change within ±20% | Consistent crime levels |
| 🆕 New | All incidents in second half | Recently emerged hotspot |
This trend data is passed to the AI model for momentum-aware predictions.
Edit the CUSTOM_CSS variable in src/crime_analyst_ai/app.py.
Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct first.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Folium - Interactive map visualization
- Pandas - Data analysis and manipulation
- Scikit-learn - DBSCAN clustering algorithm
- Prophet - Time-series forecasting (Meta)
- Gradio - Web interface framework
- Ollama - Local AI model runtime
- Mistral AI - Ministral-3:3b language model
Built with ❤️ for public safety