Skip to contents

Check the inputs before calculating SPI

Source: R/spi_check_inputs.R
spi_check_inputs.Rd

Checks case counts, population denominators, and district boundaries before fitting the model-based SPI (method = "model") or calculating the simple SPI (method = "simple"). Reports mismatched district IDs, missing periods, invalid population values, and geometry problems together.

Usage

spi_check_inputs(
  cases,
  population = NULL,
  shapefile = NULL,
  covariates = NULL,
  id_col = NULL,
  pop_col = NULL,
  verbose = TRUE,
  method = c("model", "simple"),
  year_col = "year",
  count_col = "npafp_cases"
)

Arguments

cases

For method = "model", a tibble with the district identifier (see id_col), month (Date), and count (integer-valued). For method = "simple", the district-year table: the district identifier, the year (year_col), the number of cases (count_col) and, when population is NULL, the population (pop_col).

population

Tibble with the district identifier, the denominator column (see pop_col), and either a month (Date) or year (integer) column. The time unit is inferred from these columns. For method = "simple" it is optional and keyed by year; NULL takes the population from cases.

shapefile

An sf object of district polygons, or a pre-built nb neighbour object. Geometry validity is only checked for sf input. Required for method = "model"; not used for method = "simple".

covariates

Optional tibble of district covariates. Only its ids are compared with the district IDs in the case data.

id_col

Character. Name of the district identifier column, shared by cases, population, covariates, and shapefile. Default "district_id" for method = "model" and "district" for method = "simple".

pop_col

Character. Name of the denominator column. Default "pop_u15" for method = "model" and "population_u15" for method = "simple".

verbose

Logical. Print the report once built. Default TRUE.

method

Character. "model" (default) checks the inputs of spi_index(); "simple" checks the inputs of spi_simple().

year_col, count_col

Character. Year and case-count columns for method = "simple". Defaults "year" and "npafp_cases".

Value

A spi_input_check object: a list with issues (a tibble of findings by severity, one row each with severity, code, message, and the affected ids), gaps (a district_id x month tibble of missing district-months, or district_id x year for method = "simple"), n_error / n_warning / n_note counts, ok (TRUE when there are no error-level issues), and the numbers of districts and months or years. Has a print method.

Details

Issues have three severity levels:

  • error – blocks the fit (missing columns, negative counts, negative population, duplicate district-months, case ids absent from the shapefile).

  • warning – needs review (missing district-months, zero population, incomplete coverage, shapefile districts with no case rows, invalid geometry, covariate ids absent from the case data).

  • note – additional information (separate groups in the neighbour graph).

spi_expected() calls this check and stops on errors. Run it separately to review warnings before fitting.

Simple SPI. With method = "simple", cases is the district-year table passed to spi_simple() and shapefile is not needed. The check covers missing columns, years that are not whole numbers, invalid or negative counts, duplicate district-years, missing, zero or negative populations, district-years that would be left out or counted as zero cases, and the population flags that spi_simple() returns in population_qc.

See also

spi_expected(), spi_simple(), spi_adjacency(), and vignette("spi-data-preparation") for how to prepare the inputs.

Examples

# inputs of the simple SPI: annual counts and population
annual <- synth_surveillance$cases |>
  dplyr::mutate(year = as.integer(format(month, "%Y"))) |>
  dplyr::summarise(count = sum(count), .by = c(adm2_guid, year))
spi_check_inputs(
  cases = annual,
  population = synth_surveillance$population,
  method = "simple",
  id_col = "adm2_guid",
  count_col = "count",
  pop_col = "pop_u15"
)
#> 
#> ── spi input check ─────────────────────────────────────────────────────────────
#> ✔ All input checks passed -- 236 districts x 10 years (2015 to 2024).

if (FALSE) { # \dontrun{
rpt <- spi_check_inputs(
  cases = synth_surveillance$cases,
  population = synth_surveillance$population,
  shapefile = synth_surveillance$boundaries,
  id_col = "adm2_guid"
)
rpt
rpt$gaps
} # }