Clarify some intervention parametrization documentation.

The `set_tbv` function was located at the bottom of `pev_parameters.R`,
which was confusing and unintuitive. I believe this was a remnant of a
time when that file was named `vaccine_parameters.R`. It is now moved to
its own file, named `tbv_parameters.R`. This matches the general naming
convention used by all other interventions.

The ages parameter of `set_tbv` was previously described as being
"per-round", which might hint at it being, eg. a list of age ranges with
one entry per round. This did not match the implementation, which uses
the same whole `tbv_ages` parameter for every round.

I don't how useful being able to pass in a non-contiguous set of ages
is. In the future it might be clearer to change the TBV intervention to
use `min_ages` and `max_ages`, the same way other mass-event
interventions (MDA, SMC and mass-PEV) are implementated. This will make
it easy to actually have varying age ranges for each round, if desired.

This also adds a check in `set_tbv` for the length of coverages to
ensure it matches the timesteps, the same way it is done in other
interventions.

The documentation for the `timesteps` and `coverages` parameters of the
`set_pmc` method made mentions of rounds, implying that the intervention
only takes place at the given timesteps, when it is in fact a perennial
age-based intervention that may happen at any timestep. The timesteps
parameter is only used to vary the coverage over time.

Finally, there were a pair of lost words in the documentation of
`set_tbv` and `set_mda` from successive code refactors, which have now
been removed.

R/mda_parameters.R

@@ -6,7 +6,6 @@
 #' round
 #' @param min_ages a vector of minimum ages of the target population for each round exclusive (in timesteps)
 #' @param max_ages a vector of maximum ages of the target population for each round exclusive (in timesteps)
-#' drug
 #' @export
 set_mda <- function(
   parameters,
@@ -77,9 +76,9 @@ set_smc <- function(
 #' @title Parameterise a perennial malaria chemoprevention (PMC, formerly IPIi)
 #' @param parameters a list of parameters to modify
 #' @param drug the index of the drug to administer
-#' @param timesteps a vector of timesteps for each round of PMC
-#' @param coverages a vector of the proportion of the target population who receive each
-#' round
+#' @param timesteps a vector of timesteps for each change in coverage
+#' @param coverages a vector of proportions of the target population to receive
+#' the intervention
 #' @param ages a vector of ages at which PMC is administered (in timesteps)
 #' @export
 set_pmc <- function(

R/pev_parameters.R

@@ -64,7 +64,7 @@ rtss_booster_profile <- create_pev_profile(
 #' @param parameters a list of parameters to modify
 #' @param profile a list of details for the vaccine profile, create with `create_pev_profile`
 #' @param coverages a vector of coverages for the primary doses
-#' @param timesteps a vector of timesteps associated with coverages
+#' @param timesteps a vector of timesteps for each change in coverage
 #' @param age the age when an individual will receive the first dose of the
 #' vaccine (in timesteps)
 #' @param min_wait the minimum acceptable time since the last vaccination (in
@@ -221,24 +221,3 @@ set_mass_pev <- function(
   parameters$mass_pev_profile_indices <- profile_indices
   parameters
 }
-
-#' @title Parameterise an TBV strategy
-#' @param parameters a list of parameters to modify
-#' @param timesteps a vector of timesteps for each round of vaccinations
-#' @param coverages the coverage for each round of vaccinations
-#' @param ages for each round (in years)
-#' vaccine
-#' @export
-set_tbv <- function(
-  parameters,
-  timesteps,
-  coverages,
-  ages
-  ) {
-  stopifnot(all(coverages >= 0) && all(coverages <= 1))
-  parameters$tbv <- TRUE
-  parameters$tbv_timesteps <- timesteps
-  parameters$tbv_coverages <- coverages
-  parameters$tbv_ages <- ages
-  parameters
-}

R/tbv_parameters.R

@@ -0,0 +1,23 @@
+#' @title Parameterise an TBV strategy
+#' @param parameters a list of parameters to modify
+#' @param timesteps a vector of timesteps for each round of vaccinations
+#' @param coverages the coverage for each round of vaccinations
+#' @param ages a vector of ages of the target population (in years)
+#' @export
+set_tbv <- function(
+  parameters,
+  timesteps,
+  coverages,
+  ages
+  ) {
+  stopifnot(all(coverages >= 0) && all(coverages <= 1))
+  if(length(coverages) != length(timesteps)){
+    stop("coverages and timesteps do no align")
+  }
+
+  parameters$tbv <- TRUE
+  parameters$tbv_timesteps <- timesteps
+  parameters$tbv_coverages <- coverages
+  parameters$tbv_ages <- ages
+  parameters
+}

tests/testthat/test-tbv.R

@@ -1,3 +1,14 @@
+test_that('TBV checks arguments', {
+  parameters <- get_parameters()
+  expect_error(
+    parameters <- set_tbv(
+      parameters,
+      timesteps = c(50, 150),
+      coverages = 1,
+      ages = 5:60
+    ), "coverages and timesteps do no align")
+})
+
 test_that('TBV strategy parameterisation works', {
   parameters <- get_parameters()
   parameters <- set_tbv(