Skip to content
Merged
2 changes: 1 addition & 1 deletion DESCRIPTION
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Description: A set of immunization analyses beyond coverage.
License: PAHO/CIM Open Source License
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.2
RoxygenNote: 7.3.3
Depends:
R (>= 3.5)
Suggests:
Expand Down
4 changes: 4 additions & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@ export(bc_coverage)
export(cs_barplot)
export(cs_coverage)
export(cs_upsetplot)
export(dcc_barplot)
export(dcc_inconsistent)
export(dcc_inconsistent_plot)
export(dcc_rate)
export(nod_barplot)
export(nod_dropout)
export(roc_barplot)
Expand Down
75 changes: 75 additions & 0 deletions R/dcc_barplot.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
#' (D)ate (C)onsistency (C)omparison Barplot
#'
#' Generates a bar plot of date consistencies, grouped by geographic area and colored by consistency result.
#'
#' @param data The output from the \code{pahoabc::dcc_rate} function.
#' @param date_1_name Character. Label for the first date variable, used in the plot subtitle.
#' @param date_2_name Character. Label for the second date variable, used in the plot subtitle.
#' @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 plot_missing Boolean (default TRUE). Plots DATE_MISSING records as its own category. Defaults to TRUE so all bars add to 100
#' @return A ggplot object representing the bar plot.
#'
#' @import dplyr
#' @import ggplot2
#'
#' @export
dcc_barplot <- function(data, date_1_name = "date 1", date_2_name = "date 2", within_ADM1 = NULL, plot_missing = TRUE) {

.validate_dcc_barplot_data(data)
.validate_character(within_ADM1, "within_ADM1", min_len = 1)

# detect geo level
ADM_detected <- .detect_geo_level(data)

# prepare data for plot
prepare_data <- data %>%
filter(if(!is.null(within_ADM1)) {ADM1 %in% within_ADM1} else {TRUE})

# Extract number of missing values for caption
n_missing <- prepare_data %>%
filter(consistency == "DATE_MISSING") %>%
ungroup() %>%
summarise(n = sum(n)) %>%
pull(n)


prepare_data <- prepare_data %>%
mutate(consistency = factor(consistency, levels = c("DATE_MISSING", "INCONSISTENT", "CONSISTENT"))) %>%
filter(if(plot_missing == FALSE){consistency != "DATE_MISSING"} else {TRUE})



# do plot
if(ADM_detected == 0) {
p <- ggplot(prepare_data, aes(x = "ADM0", y = rate, fill = consistency))
} else {
p <- ggplot(
prepare_data,
aes(
x = factor(
!!sym(paste0("ADM", ADM_detected)),
levels = sort(unique(prepare_data[[paste0("ADM", ADM_detected)]]))
),
y = rate, fill = consistency)
)
}

p <- p + geom_col(position = "stack") +
labs(
title = "Date consistency comparison",
subtitle = paste0(date_1_name, " vs ", date_2_name),
x = "Geographic Area",
y = "Rate (%)",
caption = paste0("Number of records with at least one date missing: ", n_missing)
) +
scale_y_continuous(limits = c(0, 100.9),n.breaks = 5) +
scale_fill_manual(values = c("CONSISTENT"="#9cdbf4", "INCONSISTENT" = "#fabf7b", "DATE_MISSING" = "#838383")) +
theme_classic() +
theme(
axis.text.x = element_text(angle = 90, vjust = 0.5, hjust = 1),
legend.title = element_blank(),
panel.border = element_rect(fill = NA)
)

return(p)
}
34 changes: 34 additions & 0 deletions R/dcc_inconsistent.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
#' (D)ate (C)onsistency (C)omparison Inconsistent Records
#'
#' This function returns a record-level table of all inconsistent and "date missing" entries, including the day difference between the two dates.
#'
#' @param data.EIR Data frame. A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.
#' @param date_1 Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking for consistency.
#' @param date_2 Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking consistency against. Represents a date chronologically earlier than date_1.
#'
#' @return A data frame containing the inconsistent records in the database and the time diferential between them.
#'
#' @import dplyr
#' @import lubridate
#'
#' @export
dcc_inconsistent <- function(data.EIR, date_1, date_2) {

# validations
.validate_data.EIR(data.EIR, indicator = "dcc")
.validate_date(data.EIR[[date_1]], date_1)
.validate_date(data.EIR[[date_2]], date_2)

# Calculates the dcc_inconsistent
dcc_inconsistent <- data.EIR %>%
# Detects inconsistencies, also counts missing dates
mutate(consistency = case_when(.data[[date_2]] > .data[[date_1]] ~ "INCONSISTENT",
is.na(.data[[date_2]]) | is.na(.data[[date_1]]) ~ "DATE_MISSING",
TRUE ~ "CONSISTENT")) %>%
filter(consistency %in% c("INCONSISTENT", "DATE_MISSING")) %>%
mutate(diff = .data[[date_1]] - .data[[date_2]]) %>%
select(ID, dose, all_of(c(date_2, date_1)), consistency, diff)

#Returns summary table
return(dcc_inconsistent)
}
75 changes: 75 additions & 0 deletions R/dcc_inconsistent_plot.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
#' (D)ate (C)onsistency (C)omparison Inconsistent Records Plot
#'
#' Generates a histogram of absolute day differences for inconsistent records,
#' binned into customizable intervals with a final open-ended category.
#'
#' @param data.EIR Data frame. A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.
#' @param date_1 Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking for consistency.
#' @param date_2 Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking consistency against. Represents a date chronologically earlier than date_1.
#' @param date_1_name Character. Label for the first date variable, used in the plot subtitle. Default is \code{"date 1"}.
#' @param date_2_name Character. Label for the second date variable, used in the plot subtitle. Default is \code{"date 2"}.
#' @param day_groups List of numeric vectors of length 2. Each element is a \code{c(lower, upper)} pair defining a bin. The last bin is extended to \code{Inf} and labelled \code{"X+"}. Default is 10-day bins from 0 to 100.
#'
#' @return A ggplot object representing the histogram.
#'
#' @import dplyr
#' @import ggplot2
#'
#' @export
dcc_inconsistent_plot <- function(
data.EIR,
date_1,
date_2,
date_1_name = "date 1",
date_2_name = "date 2",
day_groups = list(
c(0, 10), c(10, 20), c(20, 30), c(30, 40), c(40, 50),
c(50, 60), c(60, 70), c(70, 80), c(80, 90), c(90, 100)
)
) {

.validate_data.EIR(data.EIR, indicator = "dcc")
.validate_date(data.EIR[[date_1]], date_1)
.validate_date(data.EIR[[date_2]], date_2)

plot_data <- data.EIR %>%
mutate(
consistency = case_when(
.data[[date_2]] > .data[[date_1]] ~ "INCONSISTENT",
is.na(.data[[date_2]]) | is.na(.data[[date_1]]) ~ "DATE_MISSING",
TRUE ~ "CONSISTENT"
)
)

n_missing <- sum(plot_data$consistency == "DATE_MISSING")

interval_labels <- sapply(day_groups, function(g) paste0(g[1], "-", g[2] - 1))
interval_labels[length(interval_labels)] <- paste0(day_groups[[length(day_groups)]][1], "+")
breaks <- c(sapply(day_groups, `[`, 1), Inf)
labels <- interval_labels

plot_data <- plot_data %>%
filter(consistency == "INCONSISTENT") %>%
mutate(
delta_abs = as.numeric(abs(.data[[date_1]] - .data[[date_2]])),
delta_cat = cut(delta_abs, breaks = breaks, labels = labels, right = FALSE, include.lowest = TRUE)
)

ggplot(plot_data, aes(x = delta_cat)) +
geom_bar(fill = "#fabf7b", color = "white") +
labs(
title = "Inconsistent records by day difference",
subtitle = paste0(date_1_name, " vs ", date_2_name),
x = "Absolute day difference (regardless of direction)",
y = "Number of records",
caption = paste0(
"Absolute value of days between dates — negative and positive differences treated equally.\n",
"Number of records with at least one date missing: ", n_missing
)
) +
theme_classic() +
theme(
axis.text.x = element_text(angle = 45, vjust = 1, hjust = 1),
panel.border = element_rect(fill = NA)
)
}
54 changes: 54 additions & 0 deletions R/dcc_rate.R
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
#' (D)ate (C)onsistency (C)omparison Rate
#'
#' This function calculates the rate of consistency between two date variables, further disaggregating 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 date_1 Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking for consistency.
#' @param date_2 Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking consistency against. Represents a date chronologically earlier than date_1.
#' @param geo_level Character. The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0".
#'
#' @return A data frame containing the consistency rate and inconsistency rate (inverse proportion) in percentages for the specified \code{geo_level}.
#'
#' @import dplyr
#' @import lubridate
#'
#' @export
dcc_rate <- function(data.EIR, date_1, date_2, geo_level = "ADM0") {

# validations
.validate_data.EIR(data.EIR, indicator = "dcc")
.validate_geo_level(geo_level)
.validate_date(data.EIR[[date_1]], date_1)
.validate_date(data.EIR[[date_2]], date_2)

#Prepare EIR
data.EIR = data.EIR %>%
rename(ADM1 = ADM1_residence, ADM2 =ADM2_residence)

# Selects group columns for geo_level
group_cols <- if (geo_level == "ADM1") {
"ADM1"
} else if (geo_level == "ADM2") {
c("ADM1", "ADM2")
} else {
character(0)
}
# Calculates the dcc_rate
dcc_rate <- data.EIR %>%
# Detects inconsistencies, also counts missing dates
mutate(consistency = case_when(.data[[date_2]] > .data[[date_1]] ~ "INCONSISTENT",
is.na(.data[[date_2]]) | is.na(.data[[date_1]]) ~ "DATE_MISSING",
TRUE ~ "CONSISTENT")) %>%
# Groups by geo_level depending on choice of variables
group_by(across(all_of(group_cols))) %>%
#Counts consistency
count(consistency) %>%
# Totals and rates across groups (grouping preserved by count)
mutate(
total = sum(n),
rate = n / total * 100
)

#Returns summary table
return(dcc_rate)
}
39 changes: 34 additions & 5 deletions R/validation.R
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,24 @@
}
}

