From ca09dea3302b70368384b26139dd0f6d30f5666b Mon Sep 17 00:00:00 2001
From: Sebastian Funk <sebastian.funk@lshtm.ac.uk>
Date: Tue, 1 Oct 2024 09:34:14 +0100
Subject: [PATCH 1/4] deprecate nonzero 0-bin generation times

---
 R/checks.R                   | 33 +++++++++++++++++++++++++++++++++
 R/opts.R                     |  2 +-
 man/check_generation_time.Rd | 17 +++++++++++++++++
 3 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 man/check_generation_time.Rd

diff --git a/R/checks.R b/R/checks.R
index 2ad4136aa..7d82a09a9 100644
--- a/R/checks.R
+++ b/R/checks.R
@@ -120,6 +120,39 @@ check_stan_delay <- function(dist) {
   }
 }
 
+#' Validate probability distribution for using as generation time
+#'
+#' @description `r lifecycle::badge("stable")`
+#' does all the checks in`check_stan_delay()` and additionally makes sure
+#' that if `dist` is nonparametric,  its first element is zero.
+#'
+#' @importFrom lifecycle deprecate_warn
+#' @inheritParams check_stan_delay dist
+#' @return Called for its side effects.
+#' @keywords internal
+check_generation_time <- function(dist) {
+  # Do the standard delay checks
+  check_stan_delay(dist)
+  ## check for nonparametric with nonzero first element
+  nonzero_first_element <- vapply(seq_len(ndist(dist)), function(i) {
+    get_distribution(dist, i) == "nonparametric" && get_pmf(dist, i)[1] > 0
+  }, logical(1))
+  if (all(nonzero_first_element)) {
+    deprecate_warn(
+      "1.6.0",
+      I(
+        "Specifying nonparametric generation times with nonzero first element"
+      ),
+      details = c(
+        "Since zero generation times are not supported by the model, the
+         generation time will be left-truncated at one. ",
+        "In future versions this will cause an error. Please ensure that the
+         first element of the nonparametric generation interval is zero."
+      )
+    )
+  }
+}
+
 #' Check that PMF tail is not sparse
 #'
 #' @description Checks if the tail of a PMF vector has more than `span`
diff --git a/R/opts.R b/R/opts.R
index bd94a2ec4..4e7e0f119 100644
--- a/R/opts.R
+++ b/R/opts.R
@@ -83,7 +83,7 @@ gt_opts <- function(dist = Fixed(1), ...,
   )
   attr(dist, "weight_prior") <- weight_prior
   attr(dist, "class") <- c("generation_time_opts", class(dist))
-  check_stan_delay(dist)
+  check_generation_time(dist)
   return(dist)
 }
 
diff --git a/man/check_generation_time.Rd b/man/check_generation_time.Rd
new file mode 100644
index 000000000..d0b02c524
--- /dev/null
+++ b/man/check_generation_time.Rd
@@ -0,0 +1,17 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/checks.R
+\name{check_generation_time}
+\alias{check_generation_time}
+\title{Validate probability distribution for using as generation time}
+\usage{
+check_generation_time(dist)
+}
+\value{
+Called for its side effects.
+}
+\description{
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}
+does all the checks in\code{check_stan_delay()} and additionally makes sure
+that if \code{dist} is nonparametric,  its first element is zero.
+}
+\keyword{internal}

From 9f1829c743bf4104e83d68dbb408be4ed9dc56a7 Mon Sep 17 00:00:00 2001
From: Sebastian Funk <sebastian.funk@lshtm.ac.uk>
Date: Tue, 1 Oct 2024 09:34:25 +0100
Subject: [PATCH 2/4] add deprecation test

---
 tests/testthat/test-delays.R | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/tests/testthat/test-delays.R b/tests/testthat/test-delays.R
index e2f056b3b..1c8bae4a7 100644
--- a/tests/testthat/test-delays.R
+++ b/tests/testthat/test-delays.R
@@ -92,3 +92,13 @@ test_that("distributions incompatible with stan models are caught", {
     Normal(2, 2, max = 10)
   ), "lognormal")
 })
