Skip to contents

Place each AFP case on the laboratory ladder

Source: R/pending.R
afp_pending_stage.Rd

Gives each case the stage of the laboratory ladder it has reached. A case sits on the furthest rung any of its specimens reached (see afp_specimen_rung()), so a second stool collected late cannot pull a case back down the ladder. Specimens are linked to cases by EPID number; specimens with no EPID are ignored. Where no specimen links, or the linked specimens are all on rung 0, a stool collection date on the case record itself (first or second stool) places the case on rung 1.

Usage

afp_pending_stage(
  cases,
  specimens = NULL,
  stages = c("none", "collected", "at_lab", "resulted"),
  cols = list()
)

Arguments

cases

A cleaned AFP table, one row per case (from clean_afp()).

specimens

An optional cleaned human-specimen table (from clean_human_spec()). When NULL, cases are placed from their own stool collection dates only.

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. Besides the specimens keys listed in afp_specimen_rung(), this function reads the cases keys epid ("epid"), stool1collection_date ("stool1collection_date") and stool2collection_date ("stool2collection_date").

Value

cases as a tibble with the columns specimens (the number of linked specimens), rung (integer 0 to 3) and stage (a factor with levels stages) added or replaced.

Details

The stage names follow the rungs in order. With the default stages:

  • none: no specimen has been collected.

  • collected: a specimen has been collected and is awaiting receipt at the laboratory.

  • at_lab: a specimen is at the laboratory and awaiting its isolation result.

  • resulted: a laboratory result is recorded and the case is awaiting final classification.

The stage is assigned to every case, open or classified. A classified case can still lack a receipt or result date, so the stage reports what POLIS has recorded rather than where a specimen physically is.

See also

calc_pending_stage().

Examples

cases <- tibble::tibble(
  epid = c("A-1", "A-2"),
  stool1collection_date = as.Date(c(NA, "2025-01-02")),
  stool2collection_date = as.Date(NA)
)
afp_pending_stage(cases)
#> # A tibble: 2 × 6
#>   epid  stool1collection_date stool2collection_date specimens  rung stage    
#>   <chr> <date>                <date>                    <int> <int> <fct>    
#> 1 A-1   NA                    NA                            0     0 none     
#> 2 A-2   2025-01-02            NA                            0     1 collected