From d689ba97ea7e9288ad711139c155a3df1da2a87b Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Sun, 10 Sep 2023 21:17:56 +0100
Subject: [PATCH 1/4] Replace all occurrences of the "serial_sampler" argument
 with "serial_dist"

---
 R/checks.R                 | 10 +++++-----
 R/epichains.R              |  2 +-
 R/simulate.r               | 38 +++++++++++++++++++-------------------
 man/aggregate.epichains.Rd |  2 +-
 man/check_serial_valid.Rd  |  8 ++++----
 man/simulate_tree.Rd       | 22 +++++++++++-----------
 vignettes/epichains.Rmd    |  2 +-
 7 files changed, 42 insertions(+), 42 deletions(-)

diff --git a/R/checks.R b/R/checks.R
index a78a5516..957d2dab 100644
--- a/R/checks.R
+++ b/R/checks.R
@@ -30,18 +30,18 @@ check_offspring_func_valid <- function(roffspring_name) {
 }
 
 
-#' Check if the serials_sampler argument is specified as a function
+#' Check if the serials_dist argument is specified as a function
 #'
-#' @param serials_sampler The serial interval generator function; the name of a
+#' @param serials_dist The serial interval distribution function; the name of a
 #' user-defined named or anonymous function with only one argument `n`,
 #' representing the number of serial intervals to generate.
 #'
 #' @keywords internal
