COVID-19 Outbreak Simulator

The COVID-19 outbreak simulator simulates the outbreak of COVID-19 in a population. It was first designed to simulate the outbreak of COVID-19 in small populations in enclosed environments, such as a FPSO (floating production storage and offloading vessel) but it is being expanded to simulate much larger populations with dynamic parameters.

This README file contains all essential information but you can also visit our documentation for more details.

Background

This simulator simulates the scenario in which

• A group of individuals in a population in which everyone is susceptible
• One virus carrier is introduced to the population, potentially after a fixed days of self-quarantine.
• Infectees are by default removed from from the population (or separated, or quarantined, as long as he or she can no longer infect others) after they displayed symptoms, but options are provided to act otherwise.

The simulator simulates the epidemic of the population with the introduction of an infector. The following questions can be answered:

1. What is the expected day and distribution for the first person to show symptoms?
2. How many people are expected to be removed once an outbreak starts?
3. How effective will self-quarantine before dispatch personnels to an enclosed environment?

The simulator uses the latest knowledge about the spread of COVID-19 and is validated against public data. This project will be contantly updated with our deepening knowledge on this virus.

Modeling the outbreak of COVID-19

We developed multiple statistical models to model the incubation time, serial interval, generation time, proportion of asymptomatic transmissions, using results from multiple publications. We validated the models with empirical data to ensure they generate, for example, correct distributions of serial intervals and proporitons of asymptomatic, pre-symptomatic, and symptomatic cases.

The statistical models and related references are available at

1. Model v1: model_v1.ipynb
2. Model v1: model_v2.ipynb

The models will continuously be updated as we learn more about the virus.

How to use the simulator

This simulator is programmed using Python >= 3.6 with numpy and scipy. A conda environment is recommended. After the set up of the environment, please run

pip install -r requirements.txt

to install required packages, and then

pip install covid19-outbreak-simulator

to install the package.

You can then use command

outbreak_simulator -h

to check the usage information.

Output from the simulator

The output file contains events that happens during the simulations. For example, for command

outbreak_simulator --repeat 100 --popsize 64 --logfile result_remove_symptomatic.txt

You will get an output file result_remove_symptomatic.txt with the following columns:

Currently the following events are tracked

The log file of a typical simulation would look like the following:

id      time    event   target  params
1       0.00    INFECTION       0       r0=0.53,r=0,r_asym=0
1       0.00    END     64      popsize=64,prop_asym=0.276
2       0.00    INFECTION       0       r0=2.42,r=1,r_presym=1,r_sym=0,incu=5.51
2       4.10    INFECTION       62      by=0,r0=1.60,r=2,r_presym=2,r_sym=0,incu=5.84
2       5.51    SHOW_SYMPTOM    0       .
2       5.51    REMOVAL 0       popsize=63
2       9.59    INFECTION       9       by=62,r0=2.13,r=2,r_presym=2,r_sym=0,incu=3.34
2       9.84    INFECTION_IGNORED       9       by=62
2       9.94    SHOW_SYMPTOM    62      .
2       9.94    REMOVAL 62      popsize=62
2       10.76   INFECTION       30      by=9,r0=1.96,r=2,r_presym=2,r_sym=0,incu=4.85
2       11.64   INFECTION       57      by=9,r0=0.39,r=0,r_asym=0
2       12.23   INFECTION       56      by=30,r0=1.65,r=1,r_presym=1,r_sym=0,incu=4.26
2       12.93   SHOW_SYMPTOM    9       .
2       12.93   REMOVAL 9       popsize=61
2       14.37   INFECTION       6       by=30,r0=1.60,r=0,r_presym=0,r_sym=0,incu=2.63
2       15.61   SHOW_SYMPTOM    30      .
2       15.61   REMOVAL 30      popsize=60
2       16.37   INFECTION       1       by=56,r0=1.57,r=1,r_presym=1,r_sym=0,incu=5.14
2       16.49   SHOW_SYMPTOM    56      .
2       16.49   REMOVAL 56      popsize=59
2       16.99   SHOW_SYMPTOM    6       .
2       16.99   REMOVAL 6       popsize=58
2       18.42   INFECTION       8       by=1,r0=2.45,r=1,r_presym=1,r_sym=0,incu=3.74
2       20.35   INFECTION       44      by=8,r0=2.37,r=1,r_presym=1,r_sym=0,incu=3.92
2       21.51   SHOW_SYMPTOM    1       .
2       21.51   REMOVAL 1       popsize=57
2       22.16   SHOW_SYMPTOM    8       .
2       22.16   REMOVAL 8       popsize=56
2       22.62   INFECTION       42      by=44,r0=1.49,r=0,r_presym=0,r_sym=0,incu=4.30
2       24.27   SHOW_SYMPTOM    44      .
2       24.27   REMOVAL 44      popsize=55
2       26.92   SHOW_SYMPTOM    42      .
2       26.92   REMOVAL 42      popsize=54
2       26.92   END     54      popsize=54,prop_asym=0.216
3       0.00    INFECTION       0       r0=2.00,r=2,r_presym=2,r_sym=0,incu=4.19

which I assume would be pretty self-explanatory.

Summary report from multiple replicates

At the end of each command, a report will be given to summarize key statistics from multiple replicated simulations. The output contains the following keys and their values

Data analysis tools

Because all the events have been recorded in the log files, it should not be too difficult for you to write your own script (e.g. in R) to analyze them and produce nice figures. We however made a small number of tools available. Please feel free to submit or own script for inclusion in the contrib library.

time_vs_size.R

The contrib/time_vs_size.R script provides an example on how to process the data and produce a figure. It can be used as follows:

Rscript time_vs_size.R  simulation.log 'COVID19 Outbreak Simulation with Default Paramters' time_vs_size.png

and produces a figure

merge_summary.py

contrib/merge_summary.py is a script to merge summary stats from multiple simulation runs.

Acknowledgements

This tool has been developed and maintained by Dr. Bo Peng, associate professor at the Baylor College of Medicine, with guidance from Dr. Christopher Amos, from the Institute for Clinical and Translational Research, Baylor College of Medicine. Contributions to this project are welcome. Please refer to the LICENSE file for proper use and distribution of this tool.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.