Package: protonoc
PROTON-OCPROTON-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 availablehere. This is the python version of the simulator; the original model was developed in Netlogo and can be foundhere.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 theJournal of Quantitative Criminology.Get startedproton-oc requires python  >= 3.8, we recommend to use a virtual environmentpip install protonocCommand Line Interfaceproton-oc integrates acommand line interfacethat 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 inresult/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 -aThis command takes the filesample_json.json(located in the samples folder) runs several simulations divided into 4 processes and saves the results in theresults/folder. At the end of the simulation it merges all the results into one pickle file.Read dataSimulations results are saved in pickle and can be extracted as a pandas DataFrame through theprotonoc.utilsmodule.fromprotonocimportutilspath="FILEPATH"data=utils.read_data(path)Integrate the model in your scriptsImportProtonOCas a simple module, create a new instance of the model and call therunfunction:fromprotonocimportProtonOCmodel=ProtonOC()model.run(n_agents=100,num_ticks=480,verbose=True)How do I change input parameters?ImportProtonOCas a simple module, create a new instance of the model, useProtonOC.overview()to show a pretty table with current parameters and the respective value. UseProtonOC.set_param()to change the parameters of the activeProtonOCinstance. Call the run function to launch the model.fromprotonocimportProtonOCmodel=ProtonOC()model.overview()model.set_param("initial_agents",10000)model.run(verbose=True)sampleProtonOC.overview()output:+-----------------------------------+----------+
|        free parameter name        |  value   |
+-----------------------------------+----------+
|            migration_on           |   True   |
|           initial_agents          |   10000  |
|             num_ticks             |   480    |
|            intervention           | baseline |
|       ......................      |    .     |
|       ......................      |    .     |
|       ......................      |    .     |
|       ......................      |    .     |
+-----------------------------------+----------+ContributePyproton-oc accepts contributions. Reports and suggestions are welcome. Feedbacks are mandatory.