overture v0.4-0

0

Monthly downloads

0th

Percentile

Tools for Writing MCMC

Simplifies MCMC setup by automatically looping through sampling functions and saving the results. Reduces the memory footprint of running MCMC and saves samples to disk as the chain runs. Allows samples from the chain to be analyzed while the MCMC is still running. Provides functions for commonly performed operations such as calculating Metropolis acceptance ratios and creating adaptive Metropolis samplers. References: Roberts and Rosenthal (2009) <doi:10.1198/jcgs.2009.06134>.

Readme

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.

Functions in overture

Name Description
AcceptProp Determine if a Metropolis<U+2013>Hastings step should be accepted
Resume Resumes an interrupted file-backed MCMC
Peek Load samples from a partial MCMC run
InitMcmc Initialize a Markov chain Monte Carlo run
Amwg Turn a non-adaptive Metropolis sampler into an adaptive Metropolis sampler
LoadMcmc Load samples from a file-backed MCMC run
ToMemory Converts matrices in a file-backed MCMC to R matrix objects
No Results!

Last month downloads

Details

Type Package
License LGPL-3
URL https://github.com/kurtis-s/overture
BugReports https://github.com/kurtis-s/overture/issues
Encoding UTF-8
LazyData true
RoxygenNote 6.1.0
NeedsCompilation no
Packaged 2019-08-10 04:39:48 UTC; kws
Repository CRAN
Date/Publication 2019-08-10 22:30:02 UTC
imports bigmemory
suggests covr , mockery , testthat
Contributors

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/overture)](http://www.rdocumentation.org/packages/overture)