est_seroincidence_by – serocalculator

Estimate Seroincidence

Description

Function to estimate seroincidences based on cross-sectional serology data and longitudinal response model.

Usage

est_seroincidence_by(
  pop_data,
  sr_params,
  noise_params,
  strata,
  curve_strata_varnames = strata,
  noise_strata_varnames = strata,
  antigen_isos = unique(pull(pop_data, "antigen_iso")),
  lambda_start = 0.1,
  build_graph = FALSE,
  num_cores = 1L,
  verbose = FALSE,
  print_graph = FALSE,
  cluster_var = NULL,
  stratum_var = NULL,
  ...
)

Arguments

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

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

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

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 = "".

antigen_isos Character vector with one or more antibody names. Must match pop_data

lambda_start starting guess for incidence rate, in events/year.

build_graph whether to graph the log-likelihood function across a range of incidence rates (lambda values)

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.

verbose logical: if TRUE, print verbose log information to console

print_graph whether to display the log-likelihood curve graph in the course of running est_seroincidence()

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.

…

Arguments passed on to est_seroincidence, stats::nlm

stepmin: A positive scalar providing the minimum allowable relative step length.
sampling_weights: optional data.frame containing sampling weights with columns for cluster/stratum identifiers and their sampling probabilities. Currently not implemented; reserved for future use.
stepmax: a positive scalar which gives the maximum allowable scaled step length. stepmax is used to prevent steps which would cause the optimization function to overflow, to prevent the algorithm from leaving the area of interest in parameter space, or to detect divergence in the algorithm. stepmax would be chosen small enough to prevent the first two of these occurrences, but should be larger than any anticipated reasonable step.
typsize: an estimate of the size of each parameter at the minimum.
fscale: an estimate of the size of f at the minimum.
ndigit: the number of significant digits in the function f.
gradtol: a positive scalar giving the tolerance at which the scaled gradient is considered close enough to zero to terminate the algorithm. The scaled gradient is a measure of the relative change in f in each direction p[i] divided by the relative change in p[i].
iterlim: a positive integer specifying the maximum number of iterations to be performed before the program is terminated.
check.analyticals: a logical scalar specifying whether the analytic gradients and Hessians, if they are supplied, should be checked against numerical derivatives at the initial parameter values. This can help detect incorrectly formulated gradients or Hessians.

Details

If strata is left empty, a warning will be produced, recommending that you use est_seroincidence() for unstratified analyses, and then the data will be passed to est_seroincidence(). If for some reason you want to use est_seroincidence_by() with no strata instead of calling est_seroincidence(), you may use NA, NULL, or ““ as the strata argument to avoid that warning.

Value

if strata has meaningful inputs: An object of class “seroincidence.by”; i.e., a list of “seroincidence” objects from est_seroincidence(), one for each stratum, with some meta-data attributes.
if strata is missing, NULL, NA, or ““: An object of class ”seroincidence”.

Examples

Code

library("serocalculator")


library(dplyr)

xs_data <-
  sees_pop_data_pk_100

curve <-
  typhoid_curves_nostrat_100 |>
  filter(antigen_iso %in% c("HlyE_IgA", "HlyE_IgG"))

noise <-
  example_noise_params_pk

est2 <- est_seroincidence_by(
  strata = "catchment",
  pop_data = xs_data,
  sr_params = curve,
  noise_params = noise,
  antigen_isos = c("HlyE_IgG", "HlyE_IgA"),
  # num_cores = 8 # Allow for parallel processing to decrease run time
  iterlim = 5 # limit iterations for the purpose of this example
)
print(est2)

`seroincidence.by` object estimated given the following setup:
a) Antigen isotypes   : HlyE_IgG, HlyE_IgA 
b) Strata       : catchment 

This object is a list of `seroincidence` objects, with added meta-data attributes:
`antigen_isos` - Character vector of antigen isotypes used in analysis.
`Strata`       - Input parameter strata of function `est_seroincidence_by()`

Call the `summary()` function to obtain output results.

Code

summary(est2)

Seroincidence estimated given the following setup:
a) Antigen isotypes   : HlyE_IgG, HlyE_IgA 
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>