---
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 = "#>",
  out.width = "100%",
  fig.dim = c(8,6)
)
```

```{r setup}
library(popim)
```

**POPulation IMmunity**

This repository contains functions to run a demographic model of
vaccine exposure over time, tracking the vaccine-derived immunity by
age through time, following implementation of one or more vaccination
activities that can target the population as a whole or selectively
target specific age groups.

## Installation

You can install the development version of popim from
[GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("mrc-ide/popim")
```

## 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
individuals tracked in this row), and immunity (as a proportion of
this cohort). Year, age and cohort are tracked as annual time steps
and age groups.

A basic, totally naive population dataframe can be setup using the
function `popim_population()`:

```{r example}
library(popim)

pop <- popim_population(region = c("UK", "FRA"), year_min = 2000, year_max = 2010,
                        age_min = 0, age_max = 10)

dim(pop)
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`.

```{r read_vacc}

vacc <- read_vacc_activities("../inst/extdata/vacc_activities.csv")
vacc

```

All vaccination activities target the UK. The first is a campaign
targeting all age groups of our dummy population, which took place 2
years before the dawn of time. As immunity is assumed not to wane, the
effects of this are still there, and therefore the functions here keep
track of this. The remaining vaccination activities are routine
vaccination of infants (restricted to age 0) with an increasing
population of the target cohort to be vaccinated.

We now apply these vaccination activities sequentially to the
population using the function `apply_vacc()`.

```{r 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 order to
achieve tick marks that suit the data better.

```{r plot_immunity}
library(ggplot2) ## needed to amend the plot returned from plot_population()

g <- plot_immunity(pop)
g + scale_x_continuous(breaks = seq(2000, 2010, by = 2)) +
    scale_y_continuous(breaks = seq(0, 10, by = 2))

```

As all vaccination activities target the "UK", the population in "FRA"
has no immunity at all. In the "UK", the top left corner it shows the
immunity remaining in the older age groups from the initial campaign,
while the infant vaccination from 2005 onwards results in immuity in
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: 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 this. Information on the vaccination activities may be given in
coverage (typical for routine infant vaccination) or doses (typical
for mass vaccination campaigns).

```{r read_population}

pop <- read_popim_pop(file = "../inst/extdata/pop_sample.csv")

```

We have read in population data for India ("IND") and Nigeria
("NGA") for the period from 1950 to 2100. The age range covered is 0
to 100 year, and the population is set up as fully unvaccinated:

```{r check_population}

dim(pop)
head(pop)

table(pop$region)
range(pop$year)
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:

```{r apply_campaigns}
campaigns <- read_vacc_activities("../inst/extdata/vacc_campaigns_NGA.csv")
campaigns

routine <- read_vacc_activities("../inst/extdata/vacc_routine_NGA.csv")
routine

```

Note that in this dataset the extent of the campaigns is given in the
number of vaccine doses administered (assuming no wastage, so this
equates to the number of people vaccinated), while the routine
vaccination is given as coverage, i.e., the proportion of the targeted
age cohort to be vaccinated.

If we know the population size that is targeted, we can convert
between doses and coverage, and there is a function
`complete_vacc_activities()` to fill in whichever one is missing:

```{r complete_vacc}

campaigns_complete <- complete_vacc_activities(campaigns, pop)
campaigns_complete

routine_complete <- complete_vacc_activities(routine, pop)
routine_complete |> head()

```

We now apply first the campaigns, then the routine vaccination to the
population, and visualise the resulting population immunity. Note that
we can use either the original or completed versions of the
vaccination activities.

```{r plot_immunity_2}

pop <- apply_vacc(pop, campaigns)
plot_immunity(pop)

pop <- apply_vacc(pop, routine)
plot_immunity(pop)

```

### Summary

The overall population immunity can be aggregated across ages using
the function `calc_pop_immunity()`:

```{r calc_pop_immunity}
pop_agg <- calc_pop_immunity(pop)
pop_agg

ggplot(pop_agg, aes(x = year, y = immunity, col = region)) +
    geom_point()

```

### 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
targeting method of the vaccination activities. Using this function on
the population we have just constructed does indeed yield the original
vaccination activities back:

```{r }

vacc_act <- vacc_from_immunity(pop, targeting = "random")
vacc_act



```