preflight: Pre-Linkage Data Quality Checks

In starling: Record Linkage for Public Health Surveillance

Pre-Linkage Data Quality Checks

Description

**Bird note**: Before a long migration, birds enter a physiological state called *hyperphagia* — they systematically assess and load up on resources, checking body condition before committing to the journey. preflight() is that pre-migration check for your data: a structured, systematic audit of both datasets before committing to probabilistic linkage with murmuration(). Skipping it is like a shorebird launching across the Pacific without first checking its fat reserves.

Runs a battery of pre-linkage data quality checks on two datasets and returns a structured report. Checks cover: completeness of linkage variables, date plausibility, uniqueness of identifier columns, consistency of factor levels across datasets (e.g. gender coding), Medicare validity (if present), name length and character distribution, duplicate record detection, and dataset overlap summaries. Optionally runs check_medicare if a Medicare column is identified.

The report is printed to the console and returned invisibly as a named list so it can be saved, embedded in a Quarto report, or passed to downstream checks.

Usage

preflight(
  data1,
  data2,
  linkage_vars = NULL,
  id_col1 = "id_var",
  id_col2 = "id_var",
  blocking_vars = NULL,
  date_cols = NULL,
  medicare_col = NULL,
  name_cols = NULL,
  min_name_length = 2L,
  verbose = TRUE
)

Arguments

data1	First data frame (typically the case/index dataset, df1 in murmuration()).
data2	Second data frame (typically the vaccination/hospitalisation dataset, df2 in murmuration()).
linkage_vars	Character vector of column names that will be used as compare_vars in murmuration(). These are the variables preflight() will assess most carefully.
id_col1	Name of the unique record identifier in data1. Default "id_var".
id_col2	Name of the unique record identifier in data2. Default "id_var".
blocking_vars	Character vector of planned blocking variable names to check for completeness. If NULL (default), blocking variables are not checked.
date_cols	Character vector of date column names to check for plausibility (no future dates, no dates before 1900). NULL (default) skips date checks.
medicare_col	Name of the Medicare number column if present and to be validated. NULL (default) skips Medicare validation. If supplied, check_medicare is run on both datasets and results summarised here.
name_cols	Character vector of name columns to check for short strings (potential initials or truncations), all-numeric entries, and excessive punctuation. Default checks "lettername1" and "lettername2" if present.
min_name_length	Integer. Names shorter than this are flagged as potentially truncated or coded. Default 2.
verbose	Logical. Print the full report to console? Default TRUE.

Value

Invisibly, a named list with the following elements:

completeness

A data frame: variable, dataset, n_present, n_missing, pct_missing for each linkage variable.

duplicates

A data frame: dataset, n_records, n_unique_ids, n_duplicate_ids, pct_duplicate.

blocking_completeness

Completeness of blocking variables, or NULL if not checked.

date_checks

Date plausibility results, or NULL if not checked.

medicare

Medicare validity results from check_medicare(), or NULL if not checked.

name_checks

Name quality results, or NULL if not checked.

factor_consistency

Comparison of factor levels for shared categorical columns.

overlap_summary

Approximate overlap statistics for key demographic variables.

flags

Character vector of warning-level flags raised during the checks. Empty if no issues found.

See Also

check_medicare, murmuration, flock

Examples

## Not run: 
# Basic pre-flight check before v2c linkage
report <- preflight(
  data1         = cases_clean,
  data2         = vax_clean,
  linkage_vars  = c("lettername1", "lettername2", "dob", "medicare10"),
  id_col1       = "id_var",
  id_col2       = "id_var",
  blocking_vars = "gender",
  date_cols     = c("dob", "onset_date"),
  medicare_col  = "medicare"
)

# Access the completeness table programmatically
report$completeness

# Save the report to a CSV for documentation
write.csv(report$completeness, "preflight_completeness.csv", row.names = FALSE)

## End(Not run)

starling documentation built on July 10, 2026, 9:07 a.m.