Merge branch 'master' of https://github.com/InstituteforDiseaseModeli…

…ng/covasim

.github/workflows/tests.yaml

@@ -19,12 +19,13 @@ jobs:
           python-version: ${{ matrix.python-version }}
           architecture: x64
       - name: Install Covasim
-        run: python setup.py develop
+        run: pip install -e .
+      - name: Install tests
+        working-directory: ./tests
+        run: pip install -r requirements_test.txt
       - name: Run integration tests
         working-directory: ./tests
-        run: |
-          pip install pytest
-          pytest test*.py --durations=0 # Run actual tests
+        run: pytest -v test_*.py --workers auto --durations=0
       - name: Run unit tests
         working-directory: ./tests/unittests
-        run: pytest test*.py --durations=0 # Run actual tests
+        run: pytest -v test_*.py --workers auto --durations=0

.readthedocs.yml

@@ -24,7 +24,7 @@ python:
   version: 3.8
   install:
     - requirements: docs/requirements.txt
-    - method: setuptools
+    - method: pip
       path: .
   system_packages: true
 

CODE_OF_CONDUCT.rst

@@ -1,22 +1,16 @@
-====================================
-Contributor covenant code of conduct
-====================================
+===============
+Code of conduct
+===============
 
 Our pledge
 ==========
 
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
+We believe that a diverse, equitable, and inclusive environment is essential for producing the best quality software. In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in Covasim development and the Covasim community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
 
 Our standards
 =============
 
-Examples of behavior that contributes to creating a positive environment
-include:
+Examples of behavior that contributes to creating a positive environment include:
 
 *   Using welcoming and inclusive language
 *   Being respectful of differing viewpoints and experiences
@@ -26,57 +20,35 @@ include:
 
 Examples of unacceptable behavior by participants include:
 
-*   The use of sexualized language or imagery and unwelcome sexual attention or
-    advances
+*   The use of sexualized language or imagery and unwelcome sexual attention or advances
 *   Trolling, insulting/derogatory comments, and personal or political attacks
 *   Public or private harassment
-*   Publishing others' private information, such as a physical or electronic
-    address, without explicit permission
-*   Other conduct which could reasonably be considered inappropriate in a
-    professional setting
+*   Publishing others' private information, such as a physical or electronic address, without explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a professional setting
 
 Our responsibilities
 ====================
 
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+Covasim maintainers are responsible for clarifying the standards of acceptable behavior and will take appropriate and fair corrective action in response to any instances of unacceptable behavior.
 
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
+Covasim maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
 Scope
 =====
 
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing Covasim or its community. Examples of representing the Covasim project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
 
 Enforcement
 ===========
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at [email protected]. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The Covasim team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
+Covasim maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of Covasim's leadership.
 
 Attribution
 ===========
 
-This Code of Conduct is adapted from the `Contributor Covenant`_, version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html.
+This Code of Conduct is adapted from the `Contributor Covenant`_, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html.
 
 .. _Contributor Covenant: https://www.contributor-covenant.org
 

FAQ.rst

@@ -12,16 +12,22 @@ This document contains answers to frequently (and some not so frequently) asked
 Usage questions
 ^^^^^^^^^^^^^^^
 
+What are the system requirements for Covasim?
+---------------------------------------------------------------------------------
+
+If your system can run scientific Python (Numpy, SciPy, and Matplotlib), then you can probably run Covasim. Covasim requires 1 GB of RAM per 1 million people, and can simulate roughly 5-10 million person-days per second. A typical use case, such as a population of 100,000 agents running for 500 days, would require 100 MB of memory and take about 5-10 seconds to run.
+
+
 Can Covasim be run on HPC clusters?
