Consistent naming of function arguments and variables (#112)

* replace . with _ in function arguments, fixes #88

* replace . with _ for variables and temporary functions, relates #88

* replace arguments with subclin with asymptomatic, relates #99

* replace prop_asym with prop_asymptomatic, relates #99

* replace asym variable and DT column with asymptomatic, relates #99

* replace infector_asym DT column with infector_asymptomatic, relates #99

* replace disp_com function arg with disp_community, relates #99

* replace disp_iso function arg with disp_isolated, relates #99

* replace infector_iso_time DT column with infector_isolation_time, relates #99

* rename control_effectiveness to prop_ascertain in parameter_sweep, relates #99

* rename index_R0 to r0community in parameter_sweep, relates #99

* rename n_sim argument and variable to n

* rename num_initial_cases argument to initial_cases

* underscore separate r0* arguments

* add NEWS item for consistent naming and style

* sync prop_ascertain and prop_asymptomatic function argument documentation

* fix GH username typo in NEWS.md

Co-authored-by: Carl A. B. Pearson <pearsonca@users.noreply.github.com>

---------

Co-authored-by: Carl A. B. Pearson <pearsonca@users.noreply.github.com>

Author: joshwlambert

NEWS.md

@@ -1,5 +1,7 @@
 # ringbp 0.1.2.9999
 
+* Function argument and variable names are consistently named and styled (snake case). Arguments that were abbreviated (e.g. `iso`) now use the full word, and arguments that had aliases (e.g. `prop_ascertain` and `control_effectiveness`) now use a single name. By @joshwlambert in #112 and reviewed by @pearsonca and @sbfnk. 
+
 * Fixed a bug in the implementation of quarantine, where isolation could happen later than onset + delay, if this was earlier than the isolation time of the infector. By @sbfnk in #107 and reviewed by @pearsonca and @joshwlambert.
 
 * Changed internal sampling to vector draws in several locations; in some cases, this was an optimization, but in others it was a bug fix correcting the use of single draw where there should have been many. Also incorporates other vectorization changes to improve performance. Because of the bug fix, users should expect results to change. Addresses issues #90, #92, #94, in #98 by @pearsonca (now added as a contributor) with review by @sbfnk and @joshwlambert.

R/aux_functions.R

@@ -29,16 +29,16 @@ inf_fn <- function(inc_samp = NULL, k = NULL) {
 #'
 #' @examples
 #' res <- scenario_sim(
-#'   n.sim = 10,
-#'   num.initial.cases = 1,
-#'   prop.asym = 0,
-#'   prop.ascertain = 0.2,
+#'   n = 10,
+#'   initial_cases = 1,
+#'   prop_asymptomatic = 0,
+#'   prop_ascertain = 0.2,
 #'   cap_cases = 4500,
 #'   cap_max_days = 350,
-#'   r0isolated = 0.5,
-#'   r0community = 2.5,
-#'   disp.com = 0.16,
-#'   disp.iso = 1,
+#'   r0_isolated = 0.5,
+#'   r0_community = 2.5,
+#'   disp_community = 0.16,
+#'   disp_isolated = 1,
 #'   onset_to_isolation = \(x) rweibull(n = x, shape = 1.65, scale = 4.28),
 #'   incubation_period = \(x) rweibull(n = x, shape = 2.322737, scale = 6.492272),
 #'   k = 0,
@@ -47,10 +47,10 @@ inf_fn <- function(inc_samp = NULL, k = NULL) {
 #' extinct_prob(res, cap_cases = 4500)
 extinct_prob <- function(outbreak_df_week = NULL, cap_cases  = NULL, week_range = 12:16) {
 
-  n_sim <- max(outbreak_df_week$sim)
+  n <- max(outbreak_df_week$sim)
 
   extinct_runs <- detect_extinct(outbreak_df_week, cap_cases, week_range)
-  out <-  sum(extinct_runs$extinct) / n_sim
+  out <-  sum(extinct_runs$extinct) / n
 
   return(out)
 }
@@ -73,16 +73,16 @@ extinct_prob <- function(outbreak_df_week = NULL, cap_cases  = NULL, week_range
 #'
 #' @examples
 #' res <- scenario_sim(
-#'   n.sim = 10,
-#'   num.initial.cases = 1,
-#'   prop.asym = 0,
-#'   prop.ascertain = 0.2,
+#'   n = 10,
+#'   initial_cases = 1,
+#'   prop_asymptomatic = 0,
+#'   prop_ascertain = 0.2,
 #'   cap_cases = 4500,
 #'   cap_max_days = 350,
-#'   r0isolated = 0.5,
-#'   r0community = 2.5,
-#'   disp.com = 0.16,
-#'   disp.iso = 1,
+#'   r0_isolated = 0.5,
+#'   r0_community = 2.5,
+#'   disp_community = 0.16,
+#'   disp_isolated = 1,
 #'   onset_to_isolation = \(x) rweibull(n = x, shape = 1.65, scale = 4.28),
 #'   incubation_period = \(x) rweibull(n = x, shape = 2.322737, scale = 6.492272),
 #'   k = 0,

R/globals.R

@@ -8,18 +8,18 @@ utils::globalVariables(c(
   "week", # <outbreak_model>
   "onset", # <outbreak_model>
   "cumulative", # <outbreak_model>
-  "asym", # <outbreak_setup>
+  "asymptomatic", # <outbreak_setup>
   "isolated_time", # <outbreak_setup>
   "onset", # <outbreak_setup>
   "new_cases", # <outbreak_step>
   "isolated", # <outbreak_step>
-  "asym", # <outbreak_step>
+  "asymptomatic", # <outbreak_step>
   "onset", # <outbreak_step>
   "caseid", # <outbreak_step>
   "isolated_time", # <outbreak_step>
   "exposure", # <outbreak_step>
-  "infector_iso_time", # <outbreak_step>
-  "infector_asym", # <outbreak_step>
+  "infector_isolation_time", # <outbreak_step>
+  "infector_asymptomatic", # <outbreak_step>
   "missed", # <outbreak_step>
   "scenario", # <parameter_sweep>
   "sims", # <parameter_sweep>

R/outbreak_model.R

@@ -1,27 +1,29 @@
 
 #' Run a single instance of the branching process model
 #' @author Joel Hellewell
-#' @param disp.iso a positive `numeric` scalar: dispersion parameter for
+#' @param disp_isolated a positive `numeric` scalar: dispersion parameter for
 #'   isolated cases (must be >0)
-#' @param disp.com a positive `numeric` scalar: dispersion parameter for
+#' @param disp_community 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
+#' @param disp_asymptomatic a positive `numeric` scalar: dispersion parameter
+#'   for sub-clincial non-isolated cases (must be >0)
+#' @param r0_isolated a positive `numeric` scalar: reproduction number for
 #'   isolated cases (must be >0)
-#' @param r0community a positive `numeric` scalar: reproduction number for
+#' @param r0_community a positive `numeric` scalar: reproduction number for
 #'   non-isolated cases (must be >0)
-#' @param r0subclin a positive `numeric` scalar: reproduction number for
+#' @param r0_asymptomatic 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 prop_ascertain a `numeric` scalar probability (between 0 and 1
+#'   inclusive): proportion of infectious contacts ascertained by contact
+#'   tracing
 #' @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; defaults to
 #'   `FALSE`
-#' @param prop.asym a nonnegative `numeric` scalar: proportion of cases that
-#'   are completely asymptomatic (sublinical) (between 0 and 1)
+#' @param prop_asymptomatic a `numeric` scalar probability (between 0 and 1
+#'   inclusive): proportion of cases that are completely asymptomatic
+#'   (subclinical)
 #' @param onset_to_isolation a `function`: a random number generating
 #'   `function` that accepts a single `integer` argument specifying the
 #'   length of the `function` output.
@@ -30,7 +32,7 @@
 #'   `function` accepts a single `integer` argument specifying the number of
 #'   times to sample the incubation period (i.e. length of the `function`
 #'   output).
-#' @param num.initial.cases a nonnegative `integer` scalar: number of initial
+#' @param 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
@@ -53,71 +55,71 @@
 #' @examples
 #' set.seed(1)
 #' out <- outbreak_model(
-#'   num.initial.cases = 1,
-#'   prop.ascertain = 0.2,
+#'   initial_cases = 1,
+#'   prop_ascertain = 0.2,
 #'   cap_max_days = 350,
 #'   cap_cases = 4500,
-#'   r0isolated = 0.5,
-#'   r0community = 2.5,
-#'   r0subclin = 2.5,
-#'   disp.iso = 1,
-#'   disp.com = 0.16,
-#'   disp.subclin = 0.16,
+#'   r0_isolated = 0.5,
+#'   r0_community = 2.5,
+#'   r0_asymptomatic = 2.5,
+#'   disp_isolated = 1,
+#'   disp_community = 0.16,
+#'   disp_asymptomatic = 0.16,
 #'   k = 0,
 #'   onset_to_isolation = \(x) rweibull(n = x, shape = 1.65, scale = 4.28),
 #'   incubation_period = \(x) rweibull(n = x, shape = 2.32, scale = 6.49),
-#'   prop.asym = 0,
+#'   prop_asymptomatic = 0,
 #'   quarantine = FALSE
 #' )
 #' out
-outbreak_model <- function(num.initial.cases = NULL, prop.ascertain = NULL,
+outbreak_model <- function(initial_cases = NULL, prop_ascertain = NULL,
                            cap_max_days = NULL, cap_cases = NULL,
-                           r0isolated = NULL, r0community = NULL,
-                           r0subclin = NULL, disp.iso = NULL,
-                           disp.com = NULL, disp.subclin = NULL,
+                           r0_isolated = NULL, r0_community = NULL,
+                           r0_asymptomatic = NULL, disp_isolated = NULL,
+                           disp_community = NULL, disp_asymptomatic = NULL,
                            k, onset_to_isolation, incubation_period,
-                           prop.asym = NULL, quarantine = FALSE) {
+                           prop_asymptomatic = NULL, quarantine = FALSE) {
 
   # Set initial values for loop indices
-  total.cases <- num.initial.cases
-  latest.onset <- 0
+  total_cases <- initial_cases
+  latest_onset <- 0
   extinct <- FALSE
 
   # Initial setup
-  case_data <- outbreak_setup(num.initial.cases = num.initial.cases,
+  case_data <- outbreak_setup(initial_cases = initial_cases,
                               incubation_period = incubation_period,
                               onset_to_isolation = onset_to_isolation,
                               k = k,
-                              prop.asym = prop.asym)
+                              prop_asymptomatic = prop_asymptomatic)
 
   # Preallocate
   effective_r0_vect <- c()
   cases_in_gen_vect <- c()
 
 
   # Model loop
-  while (latest.onset < cap_max_days & total.cases < cap_cases & !extinct) {
+  while (latest_onset < cap_max_days & total_cases < cap_cases & !extinct) {
 
     out <- outbreak_step(case_data = case_data,
-                             disp.iso = disp.iso,
-                             disp.com = disp.com,
-                             disp.subclin = disp.subclin,
-                             r0isolated = r0isolated,
-                             r0community = r0community,
-                             r0subclin = r0subclin,
+                             disp_isolated = disp_isolated,
+                             disp_community = disp_community,
+                             disp_asymptomatic = disp_asymptomatic,
+                             r0_isolated = r0_isolated,
+                             r0_community = r0_community,
+                             r0_asymptomatic = r0_asymptomatic,
                              incubation_period = incubation_period,
                              onset_to_isolation = onset_to_isolation,
-                             prop.ascertain = prop.ascertain,
+                             prop_ascertain = prop_ascertain,
                              k = k,
                              quarantine = quarantine,
-                             prop.asym = prop.asym)
+                             prop_asymptomatic = prop_asymptomatic)
 
 
     case_data <- out[[1]]
     effective_r0_vect <- c(effective_r0_vect, out[[2]])
     cases_in_gen_vect <- c(cases_in_gen_vect, out[[3]])
-    total.cases <- nrow(case_data)
-    latest.onset <- max(case_data$onset)
+    total_cases <- nrow(case_data)
+    latest_onset <- max(case_data$onset)
     extinct <- all(case_data$isolated)
   }
 

R/outbreak_setup.R

@@ -6,7 +6,7 @@
 #'
 #' @return `data.table` of cases in outbreak so far. `data.table` columns are:
 #' * `$exposure`: `numeric`
-#' * `$asym`: `logical`
+#' * `$asymptomatic`: `logical`
 #' * `$caseid`: `integer`
 #' * `$infector`: `numeric`
 #' * `$missed`: `logical`
@@ -25,30 +25,30 @@
 #' # delay distribution sampling function
 #' onset_to_isolation <- \(x) rweibull(n = x, shape = 1.65, scale = 4.28)
 #' out <- outbreak_setup(
-#'   num.initial.cases = 1,
+#'   initial_cases = 1,
 #'   incubation_period = incubation_period,
 #'   onset_to_isolation = onset_to_isolation,
 #'   k = 1.95,
-#'   prop.asym = 0
+#'   prop_asymptomatic = 0
 #' )
 #' out
-outbreak_setup <- function(num.initial.cases, incubation_period, onset_to_isolation, k, prop.asym) {
+outbreak_setup <- function(initial_cases, incubation_period, onset_to_isolation, k, prop_asymptomatic) {
   # Set up table of initial cases
   case_data <- data.table(
     exposure = 0, # Exposure time of 0 for all initial cases
-    asym = runif(num.initial.cases) < prop.asym,
-    caseid = seq_len(num.initial.cases), # set case id
+    asymptomatic = runif(initial_cases) < prop_asymptomatic,
+    caseid = seq_len(initial_cases), # set case id
     infector = 0,
     isolated = FALSE,
     missed = TRUE,
-    onset = incubation_period(num.initial.cases),
+    onset = incubation_period(initial_cases),
     new_cases = NA,
     isolated_time = Inf
   )
 
   # set isolation time for cluster to minimum time of onset of symptoms + draw from delay distribution
   case_data <- case_data[
-    asym == FALSE,
+    asymptomatic == FALSE,
     isolated_time := onset + onset_to_isolation(.N)
   ]