#' Validate input data to dcc_barplot.
#'
#' @keywords internal
#' @noRd
.validate_dcc_barplot_data <- function(data) {
if(!is.data.frame(data)) {
stop("Error: data should be a data frame.")
}

minimum_columns <- c(
"consistency", "n", "total", "rate"
)

if(!all(minimum_columns %in% names(data))) {
stop("Error: data should be the output from dcc_rate")
}
}

#' Validate input data to roc_heatmap.
#'
#' @keywords internal
Expand Down Expand Up @@ -262,11 +280,18 @@
#'
#' @keywords internal
#' @noRd
.validate_data.EIR <- function(data.EIR, data.schedule = NULL) {
.validate_data.EIR <- function(data.EIR, data.schedule = NULL, indicator = NULL) {
if(!is.data.frame(data.EIR)) {
stop("Error: data.EIR should be a data frame.")
}

if(!is.null(indicator) && indicator == "dcc"){
required_columns <- c(
"ID",
"ADM1_residence",
"ADM2_residence",
"dose"
)
} else {
required_columns <- c(
"ID",
"date_birth",
Expand All @@ -276,11 +301,15 @@
"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.")
}
stop(paste0(
"Error: data.EIR should contain the following columns: ",
paste(required_columns, collapse = ", "), "."
))
}

if(!is.null(data.schedule)) {
missing_in_schedule <- setdiff(unique(data.EIR$dose), unique(data.schedule$dose))
Expand Down
10 changes: 10 additions & 0 deletions _pkgdown.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ navbar:
href: articles/complete_schedule_en.html
- text: Birth Cohort Coverage
href: articles/birth_cohort_coverage_en.html
- text: Date Consistency Comparison
href: articles/date_consistency_comparison_en.html
- text: -------
- text: Other guides
- text: Using our Example Datasets
Expand All @@ -33,6 +35,14 @@ authors:
href: "https://www.paho.org/en"

reference:
- title: Date Consistency Comparison
desc: Functions for identifying and visualizing date inconsistencies in the EIR.
contents:
- dcc_rate
- dcc_barplot
- dcc_inconsistent
- dcc_inconsistent_plot

- title: Nominal Dropout Rate
desc: Functions for calculating and visualizing nominal dropout rate.
contents:
Expand Down
31 changes: 31 additions & 0 deletions man/dcc_barplot.Rd

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

Loading
Loading