Skip to content

Commit

Permalink
Update README and workflow files (#67)
Browse files Browse the repository at this point in the history 
* Update README to streamline information

* Update README again for clarity

* Minor changes to README

* Update run-forecast.yml to dynamically grab name of repo image

* Fix bug in run-forecast.yml with variables

* Revert run-forecast.yml changes

* Final updates to README adding link to presentation

* Remove superfluous code in run-forecast.yml
  • Loading branch information
@apulsipher
apulsipher authored Feb 11, 2025
1 parent b732eb8 commit fe5b60d
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 52 deletions.
1 change: 1 addition & 0 deletions .github/workflows/run-forecast.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ jobs:
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# NOTE: Change the container below to "ghcr.io/<your_org_name>/<your_repo_name>" (all lowercase)
container: ghcr.io/epiforesite/epiworld-forecasts
permissions:
contents: write
Expand Down
90 changes: 38 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# epiworld-forecasts

`epiworld-forecasts` is a template repository that provides scaffolding for automated disease forecasts using [`epiworldR`](https://github.com/UofUEpiBio/epiworldR/), an R package for fast agent-based model (ABM) disease simulations.
`epiworld-forecasts` is a template repository that provides scaffolding for building automatic disease forecasts.

## How It Works

Disease forecasts typically follow these steps:

Expand All @@ -10,34 +12,21 @@ Disease forecasts typically follow these steps:
4. Create a report with figures and descriptions
5. Publish the report

The epiworld-forecasts tool automates these steps, creating forecasts that regularly update without human intervention. This saves researchers and public health officials time and effort.


## Technologies

**`epiworld-forecasts`** is fully automated, powered by the following technologies:

* **Docker:** Contains all the software packages needed to run the forecast
* **GitHub Actions:** Runs the forecast inside the Docker container, manages the schedule of forecast runs, builds and pushes the Docker image to the GitHub Container Registry
* **Quarto:** Generates the forecast's report in an HTML webpage which is then published to GitHub Pages
* **GitHub:** Hosts source code repository and forecast website via GitHub Pages

![](assets/tech-chart.png)
`epiworld-forecasts` automates these steps, creating forecasts that regularly update without human intervention.

### Technologies

## Example Forecast

To demonstrate the capabilities of `epiworld-forecasts`, we created an example forecast.
This is a 14-day forecast of COVID-19 case counts in Utah using data published weekly by the UDHHS.
The forecast updates weekly and is published to [this website](https://epiforesite.github.io/epiworld-forecasts/).

![](assets/process-flow-chart.png)
`epiworld-forecasts` is powered by these technologies:

1. [**`epiworldR`**](https://github.com/UofUEpiBio/epiworldR/): R package for fast agent-based model (ABM) disease simulations
2. **Docker:** Contains all the software packages needed to run the forecast
3. **GitHub Actions:** Runs the forecast inside the Docker container, manages the schedule of forecast runs, builds and pushes the Docker image to the GitHub Container Registry
4. **Quarto:** Generates the forecast's report in an HTML webpage which is then published to GitHub Pages
5. **GitHub:** Hosts source code repository and forecast website via GitHub Pages

## Adapting `epiworld-forecasts` for Your Needs
### Adapting to Your Needs

The core of this tool is the pipeline technologies (GHA Actions, Docker, Quarto) that allow the forecast to run automatically.
As such, the tool can be adapted for different:
The `epiworld-forecasts` pipeline which can be adapted for different:

* Data sources
* Model calibrations
Expand All @@ -47,9 +36,10 @@ As such, the tool can be adapted for different:
* Forecast schedules
* Docker containers

You can make adaptations to these features by modifying the following key files:
You adjust the tool for your projects by first [creating a new repo from this template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) and then modifying the following key files:

[**`forecast.R`**](./forecast.R) contains the core logic for the forecast divided up into the following sections:

* *Libraries:* Loads required libraries, such as `epiworldR` and `ggplot2`
* *Gather Data:* Defines functions for getting the data to calibration the forecast
* *Process Data:* Defines functions for processing data for the forecast
Expand All @@ -58,53 +48,49 @@ You can make adaptations to these features by modifying the following key files:
* *Run Model Calibration:* Executes the calibration functions defined above
* *Run Forecast:* Runs the forecast with the calibrated model
* *Forecast Visualizations:* Defines functions for visualizing forecast data
All of these sections can be modified freely to produce your intended forecast.

[**`index.qmd`**](./index.qmd) defines the `index.html` page for the final generated forecast report.
This file should always start with `source("forecast.R")` to run the forecast and load in all relevant functions, but most subsections will only call printing or plotting functions (as defined in the "Forecast Visualizations" section of `forecast.R`).
By dividing the "business" logic from the HTML render logic, we make it easier to run the code outside of the Quarto file and also allow multiple web pages to show different visualizations from the same forecast run.
This file can also be freely customized to your needs.

* This file should always start with `source("forecast.R")` to run the forecast and source all relevant functions, but subsections will only call printing or plotting functions (e.g., those defined under "Forecast Visualizations" in `forecast.R`).
* By dividing the "business" logic from the HTML rendering logic, we make it easier to run the code outside of the Quarto file (i.e. without rendering the entire webpage).
This also allows multiple web pages to show different visualizations from the same forecast run.
* Our example (below) features additional [Methodology](./methodology.qmd) and [About](./about.qmd) pages, but these are not required for your project.
Adjust the global website settings in the [`_quarto.yml`](./_quarto.yml) file.

[**`run-forecast.yml`**](./.github/workflows/run-forecast.yml) contains the GitHub Actions workflow for running the forecast automatically.
This includes setting the schedule and uploading the HTML forecast report to GitHub Pages, which is what you will most likely be modifying for your project.
Take careful consideration before modifying anything other than the container, the schedule, and publishing destination to avoid breaking the workflow.
- Note that while this workflow will work immediately after copying the template repository (and will be available under "Deployments"), the website URL won't be immediately visible on the main repo page.
This can be added by editing the "About" section (clicking the gear icon) and checking the box for "Use your GitHub Pages website".

* This includes setting the schedule and publishing the report.
* While our example (below) uploads the HTML forecast to GitHub Pages, this workflow can be adapted to simply produce a downloadable data file, rather than publishing a public website.
* Be careful when modifying anything other than the container, the schedule, and publishing destination to avoid breaking the workflow.

[**`Dockerfile`**](./.devcontainer/Dockerfile) defines the Docker image for running the forecast.
This should contain all the packages you need for your forecast (e.g., `epiworldR`, `ggplot2`, etc.).
We have a separate GHA workflow file for [building the Docker image](./.github/workflows/build-docker-image.yml) from the Dockerfile so it can be used by the GHAs.

* This should contain all the packages you need for your forecast (e.g., `epiworldR`, `ggplot2`, etc.).
* We have a separate GHA workflow file for [building the Docker image](./.github/workflows/build-docker-image.yml) from the Dockerfile so it can be used by the GHAs.

#### Implementation Note

Once you copy the template repository, the `build-docker-image` workflow will create the Docker image for your new repository.
Consequently, you'll need to modify the [container in `run-forecast.yml`](https://github.com/EpiForeSITE/epiworld-forecasts/blob/0ef3472bd5084bb3a95a646e07d218cd2154725a/.github/workflows/run-forecast.yml#L36) to the newly built docker image:
```
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
container: ghcr.io/epiforesite/epiworld-forecasts -> change to "ghcr.io/<your_org_name>/<your_repo_name>"
permissions:
contents: write
# NOTE: Change the container below to "ghcr.io/<your_org_name>/<your_repo_name>" (all lowercase)
container: ghcr.io/epiforesite/epiworld-forecasts
```
Otherwise, your project will continue to use our `epiworld-forecasts` Docker image.

Our example features additional [Methodology](./methodology.qmd) and [About](./about.qmd) pages, but these are not required for your project.
Adjust the global website settings in the [`_quarto.yml`](./_quarto.yml) file.


## Data Sources
For our example forecast, we use the [weekly reports](https://coronavirus.utah.gov/case-counts/) published by Utah DHHS on COVID-19.
This includes a lot of different data, but we focus on COVID-19 case counts for the entire state.
## Example Forecast

Future forecasts, might look to other data sources, such as:
- DELPHI maintains a frequently updated COVID data API [here](https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html) and additional endpoints (less frequently updated) for influenza, dengue, and norovirus [here](https://cmu-delphi.github.io/delphi-epidata/api/README.html)
- CDC's [public datasets](https://data.cdc.gov), some are updated infrequently, others are weekly estimates (e.g., [weekly flu vaccine estimates](https://data.cdc.gov/Vaccinations/Weekly-Cumulative-Estimated-Number-of-Influenza-Va/ysd3-txwj/about_data)
To demonstrate the capabilities of `epiworld-forecasts`, we created an example forecast.
This is a 14-day forecast of COVID-19 case counts in Utah using data [published weekly](https://coronavirus.utah.gov/case-counts/) by Utah DHHS
The forecast updates weekly and is published to [this website](https://epiforesite.github.io/epiworld-forecasts/).

![](assets/process-flow-chart.png)

## Other Relevant Resources
It's worth also taking a look at:
- DELPHI's [R packages](https://delphi.cmu.edu/code/)
- [RSV Forecast Hub](https://rsvforecasthub.org/#Overview)
- [Epinowcast](https://www.epinowcast.org) and the Epinowcast [community forums](https://community.epinowcast.org)
See [this presentation](https://github.com/EpiForeSITE/software/blob/89b3110492bba30cd324f580fef0ed3d846ac26f/docs/presentations/epiworld-forecasts-2025-02-10.pdf) for more information on `epiworld-forecasts`.


## Code of Conduct
Expand Down

0 comments on commit fe5b60d

Please sign in to comment.