From eaaee1716a6019f2de4a4cfd198286713f4fa286 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Mon, 4 Sep 2023 17:54:33 +0100
Subject: [PATCH 01/17] Delete duplicated return value in function doc

---
 R/likelihood.R | 1 -
 1 file changed, 1 deletion(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index a9f566f0..07b2aec4 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -13,7 +13,6 @@
 #' contributions will be returned rather than the sum.
 #' @param ... Parameters for the offspring distribution.
 #' @return
-#' * A log-likelihood, if \code{log = TRUE} (the default)
 #' * A vector of log-likelihoods, if \code{log = TRUE} (the default) and
 #' \code{obs_prob < 1}, or
 #' * A list of individual log-likelihood contributions, if

From aab90de5ed4f7ca41c695294d377b9a322cade73 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 17:11:27 +0100
Subject: [PATCH 02/17] Replace "likelihood" with "log-likelihood" to clarify
 that the latter is being calculated

---
 R/stat_likelihoods.R  | 17 +++++++++--------
 man/gborel_size_ll.Rd |  4 ++--
 man/geom_length_ll.Rd |  4 ++--
 man/likelihood.Rd     |  1 -
 man/nbinom_size_ll.Rd |  4 ++--
 man/offspring_ll.Rd   |  7 ++++---
 man/pois_length_ll.Rd |  4 ++--
 man/pois_size_ll.Rd   |  4 ++--
 8 files changed, 23 insertions(+), 22 deletions(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index f54b7736..028fba92 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -1,4 +1,4 @@
-#' Likelihood of the size of chains with Poisson offspring distribution
+#' Log-likelihood of the size of chains with Poisson offspring distribution
 #'
 #' @param x vector of sizes
 #' @param lambda rate of the Poisson distribution
@@ -9,7 +9,7 @@ pois_size_ll <- function(x, lambda) {
   (x - 1) * log(lambda) - lambda * x + (x - 2) * log(x) - lgamma(x)
 }
 
-#' Likelihood of the size of chains with Negative-Binomial offspring
+#' Log-likelihood of the size of chains with Negative-Binomial offspring
 #' distribution
 #'
 #' @param x vector of sizes
@@ -31,7 +31,7 @@ nbinom_size_ll <- function(x, size, prob, mu) {
     (size * x + (x - 1)) * log(1 + mu / size)
 }
 
-#' Likelihood of the size of chains with gamma-Borel offspring distribution
+#' Log-likelihood of the size of chains with gamma-Borel offspring distribution
 #'
 #' @param x vector of sizes
 #' @param size the dispersion parameter (often called \code{k} in ecological
@@ -52,7 +52,7 @@ gborel_size_ll <- function(x, size, prob, mu) {
     (x - 1) * log(x) - (size + x - 1) * log(x + size / mu)
 }
 
-#' Likelihood of the length of chains with Poisson offspring distribution
+#' Log-likelihood of the length of chains with Poisson offspring distribution
 #'
 #' @param x vector of sizes
 #' @param lambda rate of the Poisson distribution
@@ -70,7 +70,7 @@ pois_length_ll <- function(x, lambda) {
   log(Gk[x + 1] - Gk[x])
 }
 
-#' Likelihood of the length of chains with geometric offspring distribution
+#' Log-likelihood of the length of chains with geometric offspring distribution
 #'
 #' @param x vector of sizes
 #' @param prob probability of the geometric distribution with mean
@@ -86,10 +86,11 @@ geom_length_ll <- function(x, prob) {
   log(GkmGkm1)
 }
 
-#' Likelihood of the length of chains with generic offspring distribution
+#' Log-likelihood of the summary (size/length) of chains with generic offspring
+#' distribution
 #'
-#' The likelihoods are calculated with a crude approximation using simulated
-#' chains by linearly approximating any missing values in the empirical
+#' The log-likelihoods are calculated with a crude approximation using simulated
+#' chain summaries by linearly approximating any missing values in the empirical
 #' cumulative distribution function (ecdf).
 #' @inheritParams likelihood
 #' @inheritParams simulate_vec
diff --git a/man/gborel_size_ll.Rd b/man/gborel_size_ll.Rd
index 618659f2..752aa56a 100644
--- a/man/gborel_size_ll.Rd
+++ b/man/gborel_size_ll.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/stat_likelihoods.R
 \name{gborel_size_ll}
 \alias{gborel_size_ll}
-\title{Likelihood of the size of chains with gamma-Borel offspring distribution}
+\title{Log-likelihood of the size of chains with gamma-Borel offspring distribution}
 \usage{
 gborel_size_ll(x, size, prob, mu)
 }
@@ -21,7 +21,7 @@ applications)}
 log-likelihood values
 }
 \description{
-Likelihood of the size of chains with gamma-Borel offspring distribution
+Log-likelihood of the size of chains with gamma-Borel offspring distribution
 }
 \author{
 Sebastian Funk
diff --git a/man/geom_length_ll.Rd b/man/geom_length_ll.Rd
index f200df93..6c7dc6ad 100644
--- a/man/geom_length_ll.Rd
+++ b/man/geom_length_ll.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/stat_likelihoods.R
 \name{geom_length_ll}
 \alias{geom_length_ll}
-\title{Likelihood of the length of chains with geometric offspring distribution}
+\title{Log-likelihood of the length of chains with geometric offspring distribution}
 \usage{
 geom_length_ll(x, prob)
 }
@@ -16,7 +16,7 @@ geom_length_ll(x, prob)
 log-likelihood values
 }
 \description{
-Likelihood of the length of chains with geometric offspring distribution
+Log-likelihood of the length of chains with geometric offspring distribution
 }
 \author{
 Sebastian Funk
diff --git a/man/likelihood.Rd b/man/likelihood.Rd
index 3bd9e76e..b5b77844 100644
--- a/man/likelihood.Rd
+++ b/man/likelihood.Rd
@@ -52,7 +52,6 @@ contributions will be returned rather than the sum.}
 }
 \value{
 \itemize{
-\item A log-likelihood, if \code{log = TRUE} (the default)
 \item A vector of log-likelihoods, if \code{log = TRUE} (the default) and
 \code{obs_prob < 1}, or
 \item A list of individual log-likelihood contributions, if
diff --git a/man/nbinom_size_ll.Rd b/man/nbinom_size_ll.Rd
index 14003322..6bbd2475 100644
--- a/man/nbinom_size_ll.Rd
+++ b/man/nbinom_size_ll.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/stat_likelihoods.R
 \name{nbinom_size_ll}
 \alias{nbinom_size_ll}
-\title{Likelihood of the size of chains with Negative-Binomial offspring
+\title{Log-likelihood of the size of chains with Negative-Binomial offspring
 distribution}
 \usage{
 nbinom_size_ll(x, size, prob, mu)
@@ -22,7 +22,7 @@ applications)}
 log-likelihood values
 }
 \description{
-Likelihood of the size of chains with Negative-Binomial offspring
+Log-likelihood of the size of chains with Negative-Binomial offspring
 distribution
 }
 \author{
diff --git a/man/offspring_ll.Rd b/man/offspring_ll.Rd
index 65763d76..d0edde23 100644
--- a/man/offspring_ll.Rd
+++ b/man/offspring_ll.Rd
@@ -2,7 +2,8 @@
 % Please edit documentation in R/stat_likelihoods.R
 \name{offspring_ll}
 \alias{offspring_ll}
-\title{Likelihood of the length of chains with generic offspring distribution}
+\title{Log-likelihood of the summary (size/length) of chains with generic offspring
+distribution}
 \usage{
 offspring_ll(
   chains,
@@ -36,11 +37,11 @@ to TRUE).}
 \item{...}{any parameters to pass to \code{\link{simulate_tree}}}
 }
 \value{
-If \code{log = TRUE} (the default), log-likelihood values,
+log-likelihood values
 else raw likelihoods
 }
 \description{
-The likelihoods are calculated with a crude approximation using simulated
+The log-likelihoods are calculated with a crude approximation using simulated
 chains by linearly approximating any missing values in the empirical
 cumulative distribution function (ecdf).
 }
diff --git a/man/pois_length_ll.Rd b/man/pois_length_ll.Rd
index 63f6088e..bf1f47ba 100644
--- a/man/pois_length_ll.Rd
+++ b/man/pois_length_ll.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/stat_likelihoods.R
 \name{pois_length_ll}
 \alias{pois_length_ll}
-\title{Likelihood of the length of chains with Poisson offspring distribution}
+\title{Log-likelihood of the length of chains with Poisson offspring distribution}
 \usage{
 pois_length_ll(x, lambda)
 }
@@ -15,7 +15,7 @@ pois_length_ll(x, lambda)
 log-likelihood values
 }
 \description{
-Likelihood of the length of chains with Poisson offspring distribution
+Log-likelihood of the length of chains with Poisson offspring distribution
 }
 \author{
 Sebastian Funk
diff --git a/man/pois_size_ll.Rd b/man/pois_size_ll.Rd
index 00e662d0..5e0645f3 100644
--- a/man/pois_size_ll.Rd
+++ b/man/pois_size_ll.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/stat_likelihoods.R
 \name{pois_size_ll}
 \alias{pois_size_ll}
-\title{Likelihood of the size of chains with Poisson offspring distribution}
+\title{Log-likelihood of the size of chains with Poisson offspring distribution}
 \usage{
 pois_size_ll(x, lambda)
 }
@@ -15,7 +15,7 @@ pois_size_ll(x, lambda)
 log-likelihood values
 }
 \description{
-Likelihood of the size of chains with Poisson offspring distribution
+Log-likelihood of the size of chains with Poisson offspring distribution
 }
 \author{
 Sebastian Funk

From 3635266f1b048c15d23ef9d8f8798c121cd8c0fb Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 17:13:11 +0100
Subject: [PATCH 03/17] Reword the docs of "offspring_ll"

---
 R/stat_likelihoods.R | 14 ++++++--------
 man/offspring_ll.Rd  | 20 ++++++++++++--------
 2 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index 028fba92..befa7c3e 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -93,15 +93,13 @@ geom_length_ll <- function(x, prob) {
 #' chain summaries by linearly approximating any missing values in the empirical
 #' cumulative distribution function (ecdf).
 #' @inheritParams likelihood
-#' @inheritParams simulate_vec
-#' @param chains Vector of sizes/lengths
+#' @inheritParams simulate_summary
+#' @param chains Vector of chain summaries (sizes/lengths)
 #' @param nsim_offspring Number of simulations of the offspring distribution
-#' for approximating the statistic (size/length) distribution
-#' @param log Logical; Should the results be log-transformed? (Defaults
-#' to TRUE).
-#' @param ... any parameters to pass to \code{\link{simulate_tree}}
-#' @return If \code{log = TRUE} (the default), log-likelihood values,
-#' else raw likelihoods
+#' for approximating the distribution of the chain statistic summary
+#' (size/length)
+#' @param ... any parameters to pass to \code{\link{simulate_summary}}
+#' @return log-likelihood values
 #' @author Sebastian Funk
 #' @export
 offspring_ll <- function(chains, offspring_dist, statistic,
diff --git a/man/offspring_ll.Rd b/man/offspring_ll.Rd
index d0edde23..58381ff2 100644
--- a/man/offspring_ll.Rd
+++ b/man/offspring_ll.Rd
@@ -15,7 +15,7 @@ offspring_ll(
 )
 }
 \arguments{
-\item{chains}{Vector of sizes/lengths}
+\item{chains}{Vector of chain summaries (sizes/lengths)}
 
 \item{offspring_dist}{Offspring distribution: a character string
 corresponding to the R distribution function (e.g., "pois" for Poisson,
@@ -29,22 +29,26 @@ numbers).}
 }}
 
 \item{nsim_offspring}{Number of simulations of the offspring distribution
-for approximating the statistic (size/length) distribution}
+for approximating the distribution of the chain statistic summary
+(size/length)}
 
