drc

docs/tutorials/t9.ipynb

@@ -0,0 +1,188 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# T9 - Advanced features\n",
+    "\n",
+    "This tutorial covers advanced features of Covasim, including custom population options and changing the internal computational methods.\n",
+    "\n",
+    "## Defining populations with SynthPops\n",
+    "\n",
+    "For complex populations, we suggest using [SynthPops](http://synthpops.org), a Python library designed specifically for this purpose. In contrast the population methods built-in to Covasim, SynthPops uses data to produce synthetic populations that are statistically indistinguishable from real ones. For a relatively complex example of how SynthPops was used to create a complex school network for the Seattle region, see [here](https://github.com/institutefordiseasemodeling/testing-the-waters/blob/main/covasim_schools/school_pop.py).\n",
+    "\n",
+    "## Defining contact layers\n",
+    "\n",
+    "As mentioned in Tutorial 1, contact layers are the graph connecting the people in the simulation. Each person is a node, and each contact is an edge. While enormous complexity can be used to define realistic contact networks, a reasonable approximation in many cases is random connectivity, often with some age assortativity. Here is an example for generating a new contact layer, nominally representing public transportation, and adding it to a simulation:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import covasim as cv\n",
+    "cv.options.set(dpi=100, show=False, close=True, verbose=0) # Standard options for Jupyter notebook\n",
+    "\n",
+    "# Create the first sim\n",
+    "orig_sim = cv.Sim(pop_type='hybrid', n_days=120, label='Default hybrid population')\n",
+    "orig_sim.initialize() # Initialize the population\n",
+    "\n",
+    "# Create the second sim\n",
+    "sim = orig_sim.copy()\n",
+    "\n",
+    "# Define the new layer, 'transport'\n",
+    "n_people = len(sim.people)\n",
+    "n_contacts_per_person = 0.5\n",
+    "n_contacts = int(n_contacts_per_person*n_people)\n",
+    "contacts_p1 = cv.choose(max_n=n_people, n=n_contacts)\n",
+    "contacts_p2 = cv.choose(max_n=n_people, n=n_contacts)\n",
+    "beta = np.ones(n_contacts)\n",
+    "layer = cv.Layer(p1=contacts_p1, p2=contacts_p2, beta=beta) # Create the new layer\n",
+    "\n",
+    "# Add this layer in and re-initialize the sim\n",
+    "sim.people.contacts.add_layer(transport=layer)\n",
+    "sim.reset_layer_pars() # Automatically add layer 'q' to the parameters using default values\n",
+    "sim.initialize() # Reinitialize\n",
+    "sim.label = f'Transport layer with {n_contacts_per_person} contacts/person'\n",
+    "\n",
+    "# Run and compare\n",
+    "msim = cv.MultiSim([orig_sim, sim])\n",
+    "msim.run()\n",
+    "msim.plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Defining custom population properties\n",
+    "\n",
+    "Another useful feature is adding additional features to people, for use in subtargeting. For example, this example shows how to define a subpopulation with higher baseline mortality rates. This is a simple example illustrating how you would identify and target people based on whether or not the have a prime-number index, based on the protecting the elderly example from Tutorial 1."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import sciris as sc\n",
+    "import covasim as cv\n",
+    "\n",
+    "def protect_the_prime(sim):\n",
+    "    if sim.t == sim.day('2020-04-01'):\n",
+    "        are_prime = sim.people.prime\n",
+    "        sim.people.rel_sus[are_prime] = 0.0\n",
+    "\n",
+    "pars = dict(\n",
+    "    pop_type = 'hybrid',\n",
+    "    pop_infected = 100,\n",
+    "    n_days = 90,\n",
+    "    verbose = 0,\n",
+    ")\n",
+    "\n",
+    "# Default simulation\n",
+    "orig_sim = cv.Sim(pars, label='Default')\n",
+    "\n",
+    "# Create the simulation\n",
+    "sim = cv.Sim(pars, label='Protect the prime', interventions=protect_the_prime)\n",
+    "sim.initialize() # Initialize to create the people array\n",
+    "sim.people.prime = np.array([sc.isprime(i) for i in range(len(sim.people))]) # Define whom to target\n",
+    "\n",
+    "# Run and plot\n",
+    "msim = cv.MultiSim([orig_sim, sim])\n",
+    "msim.run()\n",
+    "msim.plot()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Changing Numba options\n",
+    "\n",
+    "Finally, this example shows how you can change the default Numba calculation options. It's not recommended – especially running with multithreading, which is faster but gives stochastically unreproducible results – but it's there if you want it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import covasim as cv\n",
+    "\n",
+    "# Create a standard 32-bit simulation\n",
+    "sim32 = cv.Sim(label='32-bit, single-threaded (default)', verbose='brief')\n",
+    "sim32.run()\n",
+    "\n",
+    "# Use 64-bit instead of 32\n",
+    "cv.options.set(precision=64)\n",
+    "sim64 = cv.Sim(label='64-bit, single-threaded', verbose='brief')\n",
+    "sim64.run()\n",
+    "\n",
+    "# Use parallel threading\n",
+    "cv.options.set(numba_parallel=True)\n",
+    "sim_par = cv.Sim(label='64-bit, multi-threaded', verbose='brief')\n",
+    "sim_par.run()\n",
+    "\n",
+    "# Reset to defaults\n",
+    "cv.options.set('defaults')\n",
+    "sim32b = cv.Sim(label='32-bit, single-threaded (restored)', verbose='brief')\n",
+    "sim32b.run()\n",
+    "\n",
+    "# Plot\n",
+    "msim = cv.MultiSim([sim32, sim64, sim_par, sim32b])\n",
+    "msim.plot()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.6.13"
+  },
+  "pycharm": {
+   "stem_cell": {
+    "cell_type": "raw",
+    "metadata": {
+     "collapsed": false
+    },
+    "source": []
+   }
+  },
+  "toc": {
+   "base_numbering": 1,
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

examples/t1_full_usage_example.py

@@ -0,0 +1,25 @@
+'''
+Full Covasim usage example, including a custom intervention
+'''
+
+import covasim as cv
+
+# Custom intervention -- see Tutorial 5
+def protect_elderly(sim):
+    if sim.t == sim.day('2020-04-01'):
+        elderly = sim.people.age>70
+        sim.people.rel_sus[elderly] = 0.0
+
+pars = dict(
+    pop_size = 50e3, # Have 50,000 people total in the population
+    pop_infected = 100, # Start with 100 infected people
+    n_days = 90, # Run the simulation for 90 days
+    verbose = 0, # Do not print any output
+)
+
+# Running with multisims -- see Tutorial 3
+s1 = cv.Sim(pars, label='Default')
+s2 = cv.Sim(pars, interventions=protect_elderly, label='Protect the elderly')
+msim = cv.MultiSim([s1, s2])
+msim.run()
+fig = msim.plot(to_plot=['cum_deaths', 'cum_infections'])

examples/t1_hello_world.py

@@ -0,0 +1,20 @@
+'''
+Simple Covasim usage
+'''
+
+import covasim as cv
+
+# Set the parameters of the simulation
+pars = dict(
+    pop_size = 50e3,
+    pop_infected = 100,
+    start_day = '2020-04-01',
+    end_day = '2020-06-01',
+)
+
+# Run the simulation
+sim = cv.Sim(pars)
+sim.run()
+
+# Plot the results
+fig = sim.plot()

examples/t1_populations.py

@@ -0,0 +1,15 @@
+'''
+Illustrate different population options
+'''
+
+import covasim as cv
+
+pars = dict(
+    pop_size = 10_000, # Alternate way of writing 10000
+    pop_type = 'hybrid',
+    location = 'Bangladesh', # Case insensitive
+)
+
+sim = cv.Sim(pars)
+sim.initialize() # Create people
+sim.people.plot() # Show statistics of the people

examples/t2_save_load_sim.py

@@ -0,0 +1,14 @@
+'''
+Demonstration of saving and resuming a partially-run sim
+'''
+
+import covasim as cv
+
+sim_orig = cv.Sim(start_day='2020-04-01', end_day='2020-06-01', label='Load & save example')
+sim_orig.run(until='2020-05-01')
+sim_orig.save('my-half-finished-sim.sim')
+
+sim = cv.load('my-half-finished-sim.sim')
+sim['beta'] *= 0.3
+sim.run()
+sim.plot(to_plot=['new_infections', 'n_infectious', 'cum_infections'])

examples/t3_nested_multisim.py

@@ -0,0 +1,22 @@
+'''
+Example of running a nested multisim object
+'''
+
+import covasim as cv
+
+n_sims = 3
+betas = [0.012, 0.016, 0.018]
+
+msims = []
+for beta in betas:
+    sims = []
+    for s in range(n_sims):
+        sim = cv.Sim(pop_size=10e3, beta=beta, rand_seed=s, label=f'Beta = {beta}')
+        sims.append(sim)
+    msim = cv.MultiSim(sims)
+    msim.run()
+    msim.mean()
+    msims.append(msim)
+
+merged = cv.MultiSim.merge(msims, base=True)
+merged.plot(color_by_sim=True)

examples/t3_scenarios.py

@@ -0,0 +1,32 @@
+'''
+Example of a simple set of scenarios
+'''
+
+import covasim as cv
+
+# Set base parameters -- these will be shared across all scenarios
+basepars = {'pop_size':10e3}
+
+# Configure the settings for each scenario
+scenarios = {'baseline': {
+              'name':'Baseline',
+              'pars': {}
+              },
+            'high_beta': {
+              'name':'High beta (0.020)',
+              'pars': {
+                  'beta': 0.020,
+                  }
+              },
+            'low_beta': {
+              'name':'Low beta (0.012)',
+              'pars': {
+                  'beta': 0.012,
+                  }
+              },
+             }
+
+# Run and plot the scenarios
+scens = cv.Scenarios(basepars=basepars, scenarios=scenarios)
+scens.run()
+scens.plot()

examples/t4_loading_data.py

@@ -0,0 +1,14 @@
+'''
+Loading and plotting data
+'''
+
+import covasim as cv
+
+pars = dict(
+    start_day = '2020-02-01',
+    end_day   = '2020-04-11',
+    beta      = 0.015,
+)
+sim = cv.Sim(pars=pars, datafile='example_data.csv', interventions=cv.test_num(daily_tests='data'))
+sim.run()
+sim.plot(to_plot=['cum_tests', 'cum_diagnoses', 'cum_deaths'])

examples/t5_change_beta.py

@@ -0,0 +1,22 @@
+'''
+Demonstrate change beta and clip edges interventions
+'''
+
+import covasim as cv
+
+# Define baseline parameters and sim
+pars = dict(
+    start_day = '2020-03-01',
+    end_day   = '2020-06-01',
+    pop_type  = 'hybrid',
+)
+orig_sim = cv.Sim(pars, label='Baseline')
+
+# Define sim with change_beta
+cb = cv.change_beta(days=['2020-04-15', '2020-05-01', '2020-05-15'], changes=[0.2, 1.5, 0.7])
+sim = cv.Sim(pars, interventions=cb, label='With beta changes')
+
+# Run and plot
+msim = cv.MultiSim([orig_sim, sim])
+msim.run()
+msim.plot()

examples/t5_contact_tracing.py

@@ -0,0 +1,22 @@
+''' Demonstrate contact tracing '''
+
+import covasim as cv
+
+# Define the testing and contact tracing interventions
+tp = cv.test_prob(symp_prob=0.2, asymp_prob=0.001, symp_quar_prob=1.0, asymp_quar_prob=1.0)
+ct = cv.contact_tracing(trace_probs=dict(h=1.0, s=0.5, w=0.5, c=0.3))
+
+# Define the default parameters
+pars = dict(
+    pop_type      = 'hybrid',
+    pop_size      = 50e3,
+    pop_infected  = 100,
+    start_day     = '2020-02-01',
+    end_day       = '2020-05-01',
+    interventions = [tp, ct],
+)
+
+# Create, run, and plot the simulation
+sim = cv.Sim(pars)
+sim.run()
+sim.plot(to_plot=['new_infections', 'new_tests', 'new_diagnoses', 'cum_diagnoses', 'new_quarantined', 'test_yield'])