+
+test_that("nonparametric PMFs with nonzero first element for the generation time are deprecated", {
+  expect_deprecated(
+    gt_opts(c(
+      NonParametric(c(0.1, 0.5, 0.4)),
+      NonParametric(c(0.2, 0.6, 0.2))
+    )),
+    "nonzero first element"
+  )
+})

From fc116398a66a78f2c229ec39fb4c6f7d5cf1aa68 Mon Sep 17 00:00:00 2001
From: Sebastian Funk <sebastian.funk@lshtm.ac.uk>
Date: Tue, 1 Oct 2024 09:34:34 +0100
Subject: [PATCH 3/4] clarify documentation

---
 R/opts.R                    |  9 ++++++++-
 man/generation_time_opts.Rd | 11 ++++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/R/opts.R b/R/opts.R
index 4e7e0f119..66d8c56d2 100644
--- a/R/opts.R
+++ b/R/opts.R
@@ -3,9 +3,16 @@
 #' @description `r lifecycle::badge("stable")`
 #' Returns generation time parameters in a format for lower level model use.
 #'
+#' @details Because the discretised renewal equation used in the package does
+#'   not support zero generation times, any distribution specified here will be
+#'   left-truncated at one, i.e. the first element of the nonparametric or
+#'   discretised probability distribution used for the generation time is set to
+#'   zero and the resulting distribution renormalised.
 #' @rdname generation_time_opts
 #' @param dist A delay distribution or series of delay distributions . If no
-#'   distribution is given a fixed generation time of 1 will be assumed.
+#'   distribution is given a fixed generation time of 1 will be assumed.  If
+#'   passing a nonparametric distribution the first element should be zero (see
+#'   *Details* section)
 #'
 #' @param ... deprecated; use `dist` instead
 #' @param disease deprecated; use `dist` instead
diff --git a/man/generation_time_opts.Rd b/man/generation_time_opts.Rd
index 58ddcafdc..1200101c7 100644
--- a/man/generation_time_opts.Rd
+++ b/man/generation_time_opts.Rd
@@ -29,7 +29,9 @@ generation_time_opts(
 }
 \arguments{
 \item{dist}{A delay distribution or series of delay distributions . If no
-distribution is given a fixed generation time of 1 will be assumed.}
+distribution is given a fixed generation time of 1 will be assumed.  If
+passing a nonparametric distribution the first element should be zero (see
+\emph{Details} section)}
 
 \item{...}{deprecated; use \code{dist} instead}
 
@@ -60,6 +62,13 @@ distributions.
 \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}
 Returns generation time parameters in a format for lower level model use.
 }
+\details{
+Because the discretised renewal equation used in the package does
+not support zero generation times, any distribution specified here will be
+left-truncated at one, i.e. the first element of the nonparametric or
+discretised probability distribution used for the generation time is set to
+zero and the resulting distribution renormalised.
+}
 \examples{
 # default settings with a fixed generation time of 1
 generation_time_opts()

From 91fe84616799417c13ad68d267e0017493ba12c7 Mon Sep 17 00:00:00 2001
From: Sebastian Funk <sebastian.funk@lshtm.ac.uk>
Date: Tue, 1 Oct 2024 09:34:57 +0100
Subject: [PATCH 4/4] add news item

---
 NEWS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/NEWS.md b/NEWS.md
index b90816eda..082246876 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -33,6 +33,7 @@ A release that introduces model improvements to the Gaussian Process models, alo
 - `fix_dist()` has been renamed to `fix_parameters()` because it removes the uncertainty in a distribution's parameters. By @sbfnk in #733 and reviewed by @jamesmbaazam.
 - `plot.dist_spec` now uses color instead of line types to display pmfs vs cmfs. By @jamesmbaazam in #788 and reviewed by @sbfnk.
 - The use of the `{progressr}` package for displaying progress bars is now optional, as is the use of `{future}` and `{future.apply}` for parallelisation. By @sbfnk in #798 and reviewed by @seabbs.
+- Specifying nonparametric generation time intervals with a nonzero first element (corresponding to the zero bin) is being deprecated as the current behaviour of setting it to zero internally was not well exposed. By @sbfnk in #.
 
 ## Bug fixes