Skip to contents

Simulate Environmental Surveillance Samples

Source: R/simulate_es.R
simulate_es_samples.Rd

Generates one row per environmental surveillance sample, shaped like the cleaned POLIS sample table (polished_es) that rise-afg reads. Sites are placed in districts with weight by population and sampled every sampling_interval_days, with a share of collections missed. A sample finds poliovirus with probability share_positive; otherwise it finds Sabin virus, a non-polio enterovirus or nothing. A sample whose result is not due by end_date is pending and carries no classification.

Usage

simulate_es_samples(
  admin = simulate_admin_frame(),
  start_date = as.Date("2023-01-01"),
  end_date = as.Date("2024-12-31"),
  n_sites = 8L,
  sampling_interval_days = 28,
  share_missed = 0.05,
  share_positive = 0.1,
  positive_types = "WPV 1",
  positive_type_probs = 1,
  outcome_probs = c(sabin = 0.3, npev = 0.45, negative = 0.25),
  outcome_labels = c(sabin = "SABIN", npev = "NPEV", negative = "NEGATIVE"),
  sabin_serotype_probs = c(0.6, 0, 0.6),
  result_delay_mean = 21,
  notify_delay_mean = 3,
  created_delay_mean = 2,
  delay_size = 2,
  sample_conditions = c("Good", "Poor"),
  sample_condition_probs = c(0.95, 0.05),
  clusters = c("CLUSTER A", "CLUSTER B"),
  nt_changes_mean = 8,
  detected_flag = "Yes",
  jitter_deg = 0.05,
  seed = 3L
)

Arguments

admin

A geography from simulate_admin_frame(). Default simulate_admin_frame().

start_date, end_date

First and last day of collection. Defaults as.Date("2023-01-01") and as.Date("2024-12-31"). end_date is also the date the data are taken to be extracted.

n_sites

Number of sampling sites. Default 8L.

sampling_interval_days

Days between scheduled collections at a site. Default 28.

share_missed

Share of scheduled collections not made. Default 0.05.

share_positive

Share of samples in which poliovirus is found. Default 0.1.

positive_types, positive_type_probs

Virus labels a positive sample can carry, and their weights. Defaults "WPV 1" and 1.

outcome_probs

Weights for the outcome of a sample without poliovirus. Default c(sabin = 0.3, npev = 0.45, negative = 0.25).

outcome_labels

Classification labels for those outcomes. Default c(sabin = "SABIN", npev = "NPEV", negative = "NEGATIVE").

sabin_serotype_probs

Chance that a Sabin sample carries Sabin type 1, 2 and 3. A Sabin sample with none drawn carries type 1. Default c(0.6, 0, 0.6).

result_delay_mean

Mean days from collection to the final result. Default 21.

notify_delay_mean

Mean days from a positive result to notification to headquarters. Default 3.

created_delay_mean

Mean days from collection to the record being created. Default 2.

delay_size

Size parameter of the negative binomial each delay is drawn from. Default 2.

sample_conditions, sample_condition_probs

Sample condition labels and their weights. Defaults c("Good", "Poor") and c(0.95, 0.05).

clusters

Cluster names a wild positive can carry. Default c("CLUSTER A", "CLUSTER B").

nt_changes_mean

Mean nucleotide changes of a vaccine-derived positive. Default 8.

detected_flag

Value written in a raw detection field when the virus was found. Default "Yes".

jitter_deg

Largest offset of a site from its district centre, in decimal degrees. Default 0.05.

seed

Seed for the random draws. Default 3L. The caller's random state is left as it was.

Value

A tibble with one row per sample. Dates are Date, year_collection and month_collection are integer, the Sabin, npev and nvaccine flags are integer 0 or 1, the site coordinates are double, and the remaining columns are character.

Details

The labels follow the cleaning's sample outcomes: a poliovirus sample carries its virus label in vtype and classification_all; a Sabin or non-polio enterovirus sample carries vtype "none"; a negative sample carries no vtype; and a pending sample carries neither. The raw detection fields (wild1, vdpv1 to vdpv3, vaccine1 to vaccine3) hold detected_flag where the virus was found and are missing otherwise.

Column names and outcome labels follow how rise-afg reads polished_es in 02_scripts/2c_indicators/2cvii_es.R, 2cviii_es_scorecard.R, 2cxxxvi_es_profiles.R, 2ci_detections.R and 2cxl_detection_surveillance.R, and in 02_scripts/00_helper_functions/0i_pending_helpers.R. The virus pattern matches detection_vtype_pattern in 02_scripts/00_helper_functions/00_params.R. The sample condition labels are not fixed by that code and are chosen here.

Examples

admin <- simulate_admin_frame(n_provinces = 2, n_districts = 3)
samples <- simulate_es_samples(admin, n_sites = 3)
dplyr::count(samples, classification_all)
#> # A tibble: 5 × 2
#>   classification_all     n
#>   <chr>              <int>
#> 1 NEGATIVE              21
#> 2 NPEV                  35
#> 3 SABIN                 13
#> 4 WPV 1                  6
#> 5 NA                     3