Skip to contents

Compare observation models for expected counts

Source: R/spi_expected.R
spi_compare_overdispersion.Rd

Fits the same model with different overdispersion specifications and returns a side-by-side comparison of fit, complexity, and calibration diagnostics. Helps assess the overdispersion setting in spi_expected().

Usage

spi_compare_overdispersion(
  cases,
  population,
  adjacency,
  specs = c("none", "iid", "nb"),
  ...,
  n_draws = 200L,
  verbose = TRUE,
  check = TRUE
)

Arguments

cases

Tibble with the required columns for spi_expected().

population

Tibble with population data.

adjacency

nb object or sf object.

specs

Character vector of overdispersion specifications to compare. Default: c("none", "iid", "nb"). Each must be a valid overdispersion argument to spi_expected().

...

Additional arguments passed to spi_expected() (e.g. season, prior_phi, id_col). Must not include overdispersion, n_draws, or verbose; those are controlled by this function.

n_draws

Integer. Posterior draws per fit. Lower than the spi_expected() default for speed during comparison. Default: 200L.

verbose

Logical. Print progress messages. Default: TRUE.

check

Logical. Run spi_check_inputs() once before comparing, and abort on error-level issues. Each per-spec fit is then run with check = FALSE. Default TRUE.

Value

Object of class spi_comparison. A list containing:

fits

Named list of spi_expected objects, keyed by spec.

summary

Tibble of key diagnostics, one row per specification.

recommendation

List with choice (the specification selected by the package's diagnostic rule), reasoning (string explaining the choice), excluded (specs failing a diagnostic rule), and survivors (specs that passed all rules).

Details

For each specification the function refits spi_expected() and extracts: DIC, WAIC, effective parameter count, spatial SD (1/sqrt(tau_spatial)), BYM2 phi posterior median (with a "pegged" flag for boundary values), an overdispersion SD (1/sqrt(tau_obs) for "iid", 1/sqrt(nb_size) for "nb", NA for "none"), the share of observations with valid CPO, and a Kolmogorov-Smirnov (KS) distance of the probability integral transform (PIT) values from a uniform distribution.

Selection rule. A model is excluded if fewer than half its CPO values are valid, its effective parameter count exceeds 20% of observations, or its BYM2 phi is below 0.02 or above 0.98. Among the remaining models, the function selects the smallest PIT distance from a uniform distribution. If all models are excluded, choice is NA. These are diagnostic rules, not proof that the selected model is correct. The negative binomial default in spi_expected() is the pre-specified model used in the accompanying study; this comparison is an optional diagnostic.

See also

spi_expected()

Examples

if (FALSE) { # \dontrun{
cmp <- spi_compare_overdispersion(
  cases = cases,
  population = pop_u15,
  adjacency = adj,
  id_col = "adm2_guid",
  season = "harmonic"
)
cmp$summary
cmp$recommendation
} # }