further tidying function documentation

NAMESPACE

@@ -1,6 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-export(apply_vacc)
 export(apply_vaccs)
 export(calc_pop_immunity)
 export(complete_vacc_activities)

R/apply_vacc.R

@@ -1,34 +1,38 @@
-##' Function to apply a single vaccination activity to the population
+##' Apply a single vaccination activity to a "popim_population" object
+##'
+##' The vaccination activity is defined by the input parameters of the
+##' function.
 ##'
 ##' If the vaccination activity has non-missing entries for both
 ##' coverage and doses, the coverage is used - there is no test
 ##' whether the coverage and doses information are consistent with the
 ##' target population size in the popim_population object to which the
 ##' vaccination activity is applied.
 ##'
-##' @param pop_df population dataframe object such as created by
-##'     function 'popim_population'
-##' @param region region of the vaccination activity
-##' @param year year of the vaccination activity
-##' @param age_first age of the youngest age group targeted
-##' @param age_last age of the oldest age group targeted
-##' @param coverage proportion of the population to be vaccinated in
-##'     the activity
-##' @param doses number of doses available to vaccinate the target population
-##' @param targeting character to determine how successive activities are
-##'     targeted. Valid values are "random", "correlated", "targeted".
-##'     For targeting = "random" (the default), allocation of vaccine is
-##'     random within the population, therefore the resulting coverage
-##'     will be smaller than the sum of the coverages. For targeting =
-##'     "correlated", there is a 100% correlation between who will get
-##'     the vaccine in either vaccination activitiy, the resulting
-##'     coverage is simply the larger of the two inputs. For targeting =
-##'     "targeted", doses are targeted at unvaccinated people,
-##'     resulting in the sum of both coverages, though capped by 1
-##'     (full coverage).
-##' @return pop_df: the supplied population dataframe object with
+##' @param pop_df "popim_population" dataframe object such as created
+##'     by function [popim_population()]
+##' @param region character, region of the vaccination activity
+##' @param year integer, year of the vaccination activity
+##' @param age_first,age_last non-negative integer with `age_last` >=
+##'     `age_first`. Age range targeted
+##' @param coverage numeric, 0 <= `coverage` <= 1. Proportion of the
+##'     target population to be vaccinated in the activity.
+##' @param doses numeric, non-negative. Number of doses available to
+##'     vaccinate the target population.
+##' @param targeting character, determines how successive activities
+##'     are targeted. Valid values are "random", "correlated",
+##'     "targeted".  For `targeting` = "random" (the default),
+##'     allocation of vaccine is random within the population,
+##'     therefore the resulting coverage will be smaller than the sum
+##'     of the coverages. For `targeting` = "correlated", there is a
+##'     100% correlation between who will get the vaccine in either
+##'     vaccination activitiy, the resulting coverage is simply the
+##'     larger of the two inputs. For `targeting` = "targeted", doses
+##'     are targeted at unvaccinated people, resulting in the sum of
+##'     both coverages, though capped by 1 (full coverage).
+##' @return The supplied population dataframe object with
 ##'     updated immunity to reflect the vaccination activity.
-##' @export
+##' @noRd
 ##' @author Tini Garske
 apply_vacc <- function(pop_df, region, year, age_first = 0, age_last = Inf,
                        coverage = double(), doses = NA_real_,
@@ -67,19 +71,18 @@ apply_vacc <- function(pop_df, region, year, age_first = 0, age_last = Inf,
     }
     pop_df
 }
-##' Function to apply vaccination activities to a population
+##' Apply vaccination activities to a "popim_population" object
 ##'
 ##' Takes the vaccination activities listed in the input object
 ##' vaccs_df (a data.frame object of class popim_vacc_activities), and
 ##' applies them to the popim_population object pop_df, then returns
 ##' that updated object.
 ##'
