leapfrog

Leapfrog is a multistate population projection model for demographic and HIV epidemic estimation with interfaces in R, Python, C++ and Delphi.

The name leapfrog is in honor of Professor Basia Zaba.

Installation

R

Please install from our r-universe:

install.packages(
  "leapfrog",
  repos = c("https://hivtools.r-universe.dev", "https://cloud.r-project.org"))

You can install the development version of leapfrog from GitHub with:

# install.packages("remotes")
remotes::install_github("hivtools/leapfrog", subdir = "leapfrogr", ref = "r-release")

Python

Note the Python interface is a work in progress

Install from pypi

pip install leapfrog-py

Simulation model

The simulation model is implemented in a header-only C++ library located in leapfrog-core/include/leapfrog.hpp. This location allows the C++ code to be imported in other R packages via specifying LinkingTo: leapfrog in the DESCRIPTION file.

Important

We use C++20 for this package. Please make sure you have a compiler that is compatible.

See the R README for details of running the model from R.

Code design

Simulation model

The simulation model is implemented as templated C++ code in leapfrog-core/include/leapfrog.hpp. This is so 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.

Code generation

To change what parameters can be passed in from any interface or the structure of Intermediate, State or OutputState, please modify json files here.

Then to run code generation run ./scripts/generate. See codegen/README.md for more details.

Development

See the development vignette for details.

Simulation model

• The model was initially implemented using Eigen::Tensor however, we then switched to nda. This was preferred for several reasons:
  • Benchmarking found nda was twice as fast as eigen for our models.
  • Eigen supports either knowing all the dimensions at compile time or none of them. We have a lot of tensors where we know all the sizes except the last dimension (time dimension usually). nda has support for partial compile time known dimensions which is probably where most of the speed up is coming from.
  • The package is currently being maintained.
  • They have good error handling. They have test suites that test that one error is being produced for common error in heavily templated C++ code.
  • Eigen had some compiler warnings when it was compiled.
  • Column-major indexing in the same order as R (Eigen also has this).

Testing

To run any of the tests you will need to generate test data. To do this you must have R installed, you'll have to change directories to leapfrogr and run

./scripts/create_test_data.R

License

MIT © Imperial College of Science, Technology and Medicine