-check_serial_valid <- function(serials_sampler) {
-  if (!checkmate::test_function(serials_sampler)) {
+check_serial_valid <- function(serials_dist) {
+  if (!checkmate::test_function(serials_dist)) {
     stop(sprintf(
       "%s %s",
-      "The `serials_sampler` argument must be a function",
+      "The `serials_dist` argument must be a function",
       "(see details in ?sim_chain_tree)."
     ))
   }
diff --git a/R/epichains.R b/R/epichains.R
index 45254c7e..eb2a6ea7 100644
--- a/R/epichains.R
+++ b/R/epichains.R
@@ -257,7 +257,7 @@ tail.epichains <- function(x, ...) {
 #' set.seed(123)
 #' chains <- simulate_tree(
 #'   nchains = 10, statistic = "size",
-#'   offspring_dist = "pois", stat_max = 10, serials_sampler = function(x) 3,
+#'   offspring_dist = "pois", stat_max = 10, serials_dist = function(x) 3,
 #'   lambda = 2
 #' )
 #' chains
diff --git a/R/simulate.r b/R/simulate.r
index 6f7105b6..88499333 100644
--- a/R/simulate.r
+++ b/R/simulate.r
@@ -13,8 +13,8 @@
 #' @param stat_max A cut off for the chain statistic (size/length) being
 #' computed. Results above the specified value, are set to this value.
 #' Defaults to `Inf`.
-#' @param serials_sampler The serial interval generator function; the name of a
-#' user-defined named or anonymous function with only one argument `n`,
+#' @param serials_dist The serial interval distribution function; the name
+#' of a user-defined named or anonymous function with only one argument `n`,
 #' representing the number of serial intervals to generate.
 #' @param t0 Start time (if serial interval is given); either a single value
 #' or a vector of same length as `nchains` (number of simulations) with
@@ -31,7 +31,7 @@
 #' @details
 #' `simulate_tree()` simulates a branching process of the form:
 #' WIP
-#' # The serial interval (`serials_sampler`):
+#' # The serial interval (`serials_dist`):
 #'
 #' ## Assumptions/disambiguation
 #'
@@ -46,9 +46,9 @@
 #'
 #' See References below for some literature on the subject.
 #'
-#' ## Specifying `serials_sampler` in `simulate_tree()`
+#' ## Specifying `serials_dist` in `simulate_tree()`
 #'
-#' `serials_sampler` must be specified as a named or
+#' `serials_dist` must be specified as a named or
 #' [anonymous/inline/unnamed function](https://en.wikipedia.org/wiki/Anonymous_function#R) # nolint
 #' with one argument.
 #'
@@ -58,14 +58,14 @@
 #' let's call it "serial_interval", with only one argument representing the
 #' number of serial intervals to sample:
 #' \code{serial_interval <- function(n){rlnorm(n, 0.58, 1.38)}},
-#' and assign the name of the function to `serials_sampler` in
+#' and assign the name of the function to `serials_dist` in
 #' `simulate_tree()` like so
-#' \code{simulate_tree(..., serials_sampler = serial_interval)},
+#' \code{simulate_tree(..., serials_dist = serial_interval)},
 #' where `...` are the other arguments to `simulate_tree()`.
 #'
-#' Alternatively, we could assign an anonymous function to `serials_sampler`
+#' Alternatively, we could assign an anonymous function to `serials_dist`
 #' in the `simulate_tree()` call like so
-#' \code{simulate_tree(..., serials_sampler = function(n){rlnorm(n, 0.58, 1.38)})}, #nolint
+#' \code{simulate_tree(..., serials_dist = function(n){rlnorm(n, 0.58, 1.38)})}, #nolint
 #' where `...` are the other arguments to `simulate_tree()`.
 #' @seealso [simulate_summary()] for simulating the transmission chains
 #' statistic without the tree of infections.
@@ -73,7 +73,7 @@
 #' set.seed(123)
 #' chains <- simulate_tree(
 #'   nchains = 10, statistic = "size",
-#'   offspring_dist = "pois", stat_max = 10, serials_sampler = function(x) 3,
+#'   offspring_dist = "pois", stat_max = 10, serials_dist = function(x) 3,
 #'   lambda = 2
 #' )
 #' @references
@@ -89,7 +89,7 @@
 #' doi: 10.1093/aje/kwg251. PMID: 14630599.
 simulate_tree <- function(nchains, statistic = c("size", "length"),
                           offspring_dist, stat_max = Inf,
-                          serials_sampler, t0 = 0,
+                          serials_dist, t0 = 0,
                           tf = Inf, ...) {
   statistic <- match.arg(statistic)
 
@@ -102,10 +102,10 @@ simulate_tree <- function(nchains, statistic = c("size", "length"),
   roffspring_name <- paste0("r", offspring_dist)
   check_offspring_func_valid(roffspring_name)
 
-  if (!missing(serials_sampler)) {
-    check_serial_valid(serials_sampler)
+  if (!missing(serials_dist)) {
+    check_serial_valid(serials_dist)
   } else if (!missing(tf)) {
-    stop("If `tf` is specified, `serials_sampler` must be specified too.")
+    stop("If `tf` is specified, `serials_dist` must be specified too.")
   }
 
   # Initialisations
@@ -123,7 +123,7 @@ simulate_tree <- function(nchains, statistic = c("size", "length"),
     generation = generation
   )
 
-  if (!missing(serials_sampler)) {
+  if (!missing(serials_dist)) {
     tree_df$time <- t0
     times <- tree_df$time
   }
@@ -175,8 +175,8 @@ simulate_tree <- function(nchains, statistic = c("size", "length"),
 
       # if a serial interval model/function was specified, use it
       # to generate serial intervals for the cases
-      if (!missing(serials_sampler)) {
-        times <- rep(times, next_gen) + serials_sampler(sum(n_offspring))
+      if (!missing(serials_dist)) {
+        times <- rep(times, next_gen) + serials_dist(sum(n_offspring))
         current_min_time <- unname(tapply(times, indices, min))
         new_df$time <- times
       }
@@ -187,11 +187,11 @@ simulate_tree <- function(nchains, statistic = c("size", "length"),
     ## the specified maximum size/length
     sim <- which(n_offspring > 0 & stat_track < stat_max)
     if (length(sim) > 0) {
-      if (!missing(serials_sampler)) {
+      if (!missing(serials_dist)) {
         ## only continue to simulate chains that don't go beyond tf
         sim <- intersect(sim, unique(indices)[current_min_time < tf])
       }
-      if (!missing(serials_sampler)) {
+      if (!missing(serials_dist)) {
         times <- times[indices %in% sim]
       }
       ancestor_ids <- ids[indices %in% sim]
diff --git a/man/aggregate.epichains.Rd b/man/aggregate.epichains.Rd
index ab761c6e..eaf83f6d 100644
--- a/man/aggregate.epichains.Rd
+++ b/man/aggregate.epichains.Rd
@@ -27,7 +27,7 @@ Aggregate cases in epichains objects according to a grouping variable
 set.seed(123)
 chains <- simulate_tree(
   nchains = 10, statistic = "size",
-  offspring_dist = "pois", stat_max = 10, serials_sampler = function(x) 3,
+  offspring_dist = "pois", stat_max = 10, serials_dist = function(x) 3,
   lambda = 2
 )
 chains
diff --git a/man/check_serial_valid.Rd b/man/check_serial_valid.Rd
index 7a33c71f..3aef91b5 100644
--- a/man/check_serial_valid.Rd
+++ b/man/check_serial_valid.Rd
@@ -2,16 +2,16 @@
 % Please edit documentation in R/checks.R
 \name{check_serial_valid}
 \alias{check_serial_valid}
-\title{Check if the serials_sampler argument is specified as a function}
+\title{Check if the serials_dist argument is specified as a function}
 \usage{
-check_serial_valid(serials_sampler)
+check_serial_valid(serials_dist)
 }
 \arguments{
-\item{serials_sampler}{The serial interval generator function; the name of a
+\item{serials_dist}{The serial interval distribution function; the name of a
 user-defined named or anonymous function with only one argument \code{n},
 representing the number of serial intervals to generate.}
 }
 \description{
-Check if the serials_sampler argument is specified as a function
+Check if the serials_dist argument is specified as a function
 }
 \keyword{internal}
diff --git a/man/simulate_tree.Rd b/man/simulate_tree.Rd
index 1228087e..1d2239cc 100644
--- a/man/simulate_tree.Rd
+++ b/man/simulate_tree.Rd
@@ -9,7 +9,7 @@ simulate_tree(
   statistic = c("size", "length"),
   offspring_dist,
   stat_max = Inf,
-  serials_sampler,
+  serials_dist,
   t0 = 0,
   tf = Inf,
   ...
@@ -33,8 +33,8 @@ numbers).}
 computed. Results above the specified value, are set to this value.
 Defaults to \code{Inf}.}
 
-\item{serials_sampler}{The serial interval generator function; the name of a
-user-defined named or anonymous function with only one argument \code{n},
+\item{serials_dist}{The serial interval distribution function; the name
+of a user-defined named or anonymous function with only one argument \code{n},
 representing the number of serial intervals to generate.}
 
 \item{t0}{Start time (if serial interval is given); either a single value
@@ -59,7 +59,7 @@ Simulate a tree of infections with a serial and offspring distributions
 \code{simulate_tree()} simulates a branching process of the form:
 WIP
 }
-\section{The serial interval (\code{serials_sampler}):}{
+\section{The serial interval (\code{serials_dist}):}{
 \subsection{Assumptions/disambiguation}{
 
 In epidemiology, the generation interval is the duration between successive
@@ -74,9 +74,9 @@ generation interval, that is, the time between successive cases.
 See References below for some literature on the subject.
 }
 
-\subsection{Specifying \code{serials_sampler} in \code{simulate_tree()}}{
+\subsection{Specifying \code{serials_dist} in \code{simulate_tree()}}{
 
-\code{serials_sampler} must be specified as a named or
+\code{serials_dist} must be specified as a named or
 \href{https://en.wikipedia.org/wiki/Anonymous_function#R}{anonymous/inline/unnamed function} # nolint
 with one argument.
 
@@ -86,14 +86,14 @@ generator as a random log-normally distributed variable with
 let's call it "serial_interval", with only one argument representing the
 number of serial intervals to sample:
 \code{serial_interval <- function(n){rlnorm(n, 0.58, 1.38)}},
-and assign the name of the function to \code{serials_sampler} in
+and assign the name of the function to \code{serials_dist} in
 \code{simulate_tree()} like so
-\code{simulate_tree(..., serials_sampler = serial_interval)},
+\code{simulate_tree(..., serials_dist = serial_interval)},
 where \code{...} are the other arguments to \code{simulate_tree()}.
 
-Alternatively, we could assign an anonymous function to \code{serials_sampler}
+Alternatively, we could assign an anonymous function to \code{serials_dist}
 in the \code{simulate_tree()} call like so
-\code{simulate_tree(..., serials_sampler = function(n){rlnorm(n, 0.58, 1.38)})}, #nolint
+\code{simulate_tree(..., serials_dist = function(n){rlnorm(n, 0.58, 1.38)})}, #nolint
 where \code{...} are the other arguments to \code{simulate_tree()}.
 }
 }
@@ -102,7 +102,7 @@ where \code{...} are the other arguments to \code{simulate_tree()}.
 set.seed(123)
 chains <- simulate_tree(
   nchains = 10, statistic = "size",
-  offspring_dist = "pois", stat_max = 10, serials_sampler = function(x) 3,
+  offspring_dist = "pois", stat_max = 10, serials_dist = function(x) 3,
   lambda = 2
 )
 }
diff --git a/vignettes/epichains.Rmd b/vignettes/epichains.Rmd
index 68c21807..2e52afe1 100644
--- a/vignettes/epichains.Rmd
+++ b/vignettes/epichains.Rmd
@@ -68,7 +68,7 @@ library(epichains)
 tree_from_pois_offspring <- simulate_tree(
   nchains = 10,
   offspring_dist = "pois",
-  serials_sampler = function(x) 3,
+  serials_dist = function(x) 3,
   lambda = 2,
   stat_max = 10
 )

From eb592aba075cc3bd134a4cd02815df526d6c497a Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Sun, 10 Sep 2023 20:35:47 +0000
Subject: [PATCH 2/4] Update CITATION.cff

---
 CITATION.cff | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CITATION.cff b/CITATION.cff
index 6f2cf95b..3dac125f 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -49,6 +49,8 @@ keywords:
 - epidemic-dynamics
 - epidemic-modelling
 - epidemic-simulations
+- epidemiology
+- epidemiology-models
 - outbreak-simulator
 - r-package
 - r-stats

From c87aaed8c7784c152bf6d1c38f15b915bb2c2822 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Mon, 11 Sep 2023 13:37:18 +0100
Subject: [PATCH 3/4] Replace all occurences of the argument `serial_dist` with
 `serials_dist`

---
 R/simulate.r                  | 10 +++++-----
 man/simulate_tree_from_pop.Rd |  8 ++++----
 tests/testthat/tests-sim.r    |  2 +-
 vignettes/epichains.Rmd       |  4 ++--
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/R/simulate.r b/R/simulate.r
index 88499333..72fb6ab1 100644
--- a/R/simulate.r
+++ b/R/simulate.r
@@ -297,7 +297,7 @@ simulate_summary <- function(nchains, statistic = c("size", "length"),
 #' secondary cases. Ignored if \code{offspring == "pois"}. Must be > 1 to
 #' avoid division by 0 when calculating the size. See details and
 #'  \code{?rnbinom} for details on the parameterisation in Ecology.
-#' @param serial_dist The serial interval. A function that takes one
+#' @param serials_dist The serial interval. A function that takes one
 #' parameter (`n`), the number of serial intervals to randomly sample. Value
 #' must be >= 0.
 #' @param initial_immune The number of initial immunes in the population.
@@ -334,20 +334,20 @@ simulate_summary <- function(nchains, statistic = c("size", "length"),
 #' # Simulate with poisson offspring
 #' simulate_tree_from_pop(
 #'   pop = 100, offspring_dist = "pois",
-#'   offspring_mean = 0.5, serial_dist = function(x) 3
+#'   offspring_mean = 0.5, serials_dist = function(x) 3
 #' )
 #'
 #' # Simulate with negative binomial offspring
 #' simulate_tree_from_pop(
 #'   pop = 100, offspring_dist = "nbinom",
-#'   offspring_mean = 0.5, offspring_disp = 1.1, serial_dist = function(x) 3
+#'   offspring_mean = 0.5, offspring_disp = 1.1, serials_dist = function(x) 3
 #' )
 #' @export
 simulate_tree_from_pop <- function(pop,
                                    offspring_dist = c("pois", "nbinom"),
                                    offspring_mean,
                                    offspring_disp,
-                                   serial_dist,
+                                   serials_dist,
                                    initial_immune = 0,
                                    t0 = 0,
                                    tf = Inf) {
@@ -418,7 +418,7 @@ simulate_tree_from_pop <- function(pop,
     ## add to df
     if (n_offspring > 0) {
       ## draw serial times
-      new_times <- serial_dist(n_offspring)
+      new_times <- serials_dist(n_offspring)
 
       if (any(new_times < 0)) {
         stop("Serial interval must be >= 0.")
diff --git a/man/simulate_tree_from_pop.Rd b/man/simulate_tree_from_pop.Rd
index 17b5ad2f..57c5e83a 100644
--- a/man/simulate_tree_from_pop.Rd
+++ b/man/simulate_tree_from_pop.Rd
@@ -10,7 +10,7 @@ simulate_tree_from_pop(
   offspring_dist = c("pois", "nbinom"),
   offspring_mean,
   offspring_disp,
-  serial_dist,
+  serials_dist,
   initial_immune = 0,
   t0 = 0,
   tf = Inf
@@ -32,7 +32,7 @@ secondary cases. Ignored if \code{offspring == "pois"}. Must be > 1 to
 avoid division by 0 when calculating the size. See details and
 \code{?rnbinom} for details on the parameterisation in Ecology.}
 
-\item{serial_dist}{The serial interval. A function that takes one
+\item{serials_dist}{The serial interval. A function that takes one
 parameter (\code{n}), the number of serial intervals to randomly sample. Value
 must be >= 0.}
 
@@ -79,13 +79,13 @@ simulate_tree_from_pop() has a couple of key different from simulate_tree():
 # Simulate with poisson offspring
 simulate_tree_from_pop(
   pop = 100, offspring_dist = "pois",
-  offspring_mean = 0.5, serial_dist = function(x) 3
+  offspring_mean = 0.5, serials_dist = function(x) 3
 )
 
 # Simulate with negative binomial offspring
 simulate_tree_from_pop(
   pop = 100, offspring_dist = "nbinom",
-  offspring_mean = 0.5, offspring_disp = 1.1, serial_dist = function(x) 3
+  offspring_mean = 0.5, offspring_disp = 1.1, serials_dist = function(x) 3
 )
 }
 \author{
diff --git a/tests/testthat/tests-sim.r b/tests/testthat/tests-sim.r
index 9b5868d0..67386a95 100644
--- a/tests/testthat/tests-sim.r
+++ b/tests/testthat/tests-sim.r
@@ -15,7 +15,7 @@ test_that("Simulators output epichains objects", {
       offspring_dist = "nbinom",
       offspring_mean = 0.5,
       offspring_disp = 1.1,
-      serial_dist = function(x) 3
+      serials_dist = function(x) 3
     ),
     "epichains"
   )
diff --git a/vignettes/epichains.Rmd b/vignettes/epichains.Rmd
index 2e52afe1..2dcb1f0f 100644
--- a/vignettes/epichains.Rmd
+++ b/vignettes/epichains.Rmd
@@ -91,7 +91,7 @@ tree_from_pop_pois <- simulate_tree_from_pop(
   pop = 1000,
   offspring_dist = "pois",
   offspring_mean = 0.5,
-  serial_dist = function(x) 3
+  serials_dist = function(x) 3
 )
 
 tree_from_pop_pois # print the output
@@ -102,7 +102,7 @@ tree_from_pop_nbinom <- simulate_tree_from_pop(
   offspring_dist = "nbinom",
   offspring_mean = 0.5,
   offspring_disp = 1.1,
-  serial_dist = function(x) 3
+  serials_dist = function(x) 3
 )
 
 tree_from_pop_nbinom # print the output

From f4c1f0f0f83718f9397dcff08a1980033f7e807b Mon Sep 17 00:00:00 2001
From: GitHub Action <action@github.com>
Date: Sun, 10 Sep 2023 20:35:47 +0000
Subject: [PATCH 4/4] Update CITATION.cff

---
 CITATION.cff | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CITATION.cff b/CITATION.cff
index 6f2cf95b..3dac125f 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -49,6 +49,8 @@ keywords:
 - epidemic-dynamics
 - epidemic-modelling
 - epidemic-simulations
+- epidemiology
+- epidemiology-models
 - outbreak-simulator
 - r-package
 - r-stats