serosolver

Inference framework for serological data

https://github.com/seroanalytics/serosolver

Repository

Inference framework for serological data

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  eval=TRUE
)
```
# Update 16/01/2024
`serosolver` is in the midst of an overhaul. Please use the `published` branch to ensure continued compatibility with existing projects.

```{r, eval=FALSE}
devtools::install_github("seroanalytics/serosolver",ref="published")
```

# serosolver

[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

`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](https://osf.io/preprints/osf/kqdsn), 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](https://doi.org/10.1371/journal.pcbi.1007840).

## Recent changes
`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)
* Model infection histories and antibody kinetics as a function of demographic variables
* Allow some infection states to be fixed during fitting
* Ways to fix or estimate starting/baseline titres
* _IN PROGRESS_ Some small improvements to the MCMC sampler and parameter transformations
* _IN PROGRESS_ Improved guidance and support for using priors
* _IN PROGRESS_ Inclusion of explicit immunity model
* _IN PROGRESS_ Added tests


## Installation
1. Install [R][r-project]

2. Install the development version of serosolver from [GitHub](https://github.com/seroanalytics/serosolver):

```{r installation,eval=FALSE}
devtools::install_github("seroanalytics/serosolver")
library(serosolver)
```
## Guide and vignettes

Read the [guide][vignette-doc] to set up and run a simple implementation with a simulation model.

Additional vignettes:

* [Longitudinal data][c1-vignette-doc]: estimating infection timings using longitudinal data, example of influenza A/H1N1p in Hong Kong
* [Cross-sectional data][c2-vignette-doc]: estimating life-course infection histories from multi-strain serology, example of influenza A/H3N2 from the [Fluscape cohort](https://pubmed.ncbi.nlm.nih.gov/26875566/)
* 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

[r-project]: http://cran.r-project.org
[vignette-doc]: https://seroanalytics.github.io/serosolver/articles/serosolver-quick_start_guide.html
[c1-vignette-doc]: https://seroanalytics.github.io/serosolver/articles/cs1_vignette.html
[c2-vignette-doc]: https://seroanalytics.github.io/serosolver/articles/cs2_vignette.html

## Example

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

```{r example_setup, message=FALSE,warning=FALSE}
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)
```
```{r example_plot, message=FALSE,warning=FALSE, fig.width=6,fig.height=5}
plot_antibody_data(example_antibody_data,example_antigenic_map$inf_times,n_indivs=1:4,example_inf_hist)
```

```{r example_mcmc, message=FALSE,warning=FALSE}
## 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, antigenic_map=example_antigenic_map,
                filename="readme", n_chains=3,parallel=TRUE,
                mcmc_pars=c(adaptive_iterations=10000, iterations=50000),verbose=TRUE)
```
```{r example_model_fits, message=FALSE,warning=FALSE, fig.width=6,fig.height=5}
# Plot model predicted titres for a subset of individuals
chains <- load_mcmc_chains(location=getwd(),par_tab=example_par_tab,burnin = 10000)
plot_model_fits(chain = chains$theta_chain,
                infection_histories = chains$inf_chain,
                known_infection_history = example_inf_hist,
                individuals=1:4,
                orientation="cross-sectional",
                settings=output$settings)

```

Owner

CodeMeta (codemeta.json)

{
  "@context": [
    "https://doi.org/10.5063/schema/codemeta-2.0",
    "http://schema.org"
  ],
  "@type": "SoftwareSourceCode",
  "identifier": "serosolver",
  "description": "Given a table of serological data for a population, infers the\n    presence and timing of infections based on raised titres.",
  "name": "serosolver: Inference Framework for Serological Data",
  "codeRepository": "https://github.com/seroanalytics/serosolver",
  "issueTracker": "https://github.com/seroanalytics/serosolver/issues",
  "license": "https://spdx.org/licenses/GPL-3.0",
  "version": "1.0.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "version": "3.6.1",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 3.6.1 (2019-07-05)",
  "author": [
    {
      "@type": "Person",
      "givenName": "James",
      "familyName": "Hay",
      "email": "jameshay218@gmail.com",
      "@id": "https://orcid.org/0000-0002-1998-1844"
    },
    {
      "@type": "Person",
      "givenName": "Adam",
      "familyName": "Kucharski",
      "email": "Adam.Kucharski@lshtm.ac.uk"
    },
    {
      "@type": "Person",
      "givenName": "Kylie",
      "familyName": "Ainslie",
      "email": "k.ainslie@imperial.ac.uk"
    },
    {
      "@type": "Person",
      "givenName": "Amanda",
      "familyName": "Minter",
      "email": "Amanda.Minter@lshtm.ac.uk"
    },
    {
      "@type": "Person",
      "givenName": "Steven",
      "familyName": "Riley",
      "email": "s.riley@imperial.ac.uk"
    }
  ],
  "contributor": {},
  "copyrightHolder": {},
  "funder": {},
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "James",
      "familyName": "Hay",
      "email": "jameshay218@gmail.com",
      "@id": "https://orcid.org/0000-0002-1998-1844"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "coda",
      "name": "coda",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=coda"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "foreach",
      "name": "foreach",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=foreach"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "Matrix",
      "name": "Matrix",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=Matrix"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    }
  ],
  "softwareRequirements": [
    {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.5.0"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "data.table",
      "name": "data.table",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=data.table"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "plyr",
      "name": "plyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=plyr"
    }
  ],
  "readme": "https://github.com/seroanalytics/serosolver/blob/master/README.md",
  "developmentStatus": "https://www.repostatus.org/#active",
  "citation": []
}

GitHub Events