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. When fitting more than one antigen_isos at once, this argument also has a second use. log_likelihood() combines biomarkers by summing their marginal log-likelihoods, which is only valid if those contributions are independent. Two biomarker readings from the same person usually aren’t, since they share an infection history. Pass the id column returned by ids_varname() (e.g. cluster_var = ids_varname(pop_data)) to get a cluster-robust standard error that accounts for this within-person correlation. This is a distinct concern from a genuine sampling-cluster design, and multiple cluster_var values are combined additively via multi-way clustering, not collapsed to a single interaction: cluster_var = c(“cluster”, “id”) computes the three-term inclusion-exclusion sum \(V_{cluster} + V_{id} - V_{cluster,id}\), so passing both a sampling-cluster variable and the subject id captures the sampling-cluster and within-person corrections together. See issue #543. See issue #645.
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

Code
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>