diff --git a/DESCRIPTION b/DESCRIPTION index 3d773e6..b04e1c9 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -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: diff --git a/NAMESPACE b/NAMESPACE index 7dc90a0..a501c1a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -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) diff --git a/R/dcc_barplot.R b/R/dcc_barplot.R new file mode 100644 index 0000000..f3c00c2 --- /dev/null +++ b/R/dcc_barplot.R @@ -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) +} diff --git a/R/dcc_inconsistent.R b/R/dcc_inconsistent.R new file mode 100644 index 0000000..56a51ea --- /dev/null +++ b/R/dcc_inconsistent.R @@ -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) +} \ No newline at end of file diff --git a/R/dcc_inconsistent_plot.R b/R/dcc_inconsistent_plot.R new file mode 100644 index 0000000..c08fc7a --- /dev/null +++ b/R/dcc_inconsistent_plot.R @@ -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) + ) +} diff --git a/R/dcc_rate.R b/R/dcc_rate.R new file mode 100644 index 0000000..1447129 --- /dev/null +++ b/R/dcc_rate.R @@ -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) +} \ No newline at end of file diff --git a/R/validation.R b/R/validation.R index c4a44d0..450eb8b 100644 --- a/R/validation.R +++ b/R/validation.R @@ -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 @@ -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", @@ -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)) diff --git a/_pkgdown.yml b/_pkgdown.yml index 49c6344..e829948 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -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 @@ -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: diff --git a/man/dcc_barplot.Rd b/man/dcc_barplot.Rd new file mode 100644 index 0000000..0592ffa --- /dev/null +++ b/man/dcc_barplot.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/dcc_barplot.R +\name{dcc_barplot} +\alias{dcc_barplot} +\title{(D)ate (C)onsistency (C)omparison Barplot} +\usage{ +dcc_barplot( + data, + date_1_name = "date 1", + date_2_name = "date 2", + within_ADM1 = NULL, + plot_missing = TRUE +) +} +\arguments{ +\item{data}{The output from the \code{pahoabc::dcc_rate} function.} + +\item{date_1_name}{Character. Label for the first date variable, used in the plot subtitle.} + +\item{date_2_name}{Character. Label for the second date variable, used in the plot subtitle.} + +\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{plot_missing}{Boolean (default TRUE). Plots DATE_MISSING records as its own category. Defaults to TRUE so all bars add to 100} +} +\value{ +A ggplot object representing the bar plot. +} +\description{ +Generates a bar plot of date consistencies, grouped by geographic area and colored by consistency result. +} diff --git a/man/dcc_inconsistent.Rd b/man/dcc_inconsistent.Rd new file mode 100644 index 0000000..90fccc8 --- /dev/null +++ b/man/dcc_inconsistent.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/dcc_inconsistent.R +\name{dcc_inconsistent} +\alias{dcc_inconsistent} +\title{(D)ate (C)onsistency (C)omparison Inconsistent Records} +\usage{ +dcc_inconsistent(data.EIR, date_1, date_2) +} +\arguments{ +\item{data.EIR}{Data frame. A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.} + +\item{date_1}{Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking for consistency.} + +\item{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.} +} +\value{ +A data frame containing the inconsistent records in the database and the time diferential between them. +} +\description{ +This function returns a record-level table of all inconsistent and "date missing" entries, including the day difference between the two dates. +} diff --git a/man/dcc_inconsistent_plot.Rd b/man/dcc_inconsistent_plot.Rd new file mode 100644 index 0000000..0a1461d --- /dev/null +++ b/man/dcc_inconsistent_plot.Rd @@ -0,0 +1,36 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/dcc_inconsistent_plot.R +\name{dcc_inconsistent_plot} +\alias{dcc_inconsistent_plot} +\title{(D)ate (C)onsistency (C)omparison Inconsistent Records Plot} +\usage{ +dcc_inconsistent_plot( + 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)) +) +} +\arguments{ +\item{data.EIR}{Data frame. A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.} + +\item{date_1}{Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking for consistency.} + +\item{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.} + +\item{date_1_name}{Character. Label for the first date variable, used in the plot subtitle. Default is \code{"date 1"}.} + +\item{date_2_name}{Character. Label for the second date variable, used in the plot subtitle. Default is \code{"date 2"}.} + +\item{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.} +} +\value{ +A ggplot object representing the histogram. +} +\description{ +Generates a histogram of absolute day differences for inconsistent records, +binned into customizable intervals with a final open-ended category. +} diff --git a/man/dcc_rate.Rd b/man/dcc_rate.Rd new file mode 100644 index 0000000..865290c --- /dev/null +++ b/man/dcc_rate.Rd @@ -0,0 +1,23 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/dcc_rate.R +\name{dcc_rate} +\alias{dcc_rate} +\title{(D)ate (C)onsistency (C)omparison Rate} +\usage{ +dcc_rate(data.EIR, date_1, date_2, geo_level = "ADM0") +} +\arguments{ +\item{data.EIR}{Data frame. A data frame containing individual vaccination records. See \code{pahoabc.EIR} for expected structure.} + +\item{date_1}{Character. The name of a DATE formatted variable present in the EIR. This variable is the date we are checking for consistency.} + +\item{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.} + +\item{geo_level}{Character. The geographic level to aggregate results by. Must be "ADM0", "ADM1" or "ADM2". If not specified, the default is "ADM0".} +} +\value{ +A data frame containing the consistency rate and inconsistency rate (inverse proportion) in percentages for the specified \code{geo_level}. +} +\description{ +This function calculates the rate of consistency between two date variables, further disaggregating by geographic level, using data from the electronic immunization registry (EIR). +} diff --git a/vignettes/date_consistency_comparison_en.Rmd b/vignettes/date_consistency_comparison_en.Rmd new file mode 100644 index 0000000..a37edd1 --- /dev/null +++ b/vignettes/date_consistency_comparison_en.Rmd @@ -0,0 +1,205 @@ +--- +title: "Date Consistency Comparison" +author: "PAHO/CIM" +date: "June 1, 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 + +Electronic Immunization Registries (EIRs) often contain date fields that are logically constrained relative to one another. A common example is the relationship between a vaccination date and a date of birth: a vaccination event cannot occur before a person is born. When such violations exist in the data, they indicate data entry errors or record linkage issues that can bias downstream analyses. + +The date consistency comparison module allows users to systematically identify, quantify, and visualize these inconsistencies between any two date variables in the EIR. + +> **Note** +> +> All functions used for date consistency comparison analyses within PAHOabc begin with the `dcc_` prefix. + +# Glossary + +## Political Geographic Boundaries + +Throughout this vignette, we will make reference to different levels of political geographic boundaries. These levels are defined by the country/territory and can have different names from country to country. PAHOabc is agnostic to these names and requires the user to recode their variable names to fit the PAHOabc structure. + +Namely, PAHOabc can distinguish three administrative levels, which listed from top to bottom level are: ADM0, ADM1 and ADM2. + +1. ADM0: The country. This is the top-most administrative level. +2. ADM1: The first geographic subdivision in the country. ADM0 contains several ADM1 subdivisions. +3. ADM2: The second geographic subdivision in the country. Each ADM1 contains several ADM2 subdivisions. + +## Consistency Categories + +| Category | Meaning | +|---|---| +| `CONSISTENT` | `date_2` ≤ `date_1` — the chronological order is valid. | +| `INCONSISTENT` | `date_2` > `date_1` — the chronological order is violated. | +| `DATE_MISSING` | At least one of the two dates is `NA`. | + +# Usage + +## Install Package + +```{r install_package, eval=FALSE} +devtools::install_github("IM-Data-PAHO/pahoabc") +``` + +## Load Data + +The functions in this module require your **EIR dataset** in the standard PAHOabc format. + +### 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. + +```{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_residence` / `ADM2_residence`: First and second geographic administrative levels of residence. +- `dose`: Combined variable representing vaccine type and dose number (e.g., DTP1). + +## Date Consistency Comparison Analysis + +### Expected Workflow + +The `dcc_` suite contains four functions that work together: + +1. `dcc_rate()` — computes consistency rates aggregated by geographic level. +2. `dcc_barplot()` — visualizes the output of `dcc_rate()` as a stacked bar chart. +3. `dcc_inconsistent()` — lists individual inconsistent and missing records with their day difference. +4. `dcc_inconsistent_plot()` — visualizes the distribution of day differences for inconsistent records. + +The figure below shows the expected workflow. + +![Figure 1. Expected workflow for the date consistency comparison analysis.](dcc_workflow.svg) + +### Step 1 — Compute consistency rates with `dcc_rate()` + +`dcc_rate()` compares two date variables in the EIR and returns, for each geographic unit, the count and percentage of records that are `CONSISTENT`, `INCONSISTENT`, or `DATE_MISSING`. + +Here we check whether `date_vax` (date_1, the later date) is consistent with `date_birth` (date_2, the earlier date) at the ADM1 level. + +```{r dcc-rate, message=FALSE} +rate_df <- dcc_rate( + data.EIR = pahoabc.EIR, + date_1 = "date_vax", + date_2 = "date_birth", + geo_level = "ADM1" +) + +rate_df %>% kable(digits = 2, caption = "Date consistency rates by ADM1") +``` + +#### Parameters accepted + +- `data.EIR`: EIR data frame in PAHOabc format. +- `date_1`: Name of the date variable being checked (the chronologically later date). +- `date_2`: Name of the date variable checked against (the chronologically earlier date). +- `geo_level`: `"ADM0"` (default), `"ADM1"`, or `"ADM2"`. + +### Step 2 — Visualize rates with `dcc_barplot()` + +The output of `dcc_rate()` can be passed directly to `dcc_barplot()` to produce a stacked bar chart showing the breakdown of consistency categories per geographic unit. + +```{r dcc-barplot, message=FALSE, fig.width=10, fig.height=5} +dcc_barplot( + data = rate_df, + date_1_name = "Vaccination date", + date_2_name = "Date of birth" +) +``` + +#### Parameters accepted + +- `data`: Output of `dcc_rate()`. +- `date_1_name`: Display label for `date_1` in the plot subtitle. Default: `"date 1"`. +- `date_2_name`: Display label for `date_2` in the plot subtitle. Default: `"date 2"`. +- `within_ADM1`: Character vector to filter to specific ADM1 units when `geo_level = "ADM2"`. Default: `NULL`. +- `plot_missing`: Boolean. If `TRUE` (default), `DATE_MISSING` records are shown as a separate bar segment so all bars sum to 100%. + +#### Interpretation + +Each bar represents a geographic unit and is divided into three segments: `CONSISTENT` (blue), `INCONSISTENT` (orange), and `DATE_MISSING` (grey). Bars that are predominantly orange or grey indicate units with data quality issues requiring attention. + +### Step 3 — Inspect individual inconsistent records with `dcc_inconsistent()` + +`dcc_inconsistent()` returns a record-level table of all `INCONSISTENT` and `DATE_MISSING` entries, including the day difference between the two dates. + +```{r dcc-inconsistent, message=FALSE} +inconsistent_df <- dcc_inconsistent( + data.EIR = pahoabc.EIR, + date_1 = "date_vax", + date_2 = "date_birth" +) + +inconsistent_df %>% head(10) %>% kable(caption = "Sample of inconsistent and missing records") +``` + +#### Parameters accepted + +- `data.EIR`: EIR data frame in PAHOabc format. +- `date_1`: Name of the date variable being checked. +- `date_2`: Name of the date variable checked against. + +The `diff` column reports `date_1 - date_2` in days. Negative values indicate `date_1` precedes `date_2` (i.e., the inconsistency). This table can be exported for record-level correction workflows. + +### Step 4 — Visualize the distribution of day differences with `dcc_inconsistent_plot()` + +`dcc_inconsistent_plot()` produces a histogram of the **absolute** day differences for inconsistent records, grouped into customizable bins. This helps characterize the severity of inconsistencies: small differences may reflect data entry typos, while large differences suggest more systematic issues. + +```{r dcc-inconsistent-plot, message=FALSE, fig.width=10, fig.height=5} +dcc_inconsistent_plot( + data.EIR = pahoabc.EIR, + date_1 = "date_vax", + date_2 = "date_birth", + date_1_name = "Vaccination date", + date_2_name = "Date of birth" +) +``` + +#### Parameters accepted + +- `data.EIR`: EIR data frame in PAHOabc format. +- `date_1`: Name of the date variable being checked. +- `date_2`: Name of the date variable checked against. +- `date_1_name`: Display label for `date_1` in the plot subtitle. Default: `"date 1"`. +- `date_2_name`: Display label for `date_2` in the plot subtitle. Default: `"date 2"`. +- `day_groups`: List of `c(lower, upper)` numeric pairs defining the histogram bins. The last bin is always extended to `Inf` and labelled `"X+"`. Default: 10-day bins from 0 to 100. + +To use custom bin widths — for example, finer resolution for small differences: + +```{r dcc-inconsistent-plot-custom, message=FALSE, fig.width=10, fig.height=5} +dcc_inconsistent_plot( + data.EIR = pahoabc.EIR, + date_1 = "date_vax", + date_2 = "date_birth", + date_1_name = "Vaccination date", + date_2_name = "Date of birth", + day_groups = list(c(0, 1), c(1, 7), c(7, 30), c(30, 90), c(90, 180)) +) +``` + +#### Interpretation + +The horizontal axis shows the number of days between inconsistent dates. An investigation into the most common causes for the inconsistencies in each bin should be performed. For example, records with large differences can be caused by typos during data entry (e.g. when a date is written as `2022-02-25` instead of `2022-12-25`). But, they can also point to more serious systematic problems. + +# Summary + +The `dcc_` module provides a complete pipeline for assessing date consistency in EIR data. Starting from `dcc_rate()` for a geographic overview, through `dcc_barplot()` for visualization, to `dcc_inconsistent()` for record-level inspection and `dcc_inconsistent_plot()` for characterizing the magnitude of errors, the suite equips data managers and public health analysts with the tools needed to detect, quantify, and prioritize data quality corrections before any downstream analysis.