{"id":28702857,"url":"https://github.com/epiforecasts/forecast.vocs","last_synced_at":"2025-06-14T13:05:35.011Z","repository":{"id":40261358,"uuid":"383161374","full_name":"epiforecasts/forecast.vocs","owner":"epiforecasts","description":"Contains models and tools to produce short-term forecasts for both case and sequence notifications assuming circulation of either one or two variants. Tools are also provided to allow the evaluation of the use of sequence data for short-term forecasts in both real-world settings and in user generated scenarios.","archived":false,"fork":false,"pushed_at":"2023-05-08T18:48:30.000Z","size":23591,"stargazers_count":8,"open_issues_count":12,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-13T16:47:43.853Z","etag":null,"topics":["r-package"],"latest_commit_sha":null,"homepage":"http://epiforecasts.io/forecast.vocs","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epiforecasts.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2021-07-05T14:04:26.000Z","updated_at":"2023-12-14T18:59:17.000Z","dependencies_parsed_at":"2022-08-17T21:15:29.463Z","dependency_job_id":null,"html_url":"https://github.com/epiforecasts/forecast.vocs","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/epiforecasts/forecast.vocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiforecasts%2Fforecast.vocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiforecasts%2Fforecast.vocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiforecasts%2Fforecast.vocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiforecasts%2Fforecast.vocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epiforecasts","download_url":"https://codeload.github.com/epiforecasts/forecast.vocs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiforecasts%2Fforecast.vocs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259820811,"owners_count":22916548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["r-package"],"created_at":"2025-06-14T13:05:34.430Z","updated_at":"2025-06-14T13:05:35.002Z","avatar_url":"https://github.com/epiforecasts.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# Forecast case and sequence notifications using variant of concern strain dynamics\n\n[![R-CMD-as-cran-check](https://github.com/epiforecasts/forecast.vocs/actions/workflows/R-CMD-as-cran-check.yaml/badge.svg)](https://github.com/epiforecasts/forecast.vocs/actions/workflows/R-CMD-as-cran-check.yaml) [![Codecov test coverage](https://codecov.io/gh/epiforecasts/forecast.vocs/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epiforecasts/forecast.vocs)\n\n[![Universe](https://epiforecasts.r-universe.dev/badges/forecast.vocs)](https://epiforecasts.r-universe.dev/) [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/epiforecasts/forecast.vocs/blob/master/LICENSE.md/) [![GitHub contributors](https://img.shields.io/github/contributors/epiforecasts/forecast.vocs)](https://github.com/epiforecasts/forecast.vocs/graphs/contributors) \n\n[![DOI](https://zenodo.org/badge/383161374.svg)](https://zenodo.org/badge/latestdoi/383161374)\n\nContains models and tools to produce short-term forecasts for both case and sequence notifications assuming circulation of either one or two variants. Tools are also provided to allow the evaluation of the use of sequence data for short-term forecasts in both real-world settings and in user generated scenarios.\n\n## Installation\n\n\n### Installing the package\n\nInstall the stable development version of the package with:\n\n```{r, eval = FALSE}\ninstall.packages(\"forecast.vocs\", repos = \"https://epiforecasts.r-universe.dev\")\n```\n\nInstall the unstable development from GitHub using the following, \n\n```{r, eval = FALSE}\nremotes::install_github(\"epiforecasts/forecast.vocs\", dependencies = TRUE)\n```\n\n### Installing CmdStan\n\nIf you don't already have CmdStan installed then, in addition to installing `forecast.vocs`, it is also necessary to install CmdStan using CmdStanR's \n`install_cmdstan()` function to enable model fitting in `forecast.vocs`. A suitable C++ toolchain is also required. Instructions are provided in the [_Getting started with\nCmdStanR_](https://mc-stan.org/cmdstanr/articles/cmdstanr.html) vignette. See the [CmdStanR documentation](https://mc-stan.org/cmdstanr/) for further details and support. \n\n```{r, eval = FALSE}\ncmdstanr::install_cmdstan()\n```\n\n## Quick start\n\nThis quick start uses data from Germany that includes COVID-19 notifications and sequences with sequences either being positive or negative for the Delta variant. It shows how to produce forecasts for both a one and two strain model for the 19th of June 2021 when the latest available data estimated that approximately 7% of COVID-19 were positive for the Delta variant. Note that estimated growth rates and reproduction numbers shown here have been rescaled using an assumed generation time of 5.5 days and a weakly informative prior centred around Delta being 50% more transmissible than non-Delta cases has been used.\n\n```{r}\nlibrary(forecast.vocs)\noptions(mc.cores = 4)\n\nobs \u003c- filter_by_availability(\n  germany_covid19_delta_obs,\n  date = as.Date(\"2021-06-19\")\n)\nobs\n\ncurrent_obs \u003c- latest_obs(germany_covid19_delta_obs)\n```\n\n### Forecast all-in-one\n\nRun a forecast for both one and two strain models (or optionally just one of these) using the `forecast()` function. This provides a wrapper around other package tooling to initialise, fit, and summarise forecasts. Multiple forecasts can be performed efficiently across dates and scenarios using `forecast_across_dates()` and `forecast_across_scenarios()`.\n\n```{r, message = FALSE}\nforecasts \u003c- forecast(obs,\n  strains = c(1, 2), voc_scale = c(0.4, 0.2),\n  voc_label = \"Delta\", scale_r = 5.5 / 7,\n  adapt_delta = 0.99, max_treedepth = 15,\n  refresh = 0, show_messages = FALSE\n)\nforecasts\n```\n\nSummarised posterior and forecast estimates can be directly extracted from the output using the included `summary()` method. Alternatively, the complete\nsummarised posterior can be extracted using the following (which also has its own `summary()` and `plot()` options to make exploring the results easier).\nSee the documentation for further details.\n\n```{r, eval = FALSE}\nsummary(forecasts, target = \"posterior\", type = \"all\")\n```\n\nPlot the posterior prediction for cases from the single strain model (\"Overall\"), from the two strain model (\"Combined\"), and the unobserved estimates for each strain.\n\n```{r}\nplot(forecasts, current_obs)\n```\n\nPlot the posterior prediction for the fraction of cases that have the Delta variant from the two strain model.\n\n```{r}\nplot(forecasts, current_obs, type = \"voc_frac\", voc_label = \"Delta variant\")\n```\n\nPlot the posterior estimate for the growth rate over the mean of the generation time for COVID-19 cases (here assumed to be 5.5 days).\n\n```{r}\nplot(forecasts, type = \"growth\")\n```\n\nPlot the posterior estimate for the effective reproduction number of Delta and non-Delta cases.\n\n```{r}\nplot(forecasts, type = \"rt\")\n```\n\nPlot the estimated transmission advantage for Delta vs non-Delta over time. Note that as here a model with a correlated variant growth rates has been used meaning that the difference between variants may vary over time (potentially suitable where imports or present or a variant has greater immune escape than the baseline). If it is likely that the growth advantage is constant over time consider the fixed scaling model. If the variants are likely to be circulating in independent populations consider the independent variant model. See the documentation and model definition vignette for details.\n\n```{r}\nplot(forecasts, type = \"voc_advantage\")\n```\n\nAlternatively a list of all plots with sensible defaults can be produced using the following. \n\n```{r, eval = FALSE}\nplot(forecasts, current_obs, type = \"all\", voc_label = \"Delta variant\")\n```\n\n\nA potentially useful optional integration with [`scoringutils`](https://epiforecasts.io/scoringutils/) package is also provided to streamline scoring forecasts using proper scoring rules. See the documentation of the `scoringutils` package for more on this but as a simple example below we calculate average scores both the single and two strain models for this single Forecast\n\n```{r}\nlibrary(scoringutils)\nlibrary(knitr)\n\nsummary(forecasts, target = \"forecast\", type = \"cases\") |\u003e\n  fv_score_forecast(current_obs) |\u003e\n  summarise_scores(by = \"strains\") |\u003e\n  kable()\n```\n\n### Step by step forecast\n\nRather than using the all-in-one `forecast()` function individual package functions can be used to produce a forecast as follows.\n\n```{r, eval = FALSE}\ndt \u003c- fv_as_data_list(obs, horizon = 4)\n\nmodel \u003c- fv_model(strains = 2)\n\ninits \u003c- fv_inits(dt, strains = 2)\n\nfit \u003c- fv_sample(\n  data = dt, model = model, init = inits,\n  voc_scale = c(0.4, 0.2),\n  adapt_delta = 0.99, max_treedepth = 15,\n  refresh = 0, show_messages = FALSE\n)\n\nposterior \u003c- fv_tidy_posterior(fit, voc_label = \"Delta\", scale_r = 5.5 / 7)\n```\n\nAs for forecasts produced with the `forecast()` function summary plots and estimates can then be produced using `summary()`, and `plot()` methods. For example case forecasts can be returned using the following, \n\n```{r, eval = FALSE}\nsummary(posterior, type = \"cases\", forecast = TRUE)\n```\n\n## Citation\n\nIf using `forecast.vocs` in your work please consider citing it using the following,\n\n```{r, echo = FALSE}\ncitation(\"forecast.vocs\")\n```\n\n## How to make a bug report or feature request\n\nPlease briefly describe your problem and what output you expect in an [issue](https://github.com/epiforecasts/forecast.vocs/issues). If you have a question, please don't open an issue. Instead, ask on our [Q and A page](https://github.com/epiforecasts/forecast.vocs/discussions/categories/q-a).\n\n## Contributing\n\nWe welcome contributions and new contributors! We particularly appreciate help on priority problems in the [issues](https://github.com/epiforecasts/forecast.vocs/issues). Please check and add to the issues, and/or add a [pull request](https://github.com/epiforecasts/forecast.vocs/pulls).\n\n## Code of Conduct\n  \nPlease note that the `forecast.vocs` project is released with a [Contributor Code of Conduct](epiforecasts.io/forecast.vocs/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepiforecasts%2Fforecast.vocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepiforecasts%2Fforecast.vocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepiforecasts%2Fforecast.vocs/lists"}