Game_theory_rabies

Code used for the simulations, data analysis and sensitivity analysis for the article "Benefit-cost analysis of coordinated strategies for control of rabies in Africa" (DOI: https://doi.org/10.21203/rs.3.rs-2961159/v1) by Alvar Bucher, Artemiy Dimov, Günther Fink, Nakul Chitnis, Bassirou Bonfoh and Jakob Zinsstag.

List of folders and files

I. Download the repository and the data

1. To download the repository from GitHub please follow this link: Game_theory_rabies
2. Click on the green button "Code" and select "Download ZIP"
3. Unpack the zip file and place the folder Game_theory_rabies in the folder where you want to run the simulations
4. To download the images and the results from the simulations, please follow this link: Game_theory_rabies_results
5. Unpack the zip files and place the unpacked folders original_img and original_results in the folder Game_theory_rabies

Note If you want to replicate the results from the original article without running the sensitivity analysis and the Monte-Carlo simulations, please use the data from the folder original_results by specifying the parameters '2' during the execution of the script post_treatment.py (see part 4.2 below).

II. Folders' structure and description of the folders

.
├───data : Contains data used for the simulations
│
├───img : Generated figures for the manuscript and the supplementary material
│   ├───all_vac : Individual plots for countries' payoff distributions for the strategy profile "All vaccinate"
│   ├───inputs_dist: Plots of input distributions for the sensitivity analysis and Monte-Carlo simulations per country
│   └───one_vac : Individual plots for countries' payoff distributions for the strategy profile "One vaccinate"
│
├───results : Results from the simulations and post-treated results (compiled or revised results)
│   ├───dog_population : Results from the Monte-Carlo simulations for the dog population (monte_carlo_baseline_population.py)
│   ├───results_by_year : Results for the average case for each year for different  (strategy_analysis.py)
│   ├───s_reintroduction : Results of the simulations for the sensitivity analysis and Sobol indices calculation
│   │                      for reintroduction case (sensitivity_analysis_model_one_country.py)
│   └───s_vaccination : Results of the simulations for the sensitivity analysis and Sobol indices calculation
│                       for vaccination case without reintroduction (sensitivity_analysis_model_one_country.py)
│
├───jobs : Folder generated when creating jobs for the cluster with the script utils.py
│
├───original_img : Same as img but with the figures originally generated by the authors
│   ├───all_vac
│   ├───inputs_dist
│   └───one_vac
│
├───original_results : Results of the sensitivity analysis, Sobol indices calculation and Monte-Carlo simulations
│   │                  originally generated by the authors
│   ├───dog_population
│   ├───s_reintroduction
│   └───s_vaccination
│
└───src : Python scripts

III. List of appendices and description of files

Note Different Appendices were renamed as Supplementary Information or Supplementary Data for the publication, and those names will appear during the publication. Whereas, during the release, old names were used. Below is the list and equivalence of those files.

• Supplementary Information 0-3 (pdf file): "Supplementary Information"
  • "Supplementary Information 0. Notations and descriptions"
  • "Supplementary Information 1. Methods"
  • "Supplementary Information 2. Modelling of the Game "Coordinated dog rabies vaccination against incomplete PEP""
  • "Supplementary Information 3. The different layers of the game"
• Supplementary Data 1 (Excel file): Appendix 4 - Data for simulations.xlsx (in the folder data)
• Supplementary Data 9 (Excel file): Appendix 4bis - Data for simulations.xlsx
• Supplementary Data 2 (Excel file): Appendix 5 - Strategy analysis.xlsx
• Supplementary Data 3 (Excel file): Appendix 6 - Sobol indices.xlsx
• Supplementary Data 4 (Excel file): Appendix 7 - Neighbouring countries matrix.xlsx (in the folder data)
• Supplementary Data 5 (CSV file): Appendix 8 - Minimal distance matrix.csv (in the folder data)
• Supplementary Data 6 (Excel file): Appendix 9 - GDP Contribution Calculation 20220902.xlsx
• Supplementary Data 7 (Excel file): Appendix 10_1 - Dog Population Knobel 2005 including PopGrowth.xlsx,
• Supplementary Data 8 (Excel file): Appendix 10_2 - Hampson et al. 2015 numbers.xlsx

• Generated results by Python scripts are stored in the folder results
• Results originally generated by authors are stored in the folder original_results.
• Generated figures are stored in the folder img
• Figures originally generated by authors are stored in the folder original_img
• Python scripts:
  • utils.py
  • monte_carlo_baseline_populations.py
  • strategy_analysis.py
  • sensitivity_analysis_model_one_country.py
  • post_treatment.py

Installation and usage

The scripts were tested on Windows 10, 11 and the Linux environment on sciCORE.

I. Setting up the environment

1. For Windows users

For Windows users, we recommend to install Anaconda to manage the installation of the required packages.

1. Download and install Anaconda (installation time: ~ 5 minutes)
2. Open the Anaconda prompt and navigate to the folder where the repository is located
3. Create a virtual environment named game_theory_rabies using the following command

conda create -n game_theory_rabies python=3.8

4. Activate the environment

conda activate game_theory_rabies

5. Install the required packages (installation time: ~ 5 minutes)

pip install -r requirements.txt

2. For Linux users

Warning This part was not tested yet.

For Linux users, we advise to create a virtual environment using venv with the python version 3.8.

1. Download the repository from GitHub (Game_theory_rabies)
2. Open a terminal and navigate to the folder where the repository is located
3. Install Python 3.8, if not already installed (/!\ Admin rights are required)

sudo apt-get install python3.8

4. Create a virtual environment named game_theory_rabies using the following command

python3.8 -m venv game_theory_rabies

5. Activate the environment

source game_theory_rabies/bin/activate

6. Install the required packages

pip install -r requirements.txt

II. Running the scripts

Note

The scripts can be run on a cluster or on a local machine. But, considering the execution time of the scripts sensitivity_analysis_model_one_country.py and monte_carlo_baseline_populations.py when the sample size is important, it is preferable to run them on a cluster. It doesn't require a lot of resources, but it is possible to create bash scripts to run all 48 scripts (one per country) at the same time.

1. Strategy analysis (strategy_analysis.py)

This script runs the payoffs calculation using the mean values for different strategies and saves the yearly results for some intermediary and final outputs. Running time: ~ 5 minutes.

1.1. Prerequisites

Data dependencies:

• Appendix 4 - Data for simulations.xlsx (in the folder data)
• Appendix 7 - Neighbouring countries matrix.xlsx (in the folder data)
• Appendix 8 - Minimal distance matrix.csv (in the folder data)

1.2. Running the script

1. Open a terminal and navigate to the folder where the source code is located.

cd /path/to/repository/Game_theory_rabies/src

2. Activate the environment

conda activate game_theory_rabies

3. Run the script strategy_analysis.py, no arguments needed.

python strategy_analysis.py

1.3. Results

The results are saved in the folder results/results_by_year.

Generated files ({strategy} can be one_vac,all_vac, nash, one_pep, n24):

• clinical_cases_humans_{strategy}.csv : number of clinical cases in humans for each strategy profile by year
• exposed_humans_{strategy}.csv : number of exposed humans for each strategy profile by year
• payoff_total_{strategy}.csv : total payoff for each strategy profile by year
• payoff_without_hce_{strategy}.csv : payoff without HCE for each strategy profile by year
• rabid_dog_population_{strategy}.csv : rabid dog population for each strategy profile by year

Exemple of output in the terminal:

(game_theory_rabies) PS D:\Work\Game_theory_rabies\src> python .\strategy_analysis.py
============================================= Strategy analysis script =============================================
Creating files with payoffs for some strategy profiles
INFO:root:Data loaded
INFO:root:Generating data for all_vac strategy profile
INFO:root:Generating data for all_pep strategy profile
INFO:root:Generating data for nash strategy profile
INFO:root:Generating data for one_pep strategy profile
INFO:root:Generating data for n24 strategy profile

2. Monte-Carlo simulations with sensitivity analysis (sensitivity_analysis_model_one_country.py)

This script runs the Monte-Carlo simulations with sensitivity analysis for one country, as defined in Appendix 1 in the section "Sensitivity analysis and consideration of uncertainty". This script saves (i) the results of the simulations, i.e. all payoffs for the same model, but with different set of input parameters to study the effects of uncertainty, and (ii) the Sobol indices for each stochastic input parameter.

The running time depends on the sample size. As a demo, a sample size of 1000 can be used and it takes around 10 minutes to run. For the original results, the sample size of 50000 was used, the approximate running time was 12-15 hours.

2.1. Prerequisites

Data dependencies:

• Appendix 4 - Data for simulations.xlsx (in the folder data)
• Appendix 7 - Neighbouring countries matrix.xlsx (in the folder data)
• Appendix 8 - Minimal distance matrix.csv (in the folder data)

2.2. Running the script

1. Open a terminal and navigate to the folder where the source code is located.
2. Activate the environment
3. Run the script sensitivity_analysis_model_one_country.py with specific arguments

Possible arguments:

• size: sample size for the sensitivity analysis (default: 10000). The real sample size is 10 times greater. Original results obtained with sample size of 50000.
• country_code: country code for the simulation (default: COG)
• reintroduction: reintroduction of rabies in the country (Possible values: 0 (False) or 1 (True). Default: 0)
• save_simulation_results: save the results of the simulations (Possible values: 0 (False) or 1 (True). Default: 1)
• min_dist_to_compare: distance to the closest infected country in case of reintroduction (default: 1)

General command:

python sensitivity_analysis_model_one_country.py {size} {country_code} {reintroduction} {save_simulation_results} {min_dist_to_compare}

Example for the vaccination strategy with reintroduction from a neighbouring country in Algeria (DZA) with a sample size of 1000:

python sensitivity_analysis_model_one_country.py 1000 DZA 1 1 1

2.3. Results

The results for the vaccination strategy with reintroduction are saved in the folder results/s_reintroduction. The results for the vaccination strategy without reintroduction are saved in the folder results/s_vaccination.

Generated files ({strategy} can be one_vac for vaccination with reintroduction orall_vac for vaccination without reintroduction):

• sensitivity_{country_code}_{strategy}.csv: Sobol indices for the country country_code and strategy strategy.
• simulation_results_{country_code}_{strategy}.csv: Data from the simulations for the data analysis for the country country_code and strategy strategy. Each row in this file is a result of a simulation of the payoff with a different set of parameters.

Example of output in the terminal:

(game_theory_rabies) PS D:\Work\Game_theory_rabies\src> python .\sensitivity_analysis_model_one_country.py 1000 DZA 1 1 1
========================== Running sensitivity analysis for DZA ============================
Number of simulations to run: 10000
working: 0
working: 1000
working: 2000
working: 3000
working: 4000
working: 5000
working: 6000
working: 7000
working: 8000
working: 9000
Execution time: 692.4410164356232 seconds

3. Monte-Carlo simulations for the dog population estimation (monte_carlo_baseline_population.py)

This script runs the Monte-Carlo simulations for the rabid dog population estimation with stochastic inputs, as defined in Appendix 1 in the section "Sensitivity analysis and consideration of uncertainty". This script saves the results of the simulations, i.e. where each row contains the cumulative rabid dog population, the number of exposed humans and the number of clinical cases for one simulation.

The running time depends on the sample size. As a demo, a sample size of 10000 can be used and it takes around 3 minutes to run. For the original results, the sample size of 200000 was used, the approximate running time was 1-2 hours.

3.1. Prerequisites

Data dependencies:

• Appendix 4 - Data for simulations.xlsx (in the folder data)
• Appendix 7 - Neighbouring countries matrix.xlsx (in the folder data)
• Appendix 8 - Minimal distance matrix.csv (in the folder data)

3.2. Running the script

1. Open a terminal and navigate to the folder where the source code is located.
2. Activate the environment
3. Run the script monte_carlo_baseline_population.py with specific arguments

Possible arguments:

• size: sample size for the sensitivity analysis (default: 200000). The real sample size is the same as the one entered. Original results obtained with sample size of 200000.
• country_code: country code for the simulation (default: COG)

General command:

monte_carlo_baseline_populations.py {size} {country_code}

Example for Ethiopia (ETH) with a sample size of 10000:

python monte_carlo_baseline_populations.py 10000 ETH

3.3. Results

The results are saved in the folder results/dog_population.

Generated file:

• simulation_dog_population_results_{country_code}.csv:

Example of output in the terminal:

(game_theory_rabies) PS D:\Work\Game_theory_rabies\src> python .\monte_carlo_baseline_populations.py 10000 ETH
========================== Monte Carlo simulations (dog populations) for ETH ============================
Number of simulations to run: 10000
Execution time: 150.17150235176086 seconds

4. Post-treatment of the results (post_treatment.py)

This script contains several functions to post-treat (compile, save) the results of the Monte-Carlo simulations or to plot the figures. The running time depends on the process, the longest are the processes with compiling and saving the data, with a running time around 10 minutes.

The following functionalities are available (information also available in the docstrings in the script) identified by the same number that in the list below:

1. Compile and save the results of simulations from the sensitivity analysis (generated by sensitivity_analysis_model_one_country.py), as well as the individual plots for payoffs distributions.
2. Compile and save the results of simulations from the sensitivity (generated by sensitivity_analysis_model_one_country.py) analysis without individual plots
3. Compile Sobol indices results (generated by sensitivity_analysis_model_one_country.py) and plot them (figures 1 and 2 in the appendix)
4. Compile and save the data of the number of lives lost (generated by monte_carlo_baseline_populations.py), as well as the total mean values and the confidence intervals.
5. Compile, save and visualize the data from Monte-Carlo simulations for the rabid dog population estimation (generated by monte_carlo_baseline_populations.py).
6. Visualize the payoffs distributions for all countries for the all vaccination (figure 3 in the appendix) and one vaccination (figure 4 in the appendix) strategies. Utilizes the compiled data from the function 1.
7. Realize the coalition analysis from the compiled data. Utilizes the compiled data from the function 1.
8. Visualize the yearly exposure to rabid dogs for different strategy profiles (generated by strategy_analysis.py) (figure 1 in the paper).
9. Calculate and plot the break-even point for the vaccination strategy with and without accounting for the human capital effect (figure 7 in the appendix) using the data generated by strategy_analysis.py.
10. Visualize the gains by country on the map (figures 2 and 3 in the paper). Utilizes the compiled data from the function 1.
11. Calculate and plot the break-even point for different strategies with and without accounting for the human capital effect (figures 5 and 6 in the appendix) using the data generated by strategy_analysis.py.
12. Plot and print the total payoff distribution cumulative for all countries.

4.1. Prerequisites

Data dependencies:

• Functions 1, 2, 3 :
  • Results from sensitivity_analysis_model_one_country.py (in the folder results/s_reintroduction and results/s_vaccination)
• Functions 4, 5:
  • Results from monte_carlo_baseline_populations.py (in the folder results/dog_population)
• Functions 6, 7, 10:
  • Compiled data from the functions 1 or 2 (the difference is only the plotting between those functions).
• Functions 8, 9, 11:
  • Results from strategy_analysis.py (in the folder results/results_by_year)

It is possible to use the functions with the original results from authors from the folder results/original_results.

4.2. Running the script

1. Open a terminal and navigate to the folder where the source code is located.
2. Activate the environment
3. Run the script post_treatment.py
4. Enter the number of the function to run (see the list above)
5. Enter the selection of the folder where the results are located
   • 1: results
   • 2: original_results

General command:

python post_treatment.py
# Enter the number of the function to run
# Enter the selection of the folder where the results are located

4.3. Results

Generated files:

1. Function 1
   • compiled_data_all_vac.csv : Compiled simulation data for all countries for all vaccination strategy profile.
   • compiled_data_one_vac.csv : Compiled simulation data for all countries for one vaccination strategy profile.
   • summary_data_all_vac.csv : Summary of simulation data for all countries for all vaccination strategy profile.
   • summary_data_one_vac.csv : Summary of simulation data for all countries for one vaccination strategy profile.
   • payoff_distribution_{country_code}_one_vac.png : Payoff distributions for the country {country_code} for one vaccination strategy profile. In total 48 plots are generated.
   • payoff_distribution_{country_code}_all_vac.png : Payoff distributions for the country {country_code} for all
   • vaccination strategy profile. In total 48 plots are generated.
2. Function 2:
   • Only the csv files of the function 1 are generated.
3. Function 3:
   • first_order_sobol_all_vac.csv : Compiled first-order Sobol indices results for all countries for all vaccination strategy profile.
   • first_order_sobol_one_vac.csv : Compiled first-order Sobol indices results for all countries for all vaccination strategy profile.
   • total_order_sobol_all_vac.csv : Compiled first-order Sobol indices results for all countries for all vaccination strategy profile.
   • total_order_sobol_one_vac.csv : Compiled first-order Sobol indices results for all countries for all vaccination strategy profile.
   • sobol_indices_all_vac.png : Plots of the Sobol indices for all countries for all vaccination strategy profile (Figure 1 in the appendix).
   • sobol_indices_one_vac.png : Plots of the Sobol indices for all countries for all vaccination strategy profile (Figure 2 in the appendix).
4. Function 4:
   • res_lives_lost.csv : Compiled data of the number of lives lost.
5. Function 5:
   • compiled_data_rabid_dog_population.csv : Compiled data of the rabid dog population estimation from the Monte-Carlo simulations.
   • rabid_dog_population_distribution_baseline.png : Plots of the total rabid dog population, total exposed humans and total clinical cases distributions from the Monte-Carlo simulations at the baseline.
6. Function 6:
   • figure_3_appendix.png : Plots of the payoffs distributions for all countries for all vaccination strategy profile (Figure 3 in the appendix).
   • figure_4_appendix.png : Plots of the payoffs distributions for all countries for one vaccination strategy profile (Figure 4 in the appendix).
7. Function 7:
   • Only console output
8. Function 8:
   • figure_1_manuscript.png : Plots of the yearly exposure to rabid dogs for different strategy profiles (Figure 1 in the paper).
9. Function 9:
   • figure_7_payoff_total_appendix.png : Plots of the break-even point for the vaccination strategy without accounting for the human capital effect (Figure 7 in the appendix).
   • figure_7_payoff_without_hce_appendix.png : Plots of the break-even point for the vaccination strategy with the human capital effect (Figure 7 in the appendix).
10. Function 10:

• figure_2_manuscript.png : Plots of the gains by country on the map (Figure 2 in the paper).
• figure_3_manuscript.png : Plots of the gains divided by GDP by country on the map (Figure 3 in the paper).

11. Function 11:

• figure_5_appendix.png : Plots of break-even points for different strategy profiles for all countries without accounting for the human capital effect (Figure 5 in the appendix).
• figure_6_appendix.png : Plots of break-even points for different strategy profiles for all countries with HCE (Figure 6 in the appendix).

12. Function 12:

• payoff_distribution_all_vac_all_countries.png : Plots of the total payoff distribution cumulative for all countries.

Example of the console output for the function 5:

(game_theory_rabies) PS D:\Work\Game_theory_rabies\src> python .\post_treatment.py
==================================== Running the post treatment process ====================================
The following processes are available:
1. Compile and save the results of simulations from the sensitivity analysis, as well as the individual plots for payoffs distributions
2. Compile and save the results of simulations from the sensitivity analysis without individual plots
3. Compile Sobol indices results and plot them (figures 1 and 2 in the appendix)
4. Compile and save the data of the number of lives lost, as well as the total mean value and confidence interval
5. Compile, save and visualize data from Monte-Carlo simulations for the dog population
6. Visualize the payoffs distributions for all countries for the all vaccination (figure 3 in the appendix) and one vaccination (figure 4 in the appendix) strategies
7. Realize the coalition analysis from the compiled data
8. Visualize the yearly exposure to rabid dogs for different strategy profiles (figure 1 in the paper)
9. Calculate and plot the break-even point for the vaccination strategy with and without accounting for the human capital effect (figure 7 in the appendix)
10. Visualize the gains by country on the map (figures 2 and 3 in the paper)
11. Calculate and plot the break-even point for different strategies with and without accounting for the human capital effect (figures 5 and 6 in the appendix)
12. Plot and save total payoff distribution cumulative for all countries
Please enter the number of the process you want to run:
5
If the data you want to compile or to use is in folder 'results', please enter '1'
If the data is in the folder 'original_results', please enter '2':
2
INFO:root:Starting compiling data from Monte-Carlo simulations for rabid dog population, exposed humans and clinical cases
INFO:root:Starting looping over countries
INFO:root:Finished looping over countries
INFO:root:Saving compiled data
INFO:root:Saving compiled data : finished
Mean rabid dog population at baseline: 6,641,252
Percentile interval [2.5%, 97.5%] for rabid dog population at baseline: [5,352,200, 8,094,558]
Mean value of exposed humans at the baseline: 15,275,368
Percentile interval [2.5%, 97.5%] for the number of exposed humans at the baseline: [9,606,726, 23,718,481]
Mean value of clinical cases at the baseline : 2,902,293
Percentile interval [2.5%, 97.5%] for the number of clinical cases at the baseline: [1,796,748, 4,555,867]
INFO:root:Finished
==================================== End of the post treatment process ====================================