-##' @param pop_df object of class popim_population such as created by
-##'     function 'popim_population'
-##' @param vaccs_df object of class 'popim_vacc_activities' such as
-##'     created by reading from file with function
-##'     'read_vacc_activities'
-##' @return pop_df: the supplied population dataframe object with
+##' @param pop_df object of class "popim_population" such as created by
+##'     function [popim_population()].
+##' @param vaccs_df object of class "popim_vacc_activities" such as
+##'     created by [popim_vacc_activities()].
+##' @return The supplied population dataframe object with
 ##'     updated immunity to reflect the vaccination activities
 ##'     supplied in vaccs_df.
 ##' @export
@@ -160,16 +163,15 @@ coverage_from_doses <- function(pop_df, doses, region, year, age_first = 0,
 ##' targeted region(s).
 ##'
 ##' @param pop_df object of class popim_population such as created by
-##'     function `popim_population`
+##'     [popim_population()].
 ##' @param coverage proportion of the target population to be covered,
-##'     0 <= coverage <= 1
-##' @param region region to be targeted
-##' @param year year of vaccination activity
-##' @param age_first youngest age group to be targeted
-##' @param age_last oldest age group to be targeted
-##' @return doses: a non-negative number between indicating how many
-##'     doses will be needed to achieve the given coverage in the
-##'     target population.
+##'     0 <= `coverage` <= 1.
+##' @param region region to be targeted.
+##' @param year year of vaccination activity.
+##' @param age_first youngest age group to be targeted.
+##' @param age_last oldest age group to be targeted.
+##' @return A non-negative number indicating how many doses will be
+##'     needed to achieve the given coverage in the target population.
 ##' @author Tini Garske
 ##' @noRd
 doses_from_coverage <- function(pop_df, coverage, region, year, age_first = 0, age_last = Inf) {

R/calc_new_immunity.R

@@ -1,26 +1,26 @@
-#' Function to combine two coverages for the same cohort
+#' Combine two coverages for the same cohort
 #'
 #' This function calculates the resulting coverage if coverages of
 #' two separate vaccination activities are combined, and returns this
 #' single value.
 #'
-#' @param coverage coverage value of the new campaign as a proportion
-#'     - needs to be between 0 and 1.
-#' @param prev_immunity pre-existing immunity of the cohort to be
-#'     vaccinated as a proportion. Can be a vector (e.g. for
-#'     calculation of resulting immunity in the same cohort forward in
-#'     time). All entries need to be between 0 and 1.
+#' @param coverage numeric between 0 and 1. Coverage value of the new
+#'     campaign as a proportion of the target population.
+#' @param prev_immunity numeric between 0 and 1. Pre-existing immunity
+#'     of the cohort to be vaccinated as a proportion. Can be a vector
+#'     (e.g. for calculation of resulting immunity in the same cohort
+#'     forward in time).
 #' @param targeting char to determine the assumption used to combine
 #'     coverages. Valid values are "random", "correlated", "targeted".
-#'     For targeting = "random" (the default), allocation of vaccine is
-#'     random within the population, therefore the resulting coverage
-#'     will be smaller than the sum of the coverages. For targeting =
-#'     "correlated", there is a 100% correlation between who will get
-#'     the vaccine in either vaccination activitiy, the resulting
-#'     coverage is simply the larger of the two inputs. For targeting =
-#'     "targeted", doses are targeted at unvaccinated people,
-#'     resulting in the sum of both coverages, though capped by 1
-#'     (full coverage).
+#'     For targeting = "random" (the default), allocation of vaccine
+#'     is random within the population, therefore the resulting
+#'     coverage will be smaller than the sum of the coverages. For
+#'     targeting = "correlated", there is a 100% correlation between
+#'     who will get the vaccine in either vaccination activitiy, the
+#'     resulting coverage is simply the larger of the two inputs. For
+#'     targeting = "targeted", doses are targeted at unvaccinated
+#'     people, resulting in the sum of both coverages, though capped
+#'     by 1 (full coverage).
 #' @return A scalar: combined coverage
 #' @noRd
 calc_new_immunity <- function(coverage, prev_immunity, targeting) {
@@ -57,9 +57,9 @@ assert_valid_targeting <- function(x, name = deparse(substitute(x))) {
 }
 
 ##' Calculate the overall population immunity (aggregating over age)
-##' from the supplied popim_population object
+##' from the supplied "popim_population" object
 ##'
-##' @param pop popim_population object for which the population size and
+##' @param pop "popim_population" object for which the population size and
 ##'     immunity will be aggregated over age.
 ##' @return dataframe containing the popim_population aggregated by age.
 ##' @author Tini Garske

R/is_population.R

@@ -1,14 +1,14 @@
-##' Test if argument is a valid popim_population object
+##' Test if argument is a valid "popim_population" object
 ##'
 ##' This function tests whether the supplied argument is a valid
 ##' population dataframe such as might be generated by the function
-##' "popim_population".
+##' [popim_population()].
 ##' @param x argument to be tested if it fulfils the requirements for
 ##'     a population dataframe.
 ##' @param tol numerical, determines the tolerance when comparing two
 ##'     numbers. Defaults to the square root of machine
-##'     precision. This is used for checking if the cohort == year -
-##'     age (as the cohort column is redundant).
+##'     precision. This is used for checking if the `cohort` == `year`
+##'     - `age` (as the `cohort` column is redundant).
 ##' @return logical: TRUE if the argument is a valid popim_population
 ##'     object, FALSE otherwise.
 ##' @author Tini Garske

R/vacc_from_immunity.R

@@ -1,10 +1,11 @@
 ##' Infer vaccination activities from population
 ##'
-##' Given a popim_population object and an assumption of how vaccine is
-##' targeted in a partially immune population, this function infers
-##' the vaccination activities that returns a popim_vacc_activities
-##' object that details the vaccination activities that have given
-##' rise to the specified population immunity.
+##' Given a "popim_population" object and an assumption of how vaccine
+##' is targeted in a partially immune population, this function infers
+##' the vaccination activities that have given rise to the specified
+##' population immunity. When there is ambiguity (e.g., due to
+##' subsequent campaigns achieving full coverage), the minimum
+##' coverage/doses needed will be returned.
 ##'
 ##' Default is the targeting option "random", which assumes that
 ##' individuals receive vaccine independently of vaccination status,
@@ -26,13 +27,13 @@
 ##' also never be picked up as this age group will have aged out of
 ##' the population (i.e., died) before the immunity is updated in the
 ##' next year.
-##' @param pop popim_population object for which vaccination activities
-##'     are to be inferred
-##' @param targeting string to determine the assumption of how doses
+##' @param pop "popim_population" object for which vaccination activities
+##'     are to be inferred.
+##' @param targeting character, determines the assumption of how doses
 ##'     are allocated. Valid options are "random", "correlated",
 ##'     "targeted".
 ##' @param n_digits number of digits to which the coverage is to be
-##'     rounded.
+##'     rounded, defaults to 10.
 ##' @return popim_vacc_activites object
 ##' @export
 ##' @author Tini Garske
@@ -68,10 +69,10 @@ vacc_from_immunity <- function(pop, targeting = "random", n_digits = 10) {
     vaccs
 }
 
-##' Add the rate of immunity change to a popim_population object
+##' Add the rate of immunity change to a "popim_population" object
 ##'
-##' @param pop popim_population_object
-##' @return the input popim_population object with an added column
+##' @param pop "popim_population" object
+##' @return the input "popim_population" object with an added column
 ##'     `immunity_diff` that holds the difference in immunity between
 ##'     the current and next year.
 ##' @author Tini Garske
@@ -121,12 +122,12 @@ coverage_from_immunity_diff <- function(imm_now, imm_diff, targeting,
 ##' Expand the age range given by age_first and age_last into an
 ##' integer vector giving each individual age group
 ##'
-##' If the popim_vacc_activities object contains more than one row the
+##' If the "popim_vacc_activities" object contains more than one row the
 ##' rows are assumed to belong to the same campaign, but detail
 ##' different age groups. The function will expand the age ranges to a
 ##' vector that gives every single age cohort targeted.
 ##'
-##' @param va object of class popim_vacc_activities
+##' @param va object of class "popim_vacc_activities"
 ##' @return integer vector of variable length
 ##' @author Tini Garske
 get_all_ages <- function(va) {