diff --git a/DESCRIPTION b/DESCRIPTION index 21214c4..0faab03 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -12,29 +12,18 @@ Authors@R: c( person("University College London", role = "cph"), person("Engineering and Physical Sciences Research Council", role = "fnd") ) -Description: Functions for simulating Markov chains using the Barker proposal - to compute Markov chain Monte Carlo (MCMC) estimates of expectations with - respect to a target distribution on a real-valued vector space. The Barker - proposal, described in Livingstone and Zanella (2022) - , is a gradient-based MCMC algorithm inspired by the - Barker accept-reject rule. It combines the robustness of simpler MCMC - schemes, such as random-walk Metropolis, with the efficiency of - gradient-based methods, such as the Metropolis adjusted Langevin algorithm. - The key function provided by the package is sample_chain(), which allows - sampling a Markov chain with a specified target distribution as its - stationary distribution. The chain is sampled by generating proposals and - accepting or rejecting them using a Metropolis-Hasting acceptance rule. - During an initial warm-up stage, the parameters of the proposal distribution - can be adapted, with adapters available to both: tune the scale of the - proposals by coercing the average acceptance rate to a target value; tune - the shape of the proposals to match covariance estimates under the target - distribution. As well as the default Barker proposal, the package also - provides implementations of alternative proposal distributions, such as - (Gaussian) random walk and Langevin proposals. Optionally, if 'BridgeStan's - R interface , - available on GitHub , is installed, - then 'BridgeStan' can be used to specify the target distribution to sample - from. +Description: Functions for simulating Markov chains to compute Markov chain + Monte Carlo (MCMC) estimates of expectations with respect to a target + distribution on a real-valued vector space. The package has built-in support + for using Metropolis-Hastings transitions with random-walk, Langevin, + Hamiltonian or Barker proposals, and is designed to be easy to extend with + additional algorithms. Proposal shape and scale parameters can be + automatically adapted in an initial warm-up stage. The package has a modular + design allowing different algorithmic components such as proposals and + adapters to be mixed and matched. If 'BridgeStan's R interface + , available on + GitHub , is installed, then it can + be used to specify the target distribution to sample from. License: MIT + file LICENSE Encoding: UTF-8 Roxygen: list(markdown = TRUE) diff --git a/README.Rmd b/README.Rmd index 9b190f4..f90a49e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -25,11 +25,14 @@ knitr::opts_chunk$set( [![JOSS-status](https://joss.theoj.org/papers/b3d646dcf01299076e8a724ec8d909dc/status.svg)](https://joss.theoj.org/papers/b3d646dcf01299076e8a724ec8d909dc) -`rmcmc` is an R package for simulating Markov chains using the Barker proposal -to compute _Markov chain Monte Carlo_ (MCMC) estimates of expectations with -respect to a target distribution on a real-valued vector space. -The Barker proposal, described in [Livingstone and Zanella (2022)](https://doi.org/10.1111/rssb.12482), -is a gradient-based MCMC algorithm inspired by the Barker accept-reject rule. +`rmcmc` is an R package for simulating Markov chains to compute _Markov chain Monte Carlo_ (MCMC) +estimates of expectations with respect to a target distribution on a real-valued vector space. +The package has built-in support for using Metropolis-Hastings transitions with random-walk, Langevin, +Hamiltonian or Barker proposals, and is designed to be easy to extend with additional algorithms. + +By default chains are sampled using the Barker proposal, +described in [Livingstone and Zanella (2022)](https://doi.org/10.1111/rssb.12482), +which is a gradient-based MCMC algorithm inspired by the Barker accept-reject rule. It combines the robustness of simpler MCMC schemes, such as random-walk Metropolis, with the efficiency of gradient-based methods, such as the Metropolis adjusted Langevin algorithm. @@ -38,15 +41,23 @@ which allows sampling a Markov chain with a specified target distribution as its The chain is sampled by generating proposals and accepting or rejecting them using a Metropolis-Hasting acceptance rule. During an initial warm-up stage, the parameters of the proposal distribution can be adapted, -with adapters available to both: -tune the scale of the proposals by coercing the average acceptance rate to a target value; -tune the shape of the proposals to match covariance estimates under the target distribution. -As well as the default Barker proposal, the package also provides implementations of alternative proposal distributions, -such as (Gaussian) random walk and Langevin proposals. -Optionally, if [BridgeStan's R interface](https://roualdes.us/bridgestan/latest/languages/r.html), -available [on GitHub](https://github.com/roualdes/bridgestan), is installed, -[then BridgeStan can be used to specify the target distribution to sample -from](https://github-pages.ucl.ac.uk/rmcmc/articles/interfacing-with-stan-models.html). +with adapters available to both tune the scale and shape of proposals. + +The package has a modular design allowing different algorithmic components such +as proposals and adapters to be mixed and matched and to allow to it interface +with various existing packages: + +- If [BridgeStan's R interface](https://roualdes.us/bridgestan/latest/languages/r.html), + available [on GitHub](https://github.com/roualdes/bridgestan), is installed, + [then BridgeStan can be used to specify the target distribution to sample from]( + https://github-pages.ucl.ac.uk/rmcmc/articles/interfacing-with-stan-models.html). +- The robust adaptive Metropolis algorithm described in [Vihola (2012)]( + https://doi.org/10.1007/s11222-011-9269-5) can be used for adapting the + proposal scale and shape if [the _ramcmc_ package]( + https://cran.r-project.org/web/packages/ramcmc/index.html) is installed. +- The generated chain output can be directly passed to functions for + computing summary statistics and convergence diagnostics in + [the _posterior_ package](https://mc-stan.org/posterior/). ## Installation diff --git a/README.md b/README.md index be0d5c0..d121455 100644 --- a/README.md +++ b/README.md @@ -14,33 +14,46 @@ [![JOSS-status](https://joss.theoj.org/papers/b3d646dcf01299076e8a724ec8d909dc/status.svg)](https://joss.theoj.org/papers/b3d646dcf01299076e8a724ec8d909dc) -`rmcmc` is an R package for simulating Markov chains using the Barker -proposal to compute *Markov chain Monte Carlo* (MCMC) estimates of -expectations with respect to a target distribution on a real-valued -vector space. The Barker proposal, described in [Livingstone and Zanella -(2022)](https://doi.org/10.1111/rssb.12482), is a gradient-based MCMC -algorithm inspired by the Barker accept-reject rule. It combines the -robustness of simpler MCMC schemes, such as random-walk Metropolis, with -the efficiency of gradient-based methods, such as the Metropolis -adjusted Langevin algorithm. +`rmcmc` is an R package for simulating Markov chains to compute *Markov +chain Monte Carlo* (MCMC) estimates of expectations with respect to a +target distribution on a real-valued vector space. The package has +built-in support for using Metropolis-Hastings transitions with +random-walk, Langevin, Hamiltonian or Barker proposals, and is designed +to be easy to extend with additional algorithms. + +By default chains are sampled using the Barker proposal, described in +[Livingstone and Zanella (2022)](https://doi.org/10.1111/rssb.12482), +which is a gradient-based MCMC algorithm inspired by the Barker +accept-reject rule. It combines the robustness of simpler MCMC schemes, +such as random-walk Metropolis, with the efficiency of gradient-based +methods, such as the Metropolis adjusted Langevin algorithm. The key function provided by the package is `sample_chain()`, which allows sampling a Markov chain with a specified target distribution as its stationary distribution. The chain is sampled by generating proposals and accepting or rejecting them using a Metropolis-Hasting acceptance rule. During an initial warm-up stage, the parameters of the -proposal distribution can be adapted, with adapters available to both: -tune the scale of the proposals by coercing the average acceptance rate -to a target value; tune the shape of the proposals to match covariance -estimates under the target distribution. As well as the default Barker -proposal, the package also provides implementations of alternative -proposal distributions, such as (Gaussian) random walk and Langevin -proposals. Optionally, if [BridgeStan’s R -interface](https://roualdes.us/bridgestan/latest/languages/r.html), -available [on GitHub](https://github.com/roualdes/bridgestan), is -installed, [then BridgeStan can be used to specify the target -distribution to sample -from](https://github-pages.ucl.ac.uk/rmcmc/articles/interfacing-with-stan-models.html). +proposal distribution can be adapted, with adapters available to both +tune the scale and shape of proposals. + +The package has a modular design allowing different algorithmic +components such as proposals and adapters to be mixed and matched and to +allow to it interface with various existing packages: + +- If [BridgeStan’s R + interface](https://roualdes.us/bridgestan/latest/languages/r.html), + available [on GitHub](https://github.com/roualdes/bridgestan), is + installed, [then BridgeStan can be used to specify the target + distribution to sample + from](https://github-pages.ucl.ac.uk/rmcmc/articles/interfacing-with-stan-models.html). +- The robust adaptive Metropolis algorithm described in [Vihola + (2012)](https://doi.org/10.1007/s11222-011-9269-5) can be used for + adapting the proposal scale and shape if [the *ramcmc* + package](https://cran.r-project.org/web/packages/ramcmc/index.html) is + installed. +- The generated chain output can be directly passed to functions for + computing summary statistics and convergence diagnostics in [the + *posterior* package](https://mc-stan.org/posterior/). ## Installation @@ -128,4 +141,4 @@ results <- sample_chain( plot(results$traces[, "x"], results$traces[, "y"], col = "#1f77b4", pch = 20) ``` - + diff --git a/man/figures/README-banana-samples-1.png b/man/figures/README-banana-samples-1.png index c630411..5a9a37f 100644 Binary files a/man/figures/README-banana-samples-1.png and b/man/figures/README-banana-samples-1.png differ