Merge pull request #438 from starsimhub/quarto-docs

Quarto docs

Author: cliffckerr

.github/workflows/publish_docs.yaml

@@ -0,0 +1,44 @@
+# Runs manually or on version tags.
+
+name: Publish Covasim docs
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Quarto
+    timeout-minutes: 45
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Covasim and doc dependencies
+        run: |
+          pip install -e .[full]
+          pip install -r docs/requirements.txt
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Install Quarto interlinks extension
+        working-directory: ./docs
+        run: quarto add machow/quartodoc --no-prompt
+
+      - name: Publish docs to GitHub Pages
+        working-directory: ./docs
+        run: |
+          git config --global user.name "github-actions"
+          git config --global user.email "github-actions@users.noreply.github.com"
+          ./publish

.readthedocs.yaml

@@ -1,27 +1,21 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Read the Docs configuration — Quarto build
+# https://docs.readthedocs.com/platform/stable/config-file/v2.html
 
-# Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
+  commands:
+    - pip install -e .[full]
+    - pip install -r docs/requirements.txt
+    - curl -LO https://github.com/quarto-dev/quarto-cli/releases/download/v1.6.40/quarto-1.6.40-linux-amd64.deb
+    - sudo dpkg -i quarto-1.6.40-linux-amd64.deb
+    - cd docs && quarto add machow/quartodoc --no-prompt && quarto render
+    - mkdir -p $READTHEDOCS_OUTPUT/html && cp -r docs/_site/* $READTHEDOCS_OUTPUT/html/
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-   configuration: docs/conf.py
-
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-#formats:
-#  - htmlzip
-
-# Optionally declare the Python requirements required to build your docs
 python:
   install:
-    - requirements: docs/requirements.txt
     - method: pip
       path: .

CHANGELOG.md

@@ -1,57 +1,45 @@
-===============
-Code of conduct
-===============
+# Code of conduct
 
-Our pledge
-==========
+## Our pledge
 
 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
-=============
+## Our standards
 
 Examples of behavior that contributes to creating a positive environment include:
 
-*   Using welcoming and inclusive language
-*   Being respectful of differing viewpoints and experiences
-*   Gracefully accepting constructive criticism
-*   Focusing on what is best for the community
-*   Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-*   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
+- 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
 
-Our responsibilities
-====================
+## Our responsibilities
 
 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.
 
 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
-=====
+## Scope
 
 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
-===========
+## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at info@covasim.org. 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.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <info@covasim.org>. 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.
 
 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
-===========
+## 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](https://www.contributor-covenant.org), version 1.4, available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>.
 
-.. _Contributor Covenant: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see the FAQ_.
-
-.. _FAQ: https://www.contributor-covenant.org/faq
+For answers to common questions about this code of conduct, see the [FAQ](https://www.contributor-covenant.org/faq).

CHANGELOG.rst

@@ -1,6 +1,6 @@
 include LICENSE
 global-include requirements*.txt
-global-include *.rst
+global-include *.md
 recursive-include covasim *.py
 recursive-include covasim *.json
 recursive-include covasim *.ttf

code_of_conduct.rst CODE_OF_CONDUCT.mdcode_of_conduct.rst renamed to CODE_OF_CONDUCT.md

@@ -0,0 +1,154 @@
+# Covasim
+
+## About Covasim
+
+Covasim is a stochastic agent-based simulator for performing COVID-19 analyses. These include projections of 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, quarantine, and vaccination.
+
+The original scientific paper describing Covasim is available at <http://paper.covasim.org>. The recommended citation is:
+
+> **Covasim: an agent-based model of COVID-19 dynamics and interventions**. Kerr CC, Stuart RM, Mistry D, Abeysuriya RG, Rosenfeld R, Hart G, Núñez RC, Cohen JA, Selvaraj P, Hagedorn B, George L, Jastrzębski M, Izzo A, Fowler G, Palmer A, Delport D, Scott N, Kelly S, Bennette C, Wagner B, Chang S, Oron AP, Wenger E, Panovska-Griffiths J, Famulare M, Klein DJ (2021). *PLOS Computational Biology* **17** (7): e1009149. doi: <https://doi.org/10.1371/journal.pcbi.1009149>.
+
+Covasim's immunity module (including vaccines and variants) is described here:
+
+> **Mechanistic modeling of SARS-CoV-2 immune memory, variants, and vaccines**. Cohen JA, Stuart RM, Núñez RC, Wagner B, Chang ST, Rosenfeld K, Kerr CC, Famulare M, Klein DJ (under review; posted 2021-06-01). *medRxiv* 2021.05.31.21258018; doi: <https://doi.org/10.1101/2021.05.31.21258018>.
+
+The Covasim webapp is available at <https://app.covasim.org>, and the repository for it is available [here](https://github.com/institutefordiseasemodeling/covasim_webapp).
+
+Covasim was developed by the [Institute for Disease Modeling](https://idmod.org/), with additional contributions from the [University of Copenhagen](https://www.math.ku.dk/english), the [Burnet Institute](https://www.burnet.edu.au/), [GitHub](https://github.com/), and [Microsoft](https://www.microsoft.com/en-us/ai/ai-for-health-covid-data).
+
+Questions or comments can be directed to <info@covasim.org>, or on this project's [GitHub](https://github.com/institutefordiseasemodeling/covasim) page. Full information about Covasim is provided in the [documentation](https://docs.covasim.org).
+
+**Note:** Covasim is no longer actively maintained. Please see [Starsim](https://github.com/starsimhub/starsim) for our current work on agent-based disease modeling.
+
+
+## Background
+
+Covasim has been used for analyses in over a dozen countries, both to inform policy decisions (including in the US, UK, and Australia), and as part of research studies. Some key papers that have been written using Covasim include:
+
+1.  **Controlling COVID-19 via test-trace-quarantine**. Kerr CC, Mistry D, Stuart RM, Rosenfeld R, Hart G, Núñez RC, Selvaraj P, Cohen JA, Abeysuriya RG, George L, Hagedorn B, Jastrzębski M, Fagalde M, Duchin J, Famulare M, Klein DJ (2021). *Nature Communications* 12:2993. doi: <https://doi.org/10.1038/s41467-021-23276-9>.
+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.  **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>.
+
+A more complete list of papers is given in [papers.md](papers.md).
+
+If you've written a paper or report using Covasim, we'd love to know about it! Please write to us [here](mailto:info@covasim.org).
+
+## Requirements
+
+Python 3.9-3.11 (64-bit). (Note: Python 2.7 and Python 3.12 are not supported, the latter being due to [Numba](https://numba.pydata.org/) not supporting Python 3.12 at the time of writing.)
+
+We also recommend, but do not require, installing Covasim in a virtual environment. For more information, see documentation for e.g. [Anaconda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
+
+## Quick start guide
+
+Install with `pip install covasim`. If everything is working, the following Python commands should bring up a plot:
+
+    import covasim as cv
+    sim = cv.Sim()
+    sim.run()
+    sim.plot()
+
+## Full installation instructions
+
+If you would rather download the source code rather than using the `pip` package, follow these steps:
+
+1.  Clone a copy of the repository. If you intend to make changes to the code, we recommend that you fork it first.
+
+2.  (Optional) Create and activate a virtual environment.
+
+3.  Navigate to the root of the repository and install the Covasim Python package using one of the following options:
+
+    - For normal installation (recommended):
+
+          pip install -e .
+
+    - To install Covasim and optional dependencies (be aware this may fail since it relies on nonstandard packages):
+
+          pip install -e .[full]
+
+    The module should then be importable via `import covasim as cv`.
+
+## Usage examples
+
+There are several examples in the `examples` folder. These can be run as follows:
+
+- `python examples/simple.py`
+
+  This example creates a figure using default parameter values.
+
+- `python examples/run_sim.py`
+
+  This shows a slightly more detailed example, including creating an intervention and saving to disk.
+
+- `python examples/run_scenarios.py`
+
+  This shows a more complex example, including running an intervention scenario, plotting uncertainty, and performing a health systems analysis.
+
+Other examples in that folder are taken from the tutorials.
+
+## Module structure
+
+All core model code is located in the `covasim` subfolder; standard usage is `import covasim as cv`. The `data` subfolder is described below.
+
+The model consists of two core classes: the `Person` class (which contains information on health state), and the `Sim` class (which contains methods for running, calculating results, plotting, etc.).
+
+The structure of the `covasim` folder is as follows, roughly in the order in which the modules are imported, building from most fundamental to most complex:
+
+- `version.py`: Version, date, and license information.
+- `requirements.py`: A simple module to check that imports succeeded, and turn off features if they didn't.
+- `utils.py`: Functions for choosing random numbers, many based on Numba, plus other helper functions.
+- `misc.py`: Miscellaneous helper functions.
+- `settings.py`: User-customizable options for Covasim (e.g. default font size).
+- `defaults.py`: The default colors, plots, etc. used by Covasim.
+- `parameters.py`: Functions for creating the parameters dictionary and loading the input data.
+- `plotting.py`: Plotting scripts, including Plotly graphs for the webapp (used in other Covasim classes, and hence defined first).
+- `base.py`: The `ParsObj` class, the fundamental class used in Covasim, plus basic methods of the `BaseSim` and `BasePeople` classes, and associated functions.
+- `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.
+
+The `data` folder within the Covasim package 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.
+
+## Other folders
+
+Please see the readme in each subfolder for more information.
+
+### Bin
+
+This folder contains a command-line interface (CLI) version of Covasim; example usage:
+
+    covasim --pars "{pop_size:20000, pop_infected:1, n_days:360, rand_seed:1}"
+
+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).
+
+### Tutorials
+
+This folder contains Jupyter notebooks for nine tutorials that walk you through using Covasim, from absolute basics to advanced topics such as calibration and creating custom populations.
+
+### Examples
+
+This folder contains demonstrations of simple Covasim usage, with most examples taken from the tutorials.
+
+#### Cruise ship
+
+An early application of Covasim to the Diamond Princess cruise ship.
+
+#### Calibration
+
+Examples of how to calibrate simulations, including [Optuna](https://optuna.org/) (also covered in the tutorial) and [Weights and Biases](https://www.wandb.com/).
+
+### Tests
+
+Integration, development, and unit tests. While not (yet) beautifully curated, these folders contain many usage examples. See README in the tests folder for more information.
+
+## Disclaimer
+
+The code in this repository was developed by IDM, the Burnet Institute, the University of Copenhagen, and other collaborators to support our joint research on COVID. We’ve made it publicly available under the MIT License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. Note that Covasim depends on a number of user-installed Python packages that can be installed automatically via `pip install`. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as contemplated under the MIT License. See the contributing and code of conduct READMEs for more information.