857: improve language around the use of dist_spec (#940)

* improve language around the use of dist_spec * add news item * add reviewer / fix typo Co-authored-by: James Azam <[email protected]> --------- Co-authored-by: James Azam <[email protected]>
epiforecasts · Jan 30, 2025 · 4b9c821 · 4b9c821
1 parent 6cb7e86
commit 4b9c821
Show file tree

Hide file tree

Showing 8 changed files with 16 additions and 9 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -33,6 +33,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.
+- The ways that `dist_spec()` with certain/uncertain parameters can be constrained has been clarified. By @sbfnk in #940 and reviewed by @jamesmbaazam.
 
 # EpiNow2 1.6.1
 

diff --git a/R/checks.R b/R/checks.R
@@ -111,9 +111,10 @@ check_stan_delay <- function(dist) {
   if (any(is.infinite(max(dist))) && !(attr(dist, "cdf_cutoff") > 0)) {
     cli_abort(
       c(
-        "i" = "All distribution passed to the model need to have a
+        "i" = "All distributions passed to the model need to have a
       {col_blue(\"finite maximum\")}, which can be achieved either by
-      setting {.var max} or non-zero {.var cdf_cutoff}."
+      setting {.var max} or, if using a distribution with fixed parameters,
+      non-zero {.var cdf_cutoff}."
       )
     )
   }

diff --git a/R/dist_spec.R b/R/dist_spec.R
@@ -751,8 +751,8 @@ plot.dist_spec <- function(x, samples = 50L, res = 1, cumulative = TRUE, ...) {
             c(
               "!" = "All distributions in {.var x} must have a finite
               maximum value.",
-              "i" = "You can set a finite maximum either as an
-              argument to {.fn plot} or when defining the distribution."
+              "i" = "You can set a finite maximum or CDF cutoff
+              when defining the distribution."
             )
           )
         }

diff --git a/R/opts.R b/R/opts.R
@@ -1199,7 +1199,8 @@ filter_opts <- function(opts, region) {
 #' @param dist A <dist_spec>
 #' @param default_cdf_cutoff Numeric; default CDF cutoff to be used if an
 #'   unconstrained distribution is passed as `dist`. If `dist` is already
-#'   constrained by having a maximum or CDF cutoff this is ignored.
+#'   constrained by having a maximum or CDF cutoff this is ignored. Note that
+#'   this can only be done for <dist_spec> objects with fixed parameters.
 #' @param cdf_cutoff_set Logical; whether the default CDF cutoff has been set by
 #'   the user; if yes and `dist` is constrained a warning is issued
 #' @importFrom cli cli_inform cli_warn

diff --git a/man/apply_default_cdf_cutoff.Rd b/man/apply_default_cdf_cutoff.Rd
diff --git a/man/delay_opts.Rd b/man/delay_opts.Rd
diff --git a/man/generation_time_opts.Rd b/man/generation_time_opts.Rd
diff --git a/man/trunc_opts.Rd b/man/trunc_opts.Rd