-
Notifications
You must be signed in to change notification settings - Fork 7
/
README.Rmd
117 lines (94 loc) · 5.44 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{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
[](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.
<details>
<summary>List of recent changes:</summary>
* 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
</details>
## 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, 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)
```