Merge pull request #16 from mrc-ide/examples

add examples for 6 functions

R/apply_vacc.R

@@ -95,6 +95,17 @@ apply_vacc_1 <- function(pop, region, year, age_first = 0, age_last = Inf,
 ##'     activities supplied in `vacc`.
 ##' @export
 ##' @author Tini Garske
+##' @examples
+##' ## set up population and vaccination activities:
+##' pop <- popim_population(region = "UK", year_min = 2000, year_max = 2005,
+##'                         age_min = 0, age_max = 10)
+##' vacc <- popim_vacc_activities(region = "UK", year = c(2001, 2002),
+##'                               age_first = 0, age_last = 0,
+##'                               coverage = 0.8, doses = NA,
+##'                               targeting = "random")
+##'
+##' ## update the population immunity based on the vaccination activities:
+##' pop <- apply_vacc(pop, vacc)
 apply_vacc <- function(pop, vacc) {
     for(i in seq_len(nrow(vacc))) {
 

R/popim_population.R

@@ -120,6 +120,9 @@ popim_population <- function(region = character(),
 ##'     file.
 ##' @author Tini Garske
 ##' @export
+##' @examples
+##' filename <- system.file("extdata", "pop_sample.csv", package = "popim")
+##' pop <- read_popim_pop(file = filename)
 read_popim_pop <- function(file) {
 
     ## assert_file_exists(file)
@@ -159,14 +162,18 @@ read_popim_pop <- function(file) {
 ##' @return an object of class `popim_population`
 ##' @author Tini Garske
 ##' @export
+##' @examples
+##' ## set up a minimal dataframe to convert to a popim_population object:
+##' df <- expand.grid(region = "UK", age = 0:3, year = 2000:2004, stringsAsFactors = FALSE)
+##' pop <- as_popim_pop(df)
 as_popim_pop <- function(df) {
 
     assert_column_exists(df, "region")
     assert_column_exists(df, "age")
     assert_column_exists(df, "year")
 
     if(!("pop_size" %in% names(df))) {
-        df$pop_size <- NA
+        df$pop_size <- NA_real_
     }
 
     if(!("immunity" %in% names(df))) {

R/popim_vacc_activities.R

@@ -45,7 +45,7 @@
 ##' # correct structure:
 ##' vacc <- popim_vacc_activities()
 ##'
-##' # setting up a couple of specific vaccination activities
+##' # setting up a two specific vaccination activities
 ##' vacc <- popim_vacc_activities(region = c("UK", "FRA"),
 ##'                             year = c(2010, 2005),
 ##'                             age_first = c(0, 0),
@@ -166,6 +166,9 @@ validate_vacc_activities <- function(x, name = deparse(substitute(x))) {
 ##'     [utils::read.csv()] which handles the reading of the .csv
 ##'     file.
 ##' @export
+##' @examples
+##' filename <- system.file("extdata", "vacc_activities.csv", package = "popim")
+##' vacc <- read_vacc_activities(filename)
 read_vacc_activities <- function(file) {
 
     ## assert_file_exists(file)
@@ -194,6 +197,12 @@ read_vacc_activities <- function(file) {
 ##' @author Tini Garske
 ##' @seealso [popim_vacc_activities()] for details of the S3 class.
 ##' @export
+##' @examples
+##' df <- data.frame(region = "UK", year = c(2000, 2002),
+##'                  age_first = 0, age_last = 0,
+##'                  coverage = 0.8, doses = NA,
+##'                  targeting = "random")
+##' vacc <- as_vacc_activities(df)
 as_vacc_activities <- function(df) {
 
     class(df) <- c("popim_vacc_activities", "data.frame")

R/util_assert.R

@@ -57,7 +57,8 @@ assert_0_to_1_or_missing <- function(x, name = deparse(substitute(x))) {
 
 assert_non_negative <- function(x, name = deparse(substitute(x))) {
     assert_numeric(x, name)
-    if(any(x < 0)) {
+    y <- any(x < 0, na.rm = TRUE)
+    if((is.na(y) || y)) {
         stop(sprintf("'%s' must be non-negative", name), call. = FALSE)
     }
 }

R/vacc_from_immunity.R

@@ -39,6 +39,22 @@
 ##' @seealso [apply_vacc()]
 ##' @export
 ##' @author Tini Garske
+##' @examples
+##' ## set up population and vaccination activities:
+##' pop <- popim_population(region = "UK", year_min = 2000, year_max = 2005,
+##'                         age_min = 0, age_max = 10)
+##' pop$pop_size <- 100
+##' vacc <- popim_vacc_activities(region = "UK", year = c(2001, 2002),
+##'                               age_first = 0, age_last = 0,
+##'                               coverage = 0.8, doses = NA,
+##'                               targeting = "random")
+##'
+##' ## update the population immunity based on the vaccination activities:
+##' pop <- apply_vacc(pop, vacc)
+##'
+##' ## get the vaccination activities that have created the population
+##' ## immunity - this should match the input `vacc`
+##' vacc_out <- vacc_from_immunity(pop, targeting = "random")
 vacc_from_immunity <- function(pop, targeting = "random", n_digits = 10) {
 
     assert_population(pop)

tests/testthat/test-as_popim_pop.R

@@ -2,7 +2,6 @@ test_that("as_popim_pop successfully converts a good dataframe", {
 
     df <- expand.grid(region = c("UK", "FRA"), age = 0:5, year = 2000:2002,
                       stringsAsFactors = FALSE)
-    df$pop_size <- 0
 
     expect_no_error(pop <- as_popim_pop(df))
     expect_true(is_population(pop))

tests/testthat/test-assert_non_negative.R

@@ -0,0 +1,15 @@
+test_that("non-negative or missing arguments pass", {
+    x <- 0:2
+    expect_no_error(assert_non_negative(x))
+    x <- c(0, 1, NA)
+    expect_no_error(assert_non_negative(x))
+    x <- c(NA_real_, NA_real_, NA_real_)
+    expect_no_error(assert_non_negative(x))
+})
+
+test_that("arguments with negative entries fail", {
+    x <- -1:1
+    expect_error(assert_non_negative(x))
+    x <- c(-1, NA)
+    expect_error(assert_non_negative(x))    
+})