Add expected types to all arguments and use sentence case

R/borel.r

@@ -1,9 +1,9 @@
 ##' Density of the Borel distribution
 ##'
-##' @param x Vector of quantiles; integer.
-##' @param mu mu parameter (the poisson mean); non-negative.
+##' @param x A numeric vector of quantiles.
+##' @param mu A non-negative number for the poisson mean.
 ##' @param log Logical; if TRUE, probabilities p are given as log(p).
-##' @return Probability mass.
+##' @return A numeric vector of the borel probability density.
 ##' @author Sebastian Funk
 ##' @export
 ##' @examples
@@ -28,12 +28,13 @@ dborel <- function(x, mu, log = FALSE) {
 ##' @param n Number of random variates to generate.
 ##' @inheritParams dborel
 ##' @param infinite A threshold above which the random number is set to
-##'  `Inf` as a form of truncation. This is important because `rborel()` uses
-##'  `simulate_summary()` internally with `offspring_dist = rpois`, so
-##'  when `mu >= 1`, the simulation could grow out of proportion and chain
-##'  summaries (the random numbers generated here) need to be truncated using
+##'  `Inf` as a form of truncation; A number coercible to integer. This
+##'  argument is important because `rborel()` uses `simulate_summary()`
+##'  internally with `offspring_dist = rpois`, so when `mu >= 1`, the
+##'  simulation could grow out of proportion and chain summaries (the random
+##'  numbers generated here) need to be truncated using
 ##'  `infinite`.
-##' @return Vector of random numbers
+##' @return A numeric vector of random numbers.
 ##' @author Sebastian Funk
 ##' @export
 ##' @examples
@@ -62,11 +63,12 @@ rborel <- function(n, mu, infinite = Inf) {
 ##'
 ##' @inheritParams rborel
 ##' @importFrom stats rgamma rpois
-##' @param size the dispersion parameter (often called \code{k} in ecological
-##'   applications)
-##' @param prob probability of success (in the parameterisation with
-##'   \code{prob}, see also \code{\link[stats]{NegBinomial}})
-##' @param mu mean parameter
+##' @param size The dispersion parameter (often called \code{k} in ecological
+##'   applications); A positive number.
+##' @param prob Probability of success (in the parameterisation with
+##'   \code{prob}, see also \code{\link[stats]{NegBinomial}}); A number between
+##'   0 and 1.
+##' @param mu Mean; A positive number.
 ##' @return Numeric vector of random numbers
 ##' @author Sebastian Funk
 ##' @export

R/epichains.R

@@ -11,7 +11,7 @@
 #' @param tree_df a `<data.frame>` containing at least columns for
 #' "infectee_id", "infector_id", and "generation". Also has optional columns
 #' for "time", and "chain_id".
-#' @param track_pop Was the susceptible population tracked? Logical
+#' @param track_pop Was the susceptible population tracked? Logical.
 #' @inheritParams .epichains
 #' @author James M. Azam
 #' @keywords internal
@@ -51,7 +51,7 @@
 #' @inheritParams simulate_chains
 #' @inheritParams .new_epichains
 #'
-#' @return An `<epichains>` object
+#' @return An `<epichains>` object.
 #' @author James M. Azam
 #' @keywords internal
 .epichains <- function(tree_df,
@@ -106,7 +106,7 @@
 #' `epichains_summary()` after the arguments have been checked. To create a
 #' new `<epichains_summary>` object safely, use `epichains_summary()`.
 #'
-#' @param chains_summary a `<vector>` of chain sizes and lengths.
+#' @param chains_summary A numeric `<vector>` of chain sizes and lengths.
 #' @inheritParams .new_epichains
 #' @inheritParams .simulate_chains
 #' @author James M. Azam
@@ -138,7 +138,7 @@
 #'
 #' @inheritParams .new_epichains_summary
 #'
-#' @return An `<epichains_summary>` object
+#' @return An `<epichains_summary>` object.
 #' @author James M. Azam
 #' @keywords internal
 .epichains_summary <- function(chains_summary,
@@ -197,7 +197,7 @@ print.epichains <- function(x, ...) {
 #' Print an `<epichains_summary>` object
 #'
 #' @param x An `<epichains_summary>` object.
-#' @param ... ignored.
+#' @param ... Not used.
 #' @return Invisibly returns an `<epichains_summary>`. Called for
 #' side-effects.
 #' @author James M. Azam
@@ -208,8 +208,8 @@ print.epichains_summary <- function(x, ...) {
 
 #' Format method for `<epichains>` class
 #'
-#' @param x An `<epichains>` object
-#' @param ... ignored
+#' @param x An `<epichains>` object.
+#' @param ... Not used.
 #' @return Invisibly returns an `<epichains>`.
 #' Called for printing side-effects.
 #' @author James M. Azam
@@ -258,8 +258,8 @@ format.epichains <- function(x, ...) {
 
 #' Format method for `<epichains_summary>` class
 #'
-#' @param x An `<epichains_summary>` object
-#' @param ... ignored
+#' @param x An `<epichains_summary>` object.
+#' @param ... Not used.
 #' @return Invisibly returns an `<epichains_summary>`. Called for printing
 #' side-effects.
 #' @author James M. Azam
@@ -305,14 +305,14 @@ format.epichains_summary <- function(x, ...) {
 #' chains and returns an object with the same information as that returned
 #' by an equivalent `simulate_summary()` call.
 #'
-#' @param object An `<epichains>` object
-#' @param ... ignored
+#' @param object An `<epichains>` object.
+#' @param ... Not used.
 #'
 #' @return An `<epichains_summary>` object containing the chain summary
 #' statistics as follows:
-#' "size": the total number of cases produced by a chain before it
+#' * "size": the total number of offspring produced by a chain before it
 #' goes extinct.
-#' "length": the total number of infectors produced by a chain before
+#' * "length": the number of generations achieved by a chain before
 #' it goes extinct.
 #' @author James M. Azam
 #' @export
@@ -393,10 +393,16 @@ summary.epichains <- function(object, ...) {
 
 #' Summary method for `<epichains_summary>` class
 #'
-#' @param object An `<epichains_summary>` object
-#' @param ... ignored
+#' @param object An `<epichains_summary>` object.
+#' @param ... Not used.
 #'
-#' @return List of summaries
+#' @return A list of chain summaries. The list contains the following
+#' elements:
+#' * `index_cases`: the number of index cases used to simulate the chains.
+#' * `max_stat`: the maximum chain statistic (size/length) achieved by the
+#' chains.
+#' * `min_stat`: the minimum chain statistic (size/length) achieved by the
+#' chains.
 #' @author James M. Azam
 #' @export
 summary.epichains_summary <- function(object, ...) {
@@ -425,10 +431,10 @@ summary.epichains_summary <- function(object, ...) {
 
 #' Test if x is an `epichains` object
 #'
-#' @param x An R object
+#' @param x An R object.
 #'
-#' @return logical, `TRUE` if the object is an `<epichains>` and `FALSE`
-#' otherwise
+#' @return Logical; `TRUE` if the object is an `<epichains>` and `FALSE`
+#' otherwise.
 #' @author James M. Azam
 #' @keywords internal
 .is_epichains <- function(x) {
@@ -437,10 +443,10 @@ summary.epichains_summary <- function(object, ...) {
 
 #' Test if x is an `epichains_summary` object
 #'
-#' @param x An R object
+#' @param x An R object.
 #'
-#' @return logical, `TRUE` if the object is an `epichains_summary` and `FALSE`
-#' otherwise
+#' @return Logical; `TRUE` if the object is an `<epichains_summary>` and
+#' `FALSE` otherwise.
 #' @author James M. Azam
 #' @keywords internal
 .is_epichains_summary <- function(x) {
@@ -449,9 +455,9 @@ summary.epichains_summary <- function(object, ...) {
 
 #' Validate an `<epichains>` object
 #'
-#' @param x An `<epichains>` object
+#' @param x An `<epichains>` object.
 #'
-#' @return No return.
+#' @return Invisibly returns the object if it is valid.
 #' @author James M. Azam
 #' @keywords internal
 .validate_epichains <- function(x) {
@@ -477,9 +483,9 @@ summary.epichains_summary <- function(object, ...) {
 
 #' Validate an `<epichains_summary>` object
 #'
-#' @param x An `<epichains_summary>` object
+#' @param x An `<epichains_summary>` object.
 #'
-#' @return No return.
+#' @return Invisibly returns the object if it is valid.
 #' @author James M. Azam
 #' @keywords internal
 .validate_epichains_summary <- function(x) {
@@ -492,11 +498,11 @@ summary.epichains_summary <- function(object, ...) {
 
 #' `head` and `tail` method for `<epichains>` class
 #'
-#' @param x An `<epichains>` object
-#' @param ... further arguments passed to or from other methods
+#' @param x An `<epichains>` object.
+#' @param ... Further arguments passed to or from other methods.
 #' @importFrom utils head
 #' @importFrom utils tail
-#' @return Object of class `data.frame`
+#' @return An object of class `<data.frame>`.
 #' @author James M. Azam
 #' @export
 #' @details
@@ -553,9 +559,9 @@ tail.epichains <- function(x, ...) {
 #' `<epichains>` objects.
 #'
 #' @param x An `<epichains>` object.
-#' @param by The variable to aggregate by. Options include
+#' @param by The variable to aggregate by; A character string with options
 #' "time" and "generation".
-#' @param ... ignored.
+#' @param ... Not used.
 #' @importFrom stats aggregate
 #' @return A `<data.frame>` object of cases by `by`.
 #' @author James M. Azam

R/helpers.R

@@ -1,9 +1,12 @@
 #' Determine and update the chain statistic being tracked
 #'
-#' @param stat_type Chain statistic (size/length) to update.
-#' @param stat_latest The latest chain statistic vector to be updated.
-#' @param n_offspring A vector of offspring per chain.
-#' @return A vector of chain statistics (size/length).
+#' @param stat_type Chain statistic (size/length) to update; A character string.
+#' Must be one of 'size' or 'length'.
+#' @param stat_latest The latest chain statistic numeric vector to be updated.
+#' @param n_offspring A vector of offspring per chain. A numeric vector
+#' (coercible to integer).
+#' @return A vector of chain statistics (size/length). A numeric vector
+#' coercible to integer.
 #' @keywords internal
 .update_chain_stat <- function(stat_type, stat_latest, n_offspring) {
   return(
@@ -20,7 +23,7 @@
 #'
 #' @inheritParams simulate_chains
 #'
-#' @return a function for calculating chain statistics
+#' @return A function for calculating chain statistics.
 #' @keywords internal
 .get_statistic_func <- function(chain_statistic) {
   return(
@@ -43,7 +46,7 @@
 #'
 #' @inheritParams simulate_chains
 #'
-#' @return numeric; initial susceptible population size
+#' @return Initial susceptible population size; A numeric coercible to integer.
 #' @keywords internal
 .init_susc_pop <- function(pop,
                            percent_immune,
@@ -59,12 +62,12 @@
 #' associated parameters. This function is used internally, and input
 #' checking is not performed here, only in the context where it is used.
 #' Using it directly is not recommended.
-#' @param offspring_func A function to sample offspring
-#' @param offspring_func_pars A list of parameters for the offspring function
-#' @param n_offspring A vector of the number of offspring per chain
-#' @param chains Indices of chains/infectors being simulated
+#' @param offspring_func A function to sample offspring.
+#' @param offspring_func_pars A list of parameters for the offspring function.
+#' @param n_offspring A numeric vector of the number of offspring per chain.
+#' @param chains Numeric indices of chains/infectors being simulated
 #'
-#' @return A vector of the number of offspring per chain
+#' @return A numeric vector of the number of offspring per chain.
 #' @keywords internal
 .sample_possible_offspring <- function(offspring_func,
                                        offspring_func_pars,
@@ -95,10 +98,10 @@
 #' performed here, only in the context where it is used. Using it directly
 #' is not recommended.
 #' @inheritParams simulate_chains
-#' @param new_offspring A vector of the possible new offspring per chain
-#' produced by [.sample_possible_offspring()]
-#' @return A vector of the number of offspring that can be infected given the
-#' current susceptible population size
+#' @param new_offspring A numeric vector of the possible new offspring per
+#' chain produced by [.sample_possible_offspring()].
+#' @return A numeric vector of the number of offspring that can be infected
+#' given the current susceptible population size.
 #' @keywords internal
 .get_susceptible_offspring <- function(new_offspring,
                                       susc_pop,
@@ -120,10 +123,11 @@
 #' This function is used internally, and input checking is not
 #' performed here, only in the context where it is used. Using it directly
 #' is not recommended.
-#' @param next_gen numeric; vector of next generation offspring
-#' @param susc_pop numeric; susceptible population size
+#' @param next_gen A numeric vector of next generation offspring.
+#' @param susc_pop The susceptible population size; A number coercible to
+#' integer.
 #'
-#' @return numeric; adjusted next generation offspring vector
+#' @return A numeric vector of the adjusted next generation offspring.
 #' @keywords internal
 .adjust_next_gen <- function(next_gen, susc_pop) {
   ## create hypothetical next generation individuals to sample from

R/likelihood.R

@@ -2,7 +2,7 @@
 #'
 #' @inheritParams .offspring_ll
 #' @inheritParams simulate_summary
-#' @param chains Vector of chain summaries (sizes/lengths)
+#' @param chains A numeric vector of chain summaries (sizes/lengths).
 #' @param nsim_obs Number of simulations to be used to approximate the
 #' log-likelihood/likelihood if `obs_prob < 1` (imperfect observation). If
 #' `obs_prob == 1`, this argument is ignored.
@@ -11,12 +11,13 @@
 #' simulations will be used to approximate the (log)likelihood. This will
 #' also require specifying `nsim_obs`. In the simulation, the observation
 #' process is assumed to be constant.
-#' @param log Logical; Should the log-likelihoods be transformed to
-#' likelihoods? (Defaults to TRUE).
+#' @param log Should the log-likelihoods be transformed to
+#' likelihoods? Logical. Defaults to `TRUE`.
 #' @param exclude A vector of indices of the sizes/lengths to exclude from the
 #' log-likelihood calculation.
-#' @param individual If TRUE, a vector of individual log-likelihood/likelihood
-#' contributions will be returned rather than the sum/product.
+#' @param individual Logical; If TRUE, a vector of individual
+#' log-likelihood/likelihood contributions will be returned rather than the
+#' sum/product.
 #' @return
 #' If \code{log = TRUE}
 #'