Merge pull request #14 from mrc-ide/new_vignette

New vignette

README.Rmd

@@ -37,7 +37,9 @@ You can install the development version of popim from
 devtools::install_github("mrc-ide/popim")
 ```
 
-## Example 1
+## Example 1: A simple population without specified population size
+
+### Population setup
 
 This package defines an S3 class `popim_population` which is a dataframe
 with at least the columns year, age, cohort (the year of birth for the
@@ -61,6 +63,8 @@ head(pop)
 This dataframe has 242 columns (2 regions x 11 age groups 0 - 10 x 11
 years 2000 - 2020).
 
+### Add vaccination activities
+
 Next, we read in a file containing some vaccination activites into an
 object of the class `popim_vacc_activities`.
 
@@ -87,6 +91,8 @@ pop <- apply_vacc(pop, vacc)
 
 ```
 
+### Visualisation
+
 The resulting vaccine-derived immunity of the population can be visualised with
 the function `plot_immunity()`. This is based on ggplot2, and the
 returned graph object can be further modified - here in order to
@@ -109,7 +115,9 @@ the lower right corner - and the increasing coverage highlights how
 cohorts age through time and therefore move through the plot in a
 diagonal fashion.
 
-## Example 2
+## Example 2: A population with specified size and age distribution
+
+### Population setup
 
 A more realistic scenario is to read in some real population data to
 set up the popim_population, and then apply some vaccination activities
@@ -138,6 +146,8 @@ range(pop$age)
 
 ```
 
+### Add vaccination activities
+
 Now we read in some vaccination activities for Nigeria: some campaigns
 targeting all age groups, and some routine vaccination targeting only
 infants:
@@ -186,6 +196,8 @@ plot_immunity(pop)
 
 ```
 
+### Summary
+
 The overall population immunity can be aggregated across ages using
 the function `calc_pop_immunity()`:
 
@@ -198,6 +210,8 @@ ggplot(pop_agg, aes(x = year, y = immunity, col = region)) +
 
 ```
 
+### Infer vaccination activities from `popim_population` object
+
 Given a `popim_population` object, the vaccination activities that would
 be needed to achieve the specified population immunity can be inferred
 with the function `vacc_from_immunity()`, given an assumption on the

README.md

@@ -26,7 +26,9 @@ You can install the development version of popim from
 devtools::install_github("mrc-ide/popim")
 ```
 
-## Example 1
+## Example 1: A simple population without specified population size
+
+### Population setup
 
 This package defines an S3 class `popim_population` which is a dataframe
 with at least the columns year, age, cohort (the year of birth for the
@@ -58,6 +60,8 @@ head(pop)
 This dataframe has 242 columns (2 regions x 11 age groups 0 - 10 x 11
 years 2000 - 2020).
 
+### Add vaccination activities
+
 Next, we read in a file containing some vaccination activites into an
 object of the class `popim_vacc_activities`.
 
@@ -90,6 +94,8 @@ using the function `apply_vacc()`.
 pop <- apply_vacc(pop, vacc)
 ```
 
+### Visualisation
+
 The resulting vaccine-derived immunity of the population can be
 visualised with the function `plot_immunity()`. This is based on
 ggplot2, and the returned graph object can be further modified - here in
@@ -113,7 +119,9 @@ lower right corner - and the increasing coverage highlights how cohorts
 age through time and therefore move through the plot in a diagonal
 fashion.
 
-## Example 2
+## Example 2: A population with specified size and age distribution
+
+### Population setup
 
 A more realistic scenario is to read in some real population data to set
 up the popim\_population, and then apply some vaccination activities to
@@ -153,6 +161,8 @@ range(pop$age)
 #> [1]   0 100
 ```
 
+### Add vaccination activities
+
 Now we read in some vaccination activities for Nigeria: some campaigns
 targeting all age groups, and some routine vaccination targeting only
 infants:
@@ -247,6 +257,8 @@ plot_immunity(pop)
 
 <img src="man/figures/README-plot_immunity_2-2.png" width="100%" />
 
+### Summary
+
 The overall population immunity can be aggregated across ages using the
 function `calc_pop_immunity()`:
 
@@ -275,6 +287,8 @@ ggplot(pop_agg, aes(x = year, y = immunity, col = region)) +
 
 <img src="man/figures/README-calc_pop_immunity-1.png" width="100%" />
 
+### Infer vaccination activities from `popim_population` object
+
 Given a `popim_population` object, the vaccination activities that would
 be needed to achieve the specified population immunity can be inferred
 with the function `vacc_from_immunity()`, given an assumption on the

man/rmd/apply.Rmd

@@ -42,6 +42,15 @@ is non-missing. If `coverage` is missing, the target population size
 will be calculated and the corresponding `coverage` calculated as
 `doses` / `target_population`.
 
+While the function `apply_vacc()` will calculate the coverage if it is
+missing with respect to the target population size, without modifying
+the input `popim_vacc_activities` object, the function
+`complete_vacc_activities()` will fill in missing coverage and doses
+information from the other, and check for inconsistencies in
+activities that have both data on `coverage` and `doses`. This is done
+with respect to a particular `popim_population` object which contains
+the relevant population sizes.
+
 #### Vaccinating a cohort with no previous immunity
 
 When vaccination is applied to a particular birth cohort that has no

vignettes/popim.Rmd

@@ -177,14 +177,60 @@ cat(res, sep = "\n")
 
 
 
-### The inverse
+### The inverse: inferring vaccination activities from a population
 
-`vacc_from_immunity()`
+It is not possible to infer the vaccination activities that have given
+rise to a particular immunity profile of a population by age and over
+time: The same profile can be reached with different `targeting`
+choices (where different `targeting` choices will require different
+amount of vaccine). Furthermore, if there are cohorts that reached
+100\% immunity, there may have been double vaccination of some
+individuals that left no trace in the immunity profile. However, the
+function `vacc_from_immunity()` does infer the vaccination activities
+from a population immunity profile as far as possible, returning an
+obejct of class `popim_vacc_activities`.
+
+To this end, in addition to passing the `popim_population` object of
+interest, the user needs to specify a `targeting` option (which will
+be assumed for all vaccination activities that are identified). The
+inferred vaccination activities will be the minimal activities
+possible to give rise to the observed immunity profile given the
+`targeting` option supplied.
+
+
+## Population summary & visualisation
+
+An object of class `popim_population` holds a somewhat complex dataset
+recording population size, age distribution and immunity status
+through time, and potentially disaggregated into various geographical
+regions. To facilitate interpretation of this kind of data, there are
+a couple of functions to aggregate and visualise these objects.
+
+### Visualisation
+
+The functions `plot_pop_size()` and `plot_immunity()` serve to plot
+the age-disaggregated population size and immunity through time in a
+grid where year and age are plotted on the x- and y-axis,
+respectively. The size of the cohort or proportion of the cohort that
+is immune is indicated by the colour of the grid cell. If there are
+several regions, these will be shown in separate panels.
+
+The implementation of these plot functions is based on ggplot2, and
+therefore the returned plot objects can be further modified using the
+ggplot2 syntax.
+
+### Aggregation over age
+
+While the age structure of a population's immunity profile is
+important to understand how immunity is likely to develop through
+time, for the purposes of understanding how well a population is
+protected at any point in time, often the overall proportion immune is
+of greater interest. This can be calculated using the function
+`calc_pop_immunity()` which will aggregate the population over age and
+return a dataframe with the whole population immunity over time and
+geographical region.
 
 
-## Summary & Visualisation
 
-`calc_pop_immunity()`
 
-`plot_pop_size()`, `plot_immunity()`