[FEATURE] Immunity estimation by age groups

[olivieradjagba]

Problem statement

Currently, immunity can be estimated by:

• Vaccine type (e.g., OPV and/or IPV for Polio)
• Immunity type (e.g., mucosal or humoral for Polio)
• Time step (yearly or monthly)

However, users cannot directly estimate immunity by age groups (e.g., 0-12 months, 12-24 months, 2-5 years). While users could manually subset their data and perform these calculations, it requires additional processing and is prone to errors.

Proposed solution

Add functionality to estimate immunity by user-specified age groups. Users can define either:

• Age brackets: Custom age intervals (e.g., c(0, 1, 5, 15))
• Age step: Regular age increments (e.g., step = 1 for yearly age groups)

The function would automatically compute immunity estimates for each defined group.

Example usage

# Option 1: Custom age brackets (yearly)
immunity_by_age <- compute_immunity(
  ri_data = ri_data,
  efficacy = efficacy,
  age_groups = c(0, 1, 5, 15)  # Creates [0-1), [1-5), [5-15] years
)

# Option 2: Custom age brackets (monthly)
immunity_by_age <- compute_immunity(
  ri_data = ri_data,
  efficacy = efficacy,
  age_groups = c(0, 6, 12, 24),  # Creates [0-6), [6-12), [12-24] months
  age_unit = "month"
)

# Option 3: Regular age step (yearly)
immunity_by_age <- compute_immunity(
  ri_data = ri_data,
  efficacy = efficacy,
  age_step = 1,  # Creates yearly age groups: [0-1), [1-2), [2-3), ...
  max_age = 15
)

# Option 4: Regular age step (monthly)
immunity_by_age <- compute_immunity(
  ri_data = ri_data,
  efficacy = efficacy,
  age_step = 3,  # Creates quarterly age groups: [0-3), [3-6), [6-9), ... months
  age_unit = "month",
  max_age = 24
)

# Option 5: Mixed approach (brackets + step)
immunity_by_age <- compute_immunity(
  ri_data = ri_data,
  efficacy = efficacy,
  age_groups = c(0, 1, 5),  # Infants and toddlers (in years)
  age_step = 5,             # Then 5-year increments
  max_age = 20
)

# Option 6: Age groups specified as named list
## Define age groups (in years)
age_groups <- list(
  "infants" = c(0, 1), # [0-1)
  "toddlers" = c(1, 2),
  "preschool" = c(2, 5),
  "school_age" = c(5, 15)
)
## Estimate immunity by age group
immunity_by_age <- compute_immunity(
  ri_data = ri_data,
  efficacy = efficacy,
  age_groups = age_groups
)

# Option 7: Automatic grouping based on vaccination schedule (if possible)
immunity_by_age <- compute_immunity(
  ri_data = ri_data,
  vs_info = vs_info,
  efficacy = efficacy,
  age_groups = "schedule"  # Groups based on vaccine dose timing
)

Output structure

Assuming immunity estimation by vaccine type, we would expect the following output

district	year	age_group	vaccine	immunity
A01	2010	0-1	OPV	0.85
A01	2010	1-5	OPV	0.72
A01	2010	5-10	OPV	0.68
A01	2010	10-15	OPV	0.52

Alternatives considered

1. User-level subsetting: Users manually filter data and run separate analyses
   • Drawback: Time-consuming, error-prone, inconsistent age boundaries
2. Pre-defined age groups: Hardcode common age brackets
   • Drawback: Less flexible for different epidemiological contexts
3. External post-processing: Users export results and aggregate manually
   • Drawback: Adds extra steps, breaks workflow continuity

Additional context

This feature would be particularly valuable for:

• Understanding immunity gaps in specific age cohorts
• Targeting vaccination campaigns to vulnerable age groups
• Comparing immunity profiles across different childhood stages
• Meeting reporting requirements that specify age-stratified estimates

Implementation notes

The computation would need to:

• Handle age boundaries appropriately (left-inclusive, right-exclusive)
• Aggregate individual immunity estimates for individuals within each age group
• Respect existing vaccine and immunity type groupings
• Maintain consistent output structure for downstream analysis

Checklist

• I have searched existing issues
• This feature aligns with package goals