Skip to content

Make package description in metadata and README more generic #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matt-graham merged 2 commits into from
Sep 7, 2026
Merged

Make package description in metadata and README more generic #140

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef080d5
Make package description in metadata and README more generic
matt-graham Jul 23, 2026
fc2ea78
Make README and metadata descriptions more generic per Sam's review c…
matt-graham Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 10 additions & 23 deletions DESCRIPTION
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,29 +12,16 @@ 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 using random-walk, Langevin,

@sam0287 sam0287 Jul 23, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest not mentioning specific algorithms here, broaden instead to simulating and comparing Markov chain algorithms, mention that we have these ones pre-coded but users can add others bla bla bla

Hamiltonian or Barker proposals, to compute Markov chain Monte Carlo (MCMC)
estimates of expectations with respect to a target distribution on a
real-valued vector space. 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)
Expand Down
28 changes: 19 additions & 9 deletions README.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ 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.
`rmcmc` is an R package for simulating Markov chains using random-walk, Langevin,

@sam0287 sam0287 Jul 23, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as above

Hamiltonian or Barker proposals, 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,
Expand All @@ -41,12 +41,22 @@ During an initial warm-up stage, the parameters of the proposal distribution can
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).

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

Expand Down
40 changes: 26 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,11 @@
[![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
`rmcmc` is an R package for simulating Markov chains using random-walk,

@sam0287 sam0287 Jul 23, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment here, better not to focus so much on any specific algorithm

Langevin, Hamiltonian or Barker proposals, 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
Expand All @@ -32,15 +33,26 @@ 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).
estimates under the target distribution.

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

Expand Down Expand Up @@ -128,4 +140,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%" />
Binary file modified man/figures/README-banana-samples-1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.