Estimate seroincidence by stratum, caching the result on disk

Description

A caching wrapper around est_seroincidence_by(). The first call estimates and saves; later calls with the same arguments load the saved result.

Usage

est_seroincidence_by_cached(
  ...,
  cache_path = "cache/",
  cache_id = "est_seroincidence_by",
  cache_rerun = FALSE,
  cache_verbose = TRUE,
  cache_extra = NULL
)

Arguments

…	Arguments passed on to est_seroincidence_by pop_data a data.frame with cross-sectional serology data per antibody and age, and additional columns corresponding to each element of the strata input strata a character vector of stratum-defining variables. Values must be variable names in pop_data. curve_strata_varnames A subset of strata. Values must be variable names in curve_params. Default = "". noise_strata_varnames A subset of strata. Values must be variable names in noise_params. Default = "". num_cores Number of processor cores to use for calculations when computing by strata. If set to more than 1 and package parallel is available, then the computations are executed in parallel. Default = 1L. lambda_start starting guess for incidence rate, in events/year. antigen_isos Character vector with one or more antibody names. Must match pop_data build_graph whether to graph the log-likelihood function across a range of incidence rates (lambda values) print_graph whether to display the log-likelihood curve graph in the course of running est_seroincidence() sr_params a data.frame() containing MCMC samples of parameters from the Bayesian posterior distribution of a longitudinal decay curve model. The parameter columns must be named: antigen_iso: a character() vector indicating antigen-isotype combinations iter: an integer() vector indicating MCMC sampling iterations y0: baseline antibody level at $t=0$ ($y(t=0)$) y1: antibody peak level (ELISA units) t1: duration of infection alpha: antibody decay rate (1/days for the current longitudinal parameter sets) r: shape factor of antibody decay cluster_var optional name(s) of the variable(s) in pop_data containing cluster identifiers for clustered sampling designs (e.g., households, schools). Can be a single variable name (character string) or a vector of variable names for multi-level clustering (e.g., c(“school”, “classroom”)). When provided, standard errors will be adjusted for within-cluster correlation using cluster-robust variance estimation. stratum_var optional name of the variable in pop_data containing stratum identifiers. Used in combination with cluster_var for stratified cluster sampling designs. noise_params a data.frame() (or tibble::tibble()) containing the following variables, specifying noise parameters for each antigen isotype: antigen_iso: antigen isotype whose noise parameters are being specified on each row nu: biological noise eps: measurement noise y.low: lower limit of detection for the current antigen isotype y.high: upper limit of detection for the current antigen isotype verbose logical: if TRUE, print verbose log information to console
cache_path	a character() of length 1: the directory in which to store cache files. A trailing slash is added if absent (see .validate_cache_path()). Results are written to cache_path/cache_id/.
cache_id	a character() of length 1: a stable identifier for this cache entry. Distinct calls sharing a cache_path need distinct cache_ids.
cache_rerun	a logical() of length 1: whether to discard any existing cache and recompute. The freshly computed result is saved, so later calls with cache_rerun = FALSE reuse it.
cache_verbose	a logical() of length 1: whether to report cache hits and misses via cli::cli_inform().
cache_extra	an object folded into the cache key alongside the arguments. NULL (the default) keys the cache on the arguments alone. See the note on implementation changes in sim_pop_data_multi_cached().

Details

The cache is keyed on the arguments, with the same scope and the same caveat about implementation changes described in sim_pop_data_multi_cached().

Note that build_graph = TRUE attaches a log-likelihood plot to every stratum, which makes the returned object far larger on disk than the same fit without graphs. When caching many strata, prefer build_graph = FALSE and re-fit the handful of strata you actually plot.

Value

a “seroincidence.by” object, as returned by est_seroincidence_by().

See Also

sim_pop_data_multi_cached()

Examples

library("serocalculator")


library(dplyr)

antibodies <- c("HlyE_IgA", "HlyE_IgG")

curve <-
  typhoid_curves_nostrat_100 |>
  filter(antigen_iso %in% antibodies)

# Examples must not write into the user's working directory, so send the
# cache to a temporary one.
cache_dir <- file.path(tempdir(), "serocalculator-example-cache")

ests <- est_seroincidence_by_cached(
  pop_data = sees_pop_data_pk_100,
  sr_params = curve,
  noise_params = example_noise_params_pk,
  strata = "catchment",
  antigen_isos = antibodies,
  build_graph = FALSE,
  num_cores = 1,
  iterlim = 5, # limit iterations for the purpose of this example
  cache_path = cache_dir
)

summary(ests)

Seroincidence estimated given the following setup:
a) Antigen isotypes   : HlyE_IgA, HlyE_IgG 
b) Strata       : catchment 

 Seroincidence estimates:
# A tibble: 2 × 14
  Stratum  catchment     n est.start incidence.rate     SE CI.lwr CI.upr se_type
  <chr>    <chr>     <int>     <dbl>          <dbl>  <dbl>  <dbl>  <dbl> <chr>  
1 Stratum… aku          53       0.1          0.140 0.0216  0.104  0.189 standa…
2 Stratum… kgh          47       0.1          0.200 0.0301  0.149  0.268 standa…
# ℹ 5 more variables: coverage <dbl>, log.lik <dbl>, iterations <int>,
#   antigen.isos <chr>, nlm.convergence.code <ord>