Skip to contents

Immunity: Geographic & Age-based Projection, imuGAP

Source: R/imuGAP.R
sampling.Rd

Fits the imuGAP Bayesian hierarchical vaccine coverage estimation model across arbitrary user-specified location partitions, birth cohorts, ages, and vaccine doses.

Usage

sampling(
  observations,
  populations,
  locations,
  imugap_opts = imugap_options(),
  stan_opts = stan_options(threading = TRUE)
)

Arguments

observations

a [data.frame()] containing observed data, with at least three columns:

  • an obs_id column; any type, as long as unique, non-NA

  • a positive column; non-negative integers, the observed number of vaccinated individuals

  • a sample_n column; positive integers, the number of individuals sampled, must be greater than or equal to positive

  • optionally, a censored column; numeric, NA (uncensored) or 1 (right-censored); if not present, will be assumed NA

populations

a [data.frame()] containing observation metadata, with columns:

  • obs_id, any type; the observation the row concerns (i.e. id shared with an observations data object)

  • loc_id, any type; the location the row concerns (i.e. id shared with a locations data object)

  • dose, a non-zero, positive integer (1, 2, ...); what dose row concerns

  • cohort, a positive integer; the cohort at the location row concerns

  • age, a positive integer; the age of that cohort row concerns

  • weight, a numeric, (0, 1); the relative contribution of this row to an observation. Optional if each population row has a unique obs_id.

locations

a [data.frame()] with columns loc_id and parent_id of matching types, and optionally a population column of numeric counts. See Details for restrictions.

imugap_opts

options for the imuGAP model, created by [imugap_options()].

stan_opts

sampler configuration created by [stan_options()] (see [flexstanr::stan_options()] for details on supported sampler arguments, including iter, chains, cores, seed, and backend). The {imuGAP} models support multicore calculation, so the default invocation uses threading = TRUE.

Value

an object of class imugap_fit, wrapping the raw stanfit (or CmdStanMCMC) object along with model settings and dataset metadata. For multi-layer models, retained draws include orthonormalized offsets off_layer and hierarchical shifts mu_offset (with unconstrained z_layer and intermediate raw_phi_mat omitted by default unless overridden via custom stan_opts).

Details

sampling() automatically inspects the depth of the location hierarchy supplied in locations via [canonicalize_locations()] and [assemble_layer_data()]:

  • Single-layer (1 layer): When only a root location is supplied, sampling() automatically dispatches to the optimized single-location model.

  • Multi-layer (>= 2 layers): When hierarchical sub-locations are supplied (e.g., 2-layer state -> county, 3-layer state -> county -> school, or deeper trees), sampling() dispatches to the general hierarchical model with partial pooling across layer-specific variance components.

In multi-layer models, unconstrained population offsets (z_layer) and intermediate link matrices (raw_phi_mat) are omitted from retained draws by default to save memory, while the full orthonormalized offsets (off_layer) and hierarchical shifts (mu_offset) are retained. To compute coverage probabilities or link-scale parameters for any or all locations and cohorts from retained draws, use [compute_phi()]. If you require z_layer or raw_phi_mat draws directly or wish to retain a specific set of parameters, specify pars explicitly in stan_opts = stan_options(pars = ...).

If the Stan sampler fails to initialize and produces no draws (for the rstan backend, a mode-2 stanfit with an empty @sim), sampling() raises an error of class imugap_no_draws rather than returning an empty fit, so the failure can be handled with tryCatch(). The check is backend-agnostic (see backend_has_draws()).

Examples

if (FALSE) { # interactive()
# \donttest{
data("locations_sim")
data("observations_sim")
data("populations_sim")
st_opts <- stan_options(chains = 2, iter = 500)
sampling(
  observations_sim, populations_sim, locations_sim,
  stan_opts = st_opts
)
# }
}