epikinetics

epikinetics fits Bayesian hierarchical models to repeated positive biomarker measurements after one focal exposure. It supports multiple biomarkers, participant covariates and random effects, left/right censoring, threaded Stan sampling, and population or participant-level trajectory reconstruction.

The current curve rises to a peak, wanes at an early rate, and switches to a later waning rate. It is a focused single-exposure model rather than a general model of repeated or uncertain exposure histories.

Installation

First install the CmdStanR R package and epikinetics. Then use CmdStanR to install CmdStan itself:

options(repos = c(
  stan = "https://stan-dev.r-universe.dev",
  CRAN = "https://cloud.r-project.org"
))
install.packages(c("cmdstanr", "remotes"))
remotes::install_github("seroanalytics/epikinetics")

cmdstanr::check_cmdstan_toolchain(fix = TRUE)
cmdstanr::install_cmdstan()

Installing or loading epikinetics does not install CmdStan automatically; that remains an explicit cmdstanr::install_cmdstan() step. The Stan model is compiled the first time it is needed, then its cached executable is reused.

A typical dataset

This is one example of the longitudinal data that epikinetics can analyse. The calendar-date display shows unequal sampling dates, unequal numbers of visits, participant-specific exposures (dashed lines), and several biomarkers per person. The model-facing time since exposure is calculated explicitly during data preparation; align_time_to_reference() provides an inspectable calendar-date-to-day transformation when desired. See Data for that alignment workflow and the full input contract.

Minimal workflow

Data preparation is an explicit, inspectable step:

library(epikinetics)

dat <- read.csv(
  system.file("extdata", "delta.csv", package = "epikinetics")
)

prepared <- prepare_epikinetics_data(
  dat,
  formula = ~ infection_history,
  biomarker_order = c("Ancestral", "Alpha", "Delta"),
  lower_limit = 5,
  upper_limit = 2560
)

prepared
summary(prepared)
model.matrix(prepared)
prediction_grid(prepared)
stan_data(prepared)

fit <- fit_epikinetics(
  prepared,
  chains = 4,
  parallel_chains = 4,
  threads_per_chain = 2,
  seed = 2026
)

diagnose_epikinetics(fit)

The prepared object contains the validated observations, participant and biomarker mappings, formula encoding, censoring classification, scale metadata, priors, and exact Stan data list.

Population reconstruction

population <- predict(fit, type = "population", times = 0:150)
plot(population)

Biomarkers are overlaid by colour and categorical covariate profiles determine panels. Lines are posterior medians; ribbons are pointwise 95% credible intervals for the latent trajectories. Both posterior mean and median are retained in the prediction object.

Individual reconstruction

individual <- predict(
  fit,
  type = "individual",
  participants = "202",
  times = 0:220,
  ndraws = 1000
)
plot_individual(individual, participant = "202")

Individual predictions use fitted participant effects and retain the original participant identifier. Biomarkers use separate facets while retaining their colours; observations, censoring symbols and limits, latent curves, and posterior uncertainty are shown together. For large cohorts, save_individual_plots() reuses one prediction object to write PNG, PDF, or a multi-page PDF.

The figures above were generated by the public package interface from an actual four-chain fit and are stored as documentation assets; routine site builds do not rerun MCMC.

Guided documentation

Start with:

1. Getting started with epikinetics

Then use the focused articles:

2. Data
3. Covariates
4. Censoring
5. Fitting the model
6. Population-level kinetics
7. Individual-level kinetics
8. Diagnostics
9. Case study: SARS-CoV-2 Delta-wave neutralising antibodies
10. Kinetics model and statistical structure

Advanced users retain direct access to the underlying CmdStanR fit and raw posterior draws through cmdstan_fit(fit) and posterior_draws(fit). Contributor setup and integration-test commands are in CONTRIBUTING.md.

Reference

Russell TW, Townsley H, Hellewell J, et al. Real-time estimation of immunological responses against emerging SARS-CoV-2 variants in the UK: a mathematical modelling study. Lancet Infectious Diseases (2024). doi:10.1016/S1473-3099(24)00484-5.