Make package description in metadata and README more generic

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)
-    <doi: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. 
-    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.
+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 
+    <https://roualdes.us/bridgestan/latest/languages/r.html>, available on
+    GitHub <https://github.com/roualdes/bridgestan>, 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)

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)
 <!-- badges: end -->
 
-`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
 

README.md

@@ -14,33 +14,46 @@
 [![JOSS-status](https://joss.theoj.org/papers/b3d646dcf01299076e8a724ec8d909dc/status.svg)](https://joss.theoj.org/papers/b3d646dcf01299076e8a724ec8d909dc)
 <!-- badges: end -->
 
-`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)
 ```
 
-<img src="man/figures/README-banana-samples-1.png" width="100%" />
+<img src="man/figures/README-banana-samples-1.png" alt="" width="100%" />