From 4b5ae82bda701efe4ae19dfdda1a9e1f69dd35ea Mon Sep 17 00:00:00 2001 From: Naeem Model Date: Sun, 11 Feb 2024 01:17:20 +0000 Subject: Rename WP --- R/WP.R | 229 ----------------------------------------------------------------- R/wp.R | 229 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 229 insertions(+), 229 deletions(-) delete mode 100644 R/WP.R create mode 100644 R/wp.R (limited to 'R') diff --git a/R/WP.R b/R/WP.R deleted file mode 100644 index 04791e2..0000000 --- a/R/WP.R +++ /dev/null @@ -1,229 +0,0 @@ -#' WP method -#' -#' This function implements an R0 estimation due to White and Pagano (Statistics -#' in Medicine, 2008). The method is based on maximum likelihood estimation in a -#' Poisson transmission model. See details for important implementation notes. -#' -#' This method is based on a Poisson transmission model, and hence may be most -#' most valid at the beginning of an epidemic. In their model, the serial -#' distribution is assumed to be discrete with a finite number of posible -#' values. In this implementation, if \code{mu} is not {NA}, the serial -#' distribution is taken to be a discretized version of a gamma distribution -#' with mean \code{mu}, shape parameter one, and largest possible value based on -#' parameter \code{tol}. When \code{mu} is \code{NA}, the function implements a -#' grid search algorithm to find the maximum likelihood estimator over all -#' possible gamma distributions with unknown mean and variance, restricting -#' these to a prespecified grid (see \code{search} parameter). -#' -#' When the serial distribution is known (i.e., \code{mu} is not \code{NA}), -#' sensitivity testing of \code{mu} is strongly recommended. If the serial -#' distribution is unknown (i.e., \code{mu} is \code{NA}), the likelihood -#' function can be flat near the maximum, resulting in numerical instability of -#' the optimizer. When \code{mu} is \code{NA}, the implementation takes -#' considerably longer to run. Users should be careful about units of time -#' (e.g., are counts observed daily or weekly?) when implementing. -#' -#' The model developed in White and Pagano (2008) is discrete, and hence the -#' serial distribution is finite discrete. In our implementation, the input -#' value \code{mu} is that of a continuous distribution. The algorithm -#' discretizes this input when \code{mu} is not \code{NA}, and hence the mean of -#' the serial distribution returned in the list \code{SD} will differ from -#' \code{mu} somewhat. That is to say, if the user notices that the input -#' \code{mu} and output mean of \code{SD} are different, this is to be expected, -#' and is caused by the discretization. -#' -#' @param NT Vector of case counts. -#' @param mu Mean of the serial distribution (needs to match case counts in time -#' units; for example, if case counts are weekly and the serial -#' distribution has a mean of seven days, then \code{mu} should be set -#' to one). The default value of \code{mu} is set to \code{NA}. -#' @param search List of default values for the grid search algorithm. The list -#' includes three elements: the first is \code{B}, which is the -#' length of the grid in one dimension; the second is -#' \code{scale.max}, which is the largest possible value of the -#' scale parameter; and the third is \code{shape.max}, which is -#' the largest possible value of the shape parameter. Defaults to -#' \code{B = 100, scale.max = 10, shape.max = 10}. For both shape -#' and scale, the smallest possible value is 1/\code{B}. -#' @param tol Cutoff value for cumulative distribution function of the -#' pre-discretization gamma serial distribution. Defaults to 0.999 -#' (i.e. in the discretization, the maximum is chosen such that the -#' original gamma distribution has cumulative probability of no more -#' than 0.999 at this maximum). -#' -#' @return \code{WP} returns a list containing the following components: -#' \code{Rhat} is the estimate of R0, and \code{SD} is either the -#' discretized serial distribution (if \code{mu} is not \code{NA}), or -#' the estimated discretized serial distribution (if \code{mu} is -#' \code{NA}). The list also returns the variable \code{check}, which is -#' equal to the number of non-unique maximum likelihood estimators. The -#' serial distribution \code{SD} is returned as a list made up of -#' \code{supp} (the support of the distribution) and \code{pmf} (the -#' probability mass function). -#' -#' @examples -#' # Weekly data. -#' NT <- c(1, 4, 10, 5, 3, 4, 19, 3, 3, 14, 4) -#' -#' # Obtain R0 when the serial distribution has a mean of five days. -#' res1 <- WP(NT, mu = 5 / 7) -#' res1$Rhat -#' -#' # Obtain R0 when the serial distribution has a mean of three days. -#' res2 <- WP(NT, mu = 3 / 7) -#' res2$Rhat -#' -#' # Obtain R0 when the serial distribution is unknown. -#' # NOTE: This implementation will take longer to run. -#' res3 <- WP(NT) -#' res3$Rhat -#' -#' # Find the mean of the estimated serial distribution. -#' serial <- res3$SD -#' sum(serial$supp * serial$pmf) -#' -#' @importFrom stats pexp qexp -#' -#' @export -WP <- function(NT, mu = NA, - search = list(B = 100, shape.max = 10, scale.max = 10), - tol = 0.999) { - if (is.na(mu)) { - print("You have assumed that the serial distribution is unknown.") - res <- WP_unknown(NT, B = search$B, shape.max = search$shape.max, - scale.max = search$scale.max, tol = tol) - Rhat <- res$Rhat - p <- res$p - range.max <- res$range.max - JJ <- res$JJ - } else { - print("You have assumed that the serial distribution is known.") - range.max <- ceiling(qexp(tol, rate = 1 / mu)) - p <- diff(pexp(0:range.max, 1 / mu)) - p <- p / sum(p) - res <- WP_known(NT = NT, p = p) - Rhat <- res - JJ <- NA - } - - return(list(Rhat = Rhat, - check = length(JJ), - SD = list(supp = 1:range.max, pmf = p))) -} - -#' WP method background function WP_known -#' -#' This is a background/internal function called by \code{WP}. It computes the -#' maximum likelihood estimator of R0 assuming that the serial distribution is -#' known and finite discrete. -#' -#' @param NT Vector of case counts. -#' @param p Discretized version of the serial distribution. -#' -#' @return The function returns the maximum likelihood estimator of R0. -#' -#' @noRd -WP_known <- function(NT, p) { - k <- length(p) - TT <- length(NT) - 1 - mu_t <- rep(0, TT) - - for (i in 1:TT) { - Nt <- NT[i:max(1, i - k + 1)] - mu_t[i] <- sum(p[1:min(k, i)] * Nt) - } - - Rhat <- sum(NT[-1]) / sum(mu_t) - return(Rhat) -} - -#' WP method background function WP_unknown -#' -#' This is a background/internal function called by \code{WP}. It computes the -#' maximum likelihood estimator of R0 assuming that the serial distribution is -#' unknown but comes from a discretized gamma distribution. The function then -#' implements a simple grid search algorithm to obtain the maximum likelihood -#' estimator of R0 as well as the gamma parameters. -#' -#' @param NT Vector of case counts. -#' @param B Length of grid for shape and scale (grid search parameter). -#' @param shape.max Maximum shape value (grid \code{search} parameter). -#' @param scale.max Maximum scale value (grid \code{search} parameter). -#' @param tol cutoff value for cumulative distribution function of the serial -#' distribution (defaults to 0.999). -#' -#' @return The function returns \code{Rhat}, the maximum likelihood estimator of -#' R0, as well as the maximum likelihood estimator of the discretized -#' serial distribution given by \code{p} (the probability mass function) -#' and \code{range.max} (the distribution has support on the integers -#' one to \code{range.max}). The function also returns \code{resLL} (all -#' values of the log-likelihood) at \code{shape} (grid for shape -#' parameter) and at \code{scale} (grid for scale parameter), as well as -#' \code{resR0} (the full vector of maximum likelihood estimators), -#' \code{JJ} (the locations for the likelihood for these), and \code{J0} -#' (the location for the maximum likelihood estimator \code{Rhat}). If -#' \code{JJ} and \code{J0} are not the same, this means that the maximum -#' likelihood estimator is not unique. -#' -#' @importFrom stats pgamma qgamma -#' -#' @noRd -WP_unknown <- function(NT, B = 100, shape.max = 10, scale.max = 10, - tol = 0.999) { - shape <- seq(0, shape.max, length.out = B + 1) - scale <- seq(0, scale.max, length.out = B + 1) - shape <- shape[-1] - scale <- scale[-1] - - resLL <- matrix(0, B, B) - resR0 <- matrix(0, B, B) - - for (i in 1:B) - for (j in 1:B) { - range.max <- ceiling(qgamma(tol, shape = shape[i], scale = scale[j])) - p <- diff(pgamma(0:range.max, shape = shape[i], scale = scale[j])) - p <- p / sum(p) - mle <- WP_known(NT, p) - resLL[i, j] <- computeLL(p, NT, mle) - resR0[i, j] <- mle - } - - J0 <- which.max(resLL) - R0hat <- resR0[J0] - JJ <- which(resLL == resLL[J0], arr.ind = TRUE) - range.max <- ceiling(qgamma(tol, shape = shape[JJ[1]], scale = scale[JJ[2]])) - p <- diff(pgamma(0:range.max, shape = shape[JJ[1]], scale = scale[JJ[2]])) - p <- p / sum(p) - - return(list(Rhat = R0hat, J0 = J0, ll = resLL, Rs = resR0, scale = scale, - shape = shape, JJ = JJ, p = p, range.max = range.max)) -} - -#' WP method background function computeLL -#' -#' This is a background/internal function called by \code{WP}. It computes the -#' log-likelihood. -#' -#' @param p Discretized version of the serial distribution. -#' @param NT Vector of case counts. -#' @param R0 Basic reproductive ratio. -#' -#' @return This function returns the log-likelihood at the input variables and -#' parameters. -#' -#' @noRd -computeLL <- function(p, NT, R0) { - k <- length(p) - TT <- length(NT) - 1 - mu_t <- rep(0, TT) - - for (i in 1:TT) { - Nt <- NT[i:max(1, i - k + 1)] - mu_t[i] <- sum(p[1:min(k, i)] * Nt) - } - - mu_t <- R0 * mu_t - LL <- sum(NT[-1] * log(mu_t)) - sum(mu_t) - - return(LL) -} diff --git a/R/wp.R b/R/wp.R new file mode 100644 index 0000000..04791e2 --- /dev/null +++ b/R/wp.R @@ -0,0 +1,229 @@ +#' WP method +#' +#' This function implements an R0 estimation due to White and Pagano (Statistics +#' in Medicine, 2008). The method is based on maximum likelihood estimation in a +#' Poisson transmission model. See details for important implementation notes. +#' +#' This method is based on a Poisson transmission model, and hence may be most +#' most valid at the beginning of an epidemic. In their model, the serial +#' distribution is assumed to be discrete with a finite number of posible +#' values. In this implementation, if \code{mu} is not {NA}, the serial +#' distribution is taken to be a discretized version of a gamma distribution +#' with mean \code{mu}, shape parameter one, and largest possible value based on +#' parameter \code{tol}. When \code{mu} is \code{NA}, the function implements a +#' grid search algorithm to find the maximum likelihood estimator over all +#' possible gamma distributions with unknown mean and variance, restricting +#' these to a prespecified grid (see \code{search} parameter). +#' +#' When the serial distribution is known (i.e., \code{mu} is not \code{NA}), +#' sensitivity testing of \code{mu} is strongly recommended. If the serial +#' distribution is unknown (i.e., \code{mu} is \code{NA}), the likelihood +#' function can be flat near the maximum, resulting in numerical instability of +#' the optimizer. When \code{mu} is \code{NA}, the implementation takes +#' considerably longer to run. Users should be careful about units of time +#' (e.g., are counts observed daily or weekly?) when implementing. +#' +#' The model developed in White and Pagano (2008) is discrete, and hence the +#' serial distribution is finite discrete. In our implementation, the input +#' value \code{mu} is that of a continuous distribution. The algorithm +#' discretizes this input when \code{mu} is not \code{NA}, and hence the mean of +#' the serial distribution returned in the list \code{SD} will differ from +#' \code{mu} somewhat. That is to say, if the user notices that the input +#' \code{mu} and output mean of \code{SD} are different, this is to be expected, +#' and is caused by the discretization. +#' +#' @param NT Vector of case counts. +#' @param mu Mean of the serial distribution (needs to match case counts in time +#' units; for example, if case counts are weekly and the serial +#' distribution has a mean of seven days, then \code{mu} should be set +#' to one). The default value of \code{mu} is set to \code{NA}. +#' @param search List of default values for the grid search algorithm. The list +#' includes three elements: the first is \code{B}, which is the +#' length of the grid in one dimension; the second is +#' \code{scale.max}, which is the largest possible value of the +#' scale parameter; and the third is \code{shape.max}, which is +#' the largest possible value of the shape parameter. Defaults to +#' \code{B = 100, scale.max = 10, shape.max = 10}. For both shape +#' and scale, the smallest possible value is 1/\code{B}. +#' @param tol Cutoff value for cumulative distribution function of the +#' pre-discretization gamma serial distribution. Defaults to 0.999 +#' (i.e. in the discretization, the maximum is chosen such that the +#' original gamma distribution has cumulative probability of no more +#' than 0.999 at this maximum). +#' +#' @return \code{WP} returns a list containing the following components: +#' \code{Rhat} is the estimate of R0, and \code{SD} is either the +#' discretized serial distribution (if \code{mu} is not \code{NA}), or +#' the estimated discretized serial distribution (if \code{mu} is +#' \code{NA}). The list also returns the variable \code{check}, which is +#' equal to the number of non-unique maximum likelihood estimators. The +#' serial distribution \code{SD} is returned as a list made up of +#' \code{supp} (the support of the distribution) and \code{pmf} (the +#' probability mass function). +#' +#' @examples +#' # Weekly data. +#' NT <- c(1, 4, 10, 5, 3, 4, 19, 3, 3, 14, 4) +#' +#' # Obtain R0 when the serial distribution has a mean of five days. +#' res1 <- WP(NT, mu = 5 / 7) +#' res1$Rhat +#' +#' # Obtain R0 when the serial distribution has a mean of three days. +#' res2 <- WP(NT, mu = 3 / 7) +#' res2$Rhat +#' +#' # Obtain R0 when the serial distribution is unknown. +#' # NOTE: This implementation will take longer to run. +#' res3 <- WP(NT) +#' res3$Rhat +#' +#' # Find the mean of the estimated serial distribution. +#' serial <- res3$SD +#' sum(serial$supp * serial$pmf) +#' +#' @importFrom stats pexp qexp +#' +#' @export +WP <- function(NT, mu = NA, + search = list(B = 100, shape.max = 10, scale.max = 10), + tol = 0.999) { + if (is.na(mu)) { + print("You have assumed that the serial distribution is unknown.") + res <- WP_unknown(NT, B = search$B, shape.max = search$shape.max, + scale.max = search$scale.max, tol = tol) + Rhat <- res$Rhat + p <- res$p + range.max <- res$range.max + JJ <- res$JJ + } else { + print("You have assumed that the serial distribution is known.") + range.max <- ceiling(qexp(tol, rate = 1 / mu)) + p <- diff(pexp(0:range.max, 1 / mu)) + p <- p / sum(p) + res <- WP_known(NT = NT, p = p) + Rhat <- res + JJ <- NA + } + + return(list(Rhat = Rhat, + check = length(JJ), + SD = list(supp = 1:range.max, pmf = p))) +} + +#' WP method background function WP_known +#' +#' This is a background/internal function called by \code{WP}. It computes the +#' maximum likelihood estimator of R0 assuming that the serial distribution is +#' known and finite discrete. +#' +#' @param NT Vector of case counts. +#' @param p Discretized version of the serial distribution. +#' +#' @return The function returns the maximum likelihood estimator of R0. +#' +#' @noRd +WP_known <- function(NT, p) { + k <- length(p) + TT <- length(NT) - 1 + mu_t <- rep(0, TT) + + for (i in 1:TT) { + Nt <- NT[i:max(1, i - k + 1)] + mu_t[i] <- sum(p[1:min(k, i)] * Nt) + } + + Rhat <- sum(NT[-1]) / sum(mu_t) + return(Rhat) +} + +#' WP method background function WP_unknown +#' +#' This is a background/internal function called by \code{WP}. It computes the +#' maximum likelihood estimator of R0 assuming that the serial distribution is +#' unknown but comes from a discretized gamma distribution. The function then +#' implements a simple grid search algorithm to obtain the maximum likelihood +#' estimator of R0 as well as the gamma parameters. +#' +#' @param NT Vector of case counts. +#' @param B Length of grid for shape and scale (grid search parameter). +#' @param shape.max Maximum shape value (grid \code{search} parameter). +#' @param scale.max Maximum scale value (grid \code{search} parameter). +#' @param tol cutoff value for cumulative distribution function of the serial +#' distribution (defaults to 0.999). +#' +#' @return The function returns \code{Rhat}, the maximum likelihood estimator of +#' R0, as well as the maximum likelihood estimator of the discretized +#' serial distribution given by \code{p} (the probability mass function) +#' and \code{range.max} (the distribution has support on the integers +#' one to \code{range.max}). The function also returns \code{resLL} (all +#' values of the log-likelihood) at \code{shape} (grid for shape +#' parameter) and at \code{scale} (grid for scale parameter), as well as +#' \code{resR0} (the full vector of maximum likelihood estimators), +#' \code{JJ} (the locations for the likelihood for these), and \code{J0} +#' (the location for the maximum likelihood estimator \code{Rhat}). If +#' \code{JJ} and \code{J0} are not the same, this means that the maximum +#' likelihood estimator is not unique. +#' +#' @importFrom stats pgamma qgamma +#' +#' @noRd +WP_unknown <- function(NT, B = 100, shape.max = 10, scale.max = 10, + tol = 0.999) { + shape <- seq(0, shape.max, length.out = B + 1) + scale <- seq(0, scale.max, length.out = B + 1) + shape <- shape[-1] + scale <- scale[-1] + + resLL <- matrix(0, B, B) + resR0 <- matrix(0, B, B) + + for (i in 1:B) + for (j in 1:B) { + range.max <- ceiling(qgamma(tol, shape = shape[i], scale = scale[j])) + p <- diff(pgamma(0:range.max, shape = shape[i], scale = scale[j])) + p <- p / sum(p) + mle <- WP_known(NT, p) + resLL[i, j] <- computeLL(p, NT, mle) + resR0[i, j] <- mle + } + + J0 <- which.max(resLL) + R0hat <- resR0[J0] + JJ <- which(resLL == resLL[J0], arr.ind = TRUE) + range.max <- ceiling(qgamma(tol, shape = shape[JJ[1]], scale = scale[JJ[2]])) + p <- diff(pgamma(0:range.max, shape = shape[JJ[1]], scale = scale[JJ[2]])) + p <- p / sum(p) + + return(list(Rhat = R0hat, J0 = J0, ll = resLL, Rs = resR0, scale = scale, + shape = shape, JJ = JJ, p = p, range.max = range.max)) +} + +#' WP method background function computeLL +#' +#' This is a background/internal function called by \code{WP}. It computes the +#' log-likelihood. +#' +#' @param p Discretized version of the serial distribution. +#' @param NT Vector of case counts. +#' @param R0 Basic reproductive ratio. +#' +#' @return This function returns the log-likelihood at the input variables and +#' parameters. +#' +#' @noRd +computeLL <- function(p, NT, R0) { + k <- length(p) + TT <- length(NT) - 1 + mu_t <- rep(0, TT) + + for (i in 1:TT) { + Nt <- NT[i:max(1, i - k + 1)] + mu_t[i] <- sum(p[1:min(k, i)] * Nt) + } + + mu_t <- R0 * mu_t + LL <- sum(NT[-1] * log(mu_t)) - sum(mu_t) + + return(LL) +} -- cgit v1.2.3