From 1dd2131b557bc05846a5aaddd0e6b93425c44cd9 Mon Sep 17 00:00:00 2001 From: Sebastian Funk Date: Wed, 23 Oct 2024 16:44:34 +0100 Subject: [PATCH] Documentation of alpha (#831) * update documentation of alpha * update vignette * correctly use variance / sd in alpha doc * update tests * Revert "update tests" This reverts commit 68c7b033760e64995f01fbecd2a124016841cf57. * Revert prior change * re-render docs * refine wording (where GP applies depends on model) * revert stray prior re-change --- R/opts.R | 11 ++++++----- man/gp_opts.Rd | 11 ++++++----- .../gaussian_process_implementation_details.Rmd | 12 +++++++----- 3 files changed, 19 insertions(+), 15 deletions(-) diff --git a/R/opts.R b/R/opts.R index bd08b2b44..fa4592e40 100644 --- a/R/opts.R +++ b/R/opts.R @@ -454,12 +454,13 @@ backcalc_opts <- function(prior = c("reports", "none", "infections"), #' this is smaller. #' #' @param alpha_mean Numeric, defaults to 0. The mean of the magnitude parameter -#' of the Gaussian process kernel. Should be approximately the expected variance -#' of the logged Rt. +#' of the Gaussian process kernel. Should be approximately the expected standard +#' deviation of the Gaussian process (logged Rt in case of the renewal model, +#' logged infections in case of the nonmechanistic model). #' -#' @param alpha_sd Numeric, defaults to 0.01. The standard deviation of the -#' magnitude parameter of the Gaussian process kernel. Should be approximately -#' the expected standard deviation of the logged Rt. +#' @param alpha_sd Numeric, defaults to 0.1. The standard deviation of the +#' magnitude parameter of the Gaussian process kernel. Can be tuned to adjust +#' how far alpha is allowed to deviate form its prior mean (`alpha_mean`). #' #' @param kernel Character string, the type of kernel required. Currently #' supporting the Matern kernel ("matern"), squared exponential kernel ("se"), diff --git a/man/gp_opts.Rd b/man/gp_opts.Rd index c9bbf2d9e..984baee1f 100644 --- a/man/gp_opts.Rd +++ b/man/gp_opts.Rd @@ -46,12 +46,13 @@ scale. Updated in \code{\link[=create_gp_data]{create_gp_data()}} to be the leng this is smaller.} \item{alpha_mean}{Numeric, defaults to 0. The mean of the magnitude parameter -of the Gaussian process kernel. Should be approximately the expected variance -of the logged Rt.} +of the Gaussian process kernel. Should be approximately the expected standard +deviation of the Gaussian process (logged Rt in case of the renewal model, +logged infections in case of the nonmechanistic model).} -\item{alpha_sd}{Numeric, defaults to 0.01. The standard deviation of the -magnitude parameter of the Gaussian process kernel. Should be approximately -the expected standard deviation of the logged Rt.} +\item{alpha_sd}{Numeric, defaults to 0.1. The standard deviation of the +magnitude parameter of the Gaussian process kernel. Can be tuned to adjust +how far alpha is allowed to deviate form its prior mean (\code{alpha_mean}).} \item{kernel}{Character string, the type of kernel required. Currently supporting the Matern kernel ("matern"), squared exponential kernel ("se"), diff --git a/vignettes/gaussian_process_implementation_details.Rmd b/vignettes/gaussian_process_implementation_details.Rmd index ee97fd00d..7ea2e7a29 100644 --- a/vignettes/gaussian_process_implementation_details.Rmd +++ b/vignettes/gaussian_process_implementation_details.Rmd @@ -44,21 +44,22 @@ with the following choices available for the kernel $k$ ## Matérn 3/2 covariance kernel (the default) \begin{equation} -k(\Delta t) = \alpha \left( 1 + \frac{\sqrt{3} \Delta t}{l} \right) \exp \left( - \frac{\sqrt{3} \Delta t}{l}\right) +k(\Delta t) = \alpha^2 \left( 1 + \frac{\sqrt{3} \Delta t}{l} \right) \exp \left( - \frac{\sqrt{3} \Delta t}{l}\right) \end{equation} with $l>0$ and $\alpha > 0$ the length scale and magnitude, respectively, of the kernel. +Note that here and later we use a slightly different definition of $\alpha$ compared to Riutort-Mayol et al. [@approxGP], where this is defined as our $\alpha^2$. ## Squared exponential kernel \begin{equation} -k(\Delta t) = \alpha \exp \left( - \frac{1}{2} \frac{(\Delta t^2)}{l^2} \right) +k(\Delta t) = \alpha^2 \exp \left( - \frac{1}{2} \frac{(\Delta t^2)}{l^2} \right) \end{equation} ## Ornstein-Uhlenbeck (Matérn 1/2) kernel \begin{equation} -k(\Delta t) = \alpha \exp{\left( - \frac{\Delta t}{2 l^2} \right)} +k(\Delta t) = \alpha^2 \exp{\left( - \frac{\Delta t}{2 l^2} \right)} \end{equation} ## Matérn 5/2 covariance kernel @@ -142,7 +143,7 @@ t^* = \frac{t - \frac{1}{2}t_\mathrm{GP}}{\frac{1}{2}t_\mathrm{GP}} Relevant priors are \begin{align} -\alpha &\sim \mathcal{Normal}(0, \sigma_{\alpha}) \\ +\alpha &\sim \mathcal{Normal}(\mu_\alpha, \sigma_{\alpha}) \\ \rho &\sim \mathcal{LogNormal} (\mu_\rho, \sigma_\rho)\\ \end{align} @@ -155,7 +156,8 @@ m_\rho &= 21 \\ s_\rho &= 7 \\ \rho_\mathrm{min} &= 0\\ \rho_\mathrm{max} &= 60\\ -\sigma_\alpha &= 0.05\\ +\mu_\alpha &= 0\\ +\sigma_\alpha &= 0.01 \end{align} # References