R/data.R

In starling: Record Linkage for Public Health Surveillance

#' Synthetic Notifiable Disease Case Linelist
#'
#' @description
#' **Bird note**: Like the individual birds that form a murmuration, each row
#' in this dataset is one record that must find its match in the vaccination
#' register. The dataset is designed so that some birds have a clear pair and
#' some do not — mirroring real-world linkage where not every notified case
#' appears in the AIR.
#'
#' A synthetic EDIS/case notification linelist for use in starling vignettes,
#' documentation examples, and tests. No real person data. All names, dates of
#' birth, Medicare numbers, and postcodes are randomly generated. 300 records;
#' approximately 200 have a true match in \code{\link{vax_air}}.
#'
#' The dataset deliberately includes data quality challenges that mirror
#' real-world linkage scenarios: approximately 5% of matched records have a
#' name typo (adjacent characters swapped), and approximately 10% of Medicare
#' numbers have one digit corrupted (checksum fails). These are designed to
#' demonstrate \code{\link{check_medicare}}, \code{\link{preflight}},
#' \code{\link{flock}}, \code{\link{murmuration}}, and \code{\link{perch}}.
#'
#' @format A data frame with 300 rows and 10 columns:
#' \describe{
#'   \item{id_var}{character. Unique case identifier (\code{"EDIS_00001"}, etc.).}
#'   \item{true_link_id}{character. The matching \code{id_var} from
#'     \code{\link{vax_air}} for records with a true match; \code{NA} for the
#'     ~100 unmatched cases. Used in vignettes for post-hoc recall and
#'     precision calculation. Never passed to \code{murmuration()}.}
#'   \item{lettername1}{character. First name (standardised form expected by
#'     \code{murmuration()}).}
#'   \item{lettername2}{character. Surname.}
#'   \item{dob}{Date. Date of birth.}
#'   \item{gender}{character. \code{"Male"} or \code{"Female"}.}
#'   \item{postcode}{character. Sunshine Coast postcode (4550–4562).}
#'   \item{medicare10}{character. 10-digit Medicare number. ~10\% have one
#'     digit deliberately corrupted so \code{\link{check_medicare}} flags them
#'     as invalid (flag = \code{0L}).}
#'   \item{onset_date}{Date. Date of symptom onset (2024 calendar year).}
#'   \item{pathogen}{character. Notified pathogen: one of Influenza A,
#'     Influenza B, COVID-19, RSV, Pertussis, Salmonellosis,
#'     Campylobacteriosis.}
#' }
#'
#' @source Generated by \code{data-raw/starling_synthetic_data.R}.
#'   Run \code{source("data-raw/starling_synthetic_data.R")} from the package
#'   root to rebuild.
#'
#' @seealso \code{\link{vax_air}} for the paired vaccination register dataset.
#'   \code{vignette("linked-cohort", package = "starling")} for a worked
#'   end-to-end linkage example using both datasets.
#'
#' @examples
#' \dontrun{
#' data(cases_notifiable)
#' head(cases_notifiable)
#'
#' # Check Medicare validity before linkage
#' cases_checked <- check_medicare(cases_notifiable)
#' table(cases_checked$medicare_valid, useNA = "always")
#'
#' # Pre-linkage quality audit
#' data(vax_air)
#' preflight(cases_notifiable, vax_air,
#'           linkage_vars = c("lettername1", "lettername2", "dob", "medicare10"),
#'           medicare_col = "medicare10")
#' }
"cases_notifiable"


#' Synthetic Australian Immunisation Register Extract
#'
#' @description
#' **Bird note**: This is the second flock — the AIR records whose individual
#' birds must be matched to their counterparts in the case linelist. Some will
#' pair cleanly; others will remain unpaired because the case was not vaccinated
#' or vaccination was administered elsewhere.
#'
#' A synthetic extract from the Australian Immunisation Register (AIR) for use
#' in starling vignettes, documentation examples, and tests. No real person
#' data. 400 records; approximately 200 are true matches to records in
#' \code{\link{cases_notifiable}}. All Medicare numbers have valid checksums.
#' Each person may have 1–4 vaccination doses stored in wide format
#' (\code{vax_date_1}–\code{vax_date_4}, \code{vax_type_1}–\code{vax_type_4}).
#'
#' @format A data frame with 400 rows and 15 columns:
#' \describe{
#'   \item{id_var}{character. Unique AIR identifier (\code{"AIR_00001"}, etc.).}
#'   \item{lettername1}{character. First name.}
#'   \item{lettername2}{character. Surname.}
#'   \item{dob}{Date. Date of birth.}
#'   \item{gender}{character. \code{"Male"} or \code{"Female"}.}
#'   \item{postcode}{character. Sunshine Coast postcode (4550–4562).}
#'   \item{medicare10}{character. 10-digit Medicare number. All records have
#'     valid Modulus 10 checksums (\code{\link{check_medicare}} returns
#'     \code{1L} for every row).}
#'   \item{vax_date_1}{Date. Date of first vaccination dose. Never \code{NA}.}
#'   \item{vax_type_1}{character. Vaccine type for dose 1.}
#'   \item{vax_date_2}{Date. Date of second dose; \code{NA} if person received
#'     only one dose.}
#'   \item{vax_type_2}{character. Vaccine type for dose 2; \code{NA} if absent.}
#'   \item{vax_date_3}{Date. Date of third dose; \code{NA} if fewer than three
#'     doses.}
#'   \item{vax_type_3}{character. Vaccine type for dose 3; \code{NA} if absent.}
#'   \item{vax_date_4}{Date. Date of fourth dose; \code{NA} if fewer than four
#'     doses.}
#'   \item{vax_type_4}{character. Vaccine type for dose 4; \code{NA} if absent.}
#' }
#'
#' @source Generated by \code{data-raw/starling_synthetic_data.R}.
#'   Run \code{source("data-raw/starling_synthetic_data.R")} from the package
#'   root to rebuild.
#'
#' @seealso \code{\link{cases_notifiable}} for the paired case linelist.
#'   \code{vignette("linked-cohort", package = "starling")} for a worked
#'   end-to-end linkage example using both datasets.
#'
#' @examples
#' \dontrun{
#' data(vax_air)
#' head(vax_air)
#'
#' # Confirm all Medicare numbers pass checksum
#' vax_checked <- check_medicare(vax_air)
#' mean(vax_checked$medicare_valid == 1L, na.rm = TRUE)  # should be ~1.0
#'
#' # Distribution of dose counts
#' n_doses <- rowSums(!is.na(vax_air[, paste0("vax_date_", 1:4)]))
#' table(n_doses)
#' }
"vax_air"