Start on migration vignette

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"),

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)
 ##'

_pkgdown.yml

@@ -131,3 +131,4 @@ articles:
     contents:
     - dsl-errors
     - samplers
+    - migration

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

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 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?
+
+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 a 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 `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).