Merge pull request #10 from mrc-ide/new_vignette

New vignette

.gitignore

@@ -7,3 +7,4 @@
 simple_example.R
 *function_list.ods*
 vip goals and terminology\.docx
+inst/doc

DESCRIPTION

@@ -12,6 +12,8 @@ Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.1
 Suggests:
+    knitr,
+    rmarkdown,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Imports:
@@ -21,3 +23,4 @@ Imports:
     rlang,
     tidyr,
     tidyselect
+VignetteBuilder: knitr

NAMESPACE

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

R/popim_population.R

@@ -156,7 +156,7 @@ read_popim_pop <- function(file) {
 ##' @param df a dataframe with at least columns region, age, year and pop_size.
 ##' @return an object of class `popim_population`
 ##' @author Tini Garske
-##' @noRd
+##' @export
 as_popim_pop <- function(df) {
 
     assert_column_exists(df, "region")

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/popim.Rmd

@@ -0,0 +1,155 @@
+---
+title: "popim"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{popim}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(popim)
+```
+
+The intention of the package `popim` is to provide tools to easily
+evaluate and track the POPulation IMmunity of an age-structured
+population that results from vaccination. Given that vaccination has
+long lasting effects, this requires tracking the status of the
+population through time.
+
+## Data structures
+
+To this end the package defines two S3 classes to store data in an
+appropriate format. Both classes are dataframes, but have additional
+requirements such as certain columns that must be present, and the
+format and range of these columns.
+
+### S3 class `popim_population`
+
+The class `popim_population` is designed to hold information on a
+population of interest.
+
+#### The dataframe
+
+The dataframe holds information on the population size and immunity
+status of the population through time. The population is disaggregated
+into 1-year age groups, and potentially several spatial regions. Each
+row refers to a particular (1 year) birth cohort in a given location
+and year.
+
+The mandatory columns are:
+
+* `region`: The population of interest may be spatially
+  disaggregated into separate geographical regions (e.g., countries or
+  subnational administrative regions). This column holds a string that
+  identifies which region each entry refers to.
+* `year`: The population is tracked through time using annual time
+  steps.
+* `age`: The age-structure of the population is tracked in annual age
+  groups.
+* `cohort`: This column is redundant as it equals `year` - `age`, and
+  therefore refers to the year in which this cohort was born. It is
+  included for ease of handling.
+* `immunity`: Gives the proportion of each cohort that is immune due
+  to past vaccination.
+* `pop_size`: Number of people in any given age group and year. To
+  facilitate using common units such as thousands this is not limited
+  to integer values. It is however up to the user to ensure that such
+  units are used consistently.
+
+| column     | type      | range          |
+|------------|-----------|----------------|
+| `region`   | character |                |
+| `year`     | integer   |                |
+| `age`      | integer   | non-negative   |
+| `cohort`   | integer   | `year` - `age` |
+| `immunity` | numeric   | [0, 1]         |
+| `pop_size` | numeric   | non-negative   |
+
+
+
+#### Class attributes
+
+In addition to the attributes that every dataframe has (`names`,
+`class`, `row.names`), the objects of the `popim_population` class
+also retain the input parameters of the basic constructer
+`popim_population()`:
+
+* `region`: a character vector of all regions in this object,
+* `year_min` and `year_max`: the range of years, and
+* `age_min` and `age_max`: the age range covered in this population.
+
+
+#### Create, modify and validate objects of this class
+
+create: [popim_population()], [`read_popim_pop()`], `as_popim_pop()`
+
+modify: [apply_vacc()]
+
+validate: [is_population()]
+
+
+
+
+### S3 class `popim_vacc_activities`
+
+The class `popim_vacc_activities` is designed to hold information on
+vaccination activities that have occurred or are planned in the
+population of interest. Each row of the dataframe relates to one
+vaccination activity.
+
+#### The dataframe
+
+The mandatory columns are:
+
+* `region`: The region in which the vaccination activity takes
+  place. While this is a free character field, when applied to a
+  population, this must match a region that occurs in the population.
+* `year`: year during which the vaccination activity takes place.
+* `age_first`: youngest age group to be targeted.
+* `age_last`: oldest age group to be targeted.
+* `coverage`: proportion of the target population to be immunised.
+* `doses`: number of doses used in the vaccination activity.
+* `targeting`: determines how doses are allocated when there is
+  pre-existing immunity in the population.
+
+*to do: details of coverage/doses, include assumptions of non-waning,
+100% effectiveness, no wastage.*
+
+*to do: explain targeting.*
+
+
+
+
+| column      | type      | range             |
+|-------------|-----------|-------------------|
+| `region`    | character |                   |
+| `year`      | integer   |                   |
+| `age_first` | integer   | non-negative      |
+| `age_last`  | integer   | $\ge$ `age_first` |
+| `coverage`  | numeric   | [0, 1]            |
+| `doses`     | numeric   | non-negative      |
+| `targeting` | character | `"random"`, `"correlated"`, `"targeted"` |
+
+#### Class attributes
+
+As this is a subclass of dataframe, it has the same attributes as a
+dataframe (`names`, `class` and `row_names`), and no additional
+attributes.
+
+#### Create and validate objects of this class
+
+create: [popim_vacc_activities()], [read_vacc_activities()],
+[as_vacc_activities()], [vacc_from_immunity()]
+
+modify: [complete_vacc_activities()]
+
+validate: [is_vacc_activities()]
+