-\item{log}{Logical; Should the results be log-transformed? (Defaults
-to TRUE).}
-
-\item{...}{any parameters to pass to \code{\link{simulate_tree}}}
+\item{...}{any parameters to pass to \code{\link{simulate_summary}}}
 }
 \value{
 log-likelihood values
-else raw likelihoods
 }
 \description{
 The log-likelihoods are calculated with a crude approximation using simulated
-chains by linearly approximating any missing values in the empirical
+chain summaries by linearly approximating any missing values in the empirical
 cumulative distribution function (ecdf).
 }
+\examples{
+set.seed(123)
+}
+\seealso{
+\code{\link[=simulate_summary]{simulate_summary()}} for simulating a summary of the transmission
+chains statistic (without the tree of infections)
+}
 \author{
 Sebastian Funk
 }

From 475fefe5b2a5666628aee8dede487145aed4e078 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 17:14:01 +0100
Subject: [PATCH 04/17] Revert to returning log values to comform with function
 name

---
 R/stat_likelihoods.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index befa7c3e..81e88ee1 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -122,6 +122,6 @@ offspring_ll <- function(chains, offspring_dist, statistic,
     )$y))
   lik <- acdf[chains]
   lik[is.na(lik)] <- 0
-  out <- ifelse(base::isTRUE(log), log(lik), lik)
+  out <- log(lik)
   return(out)
 }

