`final_size`

calculates the final size of an epidemic outbreak
in a population with heterogeneous mixing, and with heterogeneous
susceptibility to infection such as that conferred by an immunisation
programme.

## Arguments

- r0
The basic reproductive number \(R_0\) of the disease.

- contact_matrix
Social contact matrix. Entry \(m_{ij}\) gives average number of contacts in group \(i\) reported by participants in group \(j\)

- demography_vector
Demography vector. Entry \(v_{i}\) gives proportion of total population in group \(i\) (model will normalise if needed).

- susceptibility
A matrix giving the susceptibility of individuals in demographic group \(i\) and risk group \(k\).

- p_susceptibility
A matrix giving the probability that an individual in demography group \(i\) is in risk (or susceptibility) group \(k\). Each row represents the overall distribution of individuals in demographic group \(i\) across risk groups, and each row

*must sum to 1.0*.- solver
Which solver to use. Options are "iterative" (default) or "newton", for the iterative solver, or the Newton solver, respectively. Special conditions apply when using the Newton solver, see the

`control`

argument.- control
A list of named solver options, see

*Solver options*.

## Value

A data.frame of the proportion of infected individuals, within each
demography group and susceptibility group combination.
If the demography groups and susceptibility groups are named, these
names are added to relevant columns. If the groups are not named, synthetic
names are added of the form `demo_grp_<i>`

, for each demographic group
\(i\).

## Solver options

The `control`

argument accepts a list of solver options, with the iterative
solver taking two extra arguments than the Newton solver. This is an optional
argument, and default options are used within the solver functions if an
argument is missing. Arguments provided override the solver defaults.

### Common options

`iterations`

: The number of iterations over which to solve for the final size, unless the error is below the solver tolerance. Default = 10000.`tolerance`

: The solver tolerance; solving for final size ends when the error drops below this tolerance. Defaults to set`1e-6`

. Larger tolerance values are likely to lead to inaccurate final size estimates.

## Examples

```
# load example POLYMOD data included in the package
data(polymod_uk)
r0 <- 2.0
contact_matrix <- polymod_uk$contact_matrix
demography_vector <- polymod_uk$demography_vector
# define the number of age and susceptibility groups
n_demo_grps <- length(demography_vector)
n_risk_grps <- 3
# In this example, all risk groups from all age groups are fully
# susceptible
susceptibility <- matrix(
data = 1, nrow = n_demo_grps, ncol = n_risk_grps
)
p_susceptibility <- matrix(
data = 1, nrow = n_demo_grps, ncol = n_risk_grps
)
# p_susceptibility rows must sum to 1.0
p_susceptibility <- p_susceptibility / rowSums(p_susceptibility)
# using default arguments for `solver` and `control`
final_size(
r0 = r0,
contact_matrix = contact_matrix,
demography_vector = demography_vector,
susceptibility = susceptibility,
p_susceptibility = p_susceptibility
)
#> demo_grp susc_grp susceptibility p_infected
#> 1 [0,20) susc_grp_1 1 0.8532885
#> 2 [20,40) susc_grp_1 1 0.7974557
#> 3 40+ susc_grp_1 1 0.6880834
#> 4 [0,20) susc_grp_2 1 0.8532885
#> 5 [20,40) susc_grp_2 1 0.7974557
#> 6 40+ susc_grp_2 1 0.6880834
#> 7 [0,20) susc_grp_3 1 0.8532885
#> 8 [20,40) susc_grp_3 1 0.7974557
#> 9 40+ susc_grp_3 1 0.6880834
# using manually specified solver settings for the iterative solver
control <- list(
iterations = 100,
tolerance = 1e-3,
step_rate = 1.9,
adapt_step = TRUE
)
final_size(
r0 = r0,
contact_matrix = contact_matrix,
demography_vector = demography_vector,
susceptibility = susceptibility,
p_susceptibility = p_susceptibility,
solver = "iterative",
control = control
)
#> demo_grp susc_grp susceptibility p_infected
#> 1 [0,20) susc_grp_1 1 0.8532715
#> 2 [20,40) susc_grp_1 1 0.7974597
#> 3 40+ susc_grp_1 1 0.6880988
#> 4 [0,20) susc_grp_2 1 0.8532715
#> 5 [20,40) susc_grp_2 1 0.7974597
#> 6 40+ susc_grp_2 1 0.6880988
#> 7 [0,20) susc_grp_3 1 0.8532715
#> 8 [20,40) susc_grp_3 1 0.7974597
#> 9 40+ susc_grp_3 1 0.6880988
# manual settings for the newton solver
control <- list(
iterations = 100,
tolerance = 1e-3
)
final_size(
r0 = r0,
contact_matrix = contact_matrix,
demography_vector = demography_vector,
susceptibility = susceptibility,
p_susceptibility = p_susceptibility,
solver = "newton",
control = control
)
#> demo_grp susc_grp susceptibility p_infected
#> 1 [0,20) susc_grp_1 1 0.9999876
#> 2 [20,40) susc_grp_1 1 0.9999873
#> 3 40+ susc_grp_1 1 0.9999867
#> 4 [0,20) susc_grp_2 1 0.9999876
#> 5 [20,40) susc_grp_2 1 0.9999873
#> 6 40+ susc_grp_2 1 0.9999867
#> 7 [0,20) susc_grp_3 1 0.9999876
#> 8 [20,40) susc_grp_3 1 0.9999873
#> 9 40+ susc_grp_3 1 0.9999867
```