Use natural parameters when specifying uncertain distributions (#893)

* Use natural parameters in all examples * Add NEWS item * Remove statement about warning * Remove use of Fixed() for specifying fixed parameters * Redocument * Fix missing comma * Change uncertain parameters to numeric * Revert to using mean and sd * Use numeric instead of uncertain parameters * Revert indentation * Use natural parameters to specify uncertain distributions * Redoc after revert to mean and sd for numeric parameters * Update NEWS * Fix example in collapse.dist_spec * Align code with text * Use natural params of Gamma in vignette example * Update LogNormal example Co-authored-by: Sebastian Funk <[email protected]> * Generate docs --------- Co-authored-by: Sebastian Funk <[email protected]>
epiforecasts · Dec 17, 2024 · c04265c · c04265c
1 parent 9468c73
commit c04265c
Show file tree

Hide file tree

Showing 19 changed files with 150 additions and 65 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -29,6 +29,7 @@
 
 - Brought the docs on `alpha_sd` up to date with the code change from prior PR #853. By @zsusswein in #862 and reviewed by @jamesmbaazam.
 - The `...` argument in `estimate_secondary()` has been removed because it was not used. By @jamesmbaazam in #894 and reviewed by @.
+- All examples now use the natural parameters of distributions rather than the mean and standard deviation when specifying uncertain distributions. This is to eliminate warnings and encourage best practice. By @jamesmbaazam in #893 and reviewed by @sbfnk.
 
 # EpiNow2 1.6.1
 

diff --git a/R/dist_spec.R b/R/dist_spec.R
@@ -116,9 +116,12 @@ discrete_pmf <- function(distribution =
 #' )
 #' dist1 + dist1
 #'
-#' # An uncertain gamma distribution with mean 3 and sd 2
+#' # An uncertain gamma distribution with shape and rate normally distributed
+#' # as Normal(3, 0.5) and Normal(2, 0.5) respectively
 #' dist2 <- Gamma(
-#'   mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
+#'   shape = Normal(3, 0.5),
+#'   rate = Normal(2, 0.5),
+#'   max = 20
 #' )
 #' dist1 + dist2
 `+.dist_spec` <- function(e1, e2) {
@@ -197,9 +200,12 @@ discrete_pmf <- function(distribution =
 #' )
 #' dist1 + dist1
 #'
-#' # An uncertain gamma distribution with mean 3 and sd 2
+#' # An uncertain gamma distribution with shape and rate normally distributed
+#' # as Normal(3, 0.5) and Normal(2, 0.5) respectively
 #' dist2 <- Gamma(
-#'   mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
+#'   shape = Normal(3, 0.5),
+#'   rate = Normal(2, 0.5),
+#'   max = 20
 #' )
 #' c(dist1, dist2)
 c.dist_spec <- function(...) {
@@ -257,9 +263,12 @@ c.dist_spec <- function(...) {
 #' dist1 <- LogNormal(mean = 5, sd = 1, max = 20)
 #' mean(dist1)
 #'
-#' # An uncertain gamma distribution with mean 3 and sd 2
+#' # An uncertain gamma distribution with shape and rate normally distributed
+#' # as Normal(3, 0.5) and Normal(2, 0.5) respectively
 #' dist2 <- Gamma(
-#'  mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
+#'   shape = Normal(3, 0.5),
+#'   rate = Normal(2, 0.5),
+#'   max = 20
 #' )
 #' mean(dist2)
 #'
@@ -393,8 +402,13 @@ sd.default <- function(x, ...) {
 #' dist1 <- Gamma(mean = 5, sd = 1, max = 20)
 #' max(dist1)
 #'
-#' # An uncertain lognormal distribution with mean 3 and sd 2
-#' dist2 <- LogNormal(mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20)
+#' # An uncertain lognormal distribution with meanlog and sdlog normally
+#' # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
+#' dist2 <- LogNormal(
+#'   meanlog = Normal(3, 0.5),
+#'   sdlog = Normal(2, 0.5),
+#'   max = 20
+#' )
 #' max(dist2)
 #'
 #' # The max the sum of two distributions
@@ -447,8 +461,13 @@ discretise <- function(x, ...) {
 #' # A fixed gamma distribution with mean 5 and sd 1.
 #' dist1 <- Gamma(mean = 5, sd = 1, max = 20)
 #'
-#' # An uncertain lognormal distribution with mean 3 and sd 2
-#' dist2 <- LogNormal(mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20)
+#' # An uncertain lognormal distribution with meanlog and sdlog normally
+#' # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
+#' dist2 <- LogNormal(
+#'   meanlog = Normal(3, 0.5),
+#'   sdlog = Normal(2, 0.5),
+#'   max = 20
+#' )
 #'
 #' # The maxf the sum of two distributions
 #' discretise(dist1 + dist2, strict = FALSE)
@@ -531,11 +550,16 @@ collapse <- function(x, ...) {
 #' # A fixed gamma distribution with mean 5 and sd 1.
 #' dist1 <- Gamma(mean = 5, sd = 1, max = 20)
 #'
-#' # An uncertain lognormal distribution with mean 3 and sd 2
-#' dist2 <- LogNormal(mean = 3, sd = 2, max = 20)
+#' # An uncertain lognormal distribution with meanlog and sdlog normally
+#' # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
+#' dist2 <- LogNormal(
+#'   meanlog = Normal(3, 0.5),
+#'   sdlog = Normal(2, 0.5),
+#'   max = 20
+#' )
 #'
 #' # The maxf the sum of two distributions
-#' collapse(discretise(dist1 + dist2))
+#' collapse(discretise(dist1 + dist2, strict = FALSE))
 collapse.dist_spec <- function(x, ...) {
   return(x)
 }
@@ -588,9 +612,10 @@ collapse.multi_dist_spec <- function(x, ...) {
 #' dist1 <- LogNormal(mean = 1.5, sd = 0.5, max = 20)
 #' print(dist1)
 #'
-#' # An uncertain gamma distribution with mean 3 and sd 2
+#' # An uncertain gamma distribution with shape and rate normally distributed
+#' # as Normal(3, 0.5) and Normal(2, 0.5) respectively
 #' dist2 <- Gamma(
-#'   mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
+#'   shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20
 #' )
 #' print(dist2)
 print.dist_spec <- function(x, ...) {
@@ -680,9 +705,12 @@ print.dist_spec <- function(x, ...) {
 #' # Plot discretised distribution with 0.01 day discretisation window
 #' plot(dist1, res = 0.01, cumulative = FALSE)
 #'
-#' # An uncertain gamma distribution with mean 3 and sd 2
+#' # An uncertain gamma distribution with shape and rate normally distributed
+#' # as Normal(3, 0.5) and Normal(2, 0.5) respectively
 #' dist2 <- Gamma(
-#'   mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
+#'   shape = Normal(3, 0.5),
+#'   rate = Normal(2, 0.5),
+#'   max = 20
 #' )
 #' plot(dist2)
 #'
@@ -781,9 +809,12 @@ plot.dist_spec <- function(x, samples = 50L, res = 1, cumulative = TRUE, ...) {
 #' @examples
 #' dist1 <- LogNormal(mean = 1.6, sd = 0.5, max = 20)
 #'
-#' # An uncertain gamma distribution with mean 3 and sd 2
+#' # An uncertain gamma distribution with shape and rate normally distributed
+#' # as Normal(3, 0.5) and Normal(2, 0.5) respectively
 #' dist2 <- Gamma(
-#'   mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20
+#'   shape = Normal(3, 0.5),
+#'   rate = Normal(2, 0.5),
+#'   max = 20
 #' )
 #'
 #' # Multiple distributions
@@ -828,9 +859,12 @@ fix_parameters <- function(x, ...) {
 #' @importFrom rlang arg_match
 #' @method fix_parameters dist_spec
 #' @examples
-#' # An uncertain gamma distribution with mean 3 and sd 2
-#' dist <- LogNormal(
-#'   meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20
+#' # An uncertain gamma distribution with shape and rate normally distributed
+#' # as Normal(3, 0.5) and Normal(2, 0.5) respectively
+#' dist <- Gamma(
+#'   shape = Normal(3, 0.5),
+#'   rate = Normal(2, 0.5),
+#'   max = 20
 #' )
 #'
 #' fix_parameters(dist)
@@ -891,8 +925,13 @@ is_constrained <- function(x, ...) {
 #' # A fixed gamma distribution with mean 5 and sd 1.
 #' dist1 <- Gamma(mean = 5, sd = 1, max = 20)
 #'
-#' # An uncertain lognormal distribution with mean 3 and sd 2
-#' dist2 <- LogNormal(mean = Normal(3, 0.5), sd = Normal(2, 0.5), max = 20)
+#' # An uncertain lognormal distribution with meanlog and sdlog normally
+#' # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively
+#' dist2 <- LogNormal(
+#'   meanlog = Normal(3, 0.5),
+#'   sdlog = Normal(2, 0.5),
+#'   max = 20
+#' )
 #'
 #' # both distributions are constrained and therefore so is the sum
 #' is_constrained(dist1 + dist2)
@@ -952,7 +991,8 @@ is_constrained.multi_dist_spec <- function(x, ...) {
 #' @examples
 #' LogNormal(mean = 4, sd = 1)
 #' LogNormal(mean = 4, sd = 1, max = 10)
-#' LogNormal(mean = Normal(4, 1), sd = 1, max = 10)
+#' # If specifying uncertain parameters, use the natural parameters
+#' LogNormal(meanlog = Normal(1.5, 0.5), sdlog = 0.25, max = 10)
 LogNormal <- function(meanlog, sdlog, mean, sd, ...) {
   params <- as.list(environment())
   return(new_dist_spec(params, "lognormal", ...))

diff --git a/R/opts.R b/R/opts.R
@@ -42,8 +42,8 @@
 #' # An uncertain gamma distributed generation time
 #' generation_time_opts(
 #'   Gamma(
-#'     mean = Normal(mean = 3, sd = 1),
-#'     sd = Normal(mean = 2, sd = 0.5),
+#'     shape = Normal(mean = 3, sd = 1),
+#'     rate = Normal(mean = 2, sd = 0.5),
 #'     max = 14
 #'   )
 #' )
@@ -186,7 +186,11 @@ secondary_opts <- function(type = c("incidence", "prevalence"), ...) {
 #' delay_opts()
 #'
 #' # A single delay that has uncertainty
-#' delay <- LogNormal(mean = Normal(1, 0.2), sd = Normal(0.5, 0.1), max = 14)
+#' delay <- LogNormal(
+#'   meanlog = Normal(1, 0.2),
+#'   sdlog = Normal(0.5, 0.1),
+#'   max = 14
+#' )
 #' delay_opts(delay)
 #'
 #' # A single delay without uncertainty

diff --git a/man/Distributions.Rd b/man/Distributions.Rd
diff --git a/man/c.dist_spec.Rd b/man/c.dist_spec.Rd
diff --git a/man/collapse.Rd b/man/collapse.Rd
diff --git a/man/delay_opts.Rd b/man/delay_opts.Rd
diff --git a/man/discretise.Rd b/man/discretise.Rd
diff --git a/man/extract_single_dist.Rd b/man/extract_single_dist.Rd
diff --git a/man/fix_parameters.Rd b/man/fix_parameters.Rd
diff --git a/man/generation_time_opts.Rd b/man/generation_time_opts.Rd
diff --git a/man/is_constrained.Rd b/man/is_constrained.Rd
diff --git a/man/max.dist_spec.Rd b/man/max.dist_spec.Rd
diff --git a/man/mean.dist_spec.Rd b/man/mean.dist_spec.Rd
diff --git a/man/plot.dist_spec.Rd b/man/plot.dist_spec.Rd