Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mrc-ide/leapfrog
Multistate population projection model for demographic estimation.
https://github.com/mrc-ide/leapfrog
Last synced: about 2 months ago
JSON representation
Multistate population projection model for demographic estimation.
- Host: GitHub
- URL: https://github.com/mrc-ide/leapfrog
- Owner: mrc-ide
- License: other
- Created: 2020-02-19T07:12:37.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-06T16:01:43.000Z (5 months ago)
- Last Synced: 2024-10-06T21:16:11.526Z (3 months ago)
- Language: C++
- Size: 212 MB
- Stars: 2
- Watchers: 4
- Forks: 5
- Open Issues: 39
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
options(tidyverse.quiet = TRUE)
```
# leapfrog
[](https://github.com/mrc-ide/leapfrog/actions)
[](https://codecov.io/gh/mrc-ide/leapfrog?branch=master)
Leapfrog is a multistate population projection model for demographic and HIV epidemic estimation.
The name _leapfrog_ is in honor of [Professor](https://blogs.lshtm.ac.uk/alumni/2018/07/16/obituary-professor-basia-zaba/) Basia [Zaba](https://translate.google.co.uk/#view=home&op=translate&sl=pl&tl=en&text=%C5%BBaba).
*Note: the CCMPP model and implementation of Bayesian Population Reconstruction in TMB previously here have moved to a separate repository: https://www.github.com/mrc-ide/ccmpp.tmb*
## Simulation model
The simulation model is implemented in a header-only C++ library located in [`inst/include/leapfrog-raw.h`](inst/include/leapfrog-raw.h). This location allows the C++ code to be imported in other R packages via specifying `LinkingTo: leapfrog` in the `DESCRIPTION` file.
The simulation model is callable in R via a wrapper function `leafrogR()` created with [Rcpp](https://www.rcpp.org).
## Installation
Install the development version from [GitHub](https://github.com/mrc-ide/leapfrog) via devtools:
``` r
# install.packages("devtools")
devtools::install_github("mrc-ide/leapfrog")
```
## Example
The file `pjnz/bwa2021_v6.13.pjnz` contains an example Spectrum file constructed
from default country data for Botswana in Spectrum v2.13 (December 2021).
Prepare model inputs.
```{r example}
library(leapfrog)
pjnz <- system.file("pjnz/bwa2021_v6.13.pjnz", package = "leapfrog")
demp <- prepare_leapfrog_demp(pjnz)
hivp <- prepare_leapfrog_projp(pjnz)
```
Simulate 'full' age group (single-year age) and 'coarse' age group (collapsed
age groups) models.
```{r simulate_leapfrog}
lsimF <- leapfrogR(demp, hivp, hiv_strat = "full")
lsimC <- leapfrogR(demp, hivp, hiv_strat = "coarse")
```
Compare the HIV prevalence age 15-49 years and AIDS deaths 50+ years. Deaths 50+
years are to show some noticeable divergence between the `"full"` and `"coarse"`
age group simulations.
```{r sim_prev}
prevF <- colSums(lsimF$hivpop1[16:50,,],,2) / colSums(lsimF$totpop1[16:50,,],,2)
prevC <- colSums(lsimC$hivpop1[16:50,,],,2) / colSums(lsimC$totpop1[16:50,,],,2)
deathsF <- colSums(lsimF$hivdeaths[51:81,,],,2)
deathsC <- colSums(lsimC$hivdeaths[51:81,,],,2)
plot(1970:2030, prevF, type = "l", main = "Prevalence 15-49")
lines(1970:2030, prevC, col = 2)
plot(1970:2030, deathsF, type = "l", main = "AIDS Deaths 50+ years")
lines(1970:2030, deathsC, col = 2)
```
### Benchmarking
_Note: The function `devtools::load_all()` invokes `pkgbuild::compile_dll()`,
which executes with default arguemnt `debug = TRUE`. This compiles the package
with `-O0` compiler optimisation flags. For benchmarking, make sure to install
the package or compile the DLL with `pkgbuild::compile_dll(debug = FALSE)`._
```{r benchmarking}
library(bench)
library(eppasm)
fp <- eppasm::prepare_directincid(pjnz)
bench::mark(leapfrogR(demp, hivp, hiv_strat = "full"),
leapfrogR(demp, hivp, hiv_strat = "coarse"),
eppasm::simmod(fp),
check = FALSE)
```
## Code design
### Simulation model
The simulation model is implemented as templated C++ code in `inst/include/leapfrog-raw.h`.
This is the simulation model may be developed as a standalone C++ library
that can be called by other software without requiring R-specific code features.
The code uses header-only open source libraries to maximize portability.
### R functions
The file `src/leapfrogR.cpp` contains R wrapper functions for the model simulation
via [Rcpp](http://dirk.eddelbuettel.com/code/rcpp.html) and
[RcppEigen](http://dirk.eddelbuettel.com/code/rcpp.eigen.html).
## Development notes
### Simulation model
* The model was implemented using _Eigen::Tensor_ containers. These were preferred
for several reasons:
* Benchmarking found they were slighlty more efficient than _boost::multi_array_.
* Column-major indexing in the same order as R
* Other statistical packages (e.g. TMB, Stan) rely heavily on _Eigen_ so using
_Eigen_ containers slims the dependencies.