Simulate Human Stool Specimens — simulate_human

Builds one row per stool specimen from the cases in a table from simulate_afp_cases(), shaped like the cleaned POLIS specimen table that clean_human_spec() writes. A case contributes one specimen for each stool collection date it carries, so a case with a single stool has one specimen and a case whose stools fall after the extraction has none.

Usage

simulate_human_specimens(
  afp_cases,
  end_date = as.Date("2024-12-31"),
  delay_means = c(collect_to_lab = 3, lab_to_culture = 14, culture_to_itd = 7,
    itd_to_sequencing = 14),
  delay_size = 2,
  share_pending_resulted = 0.5,
  pending_labels = c(pending = "PENDING", lab_pending = "LAB PENDING"),
  positive_pattern = "WPV|VDPV",
  seed = 5L
)

Arguments

afp_cases: A table from simulate_afp_cases().
end_date: The date the data are taken to be extracted. Default as.Date("2024-12-31").
delay_means: Mean delays in days, one for each named step: collect_to_lab, lab_to_culture, culture_to_itd and itd_to_sequencing. Default c(collect_to_lab = 3, lab_to_culture = 14, culture_to_itd = 7, itd_to_sequencing = 14).
delay_size: Size parameter of the negative binomial each delay is drawn from; smaller values give longer tails. Default 2.
share_pending_resulted: Share of the cases pending classification, other than laboratory pending, whose specimens have a culture result. Default 0.5.
pending_labels: Classification labels of a case pending classification and of a laboratory pending case. Default c(pending = "PENDING", lab_pending = "LAB PENDING").
positive_pattern: Regular expression a classification_all label must match for the specimens of a case to receive ITD and sequencing results. Default "WPV|VDPV".
seed: Seed for the random draws. Default 5L. The caller's random state is left as it was.

Value

A tibble with one row per specimen and the columns specimen_id, epid, specimen_number (integer), country_iso3code, adm0, adm1, adm2, adm0_guid, adm1_guid, adm2_guid, date_stool_collected, year_collection, month_collection, specimen_stool_condition_name, date_stool_received_in_lab, date_final_cell_culture_results, date_itd_result_reported, dateof_sequencing, collect_to_lab, lab_to_culture and collect_to_seq. Dates are Date; years, months and intervals are double.

Details

Each specimen is received in the laboratory, given a final cell culture result and, when its case is poliovirus positive, an intratypic differentiation (ITD) result and a sequencing result. Each step follows the one before after a delay drawn from a negative binomial distribution, so the dates of a specimen always run in order. The specimens keep the state of their case. A specimen of a case classified as laboratory pending has not been received. A specimen of a case pending classification has been received, and share_pending_resulted of those cases also have their culture result. A classified case has every date up to its culture result, with dates that would fall after end_date set to end_date. For a pending case, a date after end_date has not happened yet and is left missing, along with every later date.

The year and month of collection and the laboratory intervals collect_to_lab, lab_to_culture and collect_to_seq are derived by the same code clean_human_spec() uses.

Examples

admin <- simulate_admin_frame(n_provinces = 2, n_districts = 3)
cases <- simulate_afp_cases(admin, n_positive = 2)
specimens <- simulate_human_specimens(cases)
dplyr::count(specimens, specimen_number)
#> # A tibble: 2 × 2
#>   specimen_number     n
#>             <int> <int>
#> 1               1    30
#> 2               2    29