From 2203988f1740a0c1cce6afd5cfb5ffcbcaf5d26c Mon Sep 17 00:00:00 2001 From: Paul Lietar Date: Mon, 22 Apr 2024 16:15:56 +0100 Subject: [PATCH] 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 | 7 +++---- R/pev_parameters.R | 23 +---------------------- R/tbv_parameters.R | 23 +++++++++++++++++++++++ man/CorrelationParameters.Rd | 6 ++++-- man/set_mda.Rd | 3 +-- man/set_pev_epi.Rd | 2 +- man/set_pmc.Rd | 6 +++--- man/set_tbv.Rd | 5 ++--- tests/testthat/test-tbv.R | 11 +++++++++++ 9 files changed, 49 insertions(+), 37 deletions(-) create mode 100644 R/tbv_parameters.R diff --git a/R/mda_parameters.R b/R/mda_parameters.R index a07d7e70..f84b86e1 100644 --- a/R/mda_parameters.R +++ b/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( diff --git a/R/pev_parameters.R b/R/pev_parameters.R index 7edcb39c..a9509f96 100644 --- a/R/pev_parameters.R +++ b/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 -} diff --git a/R/tbv_parameters.R b/R/tbv_parameters.R new file mode 100644 index 00000000..089455a2 --- /dev/null +++ b/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 +} diff --git a/man/CorrelationParameters.Rd b/man/CorrelationParameters.Rd index 480d663d..2898aee5 100644 --- a/man/CorrelationParameters.Rd +++ b/man/CorrelationParameters.Rd @@ -30,13 +30,15 @@ Describes an event in the simulation \subsection{Method \code{new()}}{ initialise correlation parameters \subsection{Usage}{ -\if{html}{\out{
}}\preformatted{CorrelationParameters$new(parameters)}\if{html}{\out{
}} +\if{html}{\out{
}}\preformatted{CorrelationParameters$new(population, interventions)}\if{html}{\out{
}} } \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{parameters}}{model parameters} +\item{\code{population}}{popularion size} + +\item{\code{interventions}}{character vector with the name of enabled interventions} } \if{html}{\out{
}} } diff --git a/man/set_mda.Rd b/man/set_mda.Rd index 0b6f81c0..5437faeb 100644 --- a/man/set_mda.Rd +++ b/man/set_mda.Rd @@ -18,8 +18,7 @@ round} \item{min_ages}{a vector of minimum ages of the target population for each round exclusive (in timesteps)} -\item{max_ages}{a vector of maximum ages of the target population for each round exclusive (in timesteps) -drug} +\item{max_ages}{a vector of maximum ages of the target population for each round exclusive (in timesteps)} } \description{ Parameterise a Mass Drug Administration diff --git a/man/set_pev_epi.Rd b/man/set_pev_epi.Rd index a3a4d195..077811c3 100644 --- a/man/set_pev_epi.Rd +++ b/man/set_pev_epi.Rd @@ -24,7 +24,7 @@ set_pev_epi( \item{coverages}{a vector of coverages for the primary doses} -\item{timesteps}{a vector of timesteps associated with coverages} +\item{timesteps}{a vector of timesteps for each change in coverage} \item{age}{the age when an individual will receive the first dose of the vaccine (in timesteps)} diff --git a/man/set_pmc.Rd b/man/set_pmc.Rd index 62625c04..2985e29a 100644 --- a/man/set_pmc.Rd +++ b/man/set_pmc.Rd @@ -11,10 +11,10 @@ set_pmc(parameters, drug, timesteps, coverages, ages) \item{drug}{the index of the drug to administer} -\item{timesteps}{a vector of timesteps for each round of PMC} +\item{timesteps}{a vector of timesteps for each change in coverage} -\item{coverages}{a vector of the proportion of the target population who receive each -round} +\item{coverages}{a vector of proportions of the target population to receive +the intervention} \item{ages}{a vector of ages at which PMC is administered (in timesteps)} } diff --git a/man/set_tbv.Rd b/man/set_tbv.Rd index 34a641aa..23149e6d 100644 --- a/man/set_tbv.Rd +++ b/man/set_tbv.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/pev_parameters.R +% Please edit documentation in R/tbv_parameters.R \name{set_tbv} \alias{set_tbv} \title{Parameterise an TBV strategy} @@ -13,8 +13,7 @@ set_tbv(parameters, timesteps, coverages, ages) \item{coverages}{the coverage for each round of vaccinations} -\item{ages}{for each round (in years) -vaccine} +\item{ages}{a vector of ages of the target population (in years)} } \description{ Parameterise an TBV strategy diff --git a/tests/testthat/test-tbv.R b/tests/testthat/test-tbv.R index 0e4451a1..e8af946e 100644 --- a/tests/testthat/test-tbv.R +++ b/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(