Count AFP cases awaiting classification by stage and month of onset

Builds the pending-classification stage table: one row per area and month of onset in the reporting window, giving how many AFP cases the month holds, how many are still open, how the open cases split across the laboratory ladder, and how long they have been waiting.

Usage

calc_pending_stage(
  cases,
  specimens = NULL,
  as_of = Sys.Date(),
  window_months = 12L,
  to = NULL,
  trim_window = TRUE,
  stale_days = 120L,
  level = "adm0",
  surveillance_type = "AFP",
  pending_classes = c("PENDING", "LAB PENDING"),
  stages = c("none", "collected", "at_lab", "resulted"),
  cols = list()
)

Arguments

cases: A cleaned AFP table, one row per case (from clean_afp()). It should already be limited to the country or countries of interest.
specimens: An optional cleaned human-specimen table (from clean_human_spec()). When NULL, cases are placed from their own stool collection dates only.
as_of: The reporting date, as a Date or a string that as.Date() reads. Defaults to Sys.Date(). The waiting time is measured to it, and it decides which months are marked partial.
window_months: How many months of onset the window holds before trimming. The default is 12.
to: Any date in the last month of onset in the window. When NULL (the default) it is the latest month of onset among the kept cases.
trim_window: If TRUE (the default), cut the start of the window back to the oldest month that still holds an open case.
stale_days: Waiting time in days beyond which an open case is counted in over_stale. The default is 120, the point after which a result arrives too late to change the response.
level: The reporting level: "adm0" (country, the default), "adm1" (province) or "adm2" (district). The table has one row per area that holds at least one kept case, and month.
surveillance_type: Surveillance types to keep, matched against the surveillance_type column ("surveillance_type_name"). The default "AFP" leaves out contact and healthy-child samples. Use NULL to keep every row.
pending_classes: Classification labels that mean the case is still pending. The default, c("PENDING", "LAB PENDING"), is the programme standard and matches calc_polio_indicators().
stages: Four distinct stage names for rungs 0 to 3. The default is c("none", "collected", "at_lab", "resulted").
cols: A named list overriding the default column names, in the style of calc_polio_indicators(). Besides the keys listed in afp_pending_stage(), this function reads the cases keys class, onset_date, surveillance_type and the admin guid and name columns of the chosen level.

Value

A tibble with one row per area and month of onset, sorted by area and month: level, guid and name for the chosen level, the GUID and name columns of every level above it (for example adm0_guid and adm0 when level = "adm1"), onset_month and the counts above.

Which cases count

Cases are kept when their surveillance type is in surveillance_type and they have a paralysis onset date. Each case is flagged open with afp_pending_open() and placed on the ladder with afp_pending_stage().

The reporting window

The window holds window_months calendar months of onset, ending with the month of to. By default to is the latest month of onset among the kept cases, not as_of, because the running month holds few onsets yet. With trim_window = TRUE the window is then cut back to the oldest month that still holds an open case, so months the laboratory has fully cleared at the start of the window are dropped. Every month left in the window keeps a row in every area, including months with no cases. Open cases with an onset before the window are not counted.

Counts

records: AFP cases with onset in the month.
open: those cases still awaiting classification.
open_share: open / records on a scale of 0 to 1, or NA when the month has no cases.
<stage>_n: open cases on each stage of the ladder, one column per entry of stages. Every stage keeps a column even when no case reached it.
<stage>_share: each stage's share of the month's open cases on a scale of 0 to 1, or 0 when the month has no open case.
median_days: the median number of days from onset to as_of among the month's open cases, or NA when it has none.
over_stale: open cases that have waited more than stale_days days from onset to as_of. A case that has waited exactly stale_days days is not counted.
partial: TRUE when the month of onset is the month of as_of or later, so it is still being reported.
month_label: the month of onset written as, for example, "Jan 2025".

Difference from `unclass_cases_pct`

calc_polio_indicators() reports unclass_cases_pct, the share of AFP cases that are unclassified. That indicator counts cases aged under 15 years, excludes NOT-AFP, treats UNKNOWN as unclassified, does not count a blank classification, and is reported by year of onset. The open_share here counts every case of the surveillance type whatever its age or classification, treats a blank classification as open, does not treat UNKNOWN as open, and is reported by month of onset within the window.

Examples

cases <- tibble::tibble(
  epid = c("A-1", "A-2", "A-3"),
  classification_all = c("NPAFP", "PENDING", ""),
  paralysis_onset_date = as.Date(
    c("2025-01-10", "2025-02-03", "2025-02-20")
  ),
  surveillance_type_name = "AFP",
  stool1collection_date = as.Date(c("2025-01-12", "2025-02-05", NA)),
  stool2collection_date = as.Date(NA),
  adm0_guid = "G0",
  adm0 = "COUNTRY"
)
calc_pending_stage(cases, as_of = as.Date("2025-03-15"))
#> # A tibble: 1 × 19
#>   level guid  name    onset_month records  open none_n collected_n at_lab_n
#>   <chr> <chr> <chr>   <date>        <int> <int>  <int>       <int>    <int>
#> 1 adm0  G0    COUNTRY 2025-02-01        2     2      1           1        0
#> # ℹ 10 more variables: resulted_n <int>, none_share <dbl>,
#> #   collected_share <dbl>, at_lab_share <dbl>, resulted_share <dbl>,
#> #   median_days <dbl>, over_stale <int>, open_share <dbl>, partial <lgl>,
#> #   month_label <chr>