From 896bb55af76cc21e805a189b42b2dcf3b4ef46d7 Mon Sep 17 00:00:00 2001 From: danalvarez Date: Tue, 20 Jan 2026 14:28:12 -0600 Subject: [PATCH 1/5] First version of birth cohort coverage calculation Pending further tests --- NAMESPACE | 1 + R/bc_coverage.R | 128 +++++++++++++++++++++++++++++++++++++++++++++ R/cs_coverage.R | 3 +- R/validation.R | 38 ++++++++++++++ man/bc_coverage.Rd | 37 +++++++++++++ man/cs_coverage.Rd | 2 +- 6 files changed, 207 insertions(+), 2 deletions(-) create mode 100644 R/bc_coverage.R create mode 100644 man/bc_coverage.Rd diff --git a/NAMESPACE b/NAMESPACE index 3fd60c4..373516f 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,6 @@ # Generated by roxygen2: do not edit by hand +export(bc_coverage) export(cs_barplot) export(cs_coverage) export(cs_upsetplot) diff --git a/R/bc_coverage.R b/R/bc_coverage.R new file mode 100644 index 0000000..298809a --- /dev/null +++ b/R/bc_coverage.R @@ -0,0 +1,128 @@ +#' (B)irth (C)ohort Coverage +#' +#' This function calculates the coverage by birth cohort, further disagreggating by geographic level, using data from the electronic immunization registry (EIR). +#' +#' @param data.EIR A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure. +#' @param data.schedule A data frame defining the vaccination schedule. See \code{pahoabc.schedule} for expected structure. +#' @param geo_level The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0". Note also that if \code{data.pop} is in use, it must contain the columns to match. +#' @param vaccines Character (optional). A character vector specifying the doses to include in the analysis. If \code{NULL} (default), all vaccines in \code{data.EIR} are included. +#' @param birth_cohorts Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be calculated. If \code{NULL} (default), coverage is calculated for all available cohorts. +#' @param data.pop Data frame (optional). A data frame with population denominators. See \code{pahoabc.pop.ADMX} for structure examples. If \code{NULL} (default), the denominator is taken from \code{data.EIR} for each year and \code{geo_level}. +#' @param only_valid_doses Logical (optional). If \code{TRUE} (default), only count vaccinations that occurred within the valid age window defined by \code{age_schedule_low} and \code{age_schedule_high}. If \code{FALSE}, do not filter by age at vaccination. +#' +#' @return A data frame containing the coverage by birth cohort for the specified \code{geo_level}. +#' +#' @import dplyr +#' @import lubridate +#' +#' @export +bc_coverage <- function(data.EIR, data.schedule, geo_level = "ADM0", vaccines = NULL, birth_cohorts = NULL, data.pop = NULL, only_valid_doses = TRUE) { + + # validations + .validate_geo_level(geo_level) + .validate_data.schedule(data.schedule) + .validate_data.EIR(data.EIR, data.schedule) + .validate_vaccines(vaccines, data.EIR, "data.EIR") + .validate_numeric(birth_cohorts, "birth_cohorts", min_len = 1) + .validate_data.pop(data.pop, geo_level) + .validate_vaccines(vaccines, data.schedule, "data.schedule") + .validate_logical(only_valid_doses, "only_valid_doses") + + # determine grouping column(s) + basic_groups <- c("year_cohort") + if(geo_level != "ADM0") { + # groups for ADM1 + groups <- c(basic_groups, "ADM1") + + # groups for ADM2 + if(geo_level == "ADM2") { + groups <- c(groups, geo_level) + } + } else { + groups <- basic_groups + } + + # determine vaccines to evaluate + doses_to_use <- data.EIR %>% + pull(dose) %>% + unique() + if(!is.null(vaccines)) { + doses_to_use <- vaccines + } + + # prepare schedule for selected doses + prepare_schedule <- data.schedule %>% + filter(dose %in% doses_to_use) + + # prepare EIR with valid age windows + prepare_EIR <- data.EIR %>% + select( + ID, + date_birth, + date_vax, + ADM1 = ADM1_residence, + ADM2 = ADM2_residence, + dose + ) %>% + filter(dose %in% prepare_schedule$dose) %>% + mutate( + year_cohort = year(date_birth), + age_at_vax = as.numeric(date_vax - date_birth) + ) %>% + left_join(prepare_schedule, by = "dose") + + if(only_valid_doses) { + prepare_EIR <- prepare_EIR %>% + filter( + age_at_vax >= age_schedule_low, + age_at_vax <= age_schedule_high + ) + } + + # filter for selected birth cohorts + if(!is.null(birth_cohorts)) { + prepare_EIR <- prepare_EIR %>% filter(year_cohort %in% birth_cohorts) + } + + # get number of children with valid doses for the defined groups + numerator <- prepare_EIR %>% + group_by(dose, across(all_of(groups))) %>% + summarise(numerator = n_distinct(ID), .groups = "drop") + + # get population for birth cohorts + if(is.null(data.pop)) { + line_list_denominator <- data.EIR %>% + select( + ID, + date_birth, + ADM1 = ADM1_residence, + ADM2 = ADM2_residence + ) %>% + mutate(year_cohort = year(date_birth)) + + if(!is.null(birth_cohorts)) { + line_list_denominator <- line_list_denominator %>% + filter(year_cohort %in% birth_cohorts) + } + + line_list_denominator <- line_list_denominator %>% + distinct(ID, across(all_of(groups))) + + denominator <- line_list_denominator %>% + group_by(across(all_of(groups))) %>% + summarise(population = n(), .groups = "drop") + } else { + denominator <- data.pop %>% + # select age == 0 because this contains the population of age 0 for that year + filter(age == 0) %>% + select(-age) %>% + rename(year_cohort = year) + } + + # calculate coverage + coverage <- numerator %>% + left_join(denominator, by = groups) %>% + mutate(coverage = round(numerator / population * 100, 2)) + + return(coverage) +} diff --git a/R/cs_coverage.R b/R/cs_coverage.R index aa03669..13d7aaa 100644 --- a/R/cs_coverage.R +++ b/R/cs_coverage.R @@ -6,7 +6,7 @@ #' @param data.EIR A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure. #' @param data.schedule A data frame defining the vaccination schedule. See \code{pahoabc.schedule} for expected structure. #' @param geo_level The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If \code{data.pop} is in use, it must contain the columns to match. -#' @param birth_cohorts Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be calculated. If \code{NULL} (default), coverage is calculated for all available years. +#' @param birth_cohorts Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be calculated. If \code{NULL} (default), coverage is calculated for all available cohorts. #' @param max_age Numeric (optional). The maximum age (in days) up to which vaccination completeness is assessed. If \code{NULL} (default), all doses in \code{data.schedule} are considered. #' @param data.pop Data frame (optional). A data frame with population denominators. See \code{pahoabc.pop.ADMX} for structure examples. If \code{NULL} (default), the denominator is taken from \code{data.EIR} for each year and \code{geo_level}. #' @@ -83,6 +83,7 @@ cs_coverage <- function(data.EIR, data.schedule, geo_level, birth_cohorts = NULL } else { denominator <- data.pop %>% + # select age == 0 because this contains the population of age 0 for that year filter(age == 0) %>% select(-age) } diff --git a/R/validation.R b/R/validation.R index 7a16c7f..5076076 100644 --- a/R/validation.R +++ b/R/validation.R @@ -239,3 +239,41 @@ invisible(TRUE) # silent success } + +#' Validate data.EIR structure and (optionally) schedule compatibility. +#' +#' @keywords internal +#' @noRd +.validate_data.EIR <- function(data.EIR, data.schedule = NULL) { + if(!is.data.frame(data.EIR)) { + stop("Error: data.EIR should be a data frame.") + } + + required_columns <- c( + "ID", + "date_birth", + "date_vax", + "ADM1_residence", + "ADM2_residence", + "ADM1_occurrence", + "ADM2_occurrence", + "dose" + ) + + if(!all(required_columns %in% names(data.EIR))) { + stop("Error: data.EIR should contain the following columns: ID, date_birth, date_vax, ADM1_residence, ADM2_residence, ADM1_occurrence, ADM2_occurrence, dose.") + } + + if(!is.null(data.schedule)) { + missing_in_schedule <- setdiff(unique(data.EIR$dose), unique(data.schedule$dose)) + if(length(missing_in_schedule) > 0) { + warning( + paste0( + "Warning: The following dose(s) are present in data.EIR but missing from data.schedule: ", + paste(missing_in_schedule, collapse = ", "), + "." + ) + ) + } + } +} diff --git a/man/bc_coverage.Rd b/man/bc_coverage.Rd new file mode 100644 index 0000000..888caf4 --- /dev/null +++ b/man/bc_coverage.Rd @@ -0,0 +1,37 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bc_coverage.R +\name{bc_coverage} +\alias{bc_coverage} +\title{(B)irth (C)ohort Coverage} +\usage{ +bc_coverage( + data.EIR, + data.schedule, + geo_level = "ADM0", + vaccines = NULL, + birth_cohorts = NULL, + data.pop = NULL, + only_valid_doses = TRUE +) +} +\arguments{ +\item{data.EIR}{A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.} + +\item{data.schedule}{A data frame defining the vaccination schedule. See \code{pahoabc.schedule} for expected structure.} + +\item{geo_level}{The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0". Note also that if \code{data.pop} is in use, it must contain the columns to match.} + +\item{vaccines}{Character (optional). A character vector specifying the doses to include in the analysis. If \code{NULL} (default), all vaccines in \code{data.EIR} are included.} + +\item{birth_cohorts}{Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be calculated. If \code{NULL} (default), coverage is calculated for all available cohorts.} + +\item{data.pop}{Data frame (optional). A data frame with population denominators. See \code{pahoabc.pop.ADMX} for structure examples. If \code{NULL} (default), the denominator is taken from \code{data.EIR} for each year and \code{geo_level}.} + +\item{only_valid_doses}{Logical (optional). If \code{TRUE} (default), only count vaccinations that occurred within the valid age window defined by \code{age_schedule_low} and \code{age_schedule_high}. If \code{FALSE}, do not filter by age at vaccination.} +} +\value{ +A data frame containing the coverage by birth cohort for the specified \code{geo_level}. +} +\description{ +This function calculates the coverage by birth cohort, further disagreggating by geographic level, using data from the electronic immunization registry (EIR). +} diff --git a/man/cs_coverage.Rd b/man/cs_coverage.Rd index 3c64d3f..2039ad6 100644 --- a/man/cs_coverage.Rd +++ b/man/cs_coverage.Rd @@ -20,7 +20,7 @@ cs_coverage( \item{geo_level}{The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If \code{data.pop} is in use, it must contain the columns to match.} -\item{birth_cohorts}{Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be calculated. If \code{NULL} (default), coverage is calculated for all available years.} +\item{birth_cohorts}{Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be calculated. If \code{NULL} (default), coverage is calculated for all available cohorts.} \item{max_age}{Numeric (optional). The maximum age (in days) up to which vaccination completeness is assessed. If \code{NULL} (default), all doses in \code{data.schedule} are considered.} From 4b8d540281d29914f84b9ceeccac20d4b3bd14c9 Mon Sep 17 00:00:00 2001 From: danalvarez Date: Thu, 29 Jan 2026 18:01:13 -0600 Subject: [PATCH 2/5] Added bc_barplot to plot birth cohort coverages --- NAMESPACE | 1 + R/bc_barplot.R | 82 +++++++++++++++++++++++++++++++++++++++++++++++ R/validation.R | 18 +++++++++++ man/bc_barplot.Rd | 31 ++++++++++++++++++ 4 files changed, 132 insertions(+) create mode 100644 R/bc_barplot.R create mode 100644 man/bc_barplot.Rd diff --git a/NAMESPACE b/NAMESPACE index 373516f..7dc90a0 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,6 @@ # Generated by roxygen2: do not edit by hand +export(bc_barplot) export(bc_coverage) export(cs_barplot) export(cs_coverage) diff --git a/R/bc_barplot.R b/R/bc_barplot.R new file mode 100644 index 0000000..5ad676c --- /dev/null +++ b/R/bc_barplot.R @@ -0,0 +1,82 @@ +#' (B)irth (C)ohort Coverage Bar Plot +#' +#' Generates a bar plot of birth cohort coverage, grouped by geographic area and colored by birth cohort year. +#' +#' @param data The output from the \code{pahoabc::bc_coverage} function. +#' @param vaccine A string specifying the vaccine of interest. Only one vaccine. +#' @param birth_cohorts Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be plotted. If \code{NULL} (default), all years are plotted. +#' @param within_ADM1 Character (optional). When analyzing data at the "ADM2" level, this optional character vector lets you specify one or several "ADM1" to filter. Default is \code{NULL}, which means no filtering by "ADM1". +#' @param palette Character (optional). A RColorBrewer palette name for the cohort colors. Default is \code{"YlOrBr"}. +#' +#' @return A ggplot object representing the bar plot. +#' +#' @import dplyr +#' @import ggplot2 +#' +#' @export +bc_barplot <- function(data, vaccine, birth_cohorts = NULL, within_ADM1 = NULL, palette = "YlOrBr") { + + .validate_bc_barplot_data(data) + .validate_character(vaccine, "vaccine", exp_len = 1) + .validate_vaccines(vaccine, data, "data") + .validate_numeric(birth_cohorts, "birth_cohorts", min_len = 1) + .validate_character(within_ADM1, "within_ADM1", min_len = 1) + .validate_character(palette, "palette", exp_len = 1) + + # detect geo level + ADM_detected <- .detect_geo_level(data) + geo_column <- paste0("ADM", ADM_detected) + + # prepare data for plot + prepare_data <- data %>% + filter(dose == vaccine) %>% + filter(if(!is.null(birth_cohorts)) {year_cohort %in% birth_cohorts} else {TRUE}) %>% + filter(if(!is.null(within_ADM1)) {ADM1 %in% within_ADM1} else {TRUE}) + + cohort_levels <- prepare_data %>% + pull(year_cohort) %>% + unique() %>% + sort() + + if(length(cohort_levels) > 9) { + cohort_levels <- tail(cohort_levels, 9) + prepare_data <- prepare_data %>% + filter(year_cohort %in% cohort_levels) + warning("Data has more than 9 birth cohorts; keeping only the 9 latest cohorts for plotting.") + } + + prepare_data <- prepare_data %>% + mutate(year_cohort = factor(year_cohort, levels = cohort_levels)) + + # get max coverage in data + coverage_max <- max(prepare_data$coverage, na.rm = TRUE) + coverage_max <- ceiling(coverage_max * 10) / 10 # round to tenth above + coverage_max <- max(100, coverage_max) # make sure its always at least 100 + + # do plot + if(ADM_detected == 0) { + p <- ggplot(prepare_data, aes(x = "ADM0", y = coverage, fill = year_cohort)) + } else { + p <- ggplot( + prepare_data, + aes(x = reorder(!!sym(geo_column), -coverage), y = coverage, fill = year_cohort) + ) + } + + p <- p + + geom_col(position = "dodge") + + labs( + title = paste0("Birth Cohort Coverage, ", vaccine), + x = "Geographic Area", + y = "Coverage (%)" + ) + + scale_y_continuous(breaks = seq(0, coverage_max, 25), limits = c(0, coverage_max)) + + scale_fill_brewer(palette = palette) + + theme_classic() + + theme( + axis.text.x = element_text(angle = 90, vjust = 0.5, hjust = 1), + legend.title = element_blank() + ) + + return(p) +} diff --git a/R/validation.R b/R/validation.R index 5076076..c4a44d0 100644 --- a/R/validation.R +++ b/R/validation.R @@ -162,6 +162,24 @@ } } +#' Validate input data to bc_barplot. +#' +#' @keywords internal +#' @noRd +.validate_bc_barplot_data <- function(data) { + if(!is.data.frame(data)) { + stop("Error: data should be a data frame.") + } + + minimum_columns <- c( + "dose", "year_cohort", "numerator", "population", "coverage" + ) + + if(!all(minimum_columns %in% names(data))) { + stop("Error: data should be the output from bc_coverage.") + } +} + #' Validate input data to cs_barplot. #' #' @keywords internal diff --git a/man/bc_barplot.Rd b/man/bc_barplot.Rd new file mode 100644 index 0000000..52a91b5 --- /dev/null +++ b/man/bc_barplot.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/bc_barplot.R +\name{bc_barplot} +\alias{bc_barplot} +\title{(B)irth (C)ohort Coverage Bar Plot} +\usage{ +bc_barplot( + data, + vaccine, + birth_cohorts = NULL, + within_ADM1 = NULL, + palette = "YlOrBr" +) +} +\arguments{ +\item{data}{The output from the \code{pahoabc::bc_coverage} function.} + +\item{vaccine}{A string specifying the vaccine of interest. Only one vaccine.} + +\item{birth_cohorts}{Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be plotted. If \code{NULL} (default), all years are plotted.} + +\item{within_ADM1}{Character (optional). When analyzing data at the "ADM2" level, this optional character vector lets you specify one or several "ADM1" to filter. Default is \code{NULL}, which means no filtering by "ADM1".} + +\item{palette}{Character (optional). A RColorBrewer palette name for the cohort colors. Default is \code{"YlOrBr"}.} +} +\value{ +A ggplot object representing the bar plot. +} +\description{ +Generates a bar plot of birth cohort coverage, grouped by geographic area and colored by birth cohort year. +} From dcc980aff854ee3ada770456c85372c404ca7d49 Mon Sep 17 00:00:00 2001 From: danalvarez Date: Thu, 29 Jan 2026 18:13:33 -0600 Subject: [PATCH 3/5] Improved documentation --- R/bc_barplot.R | 4 ++-- R/bc_coverage.R | 14 +++++++------- man/bc_barplot.Rd | 4 ++-- man/bc_coverage.Rd | 10 +++++----- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/R/bc_barplot.R b/R/bc_barplot.R index 5ad676c..b9a3c7d 100644 --- a/R/bc_barplot.R +++ b/R/bc_barplot.R @@ -2,8 +2,8 @@ #' #' Generates a bar plot of birth cohort coverage, grouped by geographic area and colored by birth cohort year. #' -#' @param data The output from the \code{pahoabc::bc_coverage} function. -#' @param vaccine A string specifying the vaccine of interest. Only one vaccine. +#' @param data Data frame. The output from the \code{pahoabc::bc_coverage} function. +#' @param vaccine Character. A string specifying the vaccine of interest. Only one vaccine. #' @param birth_cohorts Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be plotted. If \code{NULL} (default), all years are plotted. #' @param within_ADM1 Character (optional). When analyzing data at the "ADM2" level, this optional character vector lets you specify one or several "ADM1" to filter. Default is \code{NULL}, which means no filtering by "ADM1". #' @param palette Character (optional). A RColorBrewer palette name for the cohort colors. Default is \code{"YlOrBr"}. diff --git a/R/bc_coverage.R b/R/bc_coverage.R index 298809a..0924049 100644 --- a/R/bc_coverage.R +++ b/R/bc_coverage.R @@ -2,13 +2,13 @@ #' #' This function calculates the coverage by birth cohort, further disagreggating by geographic level, using data from the electronic immunization registry (EIR). #' -#' @param data.EIR A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure. -#' @param data.schedule A data frame defining the vaccination schedule. See \code{pahoabc.schedule} for expected structure. -#' @param geo_level The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0". Note also that if \code{data.pop} is in use, it must contain the columns to match. +#' @param data.EIR Data frame. A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure. +#' @param data.schedule Data frame. A data frame defining the vaccination schedule. See \code{pahoabc.schedule} for expected structure. +#' @param geo_level Character. The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0". Note also that if \code{data.pop} is in use, it must contain the columns to match. #' @param vaccines Character (optional). A character vector specifying the doses to include in the analysis. If \code{NULL} (default), all vaccines in \code{data.EIR} are included. #' @param birth_cohorts Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be calculated. If \code{NULL} (default), coverage is calculated for all available cohorts. #' @param data.pop Data frame (optional). A data frame with population denominators. See \code{pahoabc.pop.ADMX} for structure examples. If \code{NULL} (default), the denominator is taken from \code{data.EIR} for each year and \code{geo_level}. -#' @param only_valid_doses Logical (optional). If \code{TRUE} (default), only count vaccinations that occurred within the valid age window defined by \code{age_schedule_low} and \code{age_schedule_high}. If \code{FALSE}, do not filter by age at vaccination. +#' @param validate_doses Logical (optional). If \code{TRUE} (default), only count vaccinations that occurred within the valid age window defined by \code{age_schedule_low} and \code{age_schedule_high}. If \code{FALSE}, does not validate doses before counting them. #' #' @return A data frame containing the coverage by birth cohort for the specified \code{geo_level}. #' @@ -16,7 +16,7 @@ #' @import lubridate #' #' @export -bc_coverage <- function(data.EIR, data.schedule, geo_level = "ADM0", vaccines = NULL, birth_cohorts = NULL, data.pop = NULL, only_valid_doses = TRUE) { +bc_coverage <- function(data.EIR, data.schedule, geo_level = "ADM0", vaccines = NULL, birth_cohorts = NULL, data.pop = NULL, validate_doses = TRUE) { # validations .validate_geo_level(geo_level) @@ -26,7 +26,7 @@ bc_coverage <- function(data.EIR, data.schedule, geo_level = "ADM0", vaccines = .validate_numeric(birth_cohorts, "birth_cohorts", min_len = 1) .validate_data.pop(data.pop, geo_level) .validate_vaccines(vaccines, data.schedule, "data.schedule") - .validate_logical(only_valid_doses, "only_valid_doses") + .validate_logical(validate_doses, "validate_doses") # determine grouping column(s) basic_groups <- c("year_cohort") @@ -71,7 +71,7 @@ bc_coverage <- function(data.EIR, data.schedule, geo_level = "ADM0", vaccines = ) %>% left_join(prepare_schedule, by = "dose") - if(only_valid_doses) { + if(validate_doses) { prepare_EIR <- prepare_EIR %>% filter( age_at_vax >= age_schedule_low, diff --git a/man/bc_barplot.Rd b/man/bc_barplot.Rd index 52a91b5..d0086da 100644 --- a/man/bc_barplot.Rd +++ b/man/bc_barplot.Rd @@ -13,9 +13,9 @@ bc_barplot( ) } \arguments{ -\item{data}{The output from the \code{pahoabc::bc_coverage} function.} +\item{data}{Data frame. The output from the \code{pahoabc::bc_coverage} function.} -\item{vaccine}{A string specifying the vaccine of interest. Only one vaccine.} +\item{vaccine}{Character. A string specifying the vaccine of interest. Only one vaccine.} \item{birth_cohorts}{Numeric (optional). A vector specifying the birth cohort(s) for which coverage should be plotted. If \code{NULL} (default), all years are plotted.} diff --git a/man/bc_coverage.Rd b/man/bc_coverage.Rd index 888caf4..77f7e45 100644 --- a/man/bc_coverage.Rd +++ b/man/bc_coverage.Rd @@ -11,15 +11,15 @@ bc_coverage( vaccines = NULL, birth_cohorts = NULL, data.pop = NULL, - only_valid_doses = TRUE + validate_doses = TRUE ) } \arguments{ -\item{data.EIR}{A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.} +\item{data.EIR}{Data frame. A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.} -\item{data.schedule}{A data frame defining the vaccination schedule. See \code{pahoabc.schedule} for expected structure.} +\item{data.schedule}{Data frame. A data frame defining the vaccination schedule. See \code{pahoabc.schedule} for expected structure.} -\item{geo_level}{The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0". Note also that if \code{data.pop} is in use, it must contain the columns to match.} +\item{geo_level}{Character. The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0". Note also that if \code{data.pop} is in use, it must contain the columns to match.} \item{vaccines}{Character (optional). A character vector specifying the doses to include in the analysis. If \code{NULL} (default), all vaccines in \code{data.EIR} are included.} @@ -27,7 +27,7 @@ bc_coverage( \item{data.pop}{Data frame (optional). A data frame with population denominators. See \code{pahoabc.pop.ADMX} for structure examples. If \code{NULL} (default), the denominator is taken from \code{data.EIR} for each year and \code{geo_level}.} -\item{only_valid_doses}{Logical (optional). If \code{TRUE} (default), only count vaccinations that occurred within the valid age window defined by \code{age_schedule_low} and \code{age_schedule_high}. If \code{FALSE}, do not filter by age at vaccination.} +\item{validate_doses}{Logical (optional). If \code{TRUE} (default), only count vaccinations that occurred within the valid age window defined by \code{age_schedule_low} and \code{age_schedule_high}. If \code{FALSE}, does not validate doses before counting them.} } \value{ A data frame containing the coverage by birth cohort for the specified \code{geo_level}. From d2b14ae22fafa55471c61653fe53dfbc4a0553ff Mon Sep 17 00:00:00 2001 From: danalvarez Date: Thu, 12 Feb 2026 17:43:35 -0600 Subject: [PATCH 4/5] Add vignette for birth cohort coverage (#24) --- _pkgdown.yml | 4 + vignettes/bc_workflow.svg | 4 + vignettes/birth_cohort_coverage_en.Rmd | 154 +++++++++++++++++++++++++ 3 files changed, 162 insertions(+) create mode 100644 vignettes/bc_workflow.svg create mode 100644 vignettes/birth_cohort_coverage_en.Rmd diff --git a/_pkgdown.yml b/_pkgdown.yml index 38873b4..705588f 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -20,6 +20,8 @@ navbar: href: articles/residence_occurrence_en.html - text: Complete Schedule Coverage href: articles/complete_schedule_en.html + - text: Birth Cohort Coverage + href: articles/birth_cohort_coverage_en.html - text: ------- - text: Other guides - text: Using our Example Datasets @@ -45,6 +47,8 @@ reference: - roc_distribution - roc_heatmap - roc_coverage_by + - bc_coverage + - bc_barplot - title: Complete Schedule Coverage desc: Functions for calculating and visualizing complete schedule coverage. diff --git a/vignettes/bc_workflow.svg b/vignettes/bc_workflow.svg new file mode 100644 index 0000000..7ebbb81 --- /dev/null +++ b/vignettes/bc_workflow.svg @@ -0,0 +1,4 @@ + + + +
Table
Table
Plot
Plot
bc_coverage()
bc_coverage()
EIR
EIR
schedule
schedule
bc_barplot()
bc_barplot()
Analyze
Analyze
Analyze
Analyze
\ No newline at end of file diff --git a/vignettes/birth_cohort_coverage_en.Rmd b/vignettes/birth_cohort_coverage_en.Rmd new file mode 100644 index 0000000..2774183 --- /dev/null +++ b/vignettes/birth_cohort_coverage_en.Rmd @@ -0,0 +1,154 @@ +--- +title: "Birth Cohort Coverage" +author: "PAHO/CIM" +date: "February 12, 2026" +output: + html_document: + self_contained: true + theme: cosmo + highlight: tango + code_folding: show + code_download: true + toc: true + toc_depth: 2 +--- + +```{r setup, include = FALSE, message = FALSE, warning = FALSE} +library(pahoabc) +library(dplyr) +library(knitr) +``` + +# Rationale + +The objective of this indicator is to monitor a specific birth cohort of newborns to determine their vaccination status and estimate the level of population protection against vaccine-preventable diseases. This analysis is essential for preventing the accumulation of susceptible individuals, maximizing herd immunity, and developing targeted vaccination strategies for those who have not received the necessary doses. + +Vaccination coverage by birth cohort is calculates using the following formula: + +$$ +\text{Coverage by birth cohort (\%)} = +\frac{\text{# of vaccines administered to people in a specific birth cohort}}{\text{Total people in the specific birth cohort}} \times 100 +$$ + +> **Note** +> +> All functions used for complete schedule coverage analyses within PAHOabc begin with the `bc_` prefix. + +# Glossary + +# Usage + +## Install Package + +The first step to run the birth cohort coverage analyses is to install the PAHOabc package available on GitHub. + +```{r, install_package, eval=FALSE} +devtools::install_github("IM-Data-PAHO/pahoabc") +``` + +## Load Data + +The functions in this module require you to provide three datasets in a specific format. + +1. Your EIR. +2. The vaccination schedule related to this EIR. +3. Optionally, a table with population denominators at the same geographic level of disaggregation as your analysis. + +To make it easy for you to test out PAHOabc's functionality and understand the structure we require for your datasets, we will now explore the example datasets provided by PAHOabc that are required by this module. + +### EIR + +The `pahoabc::pahoabc.EIR` data frame provides a simulated, nominal-level table representing individual vaccination events from an Electronic Immunization Registry (EIR). Each row corresponds to a single vaccination act for a person, including information on their residence, where they were vaccinated (occurrence), their date of birth, and the vaccine dose received. + +```{r pahoabc-EIR, message=FALSE} +pahoabc.EIR %>% head() %>% kable(caption = "Example Electronic Immunization Registry") +``` + +- `ID`: Unique person identification number. +- `date_birth`: Date of birth of person. +- `date_vax`: Date of vaccination event. +- ADM1: Refers to the first geographic administrative level of the country. +- ADM2: Refers to the second geographic administrative level of the country. +- Residence: Refers to the place where the person lives. +- Occurrence: Refers to the place where the vaccination event occurred. +- `dose`: A combined variable representing the vaccine type and its corresponding dose number. For example, DTP1 refers to the first dose of a vaccine containing diphtheria, tetanus, and pertussis components. + +### Vaccination Schedule + +The `pahoabc::pahoabc.schedule` dataset defines the national immunization schedule, listing each vaccine dose and its recommended age of administration (in days). It helps the package determine whether an individual is up to date with their vaccinations. + +```{r pahoabc-schedule, message=FALSE} +pahoabc.schedule %>% kable(caption = "Example Immunization Schedule") +``` + +- `dose`: A combined variable representing the vaccine type and its corresponding dose number. For example, DTP1 refers to the first dose of a vaccine containing diphtheria, tetanus, and pertussis components. +- `age_schedule`: The recommended age of administration of the corresponding `dose` in days. +- `age_schedule_low`: The lower limit for the target age in days. +- `age_schedule_high`: The upper limit for the target age in days. + +> **Note** +> +> The `dose` names must match exactly those in the `dose` column of the `pahoabc.EIR` dataset. + +### Population Denominators + +While not mandatory, this module will lets you provide a population table to use as denominator for the coverage calculation. The geographic level of this table will be directly dependent on the geographic level of your analysis. For example, if you were to perform an analysis at ADM1 level, the required population denominator table must contain the following. + +```{r pahoabc-pop-ADM1, message=FALSE} +pahoabc.pop.ADM1 %>% head() %>% kable(caption = "Example Population at ADM1") +``` + +Note that this table is in long format and contains the `population` of children of a specific `age` during a given `year` for a certain `ADM1` level. + +> **Note** +> +> Please take into account that since this analysis is performed with birth cohorts, only the rows with `age`=0 are of interest in the population table, since these represent the number of children that belong to that specific birth cohort (year). + +## Birth cohort coverage analysis + +This module lets users estimate the vaccination coverage by birth cohort. This allows for the analysis of any vaccine among a specific birth cohort. For correct interpretation, you must take into account that it represents the percentage of people vaccinated among a specific year of birth, regardless of the year in which they were vaccinated, so it could be different from the administrative coverage of a particular year. Additionally, it allows users to select the level of aggregation for the results, which can be at the national level or subnational levels (`ADM1` or `ADM2`). + +### Expected Workflow + +The `bc_coverage()` and `bc_barplot()` functions provide a way of analyzing and visualizing coverage by birth cohort. Their relationships are shown in Figure 1. + +![Figure 1. Expected workflow for the birth cohort coverage analysis.](bc_workflow.svg) + +
+ +### Example + +Here is a simple use case of the `bc_coverage()` function, where we use our example dataset to compute vaccination coverage for the first dose of the measles-containing vaccine, for the 2022 birth year cohort. + +```{r cov-analysis-example, message=FALSE} + +# compute coverage +coverage_df <- bc_coverage( + data.EIR = pahoabc.EIR, + data.schedule = pahoabc.schedule, + geo_level = "ADM1", + vaccines = "SRP1", # this can be a vector of vaccines + birth_cohorts = 2022 # this can be a vector of years +) + +# show results in table +coverage_df %>% + kable(digits = 2, caption = "Coverage by birth cohort by ADM1 level") +``` + +We can visually observe these results by calling the `bc_barplot()` function as shown below. + +```{r cov-viz-example, message=FALSE, fig.width=12, fig.height=6} + +# visualize output from cs_coverage() +coverage_plot <- bc_barplot(data = coverage_df, vaccine = "SRP1") + +# show +coverage_plot +``` + +A review of the different subnational levels reveals a significant disparity: the `ADM1_4` region records the best performance in vaccination (~47%), while the `ADM1_2` area exhibits the poorest result (~25%). + +# Summary + +By incorporating vaccination coverage based on birth cohort, PAHOabc enables public health officials to accurately assess the immunity level of specific population groups within a given territory. This deep, cohort-specific insight is essential for effective strategic planning, including the execution of measles and rubella follow-up campaigns and the development of targeted HPV vaccine catch-up strategies. From 3906630cb9de613c4f4962ed378c849afe67bb6d Mon Sep 17 00:00:00 2001 From: danalvarez Date: Thu, 12 Feb 2026 17:43:54 -0600 Subject: [PATCH 5/5] Fix typo in complete schedule vignette (closes #14) --- vignettes/complete_schedule_en.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vignettes/complete_schedule_en.Rmd b/vignettes/complete_schedule_en.Rmd index 0baf0b5..6e3d3f9 100644 --- a/vignettes/complete_schedule_en.Rmd +++ b/vignettes/complete_schedule_en.Rmd @@ -69,7 +69,7 @@ For example, the vaccine names used in the PAHOabc package are: ## Install Package -The first step to run the residence occurrence analyses is to install the PAHOabc package available on GitHub. +The first step to run the complete schedule coverage analyses is to install the PAHOabc package available on GitHub. ```{r, install_package, eval=FALSE} devtools::install_github("IM-Data-PAHO/pahoabc")