Estimate vaccine-derived immunity

compute_immunity(): Estimate immunity based on handled extra-doses routine immunization data and dose-specific vaccine efficacy.
compute_immunity_by_type(): Estimate immunity by immunity type based on computed immunity by compute_immunity() and immunity type conferred by each vaccine.

Usage

compute_immunity(ri_data, efficacy, ..., dd_assumption = "organised")

compute_immunity_by_type(immunity_estimates, vax_imm_type = NULL, rho = 0)

Arguments

ri_data: [data.frame] Routine immunization data in the format required by impute_missing_doses(). Missing values are permitted only in vaccine-dose columns.
efficacy: [data.frame] Vaccine doses efficacy estimates table preprocessed with preprocess_efficacy() which is structured as prep_dummy_efficacy. efficacy_default defines the structure of the raw format before preprocessing.
...: Forces optional arguments to be passed by name and allows for future extensions without breaking existing code. Must be empty.
dd_assumption: ['organised' | 'random'] Indicates assumptions about dose receipt patterns when computing immunity (see Dose receipt patterns assumptions section in details).
immunity_estimates: [data.table] The immunity estimates per vaccine.
vax_imm_type: [list<character>] Named list mapping each vaccine to one or more immunity types (see Vaccine immunity type mapping in Details). For example, list(OPV = c("mucosal", "humoral"), IPV = "humoral").
rho: [numeric(1) | matrix] Controls the correlation between different vaccines when calculating immunity at the population level (see Correlation between vaccines section in details).

Value

compute_immunity(): [data.table] Immunity estimates by administrative unit, year, month (if applicable), serotype and vaccine. The columns are: administrative unit, year and month (if applicable) columns, defined in the admin, year, month (if monthly = TRUE) arguments of config_pviem() respectively, with serotype, vaccine, immunity_level, zero_dose and live_births columns. immunity_level is the immunity estimate calculated as the proportion of individuals who acquire immunity from a given vaccine while zero_dose is the proportion of individuals who did not receive any dose of a given vaccine in a birth cohort.
compute_immunity_by_type(): [data.table] Immunity estimates by administrative unit, year, month (if applicable), serotype and immunity type. The columns are the same as for the previous function with vaccine column replaced by type column holding the immunity type. Here immunity_level is the proportion of individuals who get immunity of a given type.

Details

Dose receipt patterns assumptions

The assumptions about dose receipt patterns when computing immunity are crucial for accurately estimating immunity levels in a population. The dd_assumption parameter allows you to specify these assumptions, which can significantly impact the resulting immunity estimates. Here are the details of the two assumptions:

'organised' (default): Ideally, the number of children receiving the nth dose of a vaccine in a given administrative unit-time should not exceed those who received the *(n-1)*th dose (or the birth cohort size for the first dose). However, real-world data often violates this logical constraint due to migration, mortality, or reporting discrepancies. The 'organised' assumption enforces sequential consistency in dose receipt. The algorithm works as follows:
1. For each administrative unit-time, identify the dose with the smallest count across the vaccine series (doses 1 through n)
2. This minimum count represents the number of children who received all n doses
3. Remove this dose count from the list and subtract the n-dose count from each remaining count
4. The minimum count from the new list represents the number of children who received n-1 doses
5. Repeat this process iteratively for n-2, n-3, down to 0 dose.

This process ensures no child is counted as receiving dose k without having received all preceding doses. The dose-specific populations are then combined with dose-specific efficacy estimates to calculate immunity levels.

'random': Represents a bounding case with extreme assumptions: dose numbers are recorded based solely on the child's age, independent of vaccination history. Under this scenario, receiving doses at older ages is uncorrelated with receiving doses at younger ages.

Vaccine immunity type mapping

The vax_imm_type argument allows you to specify which immunity types each vaccine confers. This should be a named list where:

Keys: Vaccine names (e.g., "OPV", "IPV")
Values: Character vectors of immunity types (e.g., c("mucosal", "humoral"))

If you are working exclusively with Polio's OPV and/or IPV vaccines named exactly as such in the vaccination schedules table (see dummy_vs_info), you can omit this argument. The function defaults to: list(OPV = c("mucosal", "humoral"), IPV = "humoral") which covers the standard Polio vaccination scenario.

The function accommodates any number of immunity types and vaccine combinations, provided that (1) the immunity types are specified in vax_imm_type, and (2) the corresponding vaccine doses appear in both your routine immunization and efficacy estimates data.

Correlation between vaccines

The rho parameter controlling the correlation between different vaccines is crucial when multiple vaccines contribute to the same immunity type:

rho = 0: Assumes that receiving one vaccine is unrelated to receiving another vaccine.
rho = 1: Assumes that children who receive one vaccine are as likely as possible to also receive the other vaccine.
0 < rho < 1: Assumes partial correlation, indicating some level of association between vaccine uptake.

If more than two vaccines contribute to the same immunity type, rho can be:

a single value applied uniformly across all vaccine pairs, or
a correlation matrix specifying pairwise correlations between each vaccine. The matrix rows and columns should be named according to the vaccine names in vax_imm_type.

This parameter represents assumptions about the overlap in uptake of vaccines that confer the same immunity type. The calculation applies this assumption when combining vaccine-specific immunity estimates.

Note

Ideally, ri_data should be the output of handle_extra_doses() to make sure that no dose count exceed the birth cohort.