Generate Predicted Antibody Response Curves (Median + 95% CI) — plot_predicted

Plots a median antibody response curve with a 95% credible interval ribbon, using MCMC samples from the posterior distribution. Optionally overlays observed data, applies logarithmic spacing on the y- and x-axes, and shows all individual sampled curves.

Usage

plot_predicted_curve(
  sr_model,
  id,
  antigen_iso,
  dataset = NULL,
  legend_obs = "Observed data",
  legend_median = "Median prediction",
  show_quantiles = TRUE,
  log_y = FALSE,
  log_x = FALSE,
  show_all_curves = FALSE,
  alpha_samples = 0.3,
  xlim = NULL,
  ylab = NULL
)

Arguments

sr_model

An sr_model object (returned by run_mod()) containing samples from the posterior distribution of the model parameters.

id

The participant ID to plot; for example, "sees_npl_128".

antigen_iso

The antigen isotype to plot; for example, "HlyE_IgA" or "HlyE_IgG".

dataset

(Optional) A dplyr::tbl_df with observed antibody response data. Must contain:

timeindays
value
id
antigen_iso

legend_obs

Label for observed data in the legend.

legend_median

Label for the median prediction line.

show_quantiles

logical; if TRUE (default), plots the 2.5%, 50%, and 97.5% quantiles.

log_y

logical; if TRUE, applies a log10 transformation to the y-axis.

log_x

logical; if TRUE, applies a log10 transformation to the x-axis.

show_all_curves

logical; if TRUE, overlays all individual sampled curves.

alpha_samples

Numeric; transparency level for individual curves (default = 0.3).

xlim

(Optional) A numeric vector of length 2 providing custom x-axis limits.

ylab

(Optional) A string for the y-axis label. If NULL (default), the label is automatically set to "ELISA units" or "ELISA units (log scale)" based on the log_y argument.

Value

A ggplot2::ggplot object displaying predicted antibody response curves with a median curve and a 95% credible interval band as default.

Examples

# 1) Prepare the on-the-fly dataset
dataset <- serodynamics::nepal_sees |>
  as_case_data(
    id_var        = "id",
    biomarker_var = "antigen_iso",
    value_var     = "value",
    time_in_days  = "timeindays"
  ) |>
  dplyr::rename(
    strat      = bldculres,
    timeindays = dayssincefeveronset,
    value      = result
  )

# 2) Extract just the one subject/antigen for overlay later
dat <- dataset |>
  dplyr::filter(id == "sees_npl_128", antigen_iso == "HlyE_IgA")

# 3) Load the pre-computed model output included with the package.
# This is much faster than running the model live.
model <- serodynamics::nepal_sees_jags_output


# 4a) Plot (linear axes) with all individual curves + median ribbon
p1 <- plot_predicted_curve(
  sr_model           = model,
  id                 = "sees_npl_128",
  antigen_iso        = "HlyE_IgA",
  dataset            = dat,
  legend_obs         = "Observed data",
  legend_median        = "Median prediction",
  show_quantiles     = TRUE,
  log_y          = FALSE,
  log_x              = FALSE,
  show_all_curves    = TRUE
)
print(p1)


# 4b) Plot (log10 y-axis) with all individual curves + median ribbon
p2 <- plot_predicted_curve(
  sr_model           = model,
  id                 = "sees_npl_128",
  antigen_iso        = "HlyE_IgA",
  dataset            = dat,
  legend_obs         = "Observed data",
  legend_median        = "Median prediction",
  show_quantiles     = TRUE,
  log_y          = TRUE,
  log_x              = FALSE,
  show_all_curves    = TRUE
)
print(p2)


# 4c) Plot with custom x-axis limits (0-600 days)
p3 <- plot_predicted_curve(
  sr_model           = model,
  id                 = "sees_npl_128",
  antigen_iso        = "HlyE_IgA",
  dataset            = dat,
  legend_obs         = "Observed data",
  legend_median        = "Median prediction",
  show_quantiles     = TRUE,
  log_y          = FALSE,
  log_x              = FALSE,
  show_all_curves    = TRUE,
  xlim               = c(0, 600)
)
print(p3)