[FEATURE] Integrate multiple birth/population cohorts for age-specific denominators

[olivieradjagba]

Problem Statement

Currently, the package uses only 0-year-old birth data (children born in a specific year) as the denominator for all immunity calculations. This implicitly assumes all children survive throughout the vaccination schedule, which is unrealistic and may introduce bias in estimates, particularly in settings with notable child mortality or when analyzing later vaccine doses.

Proposed Solution

Extend the package to allow more flexible denominator specifications:

1. Multiple population cohorts: Accept population data for different age groups (0-year, 1-year, etc.) to serve as age-appropriate denominators
2. Survival rate adjustment: Allow users to provide survival rates or life tables to adjust birth cohorts for mortality
3. Flexible denominator selection: Let users specify which population data corresponds to each vaccine dose age

Example Usage (just suggestions)

# Option 1: Multiple age-specific population data
population_data <- data.frame(
  dist_code = c("D01", "D01", "D02", "D02"),
  age_group = c(0, 1, 0, 1),
  population = c(1000, 950, 2000, 1900)
)

# Option 2: Survival rates
survival_rates <- data.frame(
  dist_code = c("D01", "D01", "D02", "D02"),
  age_year = c(0, 1, 0, 1),
  survival_prob = c(1.00, 0.95, 1.00, 0.96)
)

# Updated function call with population adjustment
compute_immunity(
  ri_data = ri_data,
  birth_data = birth_data,
  population_data = population_data,  # new option
  survival_rates = survival_rates     # alternative option
)

Alternatives Considered

• Keep current approach: Simpler but less accurate for high-mortality settings
• External adjustment: Users pre-adjust birth data outside the package (adds burden)
• Sensitivity analysis: Keep current but document limitations

Benefits

• More realistic immunity estimates, especially in high-mortality contexts
• Better accuracy for later vaccine doses (IPV2, OPV3, etc.)
• Flexibility to work with available data (cohorts or survival rates)
• Aligns with standard demographic and epidemiological practice

Implementation Considerations

• Backward compatibility: Default behavior should remain unchanged
• Data validation: Need functions to validate age-specific population data
• Documentation: Clear guidance on when and how to use these options

Additional Context

This enhancement would significantly improve the package's applicability in settings with:

• High under-5 mortality
• Varying survival rates across districts
• Available demographic surveillance or census data

Checklist

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