From a43ccaf031604674518a4d9d3fd9a04bc4cf0978 Mon Sep 17 00:00:00 2001 From: Sam Date: Fri, 27 Jan 2023 15:22:34 +0000 Subject: [PATCH] update documentation --- NAMESPACE | 1 + R/depreciated.R | 130 +++++++++++++++++++++++++++++++++++++ R/opts.R | 4 +- man/backcalc_opts.Rd | 4 +- man/estimate_infections.Rd | 6 +- man/process_opts.Rd | 75 +++++++++++++++++++++ man/rt_opts.Rd | 4 +- 7 files changed, 217 insertions(+), 7 deletions(-) create mode 100644 R/depreciated.R create mode 100644 man/process_opts.Rd diff --git a/NAMESPACE b/NAMESPACE index b477eeea6..fe2bb0cec 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -69,6 +69,7 @@ export(obs_opts) export(opts_list) export(plot_estimates) export(plot_summary) +export(process_opts) export(regional_epinow) export(regional_runtimes) export(regional_summary) diff --git a/R/depreciated.R b/R/depreciated.R new file mode 100644 index 000000000..d31e77f4d --- /dev/null +++ b/R/depreciated.R @@ -0,0 +1,130 @@ +#' Back Calculation Options +#' +#' @description `r lifecycle::badge("deprecated")` +#' Defines a list specifying the optional arguments for the back calculation +#' of cases. Only used if `rt = NULL`. +#' +#' @param prior A character string defaulting to "reports". Defines the prior +#' to use when deconvolving. Currently implemented options are to use smoothed +#' mean delay shifted reported cases ("reports"), to use the estimated +#' infections from the previous time step seeded for the first time step using +#' mean shifted reported cases ("infections"), or no prior ("none"). Using no +#' prior will result in poor real time performance. No prior and using +#' infections are only supported when a Gaussian process is present . If +#' observed data is not reliable then it a sensible first step is to explore +#' increasing the `prior_window` wit a sensible second step being to no longer +#' use reported cases as a prior (i.e set `prior = "none"`). +#' +#' @param prior_window Integer, defaults to 14 days. The mean centred smoothing +#' window to apply to mean shifted reports (used as a prior during back +#' calculation). 7 days is minimum recommended settings as this smooths day of +#' the week effects but depending on the quality of the data and the amount of +#' information users wish to use as a prior (higher values equalling a less +#' informative prior). +#' +#' @param rt_window Integer, defaults to 1. The size of the centred rolling +#' average to use when estimating Rt. This must be odd so that the central +#' estimate is included. +#' +#' @return A list of back calculation settings. +#' @author Sam Abbott +#' @export +#' @examples +#' # default settings +#' backcalc_opts() +backcalc_opts <- function(prior = "reports", prior_window = 14, rt_window = 1) { + stop("backcalc_opts is deprecated - use process_opts instead") + backcalc <- list( + prior = match.arg(prior, choices = c("reports", "none", "infections")), + prior_window = prior_window, + rt_window = as.integer(rt_window) + ) + if (backcalc$rt_window %% 2 == 0) { + stop( + "Rt rolling average window must be odd in order to include the current + estimate" + ) + } + return(backcalc) +} + +#' Time-Varying Reproduction Number Options +#' +#' @description `r lifecycle::badge("deprecated")` +#' Defines a list specifying the optional arguments for the time-varying +#' reproduction number. Custom settings can be supplied which override the +#' defaults. +#' +#' @param prior List containing named numeric elements "mean" and "sd". The +#' mean and standard deviation of the log normal Rt prior. Defaults to mean of +#' 1 and standard deviation of 1. +#' +#' @param use_rt Logical, defaults to `TRUE`. Should Rt be used to generate +#' infections and hence reported cases. +#' +#' @param rw Numeric step size of the random walk, defaults to 0. To specify a +#' weekly random walk set `rw = 7`. For more custom break point settings +#' consider passing in a `breakpoints` variable as outlined in the next section. +#' +#' @param use_breakpoints Logical, defaults to `TRUE`. Should break points be +#' used if present as a `breakpoint` variable in the input data. Break points +#' should be defined as 1 if present and otherwise 0. By default breakpoints +#' are fit jointly with a global non-parametric effect and so represent a +#' conservative estimate of break point changes (alter this by setting +#' `gp = NULL`). +#' +#' @param pop Integer, defaults to 0. Susceptible population initially present. +#' Used to adjust Rt estimates when otherwise fixed based on the proportion of +#' the population that is susceptible. When set to 0 no population adjustment +#' is done. +#' +#' @param gp_on Character string, defaulting to "R_t-1". Indicates how the +#' Gaussian process, if in use, should be applied to Rt. Currently supported +#' options are applying the Gaussian process to the last estimated Rt (i.e +#' Rt = Rt-1 * GP), and applying the Gaussian process to a global mean (i.e Rt +#' = R0 * GP). Both should produced comparable results when data is not sparse +#' but the method relying on a global mean will revert to this for real time +#' estimates, which may not be desirable. +#' +#' @return A list of settings defining the time-varying reproduction number. +#' @author Sam Abbott + +#' @inheritParams create_future_rt +#' @export +#' @examples +#' # default settings +#' rt_opts() +#' +#' # add a custom length scale +#' rt_opts(prior = list(mean = 2, sd = 1)) +#' +#' # add a weekly random walk +#' rt_opts(rw = 7) +rt_opts <- function(prior = list(mean = 1, sd = 1), + use_rt = TRUE, + rw = 0, + use_breakpoints = TRUE, + future = "latest", + gp_on = "R_t-1", + pop = 0) { + stop("rt_opts is deprecated - use process_opts instead") + rt <- list( + prior = prior, + use_rt = use_rt, + rw = rw, + use_breakpoints = use_breakpoints, + future = future, + pop = pop, + gp_on = match.arg(gp_on, choices = c("R_t-1", "R0")) + ) + + # replace default settings with those specified by user + if (rt$rw > 0) { + rt$use_breakpoints <- TRUE + } + + if (!("mean" %in% names(rt$prior) & "sd" %in% names(rt$prior))) { + stop("prior must have both a mean and sd specified") + } + return(rt) +} \ No newline at end of file diff --git a/R/opts.R b/R/opts.R index 1a7f880a4..4648fc618 100644 --- a/R/opts.R +++ b/R/opts.R @@ -431,7 +431,7 @@ process_opts <- function(model = "R", rw = 0, use_breakpoints = TRUE, future = "latest", - stationary = FALSE, + stationary = FALSE pop = 0) { ## check @@ -450,7 +450,7 @@ process_opts <- function(model = "R", use_breakpoints = use_breakpoints, future = future, stationary = stationary, - pop = pop + pop = pop, ) # replace default settings with those specified by user diff --git a/man/backcalc_opts.Rd b/man/backcalc_opts.Rd index 7535f4497..fd80501ad 100644 --- a/man/backcalc_opts.Rd +++ b/man/backcalc_opts.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/opts.R +% Please edit documentation in R/depreciated.R \name{backcalc_opts} \alias{backcalc_opts} \title{Back Calculation Options} @@ -37,7 +37,7 @@ estimate is included.} A \verb{} object of back calculation settings. } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Defines a list specifying the optional arguments for the back calculation of cases. Only used if \code{rt = NULL}. } diff --git a/man/estimate_infections.Rd b/man/estimate_infections.Rd index cf1bf069f..1a805585b 100644 --- a/man/estimate_infections.Rd +++ b/man/estimate_infections.Rd @@ -7,7 +7,7 @@ Growth} \usage{ estimate_infections( data, - model = "R", + process_opts = process_opts(), generation_time = generation_time_opts(), delays = delay_opts(), truncation = trunc_opts(), @@ -92,6 +92,10 @@ Corresponds to the "DEBUG" level from \code{futile.logger}. See \code{setup_logg for more detailed logging options.} \item{reported_cases}{Deprecated; use \code{data} instead.} +\item{process_model}{A character string that defines what is being +modelled: "infections", "growth" or "R" (default). If ' set to "R", +a generation time distribution needs to be defined via the \code{generation_time} +argument.} } \value{ A list of output including: posterior samples, summarised posterior diff --git a/man/process_opts.Rd b/man/process_opts.Rd new file mode 100644 index 000000000..8cce5af5f --- /dev/null +++ b/man/process_opts.Rd @@ -0,0 +1,75 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/opts.R +\name{process_opts} +\alias{process_opts} +\title{Process model optionss} +\usage{ +process_opts( + model = "R", + prior_mean = data.table::fcase(model == "R", list(mean = 1, sd = 1), model == "growth", + list(mean = 0, sd = 1), model == "infections", NULL), + prior_t = NULL, + rw = 0, + use_breakpoints = TRUE, + future = "latest", + stationary = FALSE, + pop = 0 +) +} +\arguments{ +\item{rw}{Numeric step size of the random walk, defaults to 0. To specify a +weekly random walk set \code{rw = 7}. For more custom break point settings +consider passing in a \code{breakpoints} variable as outlined in the next section.} + +\item{use_breakpoints}{Logical, defaults to \code{TRUE}. Should break points be +used if present as a \code{breakpoint} variable in the input data. Break points +should be defined as 1 if present and otherwise 0. By default breakpoints +are fit jointly with a global non-parametric effect and so represent a +conservative estimate of break point changes (alter this by setting +\code{gp = NULL}).} + +\item{future}{A character string or integer. This argument indicates how to set future Rt values. Supported +options are to project using the Rt model ("project"), to use the latest estimate based on partial data ("latest"), +to use the latest estimate based on data that is over 50\% complete ("estimate"). If an integer is supplied then the Rt estimate +from this many days into the future (or past if negative) past will be used forwards in time.} + +\item{pop}{Integer, defaults to 0. Susceptible population initially present. +Used to adjust Rt estimates when otherwise fixed based on the proportion of +the population that is susceptible. When set to 0 no population adjustment +is done.} + +\item{prior}{List containing named numeric elements "mean" and "sd". The +mean and standard deviation of the log normal Rt prior. Defaults to mean of +1 and standard deviation of 1.} + +\item{use_rt}{Logical, defaults to \code{TRUE}. Should Rt be used to generate +infections and hence reported cases.} + +\item{gp_on}{Character string, defaulting to "R_t-1". Indicates how the +Gaussian process, if in use, should be applied to Rt. Currently supported +options are applying the Gaussian process to the last estimated Rt (i.e +Rt = Rt-1 * GP), and applying the Gaussian process to a global mean (i.e Rt += R0 * GP). Both should produced comparable results when data is not sparse +but the method relying on a global mean will revert to this for real time +estimates, which may not be desirable.} +} +\value{ +A list of settings defining the time-varying reproduction number. +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} +Defines a list specifying the optional arguments for the process mode. +Custom settings can be supplied which override the defaults. +} +\examples{ +# default settings +process_opts() + +# add a weekly random walk +process_opts(rw = 7) +} +\author{ +Sebastian Funk + +Sam Abbott +} diff --git a/man/rt_opts.Rd b/man/rt_opts.Rd index 24774d891..c92bb86f2 100644 --- a/man/rt_opts.Rd +++ b/man/rt_opts.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/opts.R +% Please edit documentation in R/depreciated.R \name{rt_opts} \alias{rt_opts} \title{Time-Varying Reproduction Number Options} @@ -59,7 +59,7 @@ An \verb{} object with settings defining the time-varying reproduction number. } \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Defines a list specifying the optional arguments for the time-varying reproduction number. Custom settings can be supplied which override the defaults.