Skip to contents

epikinetics

R-CMD-check codecov

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

Nine participants with irregularly timed longitudinal neutralising-antibody measurements for three biomarkers. A dashed line marks each focal exposure.
Nine participants with irregularly timed longitudinal neutralising-antibody measurements for three biomarkers. A dashed line marks each focal exposure.

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)
Conditional population kinetics for three biomarkers and two infection-history groups.
Conditional population kinetics for three biomarkers and two infection-history groups.

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")
Observed measurements and fitted latent trajectories for participant 202, faceted by biomarker.
Observed measurements and fitted latent trajectories for participant 202, faceted by biomarker.

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:

  1. Data
  2. Covariates
  3. Censoring
  4. Fitting the model
  5. Population-level kinetics
  6. Individual-level kinetics
  7. Diagnostics
  8. Case study: SARS-CoV-2 Delta-wave neutralising antibodies
  9. 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.