From db597c65ab149839444f834eef0b370f11855401 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 17:14:26 +0100
Subject: [PATCH 05/17] Remove log argument

---
 R/stat_likelihoods.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index 81e88ee1..f6e38e09 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -103,7 +103,7 @@ geom_length_ll <- function(x, prob) {
 #' @author Sebastian Funk
 #' @export
 offspring_ll <- function(chains, offspring_dist, statistic,
-                         nsim_offspring = 100, log = TRUE, ...) {
+                         nsim_offspring = 100, ...) {
   # Simulate the chains
   chains <- simulate_summary(
     nsim_offspring, offspring_dist,

From 6fc775e78b647f7ad5e2375dcc491b6693d0c052 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 17:15:02 +0100
Subject: [PATCH 06/17] Explicitly assign arguments to avoid positioning
 matching

---
 R/stat_likelihoods.R | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index f6e38e09..ad435a35 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -106,8 +106,10 @@ offspring_ll <- function(chains, offspring_dist, statistic,
                          nsim_offspring = 100, ...) {
   # Simulate the chains
   chains <- simulate_summary(
-    nsim_offspring, offspring_dist,
-    statistic, ...
+    nchains = nsim_offspring,
+    offspring_dist = offspring_dist,
+    statistic = statistic,
+    ...
   )
 
   # Compute the empirical Cumulative Distribution Function of the

From d432a6ed094ba78dac4f47d386cfa35ef31e84e8 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 17:16:36 +0100
Subject: [PATCH 07/17] Add a seealso tag and clean up examples

---
 R/stat_likelihoods.R | 10 ++++++++++
 man/offspring_ll.Rd  |  9 +--------
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index ad435a35..07bce3ab 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -102,6 +102,16 @@ geom_length_ll <- function(x, prob) {
 #' @return log-likelihood values
 #' @author Sebastian Funk
 #' @export
+#' @seealso [simulate_summary()] for simulating a summary of the transmission
+#' chains statistic (without the tree of infections)
+#' @examples
+#' set.seed(123)
+# chain_size_ll <- offspring_ll(
+#   chains = c(1, 5, 6, 8, 7, 8, 10),
+#   offspring_dist = "pois",
+#   statistic = "size",
+#   lambda = 2
+# )
 offspring_ll <- function(chains, offspring_dist, statistic,
                          nsim_offspring = 100, ...) {
   # Simulate the chains
diff --git a/man/offspring_ll.Rd b/man/offspring_ll.Rd
index 58381ff2..14b602f7 100644
--- a/man/offspring_ll.Rd
+++ b/man/offspring_ll.Rd
@@ -5,14 +5,7 @@
 \title{Log-likelihood of the summary (size/length) of chains with generic offspring
 distribution}
 \usage{
-offspring_ll(
-  chains,
-  offspring_dist,
-  statistic,
-  nsim_offspring = 100,
-  log = TRUE,
-  ...
-)
+offspring_ll(chains, offspring_dist, statistic, nsim_offspring = 100, ...)
 }
 \arguments{
 \item{chains}{Vector of chain summaries (sizes/lengths)}

From e82023f698790e6901f221ba1f29fc477c2077af Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:12:04 +0100
Subject: [PATCH 08/17] Fixed the comment tags in the examples

---
 R/stat_likelihoods.R | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index 07bce3ab..2fda56e4 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -106,12 +106,12 @@ geom_length_ll <- function(x, prob) {
 #' chains statistic (without the tree of infections)
 #' @examples
 #' set.seed(123)
-# chain_size_ll <- offspring_ll(
-#   chains = c(1, 5, 6, 8, 7, 8, 10),
-#   offspring_dist = "pois",
-#   statistic = "size",
-#   lambda = 2
-# )
+#' chain_size_ll <- offspring_ll(
+#'   chains = c(1, 5, 6, 8, 7, 8, 10),
+#'   offspring_dist = "pois",
+#'   statistic = "size",
+#'   lambda = 2
+#' )
 offspring_ll <- function(chains, offspring_dist, statistic,
                          nsim_offspring = 100, ...) {
   # Simulate the chains

From 7f7abf622e1a85582cf2d7c6b3f39afd45fa0d14 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:32:26 +0100
Subject: [PATCH 09/17] Give nsim_obs a default value

---
 R/likelihood.R    | 2 +-
 man/likelihood.Rd | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index 07b2aec4..a50afc42 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -30,7 +30,7 @@
 #' )
 #' @export
 likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
-                       nsim_obs, log = TRUE, obs_prob = 1, stat_max = Inf,
+                       nsim_obs = 100, log = TRUE, obs_prob = 1, stat_max = Inf,
                        exclude = NULL, individual = FALSE, ...) {
   statistic <- match.arg(statistic)
 
diff --git a/man/likelihood.Rd b/man/likelihood.Rd
index b5b77844..57b64b5c 100644
--- a/man/likelihood.Rd
+++ b/man/likelihood.Rd
@@ -8,7 +8,7 @@ likelihood(
   chains,
   statistic = c("size", "length"),
   offspring_dist,
-  nsim_obs,
+  nsim_obs = 100,
   log = TRUE,
   obs_prob = 1,
   stat_max = Inf,

From 7dc3fe58ca56725d792ded0b19fbc6a53c0019cb Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:33:59 +0100
Subject: [PATCH 10/17] Assign lambda a value less than 1 to prevent example
 outbreak from overshooting

---
 R/stat_likelihoods.R | 2 +-
 man/offspring_ll.Rd  | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/R/stat_likelihoods.R b/R/stat_likelihoods.R
index 2fda56e4..94428885 100644
--- a/R/stat_likelihoods.R
+++ b/R/stat_likelihoods.R
@@ -110,7 +110,7 @@ geom_length_ll <- function(x, prob) {
 #'   chains = c(1, 5, 6, 8, 7, 8, 10),
 #'   offspring_dist = "pois",
 #'   statistic = "size",
-#'   lambda = 2
+#'   lambda = 0.82
 #' )
 offspring_ll <- function(chains, offspring_dist, statistic,
                          nsim_offspring = 100, ...) {
diff --git a/man/offspring_ll.Rd b/man/offspring_ll.Rd
index 14b602f7..4aa8d874 100644
--- a/man/offspring_ll.Rd
+++ b/man/offspring_ll.Rd
@@ -37,6 +37,12 @@ cumulative distribution function (ecdf).
 }
 \examples{
 set.seed(123)
+chain_size_ll <- offspring_ll(
+  chains = c(1, 5, 6, 8, 7, 8, 10),
+  offspring_dist = "pois",
+  statistic = "size",
+  lambda = 0.82
+)
 }
 \seealso{
 \code{\link[=simulate_summary]{simulate_summary()}} for simulating a summary of the transmission

From 343955edb56a6233253fe13bb087797926a22ad1 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:35:38 +0100
Subject: [PATCH 11/17] Make documentation of likelihood function more
 consistent by using "log-likelihood" all through

---
 R/likelihood.R    | 24 ++++++++++++------------
 man/likelihood.Rd | 27 ++++++++++++++-------------
 2 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index a50afc42..287c96dd 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -1,25 +1,25 @@
-#' Estimate the (log) likelihood for observed branching processes
+#' Estimate the log-likelihood/likelihood for observed branching processes
 #'
 #' @inheritParams simulate_summary
-#' @param chains Vector of sizes/lengths of transmission chains.
-#' @param nsim_obs Number of simulations if the likelihood is to be
-#' approximated for imperfect observations.
-#' @param log Logical; Should the results be log-transformed? (Defaults
-#' to TRUE).
+#' @inheritParams offspring_ll
+#' @param nsim_obs Number of simulations if the log-likelihood/likelihood is to
+#' be approximated for imperfect observations.
+#' @param log Logical; Should the log-likelihoods be transformed to
+#' likelihoods? (Defaults to TRUE).
 #' @param obs_prob Observation probability (assumed constant)
 #' @param exclude A vector of indices of the sizes/lengths to exclude from the
-#' likelihood calculation.
-#' @param individual If TRUE, a vector of individual (log)likelihood
+#' log-likelihood calculation.
+#' @param individual If TRUE, a vector of individual log-likelihood/likelihood
 #' contributions will be returned rather than the sum.
-#' @param ... Parameters for the offspring distribution.
 #' @return
 #' * A vector of log-likelihoods, if \code{log = TRUE} (the default) and
 #' \code{obs_prob < 1}, or
 #' * A list of individual log-likelihood contributions, if
 #' \code{log = TRUE} (the default) and \code{individual = TRUE}.
-#' else raw likelihoods, or vector of likelihoods
-#' @seealso offspring_ll, pois_size_ll, nbinom_size_ll, gborel_size_ll,
-#' pois_length_ll, geom_length_ll.
+#' The interpretation follows for the other combinations of `log` and
+#' `individual`.
+#' @seealso offspring_ll(), pois_size_ll(), nbinom_size_ll(), gborel_size_ll(),
+#' pois_length_ll(), geom_length_ll()
 #' @author Sebastian Funk
 #' @examples
 #' # example of observed chain sizes
diff --git a/man/likelihood.Rd b/man/likelihood.Rd
index 57b64b5c..c8d8ff2e 100644
--- a/man/likelihood.Rd
+++ b/man/likelihood.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/likelihood.R
 \name{likelihood}
 \alias{likelihood}
-\title{Estimate the (log) likelihood for observed branching processes}
+\title{Estimate the log-likelihood/likelihood for observed branching processes}
 \usage{
 likelihood(
   chains,
@@ -18,7 +18,7 @@ likelihood(
 )
 }
 \arguments{
-\item{chains}{Vector of sizes/lengths of transmission chains.}
+\item{chains}{Vector of chain summaries (sizes/lengths)}
 
 \item{statistic}{String; Statistic to calculate. Can be one of:
 \itemize{
@@ -31,11 +31,11 @@ corresponding to the R distribution function (e.g., "pois" for Poisson,
 where \code{\link{rpois}} is the R function to generate Poisson random
 numbers).}
 
-\item{nsim_obs}{Number of simulations if the likelihood is to be
-approximated for imperfect observations.}
+\item{nsim_obs}{Number of simulations if the log-likelihood/likelihood is to
+be approximated for imperfect observations.}
 
-\item{log}{Logical; Should the results be log-transformed? (Defaults
-to TRUE).}
+\item{log}{Logical; Should the log-likelihoods be transformed to
+likelihoods? (Defaults to TRUE).}
 
 \item{obs_prob}{Observation probability (assumed constant)}
 
@@ -43,12 +43,12 @@ to TRUE).}
 computed. Results above the specified value, are set to \code{Inf}.}
 
 \item{exclude}{A vector of indices of the sizes/lengths to exclude from the
-likelihood calculation.}
+log-likelihood calculation.}
 
-\item{individual}{If TRUE, a vector of individual (log)likelihood
+\item{individual}{If TRUE, a vector of individual log-likelihood/likelihood
 contributions will be returned rather than the sum.}
 
-\item{...}{Parameters for the offspring distribution.}
+\item{...}{Parameters of the offspring distribution as required by R.}
 }
 \value{
 \itemize{
@@ -56,11 +56,12 @@ contributions will be returned rather than the sum.}
 \code{obs_prob < 1}, or
 \item A list of individual log-likelihood contributions, if
 \code{log = TRUE} (the default) and \code{individual = TRUE}.
-else raw likelihoods, or vector of likelihoods
+The interpretation follows for the other combinations of \code{log} and
+\code{individual}.
 }
 }
 \description{
-Estimate the (log) likelihood for observed branching processes
+Estimate the log-likelihood/likelihood for observed branching processes
 }
 \examples{
 # example of observed chain sizes
@@ -71,8 +72,8 @@ likelihood(
 )
 }
 \seealso{
-offspring_ll, pois_size_ll, nbinom_size_ll, gborel_size_ll,
-pois_length_ll, geom_length_ll.
+offspring_ll(), pois_size_ll(), nbinom_size_ll(), gborel_size_ll(),
+pois_length_ll(), geom_length_ll()
 }
 \author{
 Sebastian Funk

From 7231e4c84fbb7f737f84baf8cd038c8437507729 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:36:00 +0100
Subject: [PATCH 12/17] Improve error message

---
 R/likelihood.R | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index 287c96dd..47501a99 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -37,7 +37,9 @@ likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
   ## checks
   check_offspring_valid(offspring_dist)
 
-  if (obs_prob <= 0 || obs_prob > 1) stop("'obs_prob' must be within (0,1]")
+  if (obs_prob <= 0 || obs_prob > 1) {
+    stop("'obs_prob' is a probability and must be between 0 and 1 inclusive")
+    }
   if (obs_prob < 1) {
     if (missing(nsim_obs)) {
       stop("'nsim_obs' must be specified if 'obs_prob' is < 1")

From cf67402b023d753497808634fd8b60adaa398a79 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:36:20 +0100
Subject: [PATCH 13/17] Rename a variable

---
 R/likelihood.R | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index 47501a99..7af5e924 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -45,10 +45,10 @@ likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
       stop("'nsim_obs' must be specified if 'obs_prob' is < 1")
     }
 
-    sample_func <- get_statistic_func(statistic)
+    statistic_func <- get_statistic_func(statistic)
 
     sampled_x <- replicate(nsim_obs, pmin(
-      sample_func(
+      statistic_func(
         length(chains),
         chains, obs_prob
       ),

From dce207a7375ecbace2199d5efb471cde5fc45f5d Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:36:59 +0100
Subject: [PATCH 14/17] Replace "likelihood" with "log-likelihood"

---
 R/likelihood.R | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index 7af5e924..63e56bef 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -64,19 +64,19 @@ likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
     sampled_x <- list(chains)
   }
 
-  ## determine for which sizes to calculate the likelihood (for true chain size)
+  ## determine for which sizes to calculate the log-likelihood (for true chain size)
   if (any(size_x == stat_max)) {
     calc_sizes <- seq_len(stat_max - 1)
   } else {
     calc_sizes <- unique(c(size_x, exclude))
   }
 
-  ## get likelihood function as given by offspring_dist and statistic
+  ## get log-likelihood function as given by offspring_dist and statistic
   likelihoods <- vector(mode = "numeric")
   ll_func <- construct_offspring_ll_name(offspring_dist, statistic)
   pars <- as.list(unlist(list(...))) ## converts vectors to lists
 
-  ## calculate likelihoods
+  ## calculate log-likelihoods
   if (exists(ll_func, where = asNamespace("epichains"), mode = "function")) {
     func <- get(ll_func)
     likelihoods[calc_sizes] <- do.call(func, c(list(x = calc_sizes), pars))

From e87ca2ff0969c502e1c1b0303cd498ce91079d99 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:37:24 +0100
Subject: [PATCH 15/17] Lint

---
 R/likelihood.R | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index 63e56bef..5b07b1bc 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -55,9 +55,7 @@ likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
       stat_max
     ), simplify = FALSE)
     size_x <- unlist(sampled_x)
-    if (!is.finite(stat_max)) {
-      stat_max <- max(size_x) + 1
-    }
+    stat_max <- max(size_x) + 1
   } else {
     chains[chains >= stat_max] <- stat_max
     size_x <- chains
@@ -82,14 +80,18 @@ likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
     likelihoods[calc_sizes] <- do.call(func, c(list(x = calc_sizes), pars))
   } else {
     likelihoods[calc_sizes] <-
-      do.call(
-        offspring_ll,
-        c(list(
-          chains = calc_sizes, offspring_dist = offspring_dist,
-          statistic = statistic, stat_max = stat_max,
-          log = log
-        ), pars)
+    do.call(
+      offspring_ll,
+      c(
+        list(
+          chains = calc_sizes,
+          offspring_dist = offspring_dist,
+          statistic = statistic,
+          stat_max = stat_max
+        ),
+        pars
       )
+    )
   }
 
   ## assign probabilities to stat_max outbreak sizes

From 80cd74f4b6699df67e8e458cea6c1911c7328c94 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:38:25 +0100
Subject: [PATCH 16/17] Add exp transformation for when log=FALSE

---
 R/likelihood.R | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/R/likelihood.R b/R/likelihood.R
index 5b07b1bc..4a028f2b 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -113,6 +113,11 @@ likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
     likelihoods[sx[!(sx %in% exclude)]]
   })
 
+  ## transform log-likelihoods into likelihoods if required
+  if (!log) {
+    chains_likelihood <- lapply(chains_likelihood, function(ll) exp(ll))
+  }
+
   if (!individual) {
     chains_likelihood <- vapply(chains_likelihood, sum, 0)
   }

From 7bc7d749cb1280f8034f67d5775693adf4480406 Mon Sep 17 00:00:00 2001
From: jamesaazam <james.azam@lshtm.ac.uk>
Date: Wed, 6 Sep 2023 19:39:42 +0100
Subject: [PATCH 17/17] Add joint likelihood calculation for where
 individual=TRUE and depending on log=T/F

---
 R/likelihood.R | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/R/likelihood.R b/R/likelihood.R
index 4a028f2b..be4b2928 100644
--- a/R/likelihood.R
+++ b/R/likelihood.R
@@ -118,8 +118,15 @@ likelihood <- function(chains, statistic = c("size", "length"), offspring_dist,
     chains_likelihood <- lapply(chains_likelihood, function(ll) exp(ll))
   }
 
+  ## if individual == FALSE, return the joint log-likelihood
+  ## (sum of the log-likelihoods), if log == TRUE, else
+  ## multiply the likelihoods
   if (!individual) {
-    chains_likelihood <- vapply(chains_likelihood, sum, 0)
+    if (log) {
+      chains_likelihood <- vapply(chains_likelihood, sum, 0)
+    } else{
+      chains_likelihood <- vapply(chains_likelihood, prod, 0)
+    }
   }
 
   return(chains_likelihood)