PROTON-OC is an agent-based model that explores the dynamics and processes that lead to recruitment into organized crime. The simulator investigates a wide variety of factors in the individual sphere and focuses on the social relationships between agents. Detailed information on the theoretical background, model development process, and model functioning available here. This is the python version of the simulator; the original model was developed in Netlogo and can be found here.
The simulation is developed by LABSS-CNR as a follow-up of the PROTON project, https://www.projectproton.eu/
Results from the original simulator have been published on the Journal of Quantitative Criminology.
proton-oc requires python >= 3.8, we recommend to use a virtual environment
pip install protonoc
To run directly from source, pip install mesa prettytable numba is a simple way to check some of the dependences. pytest is needed for running unit tests.
proton-oc integrates a command line interface that offers two usage modes:
-
base mode
>> protonoc base --help Usage: protonoc base [OPTIONS] Run a simple baseline simulation Options: -name, -n TEXT The name of the file being generated. By default it is hour_minutes -collect, -c PATH Specify the path where the results are saved. (e.g. -c /this_folder/another_folder). default is cwd -snapshot, -s INTEGER If this option is passed with an integer value, collects results only at certain ticks (e.g. -s 56 -s 89) save results at tick 56 and tick 89. Accepts multiple calls, default is None. -alldata, -a By default only model ouputs are collected. If this option is passed the attributes of every single agent are also collected. Warning: The output may be large. -randomstate, -r INTEGER If this option is called with an integer value, the simulation uses that seed for the random generator. --help Show this message and exit.Example:
protonoc base -c result/ -n sample -r 42This command launches a simulation with baseline parameters, saves results in
result/with the name"sample"and uses the seed42. Results are saved in pickle format. -
override mode
>> protonoc override --help Usage: protonoc override [OPTIONS] [SOURCE_PATH] This command takes as argument an .xml file a .json file or a folder containing several .json or .xml files. It overwrites the model parameters with the files and performs several simulations. SOURCE_PATH: file location, default is cwd Options: -collect, -c PATH Specify the path where the results are saved. (e.g. -c /this_folder/another_folder). default is cwd -snapshot, -s INTEGER If this option is passed with an integer value, collects results only at certain ticks (e.g. -s 56 -s 89) save results at tick 56 and tick 89. Accepts multiple calls, default is None. -alldata, -a By default only model ouputs are collected. If this option is passed the attributes of every single agent are also collected. Warning: The output may be large. -randomstate, -r INTEGER If this option is called with an integer value, the simulation uses that seed for the random generator. -parallel, -p INTEGER Adding this option with an int argument launches multiple simulations in parallel using concurrent.futures. The int value indicates how many cores to use. If the value is too high adjust the parameter based on the available machine's cores. Be careful, it does not control memory increase which may cause an out-of-memory. -merge, -m Each simulation generates a single pickle file. If this option is passed generates a single file instead. Raise MemoryError if not enough memory space. --help Show this message and exit.
Example:
protonoc override sample_json.json -c results/ -p 4 -m -a
This command takes the file sample_json.json (located in the samples folder) runs several simulations divided into 4 processes and saves the results in the results/ folder. At the end of the simulation it merges all the results into one pickle file.
Simulations results are saved in pickle and can be extracted as a pandas DataFrame through the protonoc.utils module.
from protonoc import utils
path = "FILEPATH"
data = utils.read_data(path)Import ProtonOC as a simple module, create a new instance of the model and call the run function:
from protonoc import ProtonOC
model = ProtonOC()
model.run(n_agents=100, num_ticks=480, verbose=True)Import ProtonOC as a simple module, create a new instance of the model, use ProtonOC.overview() to show a pretty table with current parameters and the respective value. Use ProtonOC.set_param() to change the parameters of the active ProtonOC instance. Call the run function to launch the model.
from protonoc import ProtonOC
model = ProtonOC()
model.overview()
model.set_param("initial_agents", 10000)
model.run(verbose=True)sample ProtonOC.overview() output:
+-----------------------------------+----------+
| free parameter name | value |
+-----------------------------------+----------+
| migration_on | True |
| initial_agents | 10000 |
| num_ticks | 480 |
| intervention | baseline |
| ...................... | . |
| ...................... | . |
| ...................... | . |
| ...................... | . |
+-----------------------------------+----------+
Pyproton-oc accepts contributions. Reports and suggestions are welcome. Feedbacks are mandatory.