Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Generated by roxygen2: do not edit by hand

export(bc_barplot)
export(bc_coverage)
export(cs_barplot)
export(cs_coverage)
export(cs_upsetplot)
Expand Down
82 changes: 82 additions & 0 deletions R/bc_barplot.R
Original file line number Diff line number Diff line change
@@ -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 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"}.
#'
#' @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)
}
128 changes: 128 additions & 0 deletions R/bc_coverage.R
Original file line number Diff line number Diff line change
@@ -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 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 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}.
#'
#' @import dplyr
#' @import lubridate
#'
#' @export
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)
.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(validate_doses, "validate_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(validate_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)
}
3 changes: 2 additions & 1 deletion R/cs_coverage.R
Original file line number Diff line number Diff line change
Expand Up @@ -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}.
#'
Expand Down Expand Up @@ -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)
}
Expand Down
56 changes: 56 additions & 0 deletions R/validation.R
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -239,3 +257,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 = ", "),
"."
)
)
}
}
}
4 changes: 4 additions & 0 deletions _pkgdown.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down
31 changes: 31 additions & 0 deletions man/bc_barplot.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

37 changes: 37 additions & 0 deletions man/bc_coverage.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading