From 152a9791c60b4035d245ddcd1731057af56bfeca Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Mon, 31 Jul 2023 19:10:48 +0100 Subject: [PATCH 1/6] Start on overall guide --- vignettes/guide.Rmd | 72 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 vignettes/guide.Rmd diff --git a/vignettes/guide.Rmd b/vignettes/guide.Rmd new file mode 100644 index 00000000..190c5fd6 --- /dev/null +++ b/vignettes/guide.Rmd @@ -0,0 +1,72 @@ +--- +title: "Guide to odin docs" +author: "Rich FitzJohn" +date: "`r Sys.Date()`" +output: + rmarkdown::html_vignette: + toc: true +vignette: > + %\VignetteIndexEntry{Guide to odin docs} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +`odin` has grown from just one package to a series of packages; this document aims to help orient you to the right place to understand how pieces fit together and where to find help. + +# The packages + +* [`odin`](https://mrc-ide.github.io/odin) contains the domain specific language (DSL), and the original implementation suitable for simple use. It can compile continuous time (ODE) and discrete time models to C, R or JavaScript. It contains no ability to do inference. +* [`dust`](https://mrc-ide.github.io/dust) contains an engine for running odin-style models in parallel. It supports both continuous time and discrete time models, but does not "know" anything about odin. This is the lower level support that many users will end up engaging with eventually. +* [`odin.dust`](https://mrc-ide.github.io/odin.dust) is a package for compiling `odin` models to work with `dust`. It will likely merge into `odin` once `dust` is on CRAN. +* [`mcstate`](https://mrc-ide.github.io/mcstate) is a package for performing inference with `odin` models compiled to work with `dust`. It implements a particle filter, particle MCMC and other statistical methods. + +# Documentation + +* [**Introduction to odin**](https://mrc-ide.github.io/odin/articles/odin.html): a tour of the original odin's features +* [**Discrete time models**](https://mrc-ide.github.io/odin/articles/discrete.html): +* [**Functions available in `odin`**](https://mrc-ide.github.io/odin/articles/functions.html): a brief summary of available functions in odin. This applies to both `odin` and `odin.dust` models, but with the conditions discussed in [the porting guide](https://mrc-ide.github.io/odin.dust/articles/porting.html) +* [**Debugging `odin` code**](https://mrc-ide.github.io/odin/articles/debugging.html): this applies to both `odin` and `odin.dust` models +* [**SIR models in `odin.dust`**](https://mrc-ide.github.io/odin.dust/articles/sir_models.html): shows how to use `odin.dust` to explore a stochastic SIR model, without doing inference on it +* [**Porting `odin` models to `odin.dust`**](https://mrc-ide.github.io/odin.dust/articles/porting.html): Differences between the original version of `odin` and the subset of the DSL supported by `odin.dust` + +The documentation for `mcstate` concerns mostly performing inference with `odin.dust` models + +* [**An introduction**](https://mrc-ide.github.io/mcstate/articles/sir_models.html): walks through performing inference with a simple SIR model +* [**Deterministic models**](https://mrc-ide.github.io/mcstate/articles/deterministic.html): describes how to create deterministic models from your stochastic models, and how these can speed up your inference. +* [**Running inference on models with multiple parameter sets at once**](https://mrc-ide.github.io/mcstate/articles/nested_sir_models.html): for example a model where parameters are structured by region. +* [**Parallelisation of inference**](https://mrc-ide.github.io/mcstate/articles/parallelisation.html): the two ways that you can parallelise models (at the chain and particle level), tradeoffs and how to control this. + +* [A stratgy for restarting a pMCMC inference in time](https://mrc-ide.github.io/mcstate/articles/restart.html), [Iterated filtering](https://mrc-ide.github.io/mcstate/articles/if2.html) - an algorithm familar to [`pomp`](https://cran.r-project.org/package=pomp) users, [comparison of our particle filter with a Kalman filter](https://mrc-ide.github.io/mcstate/articles/kalman.html). + +The documentation for [`dust`](https://mrc-ide.github.io/dust) is typically more advanced, but will be useful at times for users of `odin.dust` models + +* [**The ideas in `dust`**](https://mrc-ide.github.io/dust/articles/design.html): discusses what `dust` models can do, and how they try to help you. +* [**Introduction to dust**](https://mrc-ide.github.io/dust/articles/dust.html): covers manually building a `dust` model (which you are unlikely to want to do) but also covers what `dust` models can do, by example. +* [**Working with multiple parameter sets**](https://mrc-ide.github.io/dust/articles/multi.html): covers building dust objects that simultaneously run for multiple parameter sets at once. This is the only source of documentation for this at present. +* [**Comparing models and data**](https://mrc-ide.github.io/dust/articles/data.html): covers details of the lower-level model/data comparison. +* [**Random number generation**](https://mrc-ide.github.io/dust/articles/rng.html): covers details of how the random number generation works, how it can generate numbers in parallel, and performance differences with R's built-in generators. +* [**Running models on a GPU**](https://mrc-ide.github.io/dust/articles/gpu.html): lower-level details of running models on the GPU +* Other, even more specialised topics such as [details of the random number algorithms](https://mrc-ide.github.io/dust/articles/rng_algorithms.html), [using the `dust` RNG in other packages](https://mrc-ide.github.io/dust/articles/rng_package.html) and [generating random numbers in highly-parallel situations](https://mrc-ide.github.io/dust/articles/rng_distributed.html). + +Missing topics: + +* Using ODE models with `odin.dust` +* The DSL for comparing models and data +* Higher-level documentation of multiple parameter sets at once +* Higher-level documentation for running models on a GPU +* Lower-level documentation on the relationship between deterministic and stochastic models +* More details on constructing transformation functions in `mcstate` + +Each package also comes with reference documentation, which contains examples and detailed help for individual functiosn. + +* [`odin`](https://mrc-ide.github.io/odin/reference/index.html) +* [`odin.dust`](https://mrc-ide.github.io/odin.dust/reference/index.html) +* [`dust`](https://mrc-ide.github.io/dust/reference/index.html) +* [`mcstate`](https://mrc-ide.github.io/mcstate/reference/index.html) + +# Roadmap + +* Eventually we will merge `odin.dust` into `odin` (once `dust` is on CRAN) +* We may deprecate the original discrete time interface +* We will implement some of the missing features mentioned in the [porting guide](https://mrc-ide.github.io/odin.dust/articles/porting.html) within `odin.dust` +* We are designing a DSL for `mcstate` to make the inference part of the system nicer to work with; this will include an overhaul of the nested models. From c60fc7e7f2a84843c606257d09580f3457bdc181 Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Mon, 31 Jul 2023 10:45:50 +0100 Subject: [PATCH 2/6] Disable linter --- .lintr | 1 + 1 file changed, 1 insertion(+) diff --git a/.lintr b/.lintr index e0b75398..a00868fd 100644 --- a/.lintr +++ b/.lintr @@ -1,4 +1,5 @@ linters: linters_with_defaults( + indentation_linter = NULL, object_name_linter = NULL, object_length_linter = NULL, object_usage_linter = NULL, From 8e61083e4d204abf511a56f91f58999790ae1696 Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Mon, 31 Jul 2023 19:18:38 +0100 Subject: [PATCH 3/6] Update spelling --- DESCRIPTION | 2 +- R/js.R | 2 +- README.md | 2 ++ inst/WORDLIST | 11 +++++++++++ man/odin_js_versions.Rd | 2 +- vignettes/guide.Rmd | 5 ++--- 6 files changed, 18 insertions(+), 6 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 77218506..698ff868 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -47,7 +47,7 @@ Suggests: rmarkdown, testthat VignetteBuilder: knitr -RoxygenNote: 7.2.2 +RoxygenNote: 7.2.3 Roxygen: list(old_usage = TRUE, markdown = TRUE) Encoding: UTF-8 Language: en-GB diff --git a/R/js.R b/R/js.R index d4d9882f..2a6a081a 100644 --- a/R/js.R +++ b/R/js.R @@ -345,7 +345,7 @@ to_json_js <- function(x, auto_unbox = FALSE, digits = NA, ...) { ##' @title Report JS versions ##' ##' @return A named list of [package_version] versions, for `odinjs` -##' and other coponents used in the JavaScript support. +##' and other components used in the JavaScript support. ##' ##' @export ##' @examples diff --git a/README.md b/README.md index 8335ba91..92d47306 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ In addition, the same machinery can be used to generate discrete-time models tha `odin` works using code generation; the nice thing about this approach is that it never gets bored. So if the generated code has lots of tedious repetitive bits, they're at least likely to be correct (compared with implementing yourself). +There are lots of other things you can do with odin models, see [the guide](https://mrc-ide.github.io/odin/articles/guide.html) for to work out where to start. + ## Background The "deSolve" package for R is the de-facto way of solving differential equations in R; it provides excellent solvers and has remained stable for over a decade. However, users must implement equations in R and suffer a large speed cost, or implement their equations in C which is (depending on the complexity of the system) either routine and a bit boring, or complicated and error prone. This translation can be especially complicated with delay differential equations, or with models where the variables are more naturally stored as variable sized arrays. diff --git a/inst/WORDLIST b/inst/WORDLIST index ff9bd46b..f5cc8b94 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -3,7 +3,9 @@ CodeFactor Deserialise Dormand FitzJohn +JS Jombart +Kalman Lotka ODEs Poisson @@ -19,9 +21,11 @@ VignetteEngine VignetteIndexEntry Volterra WIP +api autogeneration codecov compiledCode +composable dC dI dN @@ -36,14 +40,18 @@ etc frac gcc github +ic +inspectable io ir +js json knitr lorenz mathcal mrc odin's +pMCMC pkgbuild proc rightarrow @@ -51,9 +59,12 @@ rmarkdown roxygen rtools sim +sprintf standalone struct susceptibles th toc +tradeoffs wikipedia +wodin diff --git a/man/odin_js_versions.Rd b/man/odin_js_versions.Rd index f2f80cf1..bf2b8ae3 100644 --- a/man/odin_js_versions.Rd +++ b/man/odin_js_versions.Rd @@ -8,7 +8,7 @@ odin_js_versions() } \value{ A named list of \link{package_version} versions, for \code{odinjs} -and other coponents used in the JavaScript support. +and other components used in the JavaScript support. } \description{ Report versions of JavaScript packages used to run odin models. diff --git a/vignettes/guide.Rmd b/vignettes/guide.Rmd index 190c5fd6..b13724a1 100644 --- a/vignettes/guide.Rmd +++ b/vignettes/guide.Rmd @@ -35,8 +35,7 @@ The documentation for `mcstate` concerns mostly performing inference with `odin. * [**Deterministic models**](https://mrc-ide.github.io/mcstate/articles/deterministic.html): describes how to create deterministic models from your stochastic models, and how these can speed up your inference. * [**Running inference on models with multiple parameter sets at once**](https://mrc-ide.github.io/mcstate/articles/nested_sir_models.html): for example a model where parameters are structured by region. * [**Parallelisation of inference**](https://mrc-ide.github.io/mcstate/articles/parallelisation.html): the two ways that you can parallelise models (at the chain and particle level), tradeoffs and how to control this. - -* [A stratgy for restarting a pMCMC inference in time](https://mrc-ide.github.io/mcstate/articles/restart.html), [Iterated filtering](https://mrc-ide.github.io/mcstate/articles/if2.html) - an algorithm familar to [`pomp`](https://cran.r-project.org/package=pomp) users, [comparison of our particle filter with a Kalman filter](https://mrc-ide.github.io/mcstate/articles/kalman.html). +* Other, less generally useful articles include: [A strategy for restarting a pMCMC inference in time](https://mrc-ide.github.io/mcstate/articles/restart.html), [Iterated filtering](https://mrc-ide.github.io/mcstate/articles/if2.html) - an algorithm familiar to [`pomp`](https://cran.r-project.org/package=pomp) users, [comparison of our particle filter with a Kalman filter](https://mrc-ide.github.io/mcstate/articles/kalman.html). The documentation for [`dust`](https://mrc-ide.github.io/dust) is typically more advanced, but will be useful at times for users of `odin.dust` models @@ -57,7 +56,7 @@ Missing topics: * Lower-level documentation on the relationship between deterministic and stochastic models * More details on constructing transformation functions in `mcstate` -Each package also comes with reference documentation, which contains examples and detailed help for individual functiosn. +Each package also comes with reference documentation, which contains examples and detailed help for individual functions. * [`odin`](https://mrc-ide.github.io/odin/reference/index.html) * [`odin.dust`](https://mrc-ide.github.io/odin.dust/reference/index.html) From 8c9cc451e3a7238e487c3beb43ecf3cbc6383740 Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Mon, 31 Jul 2023 19:26:40 +0100 Subject: [PATCH 4/6] Add bits on the js ecosystem --- inst/WORDLIST | 5 +++++ vignettes/guide.Rmd | 11 +++++++++++ 2 files changed, 16 insertions(+) diff --git a/inst/WORDLIST b/inst/WORDLIST index f5cc8b94..3a64fea5 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -15,12 +15,14 @@ Rmath Rtools SEIRDS Thibaut +TypeScript Vano VignetteEncoding VignetteEngine VignetteIndexEntry Volterra WIP +ac api autogeneration codecov @@ -35,7 +37,9 @@ dde deSolve debuggable deserialisation +dide dt +epimodels etc frac gcc @@ -66,5 +70,6 @@ susceptibles th toc tradeoffs +uk wikipedia wodin diff --git a/vignettes/guide.Rmd b/vignettes/guide.Rmd index b13724a1..01ea918e 100644 --- a/vignettes/guide.Rmd +++ b/vignettes/guide.Rmd @@ -63,6 +63,17 @@ Each package also comes with reference documentation, which contains examples an * [`dust`](https://mrc-ide.github.io/dust/reference/index.html) * [`mcstate`](https://mrc-ide.github.io/mcstate/reference/index.html) +# The TypeScript ecosystem + +In addition to the above, we are growing our ability to work with JavaScript models - the main output of this is [wodin](https://github.com/mrc-ide/wodin), an interface for running `odin` models on the web, which you can see at [`epimodels.dide.ic.ac.uk](https://epimodels.dide.ic.ac.uk/). + +* [`wodin`](https://github.com/mrc-ide/wodin): wodin itself +* [`dopri-js`](https://github.com/mrc-ide/dopri-js): an ODE solver in TypeScript allowing smooth interpolation of its solutions +* [`dfoptim`](https://github.com/reside-ic/dfoptim): derivative-free optimisation methods for TypeScript +* [`odin-js`](https://github.com/mrc-ide/odin-js): TypeScript support for running continuous time `odin` models +* [`dust-js`](https://github.com/mrc-ide/dust-js): An implementation of part of the `dust` interface in TypeScript +* [`random-js`](https://github.com/reside-ic/random-js): Another random number library for JavaScript + # Roadmap * Eventually we will merge `odin.dust` into `odin` (once `dust` is on CRAN) From cef8a07da4bdb0d70442a8017c8f1cc2930bc8a6 Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Mon, 31 Jul 2023 19:27:31 +0100 Subject: [PATCH 5/6] Bump version --- DESCRIPTION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 698ff868..59b2c245 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: odin Title: ODE Generation and Integration -Version: 1.5.4 +Version: 1.5.5 Authors@R: c(person("Rich", "FitzJohn", role = c("aut", "cre"), email = "rich.fitzjohn@gmail.com"), person("Thibaut", "Jombart", role = "ctb"), From cf55eee3b9aa627947d299b5ca50a4b6f07d7303 Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Wed, 2 Aug 2023 13:28:53 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Wes Hinsley --- README.md | 2 +- vignettes/guide.Rmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 92d47306..a9b5d3bd 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ In addition, the same machinery can be used to generate discrete-time models tha `odin` works using code generation; the nice thing about this approach is that it never gets bored. So if the generated code has lots of tedious repetitive bits, they're at least likely to be correct (compared with implementing yourself). -There are lots of other things you can do with odin models, see [the guide](https://mrc-ide.github.io/odin/articles/guide.html) for to work out where to start. +There are lots of other things you can do with odin models, see [the guide](https://mrc-ide.github.io/odin/articles/guide.html) to work out where to start. ## Background diff --git a/vignettes/guide.Rmd b/vignettes/guide.Rmd index 01ea918e..7393ca9f 100644 --- a/vignettes/guide.Rmd +++ b/vignettes/guide.Rmd @@ -65,7 +65,7 @@ Each package also comes with reference documentation, which contains examples an # The TypeScript ecosystem -In addition to the above, we are growing our ability to work with JavaScript models - the main output of this is [wodin](https://github.com/mrc-ide/wodin), an interface for running `odin` models on the web, which you can see at [`epimodels.dide.ic.ac.uk](https://epimodels.dide.ic.ac.uk/). +In addition to the above, we are growing our ability to work with JavaScript models - the main output of this is [wodin](https://github.com/mrc-ide/wodin), an interface for running `odin` models on the web, which you can see at [`epimodels.dide.ic.ac.uk`](https://epimodels.dide.ic.ac.uk/). * [`wodin`](https://github.com/mrc-ide/wodin): wodin itself * [`dopri-js`](https://github.com/mrc-ide/dopri-js): an ODE solver in TypeScript allowing smooth interpolation of its solutions