Skip to content
R package to simplify writing MCMC
R
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
R
examples added documentation and example for 'Resume' Aug 9, 2019
man
tests
tools
.Rbuildignore moved traceplot.png into tools Mar 14, 2019
.gitignore
.travis.yml added additional versions of R to travis checks Jan 10, 2019
DESCRIPTION incremented version number Aug 10, 2019
NAMESPACE
NEWS.md
README.md moved traceplot.png into tools Mar 14, 2019
codecov.yml added covr Jan 4, 2019
cran-comments.md
overture.Rproj
traceplotmaker.R

README.md

overture

Build Status Coverage status CRAN status

Features

Overture makes writing Markov chain Monte Carlo (MCMC) samplers simpler. With overture you can:

  • Write less code Overture eliminates boilerplate code, looping through sampling functions and saving the results automatically.
  • Easily recover from interruptions Samples can be saved on-disk as the MCMC runs, so it's easy to resume the chain if something goes wrong.
  • Run more chains in parallel Saving samples on-disk results in a dramatically smaller memory footprint for high-dimensional models, allowing more chains to be run when available RAM is limited.
  • Monitor chain progress Samples can be viewed in another R process while the MCMC is still running.

Usage

Basic Usage

Using overture is easy:

1. Write the sampling functions

SampleX <- function(x) {
    x + 1
}

SampleY <- function(y) {
    y * y
}

2. Initialize the MCMC

Mcmc <- InitMcmc(3) # Run the chain for 3 iterations

3. Set initial values for the chain

x <- c(0, 10) # Initial value for x
y <- 2 # Initial value for y

4. Run the MCMC

samples <- Mcmc({
    x <- SampleX(x)
    y <- SampleY(y)
})

5. Analyze the results

> samples$x
     [,1] [,2]
[1,]    1   11
[2,]    2   12
[3,]    3   13
> samples$y
     [,1]
[1,]    4
[2,]   16
[3,]  256

Save samples on-disk

To save samples on disk, specify the directory where the samples should be saved:

Mcmc <- InitMcmc(3, backing.path="/save/directory/path/")
samples <- Mcmc({
    x <- SampleX(x)
    y <- SampleY(y)
})

The samples can be analyzed as before:

> samples$x[,]
     [,1] [,2]
[1,]    1   11
[2,]    2   12
[3,]    3   13
> samples$y[,, drop=FALSE]
     [,1]
[1,]    4
[2,]   16
[3,]  256

To load the samples from disk, use LoadMcmc:

loaded.samples <- LoadMcmc("/save/directory/path/")

To convert a file-backed MCMC into a list of R in-memory matrices, use ToMemory:

samples.in.memory <- ToMemory(loaded.samples)
> samples.in.memory
$x
     [,1] [,2]
[1,]    1   11
[2,]    2   12
[3,]    3   13

$y
     [,1]
[1,]    4
[2,]   16
[3,]  256

Monitor the progress of an MCMC while it's still running

Samples from an MCMC can be viewed before its completion. First, start the slow running MCMC as a file-backed chain:

SlowMcmc <- InitMcmc(10000, backing.path="/save/directory/path/")
SlowMcmc({
    x <- SlowSampler()
})

Then, in another R process while the MCMC is still running, use Peek to load and analyze the samples taken so far:

samples.so.far <- Peek("/save/directory/path/")
samples.so.far$x[,]

Get more information

More examples and details are given in the package documentation.

Installation

To install from CRAN run:

install.packages("overture")

To install from GitHub, after installing devtools run:

devtools::install_github("kurtis-s/overture")

If you aren't sure which version to install, you probably want to install from CRAN.

You can’t perform that action at this time.