README.md

dust

Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. R build status Build status CodeFactor codecov.io

Stochastic models appear in many domains as they are easy to write out, but hard to analyse without running many realisations of the process. dust provides an engine for running stochastic models, taking care of many bookkeeping details such as:

Get started

Two vignettes provide an overview of the package, depending on your tastes:

There are further vignettes describing details:

And several on the random number generator, around which dust is built:

The C++ API is documented in a separate set of documentation

You can also read our open access paper describing dust and some related tools that use it:

FitzJohn, Knock, Whittles, Perez-Guizman, Bhatia, Guntoro, Watson, Whittaker, Ferguson, Cori, Baguelin, Lees 2021: Reproducible parallel inference and simulation of stochastic state space models using odin, dust, and mcstate, Wellcome Open Research 5, 288

Higher-level

The dust package, while designed to be user-friendly, is lower-level than many users need. The odin.dust package provides a way of compiling stochastic odin models to work with dust. For example, to create a parallel epidemiological model, one might write simply:

sir <- odin.dust::odin_dust({
  update(S) <- S - n_SI
  update(I) <- I + n_SI - n_IR
  update(R) <- R + n_IR

  n_IR <- rbinom(I, 1 - exp(-beta * I / (S + I + R)))
  n_SI <- rbinom(S, 1 - exp(-gamma))

  initial(S) <- S_ini
  initial(I) <- I_ini
  initial(R) <- 0

  S_ini <- user(1000)
  I_ini <- user(10)
  beta <- user(0.2)
  gamma <- user(0.1)
})

Use-cases

We use dust to power several epidemiological models. Public examples include:

Installation

To install dust:

# install.packages("drat") # -- if you don't have drat installed
drat:::add("ncov-ic")
install.packages("dust")

You will need a compiler to install dependencies for the package, and to build any models with dust. dust uses pkgbuild to build its shared libraries so use pkgbuild::check_build_tools() to see if your system is ok to use.

The development version of the package can be installed directly from GitHub if you prefer with:

remotes::install_github("mrc-ide/dust", upgrade = FALSE)

License

MIT © Imperial College of Science, Technology and Medicine



mrc-ide/dust documentation built on Aug. 26, 2022, 12:03 p.m.