Compute the Surveillance Performance Index (SPI)

Computes posterior draws of the Surveillance Performance Index, the ratio of observed to expected counts, centred by default on the national ratio for each period. Each assessment year's expected counts are estimated from preceding years only. For every assessment year, spi_expected() is refitted on the months before it. The assessment year's counts are masked (set to NA), so the model predicts them from the earlier months, and later months are dropped. The year's observed counts are then compared with that prediction. At least min_history years of history are required before the first assessment year.

The credible interval describes uncertainty in expected counts. With national centring, SPI = 1 means the district and national observed-to-expected ratios are equal. SPI below 1 means the district ratio is lower. With centre = "none", SPI below 1 means the district reported fewer cases than its own expected count. The model defaults are those of spi_expected(), which are the paper specification.

Usage

spi_index(
  cases,
  population,
  adjacency,
  first_assessment,
  last_assessment = NULL,
  min_history = 3L,
  level = c("district_year", "district_month", "district_quarter", "district_total"),
  centre = c("national", "none"),
  year_end_month = 12L,
  covariates = NULL,
  id_col = "district_id",
  pop_col = "pop_u15",
  boundaries = NULL,
  min_expected = 1,
  predictive = FALSE,
  verbose = TRUE,
  ...
)

Arguments

cases: Tibble with the district identifier (see id_col), month (Date) and count. One row per district-month, covering the history and every assessment year.
population: Tibble with the district identifier and the denominator column named by pop_col, keyed by year (integer) or by month (Date), as in spi_expected().
adjacency: nb object or sf object, as in spi_expected().
first_assessment: Integer. The first year to assess, labelled by the calendar year in which its window closes (see year_end_month). Its window must open at least min_history years after the first month in cases.
last_assessment: Integer or NULL. The last year to assess. NULL (default) uses the year of the last month in cases.
min_history: Integer. The number of years of history a fit needs before the window it assesses. Default: 3.
level: Character. Aggregation level: "district_month" (monthly SPI per district), "district_quarter" (calendar-quarter SPI per district), "district_year" (annual SPI per district, default), "district_total" (single SPI per district over all assessment years).
centre: Character. "national" (default) divides each period's SPI draws and summaries by that period's national observed-to-expected ratio, so SPI compares each district with the country in that period. "none" returns the district observed-to-expected ratio without this adjustment.
year_end_month: Integer 1 to 12. Month in which the assessment year closes, for level = "district_year". The default, 12, gives calendar years. Any other value gives a non-calendar reporting year: year_end_month = 4 assesses May through April. Each window is labelled by the calendar year in which it closes, so May 2024 to April 2025 is labelled 2025, and is predicted from the months before it opens, here up to April 2024. The monthly offset still uses the calendar-year denominator. Ignored at every other level, which assess calendar years. For a rolling 12-month SPI updated every month, rerun with year_end_month set to the month that has just closed. Default: 12 (calendar years).
covariates: Optional tibble of covariates keyed by year or month, as in spi_expected(). Each fit receives only the rows up to the end of its assessment year. Default: NULL.
id_col: Character. Name of the district identifier column. Default: "district_id".
pop_col: Character. Name of the denominator column in population. Default: "pop_u15".
boundaries: Optional sf object or data frame carrying the id column plus admin name columns (adm1_name, adm2_name, ...). When supplied, the names are added to summary next to the district identifier. Default NULL.
min_expected: Numeric. Districts or district-periods with total expected count below this threshold are marked as low-information. SPI is still computed; inspect the counts and uncertainty before interpreting it. Default: 1.
predictive: Logical. Reserved for a held-out predictive check. Only FALSE is supported at present. Default: FALSE.
verbose: Logical. Progress messages via cli, with one step per assessment year. Default: TRUE.
...: Further arguments passed to spi_expected(), such as season, year_effect, overdispersion, n_draws or seed. The arguments this function sets itself (cases, population, adjacency, covariates, id_col, pop_col, keep_draws and verbose) cannot be passed here.

Value

Object of class spi_index. A list containing:

draws: Matrix [n_draws x n_groups] of posterior SPI samples.
summary: Tibble with grouping variables and SPI summaries (median, mean, q05, q10, q90, q95) per district or district-period.
level: Aggregation level used.
low_information: Tibble of districts or district-periods marked as low-information.
totals: Tibble of overall observed and expected totals.
id_col: The id column name, echoed for downstream use.
centre: The centre argument used.
national: Tibble of the national observed-to-expected ratio per period (national_observed, national_expected, national_oe, districts), or NULL when centre = "none". national_expected is the median of the summed expected draws.
windows: Tibble with one row per assessment year: year, window_start, window_end, training_start, training_end (first days of months), months and districts.
call: Matched call.

Details

For aggregated levels, observed counts are summed within each grouping, expected counts are summed within each grouping per posterior draw, and the ratio is computed per draw. Within each fit, this keeps the uncertainty shared by expected counts in different districts and months.

The draws of different assessment years come from separate fits. At level = "district_total" and in the totals row, expected counts are summed across years draw by draw, so these summaries do not describe a joint posterior distribution across years.

With centre = "national", every district's SPI draws for a period are further divided by that period's national observed-to-expected ratio, computed within the same posterior draw (summed observed over the summed expected draw, across districts). This compares the district ratio with the national ratio. Uncertainty shared by every district in a period, such as a common year effect, cancels before spi_median, spi_q05 and spi_q95 are taken from the centred draws. District SPI can stay unchanged when district and national ratios change together, so review the national ratio separately. $national reports summed observed over the median summed expected count. A period with no reported cases nationally has no ratio to divide by; its rows become NA and a warning names the affected periods.

An assessment year with fewer than 12 months of data is kept, and a warning names it. At level = "district_year", the n_months column shows how many months each row covers.

Runtime

Each assessment year needs its own INLA fit, so the run time grows with the number of assessment years. Every fit uses the same ... arguments, including n_draws. Each call refits the model, so a second level or centring setting repeats the fits.

Examples

if (FALSE) { # \dontrun{
s <- synth_surveillance
spi_dy <- spi_index(
  cases = s$cases,
  population = s$population,
  adjacency = s$boundaries,
  first_assessment = 2018,
  id_col = "adm2_guid",
  boundaries = s$boundaries
)
print(spi_dy)
spi_dy$windows
} # }