Repository files navigation

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

1. Clone and navigate to the project:

   cd"Crime modeling"

2. Create a virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt

fromcore.simulationimportCriminalBehaviorSimulationfromconfig.settingsimportSIMULATION_CONFIG# Run a basic crime simulationsimulation=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.py

The simulation generates an interactive web dashboard atoutput/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

fromcore.simulationimportCriminalBehaviorSimulationfromconfig.settingsimportSIMULATION_CONFIG# Initialize simulationsim=CriminalBehaviorSimulation(config=SIMULATION_CONFIG)# Run simulationsim.run_simulation(steps=1000)# Analyze resultsresults=sim.get_results()crime_patterns=sim.analyze_crime_patterns()

fromanalytics.predictive_modelimportPredictiveModel# Initialize predictorpredictor=PredictiveModel()# Train on historical datapredictor.train(features,targets)# Generate predictionshotspots=predictor.predict_hotspots(current_conditions)risk_scores=predictor.calculate_risk_scores(locations)

fromvisualization.crime_visualizationimportCrimeVisualizationToolsviz=CrimeVisualizationTools()# Create crime heatmapviz.create_crime_heatmap(crime_data,save_path="heatmap.png")# Generate time series analysisviz.plot_temporal_patterns(temporal_data)# Launch interactive dashboardviz.create_interactive_dashboard(simulation_data)

Run the test suite:

python -m pytest tests/ -v

Run specific test categories:

# Test agent behaviorspython -m pytest tests/test_agents.py# Test simulation enginepython -m pytest tests/test_simulation.py# Test predictive modelspython -m pytest tests/test_analytics.py

Customize simulation parameters inconfig/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

1. Fork the repository
2. Create a feature branch:git checkout -b feature-name
3. Make your changes and add tests
4. Ensure all tests pass:pytest tests/
5. 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:

fromagents.base_agentimportBaseAgentclassSecurityGuardAgent(BaseAgent):def__init__(self,unique_id,model):super().__init__(unique_id,model)self.patrol_route= []self.detection_range=5defstep(self):self.patrol()self.detect_crimes()

Connect with external data sources:

# Import crime datacrime_data=pd.read_csv('real_crime_data.csv')sim.initialize_from_data(crime_data)# Export resultsresults=sim.get_detailed_results()results.to_csv('simulation_output.csv')

• API Documentation
• Agent Development Guide
• Environment Modeling
• Analytics and ML
• Visualization Guide

This project is licensed under the MIT License - see theLICENSE 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.