Update function documentation

DESCRIPTION

@@ -33,7 +33,7 @@ License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 Depends:
     R (>= 3.5.0)
 Imports: 

R/aux_functions.R

@@ -1,7 +1,9 @@
 #' Create partial function to sample from gamma distributions
 #' @author Joel Hellewell
-#' @param dist_shape numeric shape parameter of Weibull distribution
-#' @param dist_scale numeric scale parameter of Weibull distribution
+#' @param dist_shape a positive `numeric` scalar: shape parameter of Weibull
+#'   distribution
+#' @param dist_scale a positive `numeric` scalar: scale parameter of Weibull
+#'   distribution
 #'
 #' @return partial function that takes a numeric argument for number of samples
 #' @export
@@ -17,9 +19,11 @@ dist_setup <- function(dist_shape = NULL, dist_scale = NULL) {
 
 #' Samples the serial interval for given incubation period samples
 #'
-#' @param inc_samp vector of samples from the incubation period distribution
-#' @param k numeric skew parameter for sampling the serial interval from the incubation period
+#' @param inc_samp a positive `numeric` vector: samples from the incubation
+#'   period distribution
+#' @inheritParams outbreak_model
 #'
+#' @return a `numeric` vector of equal length to the vector input to `inc_samp`
 #' @export
 #' @importFrom sn rsn
 
@@ -38,6 +42,7 @@ inf_fn <- function(inc_samp = NULL, k = NULL) {
 #' Calculate proportion of runs that have controlled outbreak
 #'
 #' @author Joel Hellewell
+#' @return a single `numeric` with the probability of extinction
 #' @export
 #' @inheritParams detect_extinct
 extinct_prob <- function(outbreak_df_week = NULL, cap_cases  = NULL, week_range = 12:16) {
@@ -53,11 +58,16 @@ extinct_prob <- function(outbreak_df_week = NULL, cap_cases  = NULL, week_range
 
 #' Calculate whether outbreaks went extinct or not
 #' @author Joel Hellewell
-#' @param outbreak_df_week data.table  weekly cases produced by the outbreak model
-#' @param cap_cases integer number of cumulative cases at which the branching process was terminated
-#' @param week_range integer vector giving the (zero indexed) week range to test for whether an extinction occurred.
+#' @param outbreak_df_week a `data.table`: weekly cases produced by the
+#'   outbreak model
+#' @inheritParams outbreak_model
+#' @param week_range a positive `integer` vector: giving the (zero indexed)
+#'   week range to test for whether an extinction occurred.
 #' @importFrom data.table as.data.table fifelse
 #'
+#' @return A `data.table`, with two columns `sim` and `extinct`, for a binary
+#' classification of whether the outbreak went extinct in each simulation
+#' replicate. `1` is an outbreak that went extinct, `0` if not.
 #' @export
 #'
 detect_extinct <- function(outbreak_df_week  = NULL, cap_cases  = NULL, week_range = 12:16) {

R/outbreak_model.R

@@ -1,16 +1,45 @@
 
 #' Run a single instance of the branching process model
 #' @author Joel Hellewell
-#' @inheritParams outbreak_step
-#' @param delay_shape numeric shape parameter of delay distribution
-#' @param delay_scale numeric scale parameter of delay distribution
-#' @param num.initial.cases The number of initial or starting cases which are all assumed to be missed.
-#' @param cap_cases Stop the simulation when this many cases is reached.
-#' @param cap_max_days Stop the simulation when this many days is reached.
+#' @param disp.iso a positive `numeric` scalar: dispersion parameter for
+#'   isolated cases (must be >0)
+#' @param disp.com a positive `numeric` scalar: dispersion parameter for
+#'   non-isolated cases (must be >0)
+#' @param disp.subclin a positive `numeric` scalar: dispersion parameter for
+#'   sub-clincial non-isolated cases (must be >0)
+#' @param r0isolated a positive `numeric` scalar: reproduction number for
+#'   isolated cases (must be >0)
+#' @param r0community a positive `numeric` scalar: reproduction number for
+#'   non-isolated cases (must be >0)
+#' @param r0subclin a positive `numeric` scalar: reproduction number for
+#'   sub-clinical non-isolated cases (must be >0)
+#' @param prop.ascertain a nonnegative `numeric` scalar: proportion of
+#'   infectious contacts ascertained by contact tracing (must be 0<=x<=1)
+#' @param k a `numeric` scalar: skew parameter for sampling the serial
+#'   interval from the incubation period
+#' @param quarantine a `logical` scalar: whether quarantine is in effect, if
+#'   `TRUE` then traced contacts are isolated before symptom onset
+#' @param prop.asym a nonnegative `numeric` scalar: proportion of cases that
+#'   are completely asymptomatic (sublinical) (between 0 and 1)
+#' @param delay_shape a positive `numeric` scalar: shape parameter of delay
+#'   distribution
+#' @param delay_scale a positive `numeric` scalar: scale parameter of delay
+#'   distribution
+#' @param num.initial.cases a nonnegative `integer` scalar: number of initial
+#'   or starting cases which are all assumed to be missed.
+#' @param cap_cases a positive `integer` scalar: number of cumulative cases at
+#'   which the branching process (simulation) was terminated
+#' @param cap_max_days a positive `integer` scalar: stop the simulation when
+#'   this many days is reached.
 #'
 #'
-#'
-#' @return data.table of cases by week, cumulative cases, and the effective reproduction number of the outreak
+#' @return `data.table` of cases by week, cumulative cases, and the effective
+#' reproduction number of the outbreak. `data.table` columns are:
+#' * `$week`: `numeric`
+#' * `$weekly_cases`: `numeric`
+#' * `$cumulative`: `numeric`
+#' * `$effective_r0`: `numeric`
+#' * `$cases_per_gen`: `list`
 #' @export
 #'
 #' @importFrom data.table rbindlist

R/outbreak_setup.R

@@ -1,13 +1,19 @@
 #' Set up initial cases for branching process
 #' @author Joel Hellewell
 #'
-#' @param num.initial.cases Integer number of initial cases
-#' @param incfn function that samples from incubation period Weibull distribution; generated using dist_setup
-#' @param delayfn function that samples from the onset-to-hospitalisation delay Weibull distribution; generated using dist_setup
-#' @param k Numeric skew parameter for sampling the serial interval from the incubation period
-#' @param prop.asym Numeric proportion of cases that are sublinical (between 0 and 1)
+#' @inheritParams outbreak_model
+#' @inheritParams outbreak_step
 #'
-#' @return data.table of cases in outbreak so far
+#' @return `data.table` of cases in outbreak so far. `data.table` columns are:
+#' * `$exposure`: `numeric`
+#' * `$asym`: `logical`
+#' * `$caseid`: `integer`
+#' * `$infector`: `numeric`
+#' * `$missed`: `logical`
+#' * `$onset`: `numeric`
+#' * `$new_cases`: `logical`
+#' * `$isolated_time`: `numeric`
+#' * `$isolated`: `logical`
 #' @export
 #' @importFrom data.table data.table
 #' @importFrom stats rbinom

R/outbreak_step.R

@@ -2,24 +2,23 @@
 #'
 #' @author Joel Hellewell
 #'
-#' @param case_data data.table of cases in outbreak so far; initially generated by outbreak_setup
-#' @param disp.iso numeric dispersion parameter for isolated cases (must be >0)
-#' @param disp.com numeric dispersion parameter for non-isolated cases (must be >0)
-#' @param disp.subclin numeric dispersion parameter for sub-clincial non-isolated cases (must be >0)
-#' @param r0isolated numeric reproduction number for isolated cases (must be >0)
-#' @param r0community numeric reproduction number for non-isolated cases (must be >0)
-#' @param r0subclin numeric reproduction number for sub-clinical non-isolated cases (must be >0)
-#' @param incfn function samples from incubation period; generated by dist_setup
-#' @param delayfn function samples from the onset-to-hospitalisation delay; generated by dist_setup
-#' @param prop.ascertain numeric proportion of infectious contacts ascertained by contact tracing (must be 0<=x<=1)
-#' @param k numeric skew parameter for sampling the serial interval from the incubation period
-#' @param quarantine logical whether quarantine is in effect, if TRUE then traced contacts are isolated before symptom onset
-#' @param prop.asym proportion of cases that are completely asymptomatic.
+#' @param case_data a `data.table`: cases in outbreak so far; initially
+#'   generated by [outbreak_setup()]
+#' @inheritParams outbreak_model
+#' @param incfn a `function` that samples from incubation period Weibull
+#'   distribution; generated using [dist_setup()]
+#' @param delayfn a `function` that samples from the onset-to-hospitalisation
+#'   delay Weibull distribution; generated using [dist_setup()]
 #'
 #' @importFrom data.table data.table rbindlist
 #' @importFrom purrr map2 map2_dbl map_lgl
 #' @importFrom stats rbinom
 #'
+#' @return A `list` with three elements:
+#'   1. `$cases`: a `data.table` with case data
+#'   2. `$effective_r0`: a `numeric` with the effective reproduction number
+#'   3. `$cases_in_gen`: a `numeric` with the number of new cases in that
+#'   generation
 #' @export
 #'
 #' @examples
@@ -48,7 +47,7 @@
 #'}
 outbreak_step <- function(case_data = NULL, disp.iso = NULL, disp.com = NULL,
                           r0isolated = NULL, r0community = NULL,
-                          prop.asym = NULL, incfn = NULL, delayfn = NULL, 
+                          prop.asym = NULL, incfn = NULL, delayfn = NULL,
                           prop.ascertain = NULL, k = NULL, quarantine = NULL,
                           r0subclin = NULL, disp.subclin = NULL) {
 

R/parameter_sweep.R

@@ -4,13 +4,14 @@
 #' are included in the grid are currently hard coded. Use the `future` package to control parallisation
 #' outside of the function.
 #'
-#' @param scenarios A dataframe containing all gridded  scenarios - see the examples for the required structure.
-#' Defaults to NULL.
-#' @param samples Numeric, defaults to 1. The number of samples to take.
-#' @param sim_fn Function, defaults to NULL. The vectorised model simulation function - see the examples
-#' for usage.
-#'
-#' @return A nested tibble containing the parameters for each scenario and a nested list of output
+#' @param scenarios a `data.frame`: containing all gridded scenarios - see the
+#'   examples for the required structure. Defaults to `NULL`.
+#' @param samples a positive `integer` scalar: the number of samples to take.
+#'   Defaults to `1`.
+#' @param sim_fn a `function`: defaults to `NULL`. The vectorised model
+#'   simulation function - see the examples for usage.
+#'
+#' @return A nested `data.table` containing the parameters for each scenario and a nested list of output
 #' from `wuhan_sim`.
 #' @export
 #' @importFrom future.apply future_lapply

R/scenario_sim.R

@@ -1,6 +1,6 @@
 #' Run a specified number of simulations with identical parameters
 #' @author Joel Hellewell
-#' @param n.sim number of simulations to run
+#' @param n.sim a positive `integer` scalar: number of simulations to run
 #'
 #' @inheritParams outbreak_model
 #' @inheritParams outbreak_step
@@ -13,7 +13,7 @@
 #' @importFrom stats quantile
 #' @importFrom stats rweibull
 #' @importFrom utils data
-#' @return A data.table object returning the results for multiple simulations using
+#' @return A `data.table` object returning the results for multiple simulations using
 #' the same set of parameters. The table has columns
 #' * week: The week in the simulation.
 #' * weekly_cases: The number of new cases that week.
@@ -85,6 +85,6 @@ utils::globalVariables(c(".", ".N", ":=", "asym", "control_effectiveness", "cumu
                          "new_cases", "num.initial.cases", "onset", "pext", "prob_extinct", "prop.asym",
                          "r0", "rweibull", "samp", "samples", "scenario", "sim", "sims", "theta", "upper", "value",
                          "week", "weekly_cases", "x", "y", "y0", "y100", "y25", "y50", "y75"))
-                         
+