From dc5a183498c0f0baeb7e6f4ce8b714366512d7a6 Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Fri, 13 Dec 2024 17:19:33 +0000 Subject: [PATCH 1/4] Add basic migration vignette --- _pkgdown.yml | 1 + vignettes/migration.Rmd | 99 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 vignettes/migration.Rmd diff --git a/_pkgdown.yml b/_pkgdown.yml index 81731d32..bebcaf20 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -131,3 +131,4 @@ articles: contents: - dsl-errors - samplers + - migration diff --git a/vignettes/migration.Rmd b/vignettes/migration.Rmd new file mode 100644 index 00000000..187502e1 --- /dev/null +++ b/vignettes/migration.Rmd @@ -0,0 +1,99 @@ +--- +title: "Migration from mcstate" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Migration from mcstate} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +`monty` is the spiritual replacement for [`mcstate`](https://mrc-ide.github.io/mcstate/), which was used for inference of [odin.dust](https://mrc-ide.github.io/odin.dust/) models from 2020 to 2024. + +Unlike with the new versions of [`odin`](https://mrc-ide.github.io/odin/) ([`odin2`](https://mrc-ide.github.io/odin2/)) and [`dust`](https://mrc-ide.github.io/dust/) ([`dust2`](https://mrc-ide.github.io/dust2/)), we have not changed `mcstate` in place as we no longer felt that the name as appropriate; mcstate was explicitly about working with state space models, while `monty` is about Monte Carlo methods in general. And Wes has a goat called Monty, so here we are. + +# Where is everything? + +Some features have moved out of this package and into `dust2`: + +## The particle filter + +The particle filter has moved into [`dust2`](https://mrc-ide.github.io/dust2), see [`dust2::dust_filter_create`](https://mrc-ide.github.io/dust2/reference/dust_filter_create.html) + +What was previously a method on the old `particle_filter` object has now changed to be free function: + +Action | mcstate | dust2 +-------------------------+---------------------+----------------------------- +Allocate | `$new()` | `dust_filter_create()` (1) +Run | `$run()` | `dust_likelihood_run()` +Stateful run | `$run_begin()` | Not supported +Get final state | `$state()` | `dust_likelihood_last_state()` +Get trajectories | `$history()` | `dust_likelihood_last_trajectories()` +Get ODE statistics | `$ode_statistics()` | Not yet supported +Get intermediate state | `$restart_state()` | Not yet supported +Get inputs | `$inputs` | Not yet supported +Change number of threads | `set_n_threads()` | Not supported + +1. Or `dust_unfilter_create` for deterministic models + +In addition, differentiable deterministic models have `dust_likelihood_last_gradient()` to get the gradient of the likelihood at the last point. + +## Other state space methods + +In mcstate, we implemented two other sequential Monte Carlo methods: SMC^2 and IF2. Neither of these have been reimplemented yet, but these will appear in dust if and when we do so. Please let us know if you used these! + +# Running MCMC + +How these are specified and configured has totally changed, to the point where it is not really meaningful to do a table-based comparison of methods. + +A typical use with mcstate looked like this (adapted with simplification from the old [SIR models vignette](https://mrc-ide.github.io/mcstate/articles/sir_models.html)) + +```r +filter <- mcstate::particle_filter$new(data = ..., model = ..., compare = ..., + n_particles = ...) +beta <- mcstate::pmcmc_parameter("beta", 0.2, min = 0) +gamma <- mcstate::pmcmc_parameter("gamma", 0.1, min = 0, prior = function(p) + dgamma(p, shape = 1, scale = 0.2, log = TRUE)) + +proposal_matrix <- diag(0.1, 2) +mcmc_pars <- mcstate::pmcmc_parameters$new(list(beta = beta, gamma = gamma), + proposal_matrix) +control <- mcstate::pmcmc_control( + n_steps, + save_state = TRUE, + save_trajectories = TRUE, + progress = TRUE) +samples <- mcstate::pmcmc(mcmc_pars, filter, control = control) +``` + +With monty this would look more like: + +```r +filter <- dust_filter_create(generator, time_start, data, n_particles) +packer <- monty_packer(c("beta", "gamma")) +model <- dust_likelihood_monty(filter, packer, + save_state = TRUE, + save_trajectories = TRUE) +prior <- monty_dsl({ + beta ~ Uniform(0, 100) + gamma ~ Gamma(shape = 1, scale = 0.2) +}) +sampler <- monty_sampler_random_walk(diag(0.2, 2)) +samples <- monty_sample(model + prior, sampler, n_steps) +``` + +which contains roughly the same bits of information but in quite a different presentation: + +**The way that parameters are specified**: in `mcstate` we had `pmcmc_parameter` and `pmcmc_parameters`, one of which was a function and the other was a combination that included the sampler's proposal kernel! This is all a bit silly. Now: + * we use our [packer interface](https://mrc-ide.github.io/monty/reference/monty_packer.html) to smooth over the gap between how it is convenient to represent parameters in your odin model and how you need to represent them to think about moving around in parameter space + * we use the DSL to specify priors, removing the need to write out distributions, to sample from these distributions automatically and to prevent forgetting the `log = TRUE` on densities. + +**The the `pmcmc_control` object has gone**: this contained information that really effected the filter (e.g., `save_state` which has moved into the `dust_likelihood_monty` function) and the running of the chain itself. + +**The control over samplers has moved into a new sampler object**: we needed this additional level of control to allow different samplers to be used in different situations (e.g., to allow HMC in the case of a deterministic differentiable density). From c12ddbe4bc35ba002ebea91edb1db23754cafa9b Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Fri, 13 Dec 2024 17:20:27 +0000 Subject: [PATCH 2/4] Fix spelling --- R/random.R | 2 +- inst/WORDLIST | 4 ++++ man/monty_rng_create.Rd | 2 +- 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/R/random.R b/R/random.R index a9efbe4b..e2367fe0 100644 --- a/R/random.R +++ b/R/random.R @@ -22,7 +22,7 @@ ##' and you set `preserve_stream_dimension` to `FALSE` then we will ##' drop this dimension and return a matrix. ##' -##' @title Create a monty random number genreator +##' @title Create a monty random number generator ##' ##' @param n_streams The number of streams to create (see Details) ##' diff --git a/inst/WORDLIST b/inst/WORDLIST index 7611b273..2ac6dd49 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -2,11 +2,13 @@ CMD COVID HMC HPC +HWHM Hasting OpenMP Poisson R's SEF +SMC VCV WIP burnin @@ -27,6 +29,7 @@ parallelisable parameterisations pmcmc quosures +raws restartable rhyper rlang's @@ -36,3 +39,4 @@ splitmix st stan th +untruncated diff --git a/man/monty_rng_create.Rd b/man/monty_rng_create.Rd index aabbe6c9..62a44ecb 100644 --- a/man/monty_rng_create.Rd +++ b/man/monty_rng_create.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/random.R \name{monty_rng_create} \alias{monty_rng_create} -\title{Create a monty random number genreator} +\title{Create a monty random number generator} \usage{ monty_rng_create( n_streams = 1L, From 414dc7a08aa270241449156aadafac85958b7527 Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Mon, 16 Dec 2024 09:19:54 +0000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Wes Hinsley --- vignettes/migration.Rmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/vignettes/migration.Rmd b/vignettes/migration.Rmd index 187502e1..2e0e2178 100644 --- a/vignettes/migration.Rmd +++ b/vignettes/migration.Rmd @@ -16,7 +16,7 @@ knitr::opts_chunk$set( `monty` is the spiritual replacement for [`mcstate`](https://mrc-ide.github.io/mcstate/), which was used for inference of [odin.dust](https://mrc-ide.github.io/odin.dust/) models from 2020 to 2024. -Unlike with the new versions of [`odin`](https://mrc-ide.github.io/odin/) ([`odin2`](https://mrc-ide.github.io/odin2/)) and [`dust`](https://mrc-ide.github.io/dust/) ([`dust2`](https://mrc-ide.github.io/dust2/)), we have not changed `mcstate` in place as we no longer felt that the name as appropriate; mcstate was explicitly about working with state space models, while `monty` is about Monte Carlo methods in general. And Wes has a goat called Monty, so here we are. +Unlike with the new versions of [`odin`](https://mrc-ide.github.io/odin/) ([`odin2`](https://mrc-ide.github.io/odin2/)) and [`dust`](https://mrc-ide.github.io/dust/) ([`dust2`](https://mrc-ide.github.io/dust2/)), we have not changed `mcstate` in place as we no longer felt that the name was appropriate; mcstate was explicitly about working with state space models, while `monty` is about Monte Carlo methods in general. And Wes has a goat called Monty, so here we are. # Where is everything? @@ -26,7 +26,7 @@ Some features have moved out of this package and into `dust2`: The particle filter has moved into [`dust2`](https://mrc-ide.github.io/dust2), see [`dust2::dust_filter_create`](https://mrc-ide.github.io/dust2/reference/dust_filter_create.html) -What was previously a method on the old `particle_filter` object has now changed to be free function: +What was previously a method on the old `particle_filter` object has now changed to be a free function: Action | mcstate | dust2 -------------------------+---------------------+----------------------------- @@ -94,6 +94,6 @@ which contains roughly the same bits of information but in quite a different pre * we use our [packer interface](https://mrc-ide.github.io/monty/reference/monty_packer.html) to smooth over the gap between how it is convenient to represent parameters in your odin model and how you need to represent them to think about moving around in parameter space * we use the DSL to specify priors, removing the need to write out distributions, to sample from these distributions automatically and to prevent forgetting the `log = TRUE` on densities. -**The the `pmcmc_control` object has gone**: this contained information that really effected the filter (e.g., `save_state` which has moved into the `dust_likelihood_monty` function) and the running of the chain itself. +**The `pmcmc_control` object has gone**: this contained information that really affected the filter (e.g., `save_state` which has moved into the `dust_likelihood_monty` function) and the running of the chain itself. **The control over samplers has moved into a new sampler object**: we needed this additional level of control to allow different samplers to be used in different situations (e.g., to allow HMC in the case of a deterministic differentiable density). From fc2b4f4ca9495d2be5d24ee48520f71498ef2b3b Mon Sep 17 00:00:00 2001 From: Rich FitzJohn Date: Mon, 16 Dec 2024 09:43:19 +0000 Subject: [PATCH 4/4] Bump version --- DESCRIPTION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index f58a13e5..0a825a6d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: monty Title: Monte Carlo Models -Version: 0.3.21 +Version: 0.3.22 Authors@R: c(person("Rich", "FitzJohn", role = c("aut", "cre"), email = "rich.fitzjohn@gmail.com"), person("Wes", "Hinsley", role = "aut"),