Calculate AFP timeliness by step — calc_afp

For each administrative unit, the share of AFP cases that met each of three timeliness standards: onset to notification, notification to investigation, and investigation to first stool collection. Each step has its own denominator, since a case can carry one date and not another.

Usage

calc_afp_timeliness(
  cases,
  level = "adm0",
  admin_units = NULL,
  from = NULL,
  to = NULL,
  notify_days = 7,
  invest_days = 2,
  stool_days = 3,
  cols = list()
)

Arguments

cases: Cleaned AFP cases, one row per case (data.frame or tibble).
level: Administrative level to group by: "adm0" (country, the default), "adm1" (province) or "adm2" (district). Cases with no identifier at that level are left out.
admin_units: Optional data frame listing every unit to report, with the level's GUID column (for example adm2_guid) and optionally its name column (for example adm2). A unit with no cases is kept with zero counts and NA percentages. Without it, only units with cases are reported.
from, to: First and last onset date of the reporting window, or NULL for no bound.
notify_days: Most days from onset to notification that count as on time (default 7).
invest_days: Most days from notification to investigation that count as on time (default 2).
stool_days: Most days from investigation to first stool collection that count as on time (default 3).
cols: Named list overriding default column names, in the style of calc_polio_indicators(), for example list(cases = list(stool1_condition = "s1_cond")). The defaults are the polished defaults plus the module columns listed under Details of calc_afp_timeliness().

Value

A tibble with one row per unit: level, guid, name, cases, then for each step (notify, invest, stool) the denominator _n, the numerator _ok and the percentage _pct. The _pct columns are on a scale of 0 to 100.

Details

Numerator: cases whose interval is at or under the step's threshold (notify_days, invest_days, stool_days; defaults 7, 2 and 3 days).
Denominator: cases where that interval is not missing.
The percentage is NA when the denominator is zero.

The cases counted are those with onset between from and to. A case without an onset date is left out whenever either bound is given.

This differs from inv_timeliness_pct in calc_polio_indicators(), whose denominator is every AFP case (so a missing interval counts as late) and whose numerator also requires the interval to be zero or more. Here a missing interval leaves the case out of that step, and a negative interval counts as on time; clean_afp() already sets intervals outside 0 to 365 days to NA, except investigation to first stool, which may be negative.

Columns used beyond the defaults of calc_polio_indicators(): in cases, epid, onset_to_notify, invest_to_stool1, stool1collection_date, adequate_stool_polis (adequate_stool_with_condition), followup_findings, doses_reported (total_number_of_doses) and doses_calculated (calc_doses_risi); in specimens, epid, date_collected (date_stool_collected) and date_received (date_stool_received_in_lab).

Examples

cases <- tibble::tibble(
  adm0_guid = "G0",
  adm0 = "Country",
  paralysis_onset_date = as.Date("2025-03-01") + 0:3,
  onset_to_notify = c(3, 9, NA, 7),
  notify_to_invest = c(1, 2, 3, NA),
  invest_to_stool1 = c(0, 4, 1, 2)
)
calc_afp_timeliness(cases)
#> # A tibble: 1 × 13
#>   level guid  name    notify_pct invest_pct stool_pct cases notify_n notify_ok
#>   <chr> <chr> <chr>        <dbl>      <dbl>     <dbl> <int>    <int>     <int>
#> 1 adm0  G0    Country       66.7       66.7        75     4        3         2
#> # ℹ 4 more variables: invest_n <int>, invest_ok <int>, stool_n <int>,
#> #   stool_ok <int>