README.md
In seroanalytics/serosolver: Inference Framework for Serological Data

Update 16/01/2024

serosolver is in the midst of an overhaul. Please use the published branch to ensure continued compatibility with existing projects.

devtools::install_github("seroanalytics/serosolver",ref="published")

serosolver

serosolver uses a hierarchical model with a custom Markov chain Monte Carlo sampler to simultaneously infer antibody kinetics and infection histories from cross-sectional or longitudinal serological data. serosolver is a time-since-infection serodynamics model, meaning that infection times are back-calculated from one or more antibody measurements through an antibody kinetics model. serosolver can be used to infer infection timings during a study period using longitudinal measurements against a single antigen, or lifetime infection histories using multi-antigen serology panels. The package and model are described by Hay et al. here.

serosolver is back in active development to fix bugs, standardize variable names and add new features.

List of recent changes:

Overhaul of variable names (e.g., titre -> measurement, strain -> biomarker_id)
Consolidation of plotting functions
Moving more options and inputs behind the scenes to streamline the user interface
Generalization to consider multiple biomarker types per sample (e.g., antibody titre and avidity)
Support for continuous as well as discrete observations (e.g., can now fit to ELISA data as well as HAI titres)
IN PROGRESS Some small improvements to the MCMC sampler and parameter transformations
IN PROGRESS Improved guidance and support for using priors
IN PROGRESS Model infection histories and antibody kinetics as a function of demographic variables
IN PROGRESS Allow some infection states to be fixed during fitting
IN PROGRESS Inclusion of explicit immunity model
IN PROGRESS Ways to fix or estimate starting/baseline titres
IN PROGRESS Added tests

Install R
Install the development version of serosolver from GitHub:

devtools::install_github("seroanalytics/serosolver")
library(serosolver)

Read the guide to set up and run a simple implementation with a simulation model.

Additional vignettes:

Longitudinal data: estimating infection timings using longitudinal data, example of influenza A/H1N1p in Hong Kong
Cross-sectional data: estimating life-course infection histories from multi-strain serology, example of influenza A/H3N2 from the Fluscape cohort
TBC Overview of optional features: walkthrough of additional serosolver features and use cases, such as inclusion of biomarker-specific measurement offsets
TBC Multiple measurements: fitting serosolver to multiple biomarker types, example of binding avidity and ELISA measurements per sample
TBC Group-level differences: estimating demographic differences in antibody kinetics and attack rates

This is a basic example of simulating some serological data and fitting the model using the MCMC framework.

library(serosolver)
library(ggplot2)
library(plyr)
library(dplyr)
library(tidyr)
library(data.table)
library(doParallel)
library(coda)

## Load in example parameter values and antigenic map
data(example_par_tab)
data(example_antigenic_map)
data(example_antibody_data)
data(example_inf_hist)

plot_antibody_data(example_antibody_data,example_antigenic_map$inf_times,n_indivs=1:4,example_inf_hist)

## Run the MCMC
# This example uses prior version 2 (i.e. beta prior on phi with parameters shape1 and shape2)
output <- serosolver::serosolver(example_par_tab, example_antibody_data, example_antigenic_map,
                filename="readme", prior_version=2,n_chains=3,parallel=TRUE,
                mcmc_pars=c(adaptive_iterations=100000, iterations=500000),verbose=FALSE)

# Plot model predicted titres for a subset of individuals
chains <- load_mcmc_chains(location=getwd(),par_tab=example_par_tab,burnin = 100000,unfixed=TRUE)
plot_model_fits(chain = chains$theta_chain,
                infection_histories = chains$inf_chain,
                known_infection_history = example_inf_hist,
                antibody_data = example_antibody_data,individuals=1:4,
                antigenic_map=example_antigenic_map,
                par_tab=example_par_tab,
                orientation="cross-sectional")