A comprehensive agent-based modeling (ABM) framework for simulating criminal behavior, environmental influences, and law enforcement strategies using machine learning and advanced visualization tools.
This simulation workspace provides researchers, policymakers, and law enforcement agencies with tools to:
- Model individual criminal decision-making processes
- Simulate routine activity theory dynamics
- Analyze environmental influences on crime patterns
- Test intervention strategies and policy changes
- Generate predictive analytics for crime prevention
- Visualize complex crime patterns and trends
crime_modeling/
├── agents/ # Agent behavior models
│ ├── criminal_agent.py # Criminal decision-making and behavior
│ ├── victim_agent.py # Victim vulnerability and protection
│ └── law_enforcement_agent.py # Police patrol and response
├── environment/ # Environmental modeling
│ └── urban_environment.py # Spatial grids and dynamics
├── core/ # Simulation engine
│ └── simulation.py # Main orchestration
├── analytics/ # Predictive modeling
│ └── predictive_model.py # ML-based crime prediction
├── visualization/ # Data visualization
│ └── crime_visualization.py # Charts and dashboards
├── config/ # Configuration management
│ └── settings.py # Simulation parameters
├── examples/ # Usage examples
│ └── basic_simulation.py # Getting started
├── tests/ # Unit tests
└── data/ # Input/output data
- Python 3.8+ (Tested with Python 3.12)
- Mesa 3.2.0+ (Agent-based modeling framework)
- VS Code (recommended)
- Git
-
Clone and navigate to the project:
cd "Crime modeling"
-
Create a virtual environment:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies:
pip install -r requirements.txt
from core.simulation import CriminalBehaviorSimulation
from config.settings import SIMULATION_CONFIG
# Run a basic crime simulation
simulation = CriminalBehaviorSimulation(config=SIMULATION_CONFIG)
simulation.run_simulation(steps=100)
results = simulation.get_results()
print(f"Simulation completed with {len(simulation.agents)} agents")Or run the example directly:
python examples/basic_simulation.pyThe simulation generates an interactive web dashboard at output/interactive_dashboard.html that includes:
- Real-time crime mapping
- Agent behavior visualization
- Environmental factor analysis
- Statistical reports and trends
- Mesa 3.x Framework: ✅ Successfully integrated and tested
- All Core Components: ✅ Working (Agents, Environment, Analytics, Visualization)
- Real-time Simulation: ✅ Running with 260+ agent interactions per step
- Interactive Dashboard: ✅ Web-based visualization available
- Machine Learning: ✅ Predictive models operational
- Test Suite: ✅ Comprehensive unit tests available
Latest Test Results: All core modules passing ✓
- Criminal Agents: Rational choice decision-making, risk assessment, routine activities
- Victim Agents: Vulnerability factors, protective behaviors, activity patterns
- Law Enforcement Agents: Patrol strategies, investigation, arrest procedures
- Spatial Grids: Lighting, surveillance, socioeconomic factors
- Temporal Dynamics: Time-of-day effects, seasonal patterns
- Urban Features: Population density, commercial areas, residential zones
- Predictive Models: Crime hotspot identification, risk prediction
- Feature Engineering: Spatial-temporal feature extraction
- Model Validation: Cross-validation, performance metrics
- Heatmaps: Crime density, risk surfaces
- Time Series: Temporal crime patterns
- Interactive Dashboards: Real-time simulation monitoring
- Network Analysis: Criminal network visualization
Models the convergence of motivated offenders, suitable targets, and absence of capable guardians in space and time.
Simulates criminal decision-making as cost-benefit analysis considering:
- Expected rewards
- Risk of detection/arrest
- Severity of punishment
- Opportunity factors
Incorporates spatial and temporal crime patterns:
- Crime attractors and generators
- Defensible space theory
- Crime pattern theory
from core.simulation import CriminalBehaviorSimulation
from config.settings import SIMULATION_CONFIG
# Initialize simulation
sim = CriminalBehaviorSimulation(config=SIMULATION_CONFIG)
# Run simulation
sim.run_simulation(steps=1000)
# Analyze results
results = sim.get_results()
crime_patterns = sim.analyze_crime_patterns()from analytics.predictive_model import PredictiveModel
# Initialize predictor
predictor = PredictiveModel()
# Train on historical data
predictor.train(features, targets)
# Generate predictions
hotspots = predictor.predict_hotspots(current_conditions)
risk_scores = predictor.calculate_risk_scores(locations)from visualization.crime_visualization import CrimeVisualizationTools
viz = CrimeVisualizationTools()
# Create crime heatmap
viz.create_crime_heatmap(crime_data, save_path="heatmap.png")
# Generate time series analysis
viz.plot_temporal_patterns(temporal_data)
# Launch interactive dashboard
viz.create_interactive_dashboard(simulation_data)Run the test suite:
python -m pytest tests/ -vRun specific test categories:
# Test agent behaviors
python -m pytest tests/test_agents.py
# Test simulation engine
python -m pytest tests/test_simulation.py
# Test predictive models
python -m pytest tests/test_analytics.pyCustomize simulation parameters in config/settings.py:
SIMULATION_CONFIG = {
'grid_size': (100, 100),
'num_criminals': 50,
'num_victims': 200,
'num_police': 20,
'simulation_steps': 1000,
'crime_rate_base': 0.01,
'patrol_effectiveness': 0.7
}The simulation generates various outputs:
- Crime Events: Location, time, type, participants
- Agent Trajectories: Movement patterns, decision points
- Environmental Changes: Dynamic factor evolution
- Prediction Accuracy: Model performance metrics
- Intervention Effects: Policy impact assessment
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes and add tests
- Ensure all tests pass:
pytest tests/ - Submit a pull request
- Follow PEP 8 style guidelines
- Include docstrings for all public methods
- Write unit tests for new features
- Update documentation as needed
- Crime pattern analysis
- Policy intervention testing
- Theoretical model validation
- Comparative criminology studies
- Resource allocation optimization
- Patrol strategy development
- Crime prevention planning
- Risk assessment tools
- Crime impact assessment
- Environmental design evaluation
- Community safety planning
- Development impact analysis
Extend the framework with custom agent types:
from agents.base_agent import BaseAgent
class SecurityGuardAgent(BaseAgent):
def __init__(self, unique_id, model):
super().__init__(unique_id, model)
self.patrol_route = []
self.detection_range = 5
def step(self):
self.patrol()
self.detect_crimes()Connect with external data sources:
# Import crime data
crime_data = pd.read_csv('real_crime_data.csv')
sim.initialize_from_data(crime_data)
# Export results
results = sim.get_detailed_results()
results.to_csv('simulation_output.csv')This project is licensed under the MIT License - see the LICENSE file for details.
For questions, issues, or contributions:
- Open an issue on GitHub
- Check the documentation
- Review example implementations
- Mesa framework for agent-based modeling
- Scikit-learn for machine learning capabilities
- Plotly and Matplotlib for visualization
- Criminological research community for theoretical foundations
Note: This simulation is designed for research and educational purposes. Real-world crime prediction and prevention should involve domain experts and consider ethical implications.