Merge pull request #1013 from amath-idm/rc3.0.2

Covasim version 3.0.2

CHANGELOG.rst

@@ -25,6 +25,21 @@ Latest versions (3.0.x)
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 
+Version 3.0.2 (2021-04-26)
+--------------------------
+- Added Novavax as one of the default vaccines.
+- If ``use_waning=True``, people will now become *undiagnosed* when they recover (so they are not incorrectly marked as diagnosed if they become reinfected).
+- Added a new method, ``sim.to_df()``, that exports results to a pandas dataframe.
+- Added ``people.lock()`` and ``people.unlock()`` methods, so you do not need to set ``people._lock`` manually.
+- Added extra parameter checking to ``people.set_pars(pars)``, so ``pop_size`` is guaranteed to be an integer.
+- Flattened ``sim['immunity']`` to no longer have separate axes for susceptible, symptomatic, and severe.
+- Fixed a bug in ``cv.sequence()``, introduced in version 2.1.2, that meant it would only ever trigger the last intervention.
+- Fixed a bug where if subtargeting was used with ``cv.vaccinate()``, it would trigger on every day.
+- Fixed ``msim.compare()`` to be more careful about not converting all results to integers.
+- *Regression information*: If you are using waning, ``sim.people.diagnosed`` no longer refers to everyone who has ever been diagnosed, only those still infectious. You can use ``sim.people.defined('date_diagnosed')`` in place of ``sim.people.true('diagnosed')`` (before these were identical).
+- *GitHub info*: PR `1020 <https://github.com/amath-idm/covasim/pull/1020>`__
+
+
 Version 3.0.1 (2021-04-16)
 --------------------------
 - Immunity and vaccine parameters have been updated.

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.)?

covasim/README.rst

@@ -6,9 +6,9 @@ This file describes each of the input parameters in Covasim. Note: the overall i
 
 Population parameters
 ---------------------
-* ``pop_size``     = Number ultimately susceptible to CoV
+* ``pop_size``     = Number of agents, i.e., people susceptible to SARS-CoV-2
 * ``pop_infected`` = Number of initial infections
-* ``pop_type``     = What type of population data to use -- random (fastest), synthpops (best), hybrid (compromise), or clustered (not recommended)
+* ``pop_type``     = What type of population data to use -- 'random' (fastest), 'synthpops' (best), 'hybrid' (compromise)
 * ``location``     = What location to load data from -- default Seattle
 
 Simulation parameters
@@ -17,31 +17,50 @@ Simulation parameters
 * ``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)
+* ``verbose``    = Whether or not to display information during the run -- options are 0 (silent), 0.1 (some; default), 1 (more), 2 (everything)
 
 Rescaling parameters
 --------------------
 * ``pop_scale``         = Factor by which to scale the population -- e.g. 1000 with pop_size = 10e3 means a population of 10m
+* ``scaled_pop``        = The total scaled population, i.e. the number of agents times the scale factor; alternative to pop_scale
 * ``rescale``           = Enable dynamic rescaling of the population
 * ``rescale_threshold`` = Fraction susceptible population that will trigger rescaling if rescaling
 * ``rescale_factor``    = Factor by which we rescale the population
 
 Basic disease transmission
 --------------------------
-* ``beta``        = Beta per symptomatic contact; absolute
-* ``contacts``    = The number of contacts per layer; set below
-* ``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; 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
--------------------------------
+* ``beta``         = Beta per symptomatic contact; absolute
+* ``n_imports``    = Average daily number of imported cases (actual number is drawn from Poisson distribution)
+* ``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
 * ``asymp_factor`` = Multiply beta by this factor for asymptomatic cases; no statistically significant difference in transmissibility: https://www.sciencedirect.com/science/article/pii/S1201971220302502
-* ``iso_factor``  = Multiply beta by this factor for diganosed cases to represent isolation; set below
-* ``quar_factor``  = Quarantine multiplier on transmissibility and susceptibility; set below
-* ``quar_period``  = Number of days to quarantine for; assumption based on standard policies
+
+Network parameters
+------------------
+* ``contacts``    = The number of contacts per layer
+* ``dynam_layer`` = Which layers are dynamic
+* ``beta_layer``  = Transmissibility per layer
+
+Multi-strain parameters
+-----------------------
+* ``n_imports`` = Average daily number of imported cases (actual number is drawn from Poisson distribution)
+* ``n_strains`` = The number of strains circulating in the population
+
+Immunity parameters
+-------------------
+* ``use_waning``   = Whether to use dynamically calculated immunity
+* ``nab_init``     = Parameters for the distribution of the initial level of log2(nab) following natural infection, taken from fig1b of https://doi.org/10.1101/2021.03.09.21252641
+* ``nab_decay``    = Parameters describing the kinetics of decay of nabs over time, taken from fig3b of https://doi.org/10.1101/2021.03.09.21252641
+* ``nab_kin``      = Constructed during sim initialization using the nab_decay parameters
+* ``nab_boost``    = Multiplicative factor applied to a person's nab levels if they get reinfected. # TODO: add source
+* ``nab_eff``      = Parameters to map nabs to efficacy
+* ``rel_imm_symp`` = Relative immunity from natural infection varies by symptoms
+* ``immunity``     = Matrix of immunity and cross-immunity factors, set by init_immunity() in immunity.py
+
+Strain-specific parameters
+--------------------------
+* ``rel_beta``       = Relative transmissibility varies by strain
+* ``rel_imm_strain`` = Relative own-immunity varies by strain
 
 Time for disease progression
 ----------------------------
@@ -66,6 +85,12 @@ Severity parameters
 * ``prog_by_age``     = Whether to set disease progression based on the person's age
 * ``prognoses``       = The actual arrays of prognoses by age; this is populated later
 
+Efficacy of protection measures
+-------------------------------
+* ``iso_factor``  = Multiply beta by this factor for diganosed cases to represent isolation; set below
+* ``quar_factor``  = Quarantine multiplier on transmissibility and susceptibility; set below
+* ``quar_period``  = Number of days to quarantine for; assumption based on standard policies
+
 Events and interventions
 ------------------------
 * ``interventions`` = The interventions present in this simulation; populated by the user