Tools for Writing MCMC.
overture
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.