Quick Guide¶

Abstract

This is a basic guide on how install dependencies, prepare and run a simulation using COMORBUSS

Dependencies¶

For simulation and output¶

Basic dependencies for running simulations:

Python (tested with version 3.7.6)
NumPy (version 1.18)
Matplotlib
Seaborn
h5dict (v0.2.2)
Pandas
SciPy
networkx
tqdm
numba

All the above dependencies, except for h5dict, comes included with the Anaconda Python Distribution, after Anaconda is installed, both can be installed with pip:

python -m pip install "h5dict>=0.2.2"

Tip

With Anaconda and h5dict installed you have all dependencies, if you just want to run COMORBUSS and generate plots with results you can now skip to Installation.

Alternative dependencies with mini-conda¶

In a scenario where running a full Anaconda is not feasible an alternative is to run COMORBUSS with miniconda, a local installation of miniconda on a 64 bits linux can be done with:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
chmod a+x Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh

Then the dependencies can be installed with:

conda install numpy scipy pandas h5py matplotlib seaborn networkx numba
python -m pip install "h5dict>=0.2.2"

Alternative dependencies without Anaconda (not recommended)¶

Without Anaconda dependencies can be installed with pip:

pyhton -m pip install 'numpy>=1.18' scipy matplotlib seaborn "h5dict>=0.2.2" pandas networkx tqdm numba

For interactive visualization¶

Info

Only used on Visualizer module, not needed for basic simulation and output of results.

PyGame

PyGame can be also installed with pip:

python -m pip install pygame

Installation¶

For instalantion as a python module first clone the repository, than run the setup.py script:

git clone https://gitlab.com/ggoedert/comorbuss.git
cd comorbuss/main
python setup.py install

Tip

COMORBUSS doesn't need do be installed in your system, you can clone it with git (recomended method) or download it as an zip, and any script using COMORBUSS from the main folder.

Running COMORBUSS¶

COMORBUSS is designed to be run with a customized script, we provide the following examples:

the simulation_sao_carlos.py file, where the most common parameters are set;
the jupyter-examples folder in the repository.

There is also a simple example below.

Simple Example¶

But now we will construct your own script from scratch, let's start with the bare minimum to run COMORBUSS and output results:

from comorbuss import community, Analysis

parameters = {}

comm = community(**parameters)
comm.simulate()

analysis = Analysis.from_comm(comm)
analysis.plot_SEIR()
analysis.close()

In the first line from comorbuss import community, Analysis we import the community class that is the main class in COMORBUSS to run simulations and the Analysis, where most of the results analysis and output tools are.

After that we create an empty dictionary parameters = {} and use it to initialize the community object comm = community(**parameters). Note that we are not passing any parameters, in this case the community object will be initialized with it's default parameters. Now we can run the simulation itself with comm.simulate(), this is the longest step in the simulation, depending on the number of particles and the machine it's running it can take from several seconds to several minutes.

For last we create the plot object from the class plots using the simulated community as parameter to load data plot = plots.from_comm(comm), and output a plot of the progression of states during the simulation plot.plot_SEIR().

Setting parameters¶

Now we can set a few parameters for the simulation, for example let's change the number of particles to 2500, increase the infection probability to 10% and turn on a quarantine intervention for diagnosed particles:

from comorbuss import community, quarantines, Analysis, diagnostics

parameters = {
    'number_of_particles': 2500,
    'inf_probability': 0.1,
    'diagnostics': [diagnostics.PCR],
    'quarantines': [quarantines.DIAGNOSTICS],
}

comm = community(**parameters)
comm.simulate()

analysis = Analysis.from_comm(comm)
analysis.plot_SEIR()
analysis.close()

Important

All parameters are set inside the parameters dictionary, when a parameter is not set the code assumes it's default value.

Let's use one more tool to set parameters, COMORBUSS comes with a demographic database for all Brazilian cities, and we can load it's data from the database using the load_demographics() function from the module comorbuss.tools:

from comorbuss import community, diagnostics, quarantines, Analysis
from comorbuss.settings import DEMO_DATA_FILE
from comorbuss.tools import load_demographics

parameters = {
    'number_of_particles': 2500,
    'inf_probability': 0.1,
    'diagnostics': [diagnostics.PCR],
    'quarantines': [quarantines.DIAGNOSTICS],
}

parameters = load_demographics("blumenau", "SC", parameters)

comm = community(**parameters)
comm.simulate()

analysis = Analysis.from_comm(comm)
analysis.plot_SEIR()
analysis.close()

To do this we first import the constant DEMO_DATA_FILE that is the address of the csv where the database is stored and then import load_demographics from comorbuss.tools.

Now we can just call load_demographics(DEMO_DATA_FILE, "blumenau", "SC", parameters) and store it's results back in the parameters dictionary. The load_demographics() loads the demographic parameters on the dictionary and preserves all other parameters. In this example demographic data from the city of Blumenau, SC will be loaded, overwriting the default demographic parameters in the simulation.

São Carlos, SP example¶

And for last in the main/simulation_sao_carlos.py we have a more complete example of COMORBUSS configured to a real city and examples of most of possible interventions for the user to turn on or off.