Generate antibody level credible intervals — get_antibody_level

Generates credible intervals on antibody levels and infection histories from an MCMC chain output.

get_antibody_level_predictions(
  chain,
  infection_histories,
  antibody_data,
  demographics = NULL,
  individuals,
  antigenic_map = NULL,
  possible_exposure_times = NULL,
  par_tab,
  nsamp = 1000,
  add_residuals = FALSE,
  measurement_bias = NULL,
  for_res_plot = FALSE,
  expand_antibody_data = FALSE,
  expand_to_all_times = FALSE,
  expand_to_all_biomarker_ids = FALSE,
  antibody_level_before_infection = FALSE,
  for_regression = FALSE,
  data_type = 1,
  start_level = "none",
  exponential_waning = FALSE
)

Arguments

chain: the full MCMC chain to generate antibody level trajectories from, usually `chains$theta_chain`
infection_histories: the MCMC chain for infection histories, usually `chains$inf_chain`
antibody_data: the antibody data frame, with one row per measurement
demographics: optional data frame identifying the demographic group for each individual. This is used when model parameters are stratified by demographics. See the [demographic stratification and covariate vignette](https://seroanalytics.github.io/serosolver/articles/demographics_covariates.html).
individuals: the subset of individual IDs to generate credible intervals for
antigenic_map: (optional) a data frame of antigenic x and y coordinates. Must have column names: x_coord; y_coord; inf_times. The `inf_times` column identifies the circulation or exposure time represented by each map entry. See example_antigenic_map
possible_exposure_times: (optional) if no antigenic map is specified, this argument gives the vector of times at which individuals can be infected
par_tab: the model control table specifying the parameters in the MCMC chain
nsamp: number of draws to take from the posterior
add_residuals: if true, returns an extra output summarising residuals between the model prediction and data
measurement_bias: default NULL, optional data frame mapping each `biomarker_id` and `biomarker_group` combination to the `rho_index` of the measurement-shift parameter that it uses. See the [advanced features vignette](https://seroanalytics.github.io/serosolver/articles/advanced_features.html).
for_res_plot: TRUE/FALSE value. If using the output of this for plotting of residuals, returns the actual data points rather than summary statistics
expand_antibody_data: TRUE/FALSE value. If TRUE, solves antibody level predictions for every observed biomarker ID at every sample time in the study period. If FALSE, only the biomarker IDs and sample times present in antibody_data are used.
expand_to_all_times: TRUE/FALSE value. If TRUE, uses all possible exposure times as sample times when expanding the prediction data. If FALSE, only the sample times represented in antibody_data are used.
expand_to_all_biomarker_ids: TRUE/FALSE value. If TRUE, solves antibody level predictions for every biomarker ID in the antigenic map while retaining the sample times in antibody_data.
antibody_level_before_infection: TRUE/FALSE value. If TRUE, solves antibody level predictions, but gives the predicted antibody level at a given time point BEFORE any infection during that time occurs.
for_regression: if TRUE, returns posterior draws rather than posterior summaries
data_type: numeric or text value: `1` or `"discrete"` for discrete, bounded data; `2` or `"continuous"` for continuous, bounded data; or `3` or `"false_positive"` for continuous data with the false-positive observation model. Supply one value per biomarker group, or one value to use for all groups. For bounded data, the limits are given by `min_measurement` and `max_measurement` in par_tab.
start_level: `"none"` or a starting-level summary or data frame. A starting level is the antibody level assigned before the modelled infection history begins. With `"none"`, starting levels are set to zero. See the [advanced features vignette](https://seroanalytics.github.io/serosolver/articles/advanced_features.html).
exponential_waning: Deprecated compatibility argument. The preferred setting is a fixed `exponential_waning` row in `par_tab`, with `values = 1` and `par_type = 0`.

Value

a list with the antibody level predictions (95

Examples

if (FALSE) { # \dontrun{
data(example_theta_chain)
data(example_inf_chain)
data(example_antibody_data)
data(example_antigenic_map)
data(example_par_tab)

y <- get_antibody_level_predictions(
  chain = example_theta_chain,
  infection_histories = example_inf_chain,
  antibody_data = example_antibody_data,
  individuals = unique(example_antibody_data$individual),
  antigenic_map = example_antigenic_map,
  par_tab = example_par_tab,
  expand_antibody_data = FALSE
)
} # }