Usage

Now that you have installed SABCoM as a package and have set up the data folders and parameter files, you can start working with the model. To do so, navigate to the folder containing the data folder in your terminal. Then there are several commands that you can use depending on your needs.

Simulation

The most often used command is simulate. Besides the need for the data files and parameters to be present, you will need to have pre-initialised seeds in your data folder in a separate initialisations folder (see our example repositories for an example). With all that in place, you can simulate the using the below inputs, first make sure that all the files and folders are in your current location. The function uses the following arguments:

  1. –input_folder_path (-i): this should contain all necessary input files, this argument is required.

  2. –output_folder_path (-o): all simulation output will be deposited here, this argument is required, if you input a folder that doesn’t exist, it will be created.

  3. –seed (-s): integer seed number that is used for Monte Carlo simulations, this argument is required.

  4. –data_output_mode (-d): this can be one of three options: csv-light (only the aggregate trends are written to a single csv file), csv (all individual agent variables are recorded in many csv files, taking up a lot of space), network (the status and connections of all agents will be recorded in a .graphx file for every time step). If not provided, the default will be csv-light.

  5. –scenario (-sc): can be one of three options: no-intervention, lockdown, or ineffective-lockdown. If not provided, the default will be no-intervention.

  6. –days (-day): integer that sets the number of simulation days, overwriting the days in the parameter.json file.

  7. –probability_transmission (-pt): change the probability of transmission between two agents, optional argument that will overwrite the value in the parameters.json.

  8. –visiting_recurring_contacts_multiplier (-cont): change the percentage of contacts agents may have, optional argument that will overwrite the value in the parameters.json.

  9. –likelihood_awareness (-la): change the likelihood that an agent is aware it is infected.

  10. –gathering_max_contacts (-maxc): change maximum number of contacts and agent is allowed to have.

  11. –initial_infections (-ini): number of initial infections.

  12. –second_infection_n (-sec): number of second wave infections.

  13. –time_4_new_infections (-sect): time of the second wave of infections.

  14. –new_infections_scenario (-scsi): scenario determining in which Wards second infections take place. Options are None, initial (same Wards as initial infections) or random.

  15. –sensitivity_config_file_path (-scf): configuration file that contains parameter combinations that will override those in the parameters.json file. This is often used for sensitivity analyses.

An example of what a simulate command might look like is:

$ simulate -i example_data -o example_data/output_file -s 2 -d csv-light -sc no-intervention

This will simulate a no_intervention scenario for the seed_2.pkl initialisation. Input files for the city of your choice, and output a csv light data file in the specified output folder (output_file). Also, note how this assumes that there is already an initialisation file. If there is no initialisation file, then the next command can be used to produce one given the input files.

Initialisation

For input folders with no initialisation file. SABCoM uses the “sabcom initialise” function to create an initialisation with the files in input folder. It uses the following input arguments:

  1. –input_folder_path (-i): this should contain all necessary input files, this argument is required.

  2. –seed (-s): integer seed number that is used for Monte Carlo simulations, this argument is required.

An example of what an initialise command might look like is:

$ sabcom initialise -i example_data -s 3

Please not that, creating a new model initialisation takes much longer than simulating one.

The next two functions can be used to estimate the values of uncertain parameters.

Sample

To estimate uncertain parameters for a city, you first need to create a set of starting parameter values. This function uses Latin Hypercube sampling to select the most efficient set of parameters that will cover as much of the parameter space as possible. The function takes three arguments:

  1. –problem_file_path (-prob): link to a json file that contains parameters and the bounds between which they should be.

  2. –n_samples (-n): the number of parameter samples that should be returned. A higher number of parameter samples will reduce the chance that the estimation algorithm will get stuck in a local optimum but will be more computationally expensive.

  3. –output_file_name (-ofn): change the name of the output file to one of your liking.

An example of what the sample command might look like is:

$ sabcom sample -prob calibration_problem.json -n 5 -ofn hypercube.json

Estimate

Using the samples produced by the sample function, the estimate algorithm will try to find a set of uncertain parameters for which the model reproduces a curve of excess fatalities recorded in the city. The estimate function uses the following parameters:

  1. –input_folder_path (-i): this should contain all necessary input files, this argument is required.

  2. –output_folder_path (-o): the estimated parameters will be deposited in this folder, this argument is required, if you input a folder that doesn’t exist, it will be created.

  3. –n_seeds (-s): integer seed number that is used for Monte Carlo simulations, this argument is required.

  4. –problem_folder_path (-pfp): leads to a json file that was generated using the sample function.

  5. –scenario (-sc): can be one of three options: no-intervention, lockdown, or ineffective-lockdown. If not provided, the default will be no-intervention.

  6. –iterations (-iter): the number iterations the Nelder-Mead optimisers should do to find the optimal parameters.

  7. –sensitivity_parameters_path (-spp): A path to a json file with parameters that need to be updated irrespective of the calibration.

An example of what the estimate command might look like is:

$ sabcom estimate -i cape_town -o output_data -sc ineffective-lockdown -pfp hyper-no-learning.json -n 1 -iter 1 -ofn super_est_pars.json -spp test_sensitivity.json