Merge pull request #237 from InstituteforDiseaseModeling/master

Update with Covasim v1.0.1

.github/workflows/ubuntu.yaml → .github/workflows/test.yaml

@@ -9,7 +9,7 @@ jobs:
       max-parallel: 8
       matrix:
         python-version: ['3.7']
-    name: Install and test
+    name: Run tests
     steps:
       - name: Set repo owner env variable
         shell: python
@@ -36,12 +36,12 @@ jobs:
         run: |
           python setup.py develop --install-dir ~/.cache/site-packages
           pip install pytest
-      - name: Run tests
+      - name: Run integration tests
         working-directory: ./tests
         run: pytest test*.py --durations=0 # Run actual tests
       - name: Run unit tests
         working-directory: ./tests/unittests
         run: pytest test*.py --durations=0 # Run actual tests
-      - name: Run other examples
-        working-directory: ./
-        run: pytest ./examples/*.py ./covasim/cruise_ship/test*.py
+      - name: Run cruise ship tests
+        working-directory: ./covasim/cruise_ship
+        run: pytest test*.py

.platform/covasim-deployment.yaml

@@ -33,7 +33,7 @@ spec:
         service: covasim
     spec:
       containers:
-      - image: "registry.hub.docker.com/jules2689/covasim:latest"
+      - image: "registry.hub.docker.com/idmod/covasim:latest-webapp"
         name: covasim
         ports:
         - containerPort: 80

CHANGELOG.rst

@@ -1,9 +1,95 @@
 What's new
 ==========
 
-All notable changes to the codebase are documented in this file. Note: in many cases,
-changes from multiple patch versions are grouped together, so numbering will not be
-strictly consecutive.
+All notable changes to the codebase are documented in this file. Note: in many cases, changes from multiple patch versions are grouped together, so numbering will not be strictly consecutive.
+
+Version 1.0.1 (2020-05-09)
+--------------------------
+- Added argument ``as_date`` for ``sim.date()`` to return a ``datetime`` object instead of a string.
+- Fixed plotting of interventions in the webapp.
+- Removed default 1-hour time limit for simulations.
+- GitHub info: PR `490 <https://github.com/amath-idm/covasim/pull/490>`__, previous head ``9a6c23b``
+
+
+Version 1.0.0 (2020-05-08)
+--------------------------
+- Official release of Covasim.
+- Made scenario and simulation plotting more flexible: ``to_plot`` can now simply be a list of results keys, e.g. ``cum_deaths``.
+- Added additional tests, increasing test coverage from 67% to 92%.
+- Fixed bug in ``cv.save()``.
+- Added ``reset()`` to MultiSim that undoes a ``reduce()`` or ``combine()`` call.
+- General code cleaning: made exceptions raised more consistent, removed unused functions, etc.
+- GitHub info: PR `487 <https://github.com/amath-idm/covasim/pull/487>`__, previous head ``c8ca32d``
+
+
+Version 0.32.1 (2020-05-06)
+---------------------------
+- Allow ``until`` to be a date, e.g. ``sim.run(until='2020-05-06')``.
+- Added ``ipywidgets`` dependency since otherwise the webapp breaks due to a `bug <https://github.com/plotly/plotly.py/issues/2443>`__ with the latest Plotly version (4.7). 
+
+
+Version 0.32.0 (2020-05-05)
+---------------------------
+- Changed the edges of the contact network from being directed to undirected, halving the amount of memory required and making contact tracing and edge clipping more realistic.
+- Added comorbidities to the prognoses parameters.
+- GitHub info: PR `482 <https://github.com/amath-idm/covasim/pull/482>`__, previous head ``029585f``
+
+
+Version 0.31.0 (2020-05-05)
+---------------------------
+- Added age-susceptible odds ratios, and modified severe and critical progression probabilities. To compensate, default ``beta`` has been increased from 0.015 to 0.016. To restore previous behavior (which was based on the `Imperial paper <https://www.imperial.ac.uk/media/imperial-college/medicine/mrc-gida/2020-03-16-COVID19-Report-9.pdf>`__), set ``beta=0.015`` and set the following values in ``sim.pars['prognoses']``::
+
+    sus_ORs[:]   = 1.0
+    severe_probs = np.array([0.00100, 0.00100, 0.01100, 0.03400, 0.04300, 0.08200, 0.11800, 0.16600, 0.18400])
+    crit_probs   = np.array([0.00004, 0.00011, 0.00050, 0.00123, 0.00214, 0.00800, 0.02750, 0.06000, 0.10333])
+
+- Relative susceptibility and transmissibility (i.e., ``sim.people.rel_sus``) are now set when the population is initialized (before, they were modified dynamically when a person became infected or recovered). This means that modifying them before a simulation starts, or during a simulation, should be more robust.
+- Reordered results dictionary to start with cumulative counts.
+- ``sim.export_pars()`` now accepts a filename to save to.
+- Added a ``tests/regression`` folder with previous versions of default parameter values.
+- Changed ``pars['n_beds']`` to interpret 0 or ``None`` as no bed constraint.
+- GitHub info: PR `480 <https://github.com/amath-idm/covasim/pull/480>`__, previous head ``c7171f8``
+
+
+Version 0.30.4 (2020-05-04)
+---------------------------
+- Changed the detailed transmission tree (``sim.people.transtree.detailed``) to include much more information.
+- Added animation method to transmission tree: ``sim.people.transtree.animate()``.
+- Added support to generate populations on the fly in SynthPops.
+- Adjusted the default arguments for ``test_prob`` and fixed a bug with ``test_num`` not accepting date input.
+- Added ``tests/devtests/intervention_showcase.py``, using and comparing all available interventions.
+
+
+Version 0.30.3 (2020-05-03)
+---------------------------
+- Fixed bugs in dynamic scaling; see ``tests/devtests/dev_test_rescaling.py``. When using ``pop_scale>1``, the recommendation is now to use ``rescale=True``.
+- In ``cv.test_num()``, renamed argument from ``sympt_test`` to ``symp_test`` for consistency.
+- Added ``plot_compare()`` method to ``MultiSim``.
+- Added ``labels`` arguments to plotting methods, to allow custom labels to be used.
+
+
+Version 0.30.2 (2020-05-02)
+---------------------------
+- Updated ``r_eff`` to use a new method based on daily new infections. The previous version, where infections were counted from when someone recovered or died, is available as ``sim.compute_r_eff(method='outcome')``, while the traditional method, where infections are counted from the day someone becomes infectious, is available via ``sim.compute_r_eff(method='infectious')``.
+
+
+Version 0.30.1 (2020-05-02)
+---------------------------
+- Added ``end_day`` as a parameter, allowing an end date to be specified instead of a number of days.
+- ``Sim.run()`` now displays the date being simulated.
+- Added a ``par_args`` arugument to ``multi_run()``, allowing arguments (e.g. ``ncpus``) to be passed to ``sc.parallelize()``.
+- Added a ``compare()`` method to multisims and stopped people from being saved by default.
+- Fixed bug whereby intervention were not getting initialized if they were added to a sim after it was initialized.
+
+
+Version 0.30.0 (2020-05-02)
+---------------------------
+- Added new ``MultiSim`` class for plotting a single simulation with uncertainty.
+- Added ``low`` and ``high`` attributes to the ``Result`` object.
+- Refactored plotting to increase consistency between ``sim.plot()``, ``sim.plot_result()``, ``scens.plot()``, and ``multisim.plot()``.
+- Doubling time calculation defaults have been updated to use a window of 3 days and a maximum of 30 days.
+- Added an ``until`` argument to ``sim.run()``, to make it easier to run a partially completed sim and then resume. See ``tests/devtests/test_run_until.py``.
+- Fixed a bug whereby ``cv.clip_edges()`` with no end day specified resulted in large sim files when saved.
 
 
 Version 0.29.9 (2020-04-28)

README.rst

@@ -8,13 +8,13 @@ indicators such as numbers of infections and peak hospital demand. Covasim can
 also be used to explore the potential impact of different interventions, including
 social distancing, school closures, testing, contact tracing, and quarantine.
 
-The Covasim webapp is available at https://covasim.idmod.org.
+The Covasim webapp is available at https://app.covasim.org.
 
 Questions or comments can be directed to [email protected], or on this project's
 GitHub_ page. Full information about Covasim is provided in the documentation_.
 
 .. _GitHub: https://github.com/institutefordiseasemodeling/covasim
-.. _documentation: https://institutefordiseasemodeling.github.io/covasim-docs
+.. _documentation: https://docs.covasim.org
 
 .. contents:: Contents
    :local:
@@ -32,6 +32,7 @@ more information, see documentation for venv_ or Anaconda_.
 .. _venv: https://docs.python.org/3/tutorial/venv.html
 .. _Anaconda: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
 
+
 Quick start guide
 ==================
 
@@ -93,7 +94,7 @@ Module structure
 ================
 
 All core model code is located in the ``covasim`` subfolder; standard usage is
-``import covasim as cv``. The other subfolders, ``cruise_ship`` and ``webapp``, are
+``import covasim as cv``. The other subfolders, ``cruise_ship``, ``data``, and ``webapp``, are
 also described below.
 
 The model consists of two core classes: the ``Person`` class (which contains
@@ -116,25 +117,36 @@ The structure of the ``covasim`` folder is as follows:
 * ``utils.py``: Functions for choosing random numbers, many based on Numba, plus other helper functions.
 * ``version.py``: Version, date, and license information.
 
-cruise_ship
+
+Cruise ship
 -----------
 
 A version of the Covasim model specifically adapted for modeling the Diamond
 Princess cruise ship. It uses its own parameters file (``parameters.py``) and has
 slight variations to the model (``model.py``).
 
-webapp
+
+Data
+----
+
+This folder contains loading scripts for the epidemiological data in the root ``data`` folder, as well as data on age distributions for different countries and household sizes.
+
+
+
+Webapp
 ------
 
 For running the interactive web application. See the `webapp README`_ for more information.
 
 .. _webapp README: https://github.com/InstituteforDiseaseModeling/covasim/tree/master/covasim/webapp
 
+
 Other folders
 =============
 
 Please see the readme in each subfolder for more information.
 
+
 bin
 ---
 
@@ -145,33 +157,39 @@ This folder contains a command-line interface (CLI) version of Covasim; example
 Note: the CLI is currently not compatible with Windows. You will need to add
 this folder to your path to run from other folders.
 
+
 data
 ----
 
 Scripts to automatically scrape data (including demographics and COVID epidemiology data),
 and the data files themselves (which are not part of the repository).
 
+
 docker
 ------
 
 This folder contains the ``Dockerfile`` and other files that allow Covasim to be
 run as a webapp via Docker.
 
+
 examples
 --------
 
 This folder contains demonstrations of simple Covasim usage.
 
+
 licenses
 --------
 
 Licensing information and legal notices.
 
+
 tests
 -----
 
 Integration, development, and unit tests.
 
+
 sweep
 -----
 

covasim/README.rst

@@ -2,7 +2,7 @@
 Parameters
 ==========
 
-This file describes the expected behavior of each parameter in the model. Note: the term "overall infection rate" can be explored using ``sim.results['doubling_time']`` and ``sim.results['r_eff']`` (a higher infection rate means lower doubling times and higher *R\_eff*), as well as by simply looking at the epidemic curves.
+This file describes each of the input parameters in Covasim. Note: the overall infection rate can be explored using ``sim.results['doubling_time']`` and ``sim.results['r_eff']`` (a higher infection rate means lower doubling times and higher *R\_eff*), as well as by simply looking at the epidemic curves.
 
 Population parameters
 ---------------------
@@ -14,7 +14,8 @@ Population parameters
 Simulation parameters
 ---------------------
 * ``start_day``  = Start day of the simulation
-* ``n_days``     = Number of days of run, if end_day isn't used
+* ``end_day``    = End day of the simulation
+* ``n_days``     = Number of days to run, if end_day isn't specified
 * ``rand_seed``  = Random seed, if None, don't reset
 * ``verbose``    = Whether or not to display information during the run -- options are 0 (silent), 1 (default), 2 (everything)
 
@@ -32,30 +33,29 @@ Basic disease transmission
 * ``dynam_layer`` = Which layers are dynamic; set below
 * ``beta_layer``  = Transmissibility per layer; set below
 * ``n_imports``   = Average daily number of imported cases (actual number is drawn from Poisson distribution)
-* ``beta_dist``   = Distribution to draw individual level transmissibility
-* ``viral_dist``  = The time varying viral load (transmissibility)
+* ``beta_dist``   = Distribution to draw individual level transmissibility; see https://wellcomeopenresearch.org/articles/5-67
+* ``viral_dist``  = The time varying viral load (transmissibility); estimated from Lescure 2020, Lancet, https://doi.org/10.1016/S1473-3099(20)30200-0
 
 Efficacy of protection measures
 -------------------------------
-* ``asymp_factor`` = Multiply beta by this factor for asymptomatic cases
-* ``diag_factor``  = Multiply beta by this factor for diganosed cases
+* ``asymp_factor`` = Multiply beta by this factor for asymptomatic cases; no statistically significant difference in transmissibility: https://www.sciencedirect.com/science/article/pii/S1201971220302502
+* ``diag_factor``  = Multiply beta by this factor for diganosed cases; based on intervention strength
 * ``quar_eff``     = Quarantine multiplier on transmissibility and susceptibility; set below
-* ``quar_period``  = Number of days to quarantine for
+* ``quar_period``  = Number of days to quarantine for; assumption based on standard policies
 
 Time for disease progression
 ----------------------------
-* ``exp2inf``  = Duration from exposed to infectious
-* ``inf2sym``  = Duration from infectious to symptomatic
-* ``sym2sev``  = Duration from symptomatic to severe symptoms
-* ``sev2crit`` = Duration from severe symptoms to requiring ICU
+* ``exp2inf``  = Duration from exposed to infectious; see Lauer et al., https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7081172/, subtracting inf2sim duration
+* ``inf2sym``  = Duration from infectious to symptomatic; see Linton et al., https://doi.org/10.3390/jcm9020538
+* ``sym2sev``  = Duration from symptomatic to severe symptoms; see Linton et al., https://doi.org/10.3390/jcm9020538Duration from severe symptoms to requiring ICU; see Wang et al., https://jamanetwork.com/journals/jama/fullarticle/2761044Duration from severe symptoms to requiring ICU
 
 Time for disease recovery
 -------------------------
-* ``asym2rec`` = Duration for asymptomatics to recover
-* ``mild2rec`` = Duration from mild symptoms to recovered
-* ``sev2rec``  = Duration from severe symptoms to recovered
-* ``crit2rec`` = Duration from critical symptoms to recovered
-* ``crit2die`` = Duration from critical symptoms to death
+* ``asym2rec`` = Duration for asymptomatic people to recover; see Wölfel et al., https://www.nature.com/articles/s41586-020-2196-x
+* ``mild2rec`` = Duration for people with mild symptoms to recover; see Wölfel et al., https://www.nature.com/articles/s41586-020-2196-x
+* ``sev2rec``  = Duration for people with severe symptoms to recover, 22.6 days total; see Verity et al., https://www.medrxiv.org/content/10.1101/2020.03.09.20033357v1.full.pdf
+* ``crit2rec`` = Duration for people with critical symptoms to recover, 22.6 days total; see Verity et al., https://www.medrxiv.org/content/10.1101/2020.03.09.20033357v1.full.pdf
+* ``crit2die`` = Duration from critical symptoms to death, 17.8 days total; see Verity et al., https://www.medrxiv.org/content/10.1101/2020.03.09.20033357v1.full.pdf
 
 Severity parameters
 -------------------
@@ -65,15 +65,15 @@ Severity parameters
 * ``rel_crit_prob``   = Scale factor for proportion of severe cases that become critical
 * ``rel_death_prob``  = Scale factor for proportion of critical cases that result in death
 * ``prog_by_age``     = Whether to set disease progression based on the person's age
-* ``prognoses``       = Populate this later
+* ``prognoses``       = The actual arrays of prognoses by age; this is populated later
 
 Events and interventions
 ------------------------
-* ``interventions`` = List of Intervention instances
+* ``interventions`` = The interventions present in this simulation; populated by the user
 * ``interv_func``   = Custom intervention function
-* ``timelimit``     = Time limit for a simulation (seconds)
+* ``timelimit``     = Time limit for the simulation (seconds)
 * ``stopping_func`` = A function to call to stop the sim partway through
 
 Health system parameters
 --------------------------
-* ``n_beds`` = Baseline assumption is that there's no upper limit on the number of beds i.e. there's enough for everyone
+* ``n_beds`` = The number of beds available for severely/critically ill patients (default is no constraint)

covasim/__init__.py

@@ -10,11 +10,12 @@
 from .utils         import *
 from .misc          import *
 from .defaults      import *
+from .plotting      import *
 from .base          import *
 from .parameters    import *
 from .people        import *
 from .population    import *
 from .interventions import *
 from .sim           import *
 from .run           import *
-from .plotting      import *
+