----------------------------------------------------------------------------------------------------------------
+---------------------------------------------------------------------------------
 
 Yes. On a single-node setup, it is quite easy: in fact, ``MultiSim`` objects will automatically scale to the number of cores available. This can also be specified explicitly with e.g. ``msim.run(n_cpus=24)``.
 
 For more complex use cases (e.g. running across multiple virtual machines), we recommend using `Celery <https://docs.celeryproject.org>`__; please `email us <mailto:[email protected]>`__ for more information.
 
 
 What method is best for saving simulation objects?
----------------------------------------------------------------------------------------------------------------
+---------------------------------------------------------------------------------
 
 The recommended way to save a simulation is simply via ``sim.save(filename)``. By default, this does *not* save the people (``sim.people``), since they are very large (i.e., 7 KB without people vs. 7 MB with people for 100,000 agents). However, if you really want to save the people, pass ``keep_people=True``.
 
@@ -37,7 +43,7 @@ Typically, parameters are held constant for the duration of the simulation. Howe
 How can you introduce new infections into a simulation?
 ---------------------------------------------------------------------------------
 
-These are referred to as *importations*. You can set the ``n_imports`` parameter for a fixed number of importations each day (or make it time-varying with ``cv.dynamic_pars()``, as described above). Alternatively, you can infect people directly using ``sim.people.infect()``.
+These are referred to as *importations*. You can set the ``n_imports`` parameter for a fixed number of importations each day (or make it time-varying with ``cv.dynamic_pars()``, as described above). Alternatively, you can infect people directly using ``sim.people.infect()``. Since version 3.0, you can also import specific strains on a given day: e.g., ``cv.Sim(strains=cv.strain('b117', days=50, n_imports=10)``.
 
 
 How do you set custom prognoses parameters (mortality rate, susceptibility etc.)?
@@ -131,12 +137,12 @@ This example illustrates the three different ways to simulation a population of
 
     import covasim as cv
 
-    s1 = cv.Sim(pop_size=100e3, pop_infected=100, pop_scale=1, rescale=True, label='Full population')
-    s2 = cv.Sim(pop_size=20e3,  pop_infected=100, pop_scale=5, rescale=True, label='Dynamic rescaling')
-    s3 = cv.Sim(pop_size=20e3,  pop_infected=20,  pop_scale=5, rescale=False, label='Static rescaling')
+    s1 = cv.Sim(n_days=120, pop_size=200e3, pop_infected=50, pop_scale=1,  rescale=True,  label='Full population')
+    s2 = cv.Sim(n_days=120, pop_size=20e3,  pop_infected=50, pop_scale=10, rescale=True,  label='Dynamic rescaling')
+    s3 = cv.Sim(n_days=120, pop_size=20e3,  pop_infected=5,  pop_scale=10, rescale=False, label='Static rescaling')
 
     msim = cv.MultiSim([s1, s2, s3])
-    msim.run()
+    msim.run(verbose=-1)
     msim.plot()
 
 Note that using the full population and using dynamic rescaling give virtually identical results, whereas static scaling gives slightly different results.

README.rst

@@ -36,34 +36,32 @@ Covasim has been used for analyses in over a dozen countries, both to inform pol
 
 2. **Determining the optimal strategy for reopening schools, the impact of test and trace interventions, and the risk of occurrence of a second COVID-19 epidemic wave in the UK: a modelling study**. Panovska-Griffiths J, Kerr CC, Stuart RM, Mistry D, Klein DJ, Viner R, Bonnell C (2020-08-03). *Lancet Child and Adolescent Health* S2352-4642(20) 30250-9. doi: https://doi.org/10.1016/S2352-4642(20)30250-9.
 
-3. **Modelling the impact of reducing control measures on the COVID-19 pandemic in a low transmission setting**. Scott N, Palmer A, Delport D, Abeysuriya RG, Stuart RM, Kerr CC, Mistry D, Klein DJ, Sacks-Davis R, Heath K, Hainsworth S, Pedrana A, Stoove M, Wilson DP, Hellard M (in press; accepted 2020-09-02). *Medical Journal of Australia* [`Preprint <https://www.mja.com.au/journal/2020/modelling-impact-reducing-control-measures-covid-19-pandemic-low-transmission-setting>`__]; doi: https://doi.org/10.1101/2020.06.11.20127027.
+3. **Estimating and mitigating the risk of COVID-19 epidemic rebound associated with reopening of international borders in Vietnam: a modelling study**. Pham QD, Stuart RM, Nguyen TV, Luong QC, Tran DQ, Phan LT, Dang TQ, Tran DN, Mistry D, Klein DJ, Abeysuriya RG, Oron AP, Kerr CC (2021-04-12). *Lancet Global Health* S2214-109X(21) 00103-0; doi: https://doi.org/10.1016/S2214-109X(21)00103-0.
 
-4. **The role of masks, testing and contact tracing in preventing COVID-19 resurgences: a case study from New South Wales, Australia**. Stuart RM, Abeysuriya RG, Kerr CC, Mistry D, Klein DJ, Gray R, Hellard M, Scott N (under review; posted 2020-09-03). *medRxiv* 2020.09.02.20186742; doi: https://doi.org/10.1101/2020.09.02.20186742.
+4. **Modelling the impact of reducing control measures on the COVID-19 pandemic in a low transmission setting**. Scott N, Palmer A, Delport D, Abeysuriya RG, Stuart RM, Kerr CC, Mistry D, Klein DJ, Sacks-Davis R, Heath K, Hainsworth S, Pedrana A, Stoove M, Wilson DP, Hellard M (in press; accepted 2020-09-02). *Medical Journal of Australia* [`Preprint <https://www.mja.com.au/journal/2020/modelling-impact-reducing-control-measures-covid-19-pandemic-low-transmission-setting>`__]; doi: https://doi.org/10.1101/2020.06.11.20127027.
 
-5. **Schools are not islands: Balancing COVID-19 risk and educational benefits using structural and temporal countermeasures**. Cohen JA, Mistry D, Kerr CC, Klein DJ (under review; posted 2020-09-10). *medRxiv* 2020.09.08.20190942; doi: https://doi.org/10.1101/2020.09.08.20190942.
+5. **The role of masks, testing and contact tracing in preventing COVID-19 resurgences: a case study from New South Wales, Australia**. Stuart RM, Abeysuriya RG, Kerr CC, Mistry D, Klein DJ, Gray R, Hellard M, Scott N (in press; accepted 2021-03-19). *BMJ Open*; doi: https://doi.org/10.1101/2020.09.02.20186742.
 
-6. **The potential contribution of face coverings to the control of SARS-CoV-2 transmission in schools and broader society in the UK: a modelling study**. Panovska-Griffiths J, Kerr CC, Waites W, Stuart RM, Mistry D, Foster D, Klein DJ, Viner R, Bonnell C (under review; posted 2020-10-08). *medRxiv* 2020.09.28.20202937; doi: https://doi.org/10.1101/2020.09.28.20202937.
+6. **The potential contribution of face coverings to the control of SARS-CoV-2 transmission in schools and broader society in the UK: a modelling study**. Panovska-Griffiths J, Kerr CC, Waites W, Stuart RM, Mistry D, Foster D, Klein DJ, Viner R, Bonnell C (in press; accepted 2021-04-08). *Nature Scientific Reports*; doi: https://doi.org/10.1101/2020.09.28.20202937.
 
-7. **COVID-19 reopening strategies at the county level in the face of uncertainty: Multiple Models for Outbreak Decision Support**. Shea K, Borchering RK, Probert WJM, et al. (under review; posted 2020-11-05). *medRxiv* 2020.11.03.20225409; doi: https://doi.org/10.1101/2020.11.03.20225409.
+7. **Schools are not islands: Balancing COVID-19 risk and educational benefits using structural and temporal countermeasures**. Cohen JA, Mistry D, Kerr CC, Klein DJ (under review; posted 2020-09-10). *medRxiv* 2020.09.08.20190942; doi: https://doi.org/10.1101/2020.09.08.20190942.
 
-8. **Lessons learned from Vietnam's COVID-19 response: the role of adaptive behaviour change and testing in epidemic control**. Pham QD, Stuart RM, Nguyen TV, Luong QC, Tran DQ, Phan LT, Dang TQ, Tran DN, Mistry D, Klein DJ, Abeysuriya RG, Oron AP, Kerr CC (under review; posted 2020-12-19). *medRxiv* 2020.12.18.20248454; doi: https://doi.org/10.1101/2020.12.18.20248454.
+8. **COVID-19 reopening strategies at the county level in the face of uncertainty: Multiple Models for Outbreak Decision Support**. Shea K, Borchering RK, Probert WJM, et al. (under review; posted 2020-11-05). *medRxiv* 2020.11.03.20225409; doi: https://doi.org/10.1101/2020.11.03.20225409.
 
 9. **Preventing a cluster from becoming a new wave in settings with zero community COVID-19 cases**. Abeysuriya RG, Delport D, Stuart RM, Sacks-Davis R, Kerr CC, Mistry D, Klein DJ, Hellard M, Scott N (under review; posted 2020-12-22). *medRxiv* 2020.12.21.20248595; doi: https://doi.org/10.1101/2020.12.21.20248595.
 
-10. **Modelling the impact of reopening schools in early 2021 in the presence of the new SARS-CoV-2 variant in the UK**. Panovska-Griffiths J, Kerr CC, Waites W, Stuart RM, Mistry D, Foster D, Klein DJ, Viner R, Bonnell C (under review).
+10. **Modelling the impact of reopening schools in early 2021 in the presence of the new SARS-CoV-2 variant in the UK**. Panovska-Griffiths J, Kerr CC, Waites W, Stuart RM, Mistry D, Foster D, Klein DJ, Viner R, Bonnell C (under review; posted 2021-02-09). *medRxiv* 2021.02.07.21251287; doi: https://doi.org/10.1101/2021.02.07.21251287.
 
 If you have written a paper or report using Covasim, we'd love to know about it! Please write to us `here <mailto:[email protected]>`__.
 
 
 Requirements
 ============
 
-Python >=3.6 (64-bit). (Note: Python 2 is not supported.)
+Python 3.7 or 3.8 (64-bit). (Note: Python 2.7 and Python 3.9 are not supported.)
 
-We also recommend, but do not require, using Python virtual environments. For
-more information, see documentation for venv_ or Anaconda_.
+We also recommend, but do not require, installing Covasim in a virtual environment. For more information, see documentation for e.g. 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
 
 
@@ -91,11 +89,11 @@ If you would rather download the source code rather than using the ``pip`` packa
 
     *   For normal installation (recommended)::
 
-          python setup.py develop
+          pip install -e .
 
     *   To install Covasim and optional dependencies (be aware this may fail since it relies on nonstandard packages)::
 
-          python setup.py develop full
+          pip install -e .[full]
 
     The module should then be importable via ``import covasim as cv``.
 
@@ -141,6 +139,7 @@ The structure of the ``covasim`` folder is as follows, roughly in the order in w
 * ``people.py``: The ``People`` class, for handling updates of state for each person.
 * ``population.py``: Functions for creating populations of people, including age, contacts, etc.
 * ``interventions.py``: The ``Intervention`` class, for adding interventions and dynamically modifying parameters, and classes for each of the specific interventions derived from it.
+* ``immunity.py``: The ``strain`` class, and functions for computing waning immunity and neutralizing antibodies.
 * ``sim.py``: The ``Sim`` class, which performs most of the heavy lifting: initializing the model, running, and plotting.
 * ``run.py``: Functions for running simulations (e.g. parallel runs and the ``Scenarios`` and ``MultiSim`` classes).
 * ``analysis.py``: The ``Analyzers`` class (for performing analyses on the sim while it's running), the ``Fit`` class (for calculating the fit between the model and the data), the ``TransTree`` class, and other classes and functions for analyzing simulations.