From 8b9a050676546354d0be7716317a37a22993e1a6 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 24 Aug 2023 12:03:30 +0200 Subject: [PATCH 01/20] Update Vignettes --- BayesianTools/vignettes/BayesianTools.Rmd | 1533 ++++++++--------- BayesianTools/vignettes/InterfacingAModel.Rmd | 607 +++---- 2 files changed, 1072 insertions(+), 1068 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index cdffad7..f11ecc3 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -1,768 +1,765 @@ ---- -title: "Bayesian Tools - General-Purpose MCMC and SMC Samplers and Tools for Bayesian Statistics" -output: - rmarkdown::html_vignette: - toc: true -vignette: > - %\VignetteIndexEntry{Manual for the BayesianTools R package} - %\VignetteEngine{knitr::rmarkdown} - \usepackage[utf8]{inputenc} -abstract: "The BayesianTools (BT) package supports model analysis (including sensitivity analysis and uncertainty analysis), Bayesian model calibration, as well as model selection and multi-model inference techniques for system models." ---- - -```{r global_options, include=FALSE} -knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) -``` - -```{r, echo = F, message = F} -set.seed(123) -``` - - -# Quick start - -The purpose of this first section is to give you a quick overview of the most important functions of the BayesianTools (BT) package. For a more detailed description, see the later sections - -## Installing, loading and citing the package - -If you haven't installed the package yet, either run - -```{r, eval = F} -install.packages("BayesianTools") -``` - -Or follow the instructions on [https://github.com/florianhartig/BayesianTools](https://github.com/florianhartig/BayesianTools) to install a development or an older version. - -Loading and citation - -```{r} -library(BayesianTools) -citation("BayesianTools") -``` - -Note: BayesianTools calls a number of secondary packages. Particular important is coda, which is used on a number of plots and summary statistics. If you make heavy use of the summary statistics and diagnostics plots, it would be nice to cite coda as well! - -Pro-tip: if you are running a stochastic algorithms such as an MCMC, you should always set or record your random seed to make your results reproducible (otherwise, results will change slightly every time you run the code) - -```{r} -set.seed(123) -``` - -In a real application, to ensure reproducibility, it would also be useful to record the session info, - -```{r, eval = F} -sessionInfo() -``` - -which lists the version number of R and all loaded packages. - -## The Bayesian Setup - -The central object in the BT package is the BayesianSetup. This class contains the information about the model to be fit (likelihood), and the priors for the model parameters. - -A BayesianSetup is created by the createBayesianSetup function. The function expects a log-likelihood and (optional) a log-prior. It then automatically creates the posterior and various convenience functions for the samplers. - -Advantages of the BayesianSetup include -1. support for automatic parallelization -2. functions are wrapped in try-catch statements to avoid crashes during long MCMC evaluations -3. and the posterior checks if the parameter is outside the prior first, in which case the likelihood is not evaluated (makes the algorithms faster for slow likelihoods). - -If no prior information is provided, an unbounded flat prior is created. If no explicit prior, but lower and upper values are provided, a standard uniform prior with the respective bounds is created, including the option to sample from this prior, which is useful for SMC and also for getting starting values. This option is used in the following example, which creates a multivariate normal likelihood density and a uniform prior for 3 parameters. - -```{r} -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) -``` - -See later more detailed description about the BayesianSetup. - -**Hint:** for an example how to run this steps for dynamic ecological model, see ?VSEM - -## Running MCMC and SMC functions - -Once you have your setup, you may want to run a calibration. The runMCMC function is the main wrapper for all other implemented MCMC/SMC functions. It always takes the following arguments - -* A bayesianSetup (alternatively, the log target function) -* The sampler name -* A list with settings - if a parameter is not provided, the default will be used - -As an example, choosing the sampler name "Metropolis" calls a versatile Metropolis-type MCMC with options for covariance adaptation, delayed rejection, tempering and Metropolis-within-Gibbs sampling. For details, see the the later reference on MCMC samplers. This is how we would call this sampler with default settings - -```{r} -iter = 10000 -settings = list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -``` - -#### Summarizing outputs - -All samplers can be plotted and summarized via the console with the standard print, and summary commands - -```{r} -print(out) -summary(out) -``` - -and plottted with several plot functions. The marginalPlot can either be plotted as histograms with density overlay, which is also the default, or as a violin plot (see "?marginalPlot"). - -```{r} -plot(out) # plot internally calls tracePlot(out) -correlationPlot(out) -marginalPlot(out, prior = TRUE) -``` - -Other Functions that can be applied to all samplers include model selection scores such as the DIC and the marginal Likelihood (for the calculation of the Bayes factor, see later section for more details), and the Maximum Aposteriori Value (MAP). For the marginal likelihood calculation it is possible to chose from a set of methods (see "?marginalLikelihood"). - -```{r} -marginalLikelihood(out) -DIC(out) -MAP(out) -``` - -You can extract (a part of) the sampled parameter values by - -```{r, eval = F} -getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) -``` - -For all samplers, you can conveniently perform multiple runs via the nrChains argument - -```{r, echo = T} -iter = 1000 -settings = list(iterations = iter, nrChains = 3, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) - -``` - -The result is an object of mcmcSamplerList, which should allow to do everything one can do with an mcmcSampler object (with slightly different output sometimes). - -```{r} -print(out) -summary(out) -``` - -For example, in the plot you now see 3 chains. - -```{r} -plot(out) -``` - -There are a few additional functions that may only be available for lists, for example convergence checks - -```{r} -#getSample(out, coda = F) -gelmanDiagnostics(out, plot = T) -``` - - -#### Which sampler to choose? - -The BT package provides a large class of different MCMC samplers, and it depends on the particular application which is most suitable. - -In the absence of further information, we currently recommend the DEzs sampler. This is also the default in the runMCMC function. - - -# BayesianSetup Reference - - -## Reference on creating likelihoods - -The likelihood should be provided as a log density function. - -```{r, eval = F} -ll = logDensity(x) -``` - -See options for parallelization below. We will use a simple 3-d multivariate normal density for this demonstration. - -```{r} -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) -``` - -#### Parallelization of the likelihood evaluations - -Likelihoods are often costly to compute. If that is the case for you, you should think about parallelization possibilities. The 'createBayesianSetup' function has the input variable 'parallel', with the following options - -* F / FALSE means no parallelization should be used -* T / TRUE means that automatic parallelization options from R are used (careful: this will not work if your likelihood writes to file, or uses global variables or functions - see general R help on parallelization) -* "external", assumed that the likelihood is already parallelized. In this case, the function needs to accept a matrix with parameters as columns, and rows as the different model runs you want to evaluate. This is the most likely option to use if you have a complicated setup (file I/O, HPC cluster) that cannot be treated with the standard R parallelization. - -Algorithms in the BayesianTools package can make use of parallel computing if this option is specified in the BayesianSetup. Note that currently, parallelization is used by the following algorithms: SMC, DEzs and DREAMzs sampler. It can also be used through the BayesianSetup with the functions of the sensitivity package. - -Here some more details on the parallelization - -#### 1. In-build parallelization: - -The in-build parallelization is the easiest way to make use of parallel computing. In the "parallel" argument you can choose the number of cores used for parallelization. Alternatively for TRUE or "auto" all available cores except for one will be used. Now the proposals are evaluated in parallel. Technically, the in-build parallelization uses an R cluster to evaluate the posterior density function. The input for the parallel function is a matrix, where each column represents a parameter and each row a proposal. In this way, the proposals can be evaluated in parallel. For sampler, where only one proposal is evaluated at a time (namely the Metropolis based algorithms as well as DE/DREAM without the zs extension), no parallelization can be used. - -#### 2. External parallelization - -The second option is to use an external parallelization. Here, a parallelization is attempted in the user defined likelihood function. To make use of external parallelization, the likelihood function needs to take a matrix of proposals and return a vector of likelihood values. In the proposal matrix each row represents one proposal, each column a parameter. Further, you need to specify the "external" parallelization in the "parallel" argument. In simplified terms the use of external parallelization uses the following steps: - -```{r, eval = FALSE} -## Definition of likelihood function -likelihood <- function(matrix){ - # Calculate likelihood in parallel - # Return vector of likelihood valus -} - -## Create Bayesian Setup -BS <- createBayesianSetup(likelihood, parallel = "external", ...) - -## Run MCMC -runMCMC(BS, sampler = "SMC", ...) -``` - - - -#### 3. Multi-core and cluster calculations -If you want to run your calculations on a cluster there are several ways to achieve it. - -In the first case you want to parallize n internal (not overall chains) on n cores. The argument "parallel = T" in "createBayesianSetup" allows only at most parallelization on 3 cores for the SMC, DEzs and DreamsSamplers. But by setting "parallel = n" to n cores in the "createBayesianSetup", the internal chains of DEzs and DREAMzs will be parallelized on n cores. This works only for the DEzs and DREAMzs samplers. - -```{r, eval = FALSE} -## n = Number of cores -n=2 -x <- c(1:10) -likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) -bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper = 5) - -## give runMCMC a matrix with n rows of proposals as startValues or sample n times from the previous created sampler -out <- runMCMC(bayesianSetup, settings = list(iterations = 1000)) -``` - -In the second case you want to parallize n internal chains on n cores with a external parallilzed likelihood function. Unlike the previous case, that way DEzs, DREAMzs, and SMC samplers can be parallelized. - -```{r, eval = FALSE} -### Create cluster with n cores -cl <- parallel::makeCluster(n) - -## Definition of the likelihood -likelihood <- function(X) sum(dnorm(c(1:10), mean = X, log = T)) - -## Definition of the likelihood which will be calculated in parallel. Instead of the parApply function, we could also define a costly parallelized likelihood -pLikelihood <- function(param) parallel::parApply(cl = cl, X = param, MARGIN = 1, FUN = likelihood) - -## export functions, dlls, libraries -# parallel::clusterEvalQ(cl, library(BayesianTools)) -parallel::clusterExport(cl, varlist = list(likelihood)) - -## create BayesianSetup -bayesianSetup <- createBayesianSetup(pLikelihood, lower = -10, upper = 10, parallel = 'external') - -## For this case we want to parallelize the internal chains, therefore we create a n row matrix with startValues, if you parallelize a model in the likelihood, do not set a n*row Matrix for startValue -settings = list(iterations = 100, nrChains = 1, startValue = bayesianSetup$prior$sampler(n)) - -## runMCMC -out <- runMCMC(bayesianSetup, settings, sampler = "DEzs") -``` - -In a another case your likelihood requires a parallized model. Start your cluster and export your model, the required libraries, and dlls. Now you can start your calculations with the argument "parallel = external" in createBayesianSetup. - -```{r, eval = FALSE} -### Create cluster with n cores -cl <- parallel::makeCluster(n) - -## export your model -# parallel::clusterExport(cl, varlist = list(complexModel)) - -## Definition of the likelihood -likelihood <- function(param) { - # ll <- complexModel(param) - # return(ll) -} - -## create BayesianSetup and settings -bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = 'external') -settings = list(iterations = 100, nrChains = 1) - -## runMCMC -out <- runMCMC(bayesianSetup, settings) - -``` - -In the last case you can parallize over whole chain calculations. However, here the likelihood itself will not be parallelized. Each chain will be run on one core and the likelihood will be calculated on that core. - -```{r, eval = FALSE} -### Definition of likelihood function -x <- c(1:10) -likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) - -## Create BayesianSetup and settings -bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = F) -settings = list(iterations = 100000) - -## Start cluster with n cores for n chains and export BayesianTools library -cl <- parallel::makeCluster(n) -parallel::clusterEvalQ(cl, library(BayesianTools)) - -## calculate parallel n chains, for each chain the likelihood will be calculated on one core -out <- parallel::parLapply(cl, 1:n, fun = function(X, bayesianSetup, settings) runMCMC(bayesianSetup, settings, sampler = "DEzs"), bayesianSetup, settings) - -## Combine the chains -out <- createMcmcSamplerList(out) -``` - - - -** Remark: even though parallelization can significantly reduce the computation time, it is not always useful because of the so-called communication overhead (computational time for distributing and retrieving infos from the parallel cores). For models with low computational cost, this procedure can take more time than the actual evaluation of the likelihood. If in doubt, make a small comparison of the runtime before starting your large sampling. ** - - - -## Reference on creating priors - -The prior in the BayesianSetup consists of four parts - -* A log density function -* An (optional) sampling function (must be a function without parameters, that returns a draw from the prior) -* lower / upper boundaries -* Additional info - best values, names of the parameters, ... - -These information can be passed by first creating an a extra object, via createPrior, or through the the createBayesianSetup function. - -#### Creating priors - -You have 5 options to create a prior - -* Do not set a prior - in this case, an infinite prior will be created -* Set min/max values - a bounded flat prior and the corresponding sampling function will be created -* Use one of the pre-definded priors, see ?createPrior for a list. One of the options here is to use a previous MCMC output as new prior. Pre-defined priors will usually come with a sampling function -* Use a user-define prior, see ?createPrior -* Create a prior from a previous MCMC sample - -#### Creating user-defined priors - -If creating a user-defined prior, the following information can/should be provided to createPrior: - -* A log density function, as a function of a parameter vector x, same syntax as the likelihood -* Additionally, you should consider providing a function that samples from the prior, because many samplers (SMC, DE, DREAM) can make use of this function for initial conditions. If you use one of the pre-defined priors, the sampling function is already implemented -* lower / upper boundaries (can be set on top of any prior, to create truncation) -* Additional info - best values, names of the parameters, ... - -#### Creating a prior from a previous MCMC sample - -The following example from the help shows how this works - -```{r} -# Create a BayesianSetup -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) - -settings = list(iterations = 2500, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) - - -newPrior = createPriorDensity(out, method = "multivariate", eps = 1e-10, lower = rep(-10, 3), upper = rep(10, 3), best = NULL) -bayesianSetup <- createBayesianSetup(likelihood = ll, prior = newPrior) - -settings = list(iterations = 1000, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) -``` - - - - -# MCMC sampler reference - -## The runMCMC() function - -The runMCMC function is the central function for starting MCMC algorithms in the BayesianTools package. It requires a bayesianSetup, a choice of sampler (standard is DEzs), and optionally changes to the standard settings of the chosen sampler. - -runMCMC(bayesianSetup, sampler = "DEzs", settings = NULL) - -One optional argument that you can always use is nrChains - the default is 1. If you choose more, the runMCMC will perform several runs. - -```{r, message = F} - -ll <- generateTestDensityMultiNormal(sigma = "no correlation") - -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) - -settings = list(iterations = 10000, nrChains= 3, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) - -plot(out) -marginalPlot(out, prior = T) -correlationPlot(out) -gelmanDiagnostics(out, plot=T) - -# option to restart the sampler - -settings = list(iterations = 1000, nrChains= 1, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) - -out2 <- runMCMC(bayesianSetup = out) - -out3 <- runMCMC(bayesianSetup = out2) - -#plot(out) -#plot(out3) - -# create new prior from posterior sample - -newPriorFromPosterior <- createPriorDensity(out2) - -``` - - -## The different MCMC samplers - -For convenience we define a number of iterations - -```{r} -iter = 10000 -``` - -### The Metropolis MCMC class - -The BayesianTools package is able to run a large number of Metropolis-Hastings (MH) based algorithms All of these samplers can be accessed by the "Metropolis" sampler in the runMCMC function by specifying the sampler's settings. - -The following code gives an overview about the default settings of the MH sampler. -```{r} -applySettingsDefault(sampler = "Metropolis") -``` - -The following examples show how the different settings can be used. As you will see different options can be activated singly or in combination. - -#### Standard MH MCMC -The following settings will run the standard Metropolis Hastings MCMC. - -Refernences: -Hastings, W. K. (1970). Monte carlo sampling methods using markov chains -and their applications. Biometrika 57 (1), 97-109. - -Metropolis, N., A. W. Rosenbluth, M. N. Rosenbluth, A. H. Teller, and E. Teller -(1953). Equation of state calculations by fast computing machines. The journal -of chemical physics 21 (6), 1087 - 1092. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = F, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Standard MH MCMC, prior optimization -This sampler uses an optimization step prior to the sampling process. -The optimization aims at improving the starting values and the covariance of the proposal distribution. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Adaptive MCMC, prior optimization -In the adaptive Metropolis sampler (AM) the information already acquired in the sampling process is used to improve (or adapt) the proposal function. In the BayesianTools package the history of the chain is used to adapt the covariance of the propoasal distribution. - -References: -Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive metropolis -algorithm. Bernoulli , 223-242. - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - -#### Standard MCMC, prior optimization, delayed rejection -Even though rejection is an essential step of a MCMC algorithm it can also mean that the proposal distribution is (locally) badly tuned to the target distribution. In a delayed rejection (DR) sampler a second (or third, etc.) proposal is made before rejection. This proposal is usually drawn from a different distribution, allowing for a greater flexibility of the sampler. In the BayesianTools package the number of delayed rejection steps as well as the scaling of the proposals can be determined. -** Note that the current version only supports two delayed rejection steps. ** - - -References: -Green, Peter J., and Antonietta Mira. "Delayed rejection in reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = F, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - - -#### Adaptive MCMC, prior optimization, delayed rejection -The delayed rejection adaptive Metropolis (DRAM) sampler is merely a combination of the two previous sampler (DR and AM). - -References: -Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." Statistics and Computing 16.4 (2006): 339-354. - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = T, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Standard MCMC, prior optimization, Gibbs updating -To reduce the dimensions of the target function a Metropolis-within-Gibbs sampler -can be run with the BayesianTools package. This means in each iteration only a subset of the parameter vector is updated. In the example below at most two (of the three) parameters are updated each step, and it is double as likely to vary one than varying two. - -** Note that currently adaptive cannot be mixed with Gibbs updating! ** - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = c(1,0.5,0), temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Standard MCMC, prior optimization, gibbs updating, tempering -Simulated tempering is closely related to simulated annealing (e.g. Bélisle, 1992) in optimization algorithms. -The idea of tempering is to increase the acceptance rate during burn-in. This should result in a faster initial scanning of the target function. -To include this a tempering function needs to be supplied by the user. -The function describes how the acceptance rate is influenced during burn-in. In the example below an exponential decline approaching 1 (= no influece on the acceptance rate)is used. - -References: -Bélisle, C. J. (1992). Convergence theorems for a class of simulated -annealing algorithms on rd. Journal of Applied Probability, 885–895. - -C. J. Geyer (2011) Importance sampling, simulated tempering, and umbrella sampling, in the Handbook of Markov Chain Monte Carlo, S. P. Brooks, et al (eds), Chapman & Hall/CRC. - -```{r, results = 'hide', eval = F} -temperingFunction <- function(x) 5 * exp(-0.01*x) + 1 -settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = c(1,1,0), temperingFunction = temperingFunction, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - - -### Differential Evolution MCMC - -The BT package implements two versions of the differential evolution MCMC. In doubt, you should use the DEzs option. - -The first is the normal DE MCMC, corresponding to Ter Braak, Cajo JF. "A Markov Chain Monte Carlo version of the genetic algorithm Differential Evolution: easy Bayesian computing for real parameter spaces." Statistics and Computing 16.3 (2006): 239-249. -In this sampler multiple chains are run in parallel (but not in the sense of parallel computing). The main difference to the Metropolis based algorithms is the creation of the proposal. Generally all samplers use the current positin of the chain and add a step in the parameter space to generate a new proposal. Whereas in the Metropolis based sampler this step is usually drawn from a multivariate normal distribution (yet every distribution is possible), the DE sampler uses the current position of two other chains to generate the step for each chain. For sucessful sampling at least 2*d chains, with d being the number of parameters, need to be run in parallel. - - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DE", settings = settings) -plot(out) -``` - -The second is the Differential Evolution MCMC with snooker update and sampling from past states, corresponding to ter Braak, Cajo JF, and Jasper A. Vrugt. "Differential evolution Markov chain with snooker updater and fewer chains." Statistics and Computing 18.4 (2008): 435-446. -This extension covers two differences to the normal DE MCMC. First a snooker update is used based on a user defined probability. Second also past states of other chains are respected in the creation of the proposal. These extensions allow for fewer chains (i.e. 3 chains are usually enough for up to 200 parameters) and parallel computing as the current position of each chain is only dependent on the past states of the other chains. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) -plot(out) -``` - - -### DREAM sampler - -Also for the DREAM sampler, there are two versions included. First of all, the standard DREAM sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte Carlo simulation by differential evolution with self-adaptive randomized subspace sampling." International Journal of Nonlinear Sciences and Numerical Simulation 10.3 (2009): 273-290. - -This sampler is largely build on the DE sampler with some significant differences: -1) More than two chains can be used to generate a proposal. -2) A randomized subspace sampling can be used to enhance the efficiency for high dimensional posteriors. Each dimension is updated with a crossover probalitity CR. To speed up the exploration of the posterior DREAM adapts the distribution of CR values during burn-in to favor large jumps over small ones. -3) Outlier chains can be removed during burn-in. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAM", settings = settings) -plot(out) -``` - -The second implementation uses the same extension as the DEzs sampler. Namely sampling from past states and a snooker update. Also here this extension allows for the use of fewer chains and parallel computing. - -Again, in doubt you should prefer "DREAMzs". - -```{r, results = 'hide', eval = FALSE} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAMzs", settings = settings) -plot(out) -``` - - - -### T-walk - -The T-walk is a MCMC algorithm developed by Christen, J. Andrés, and Colin Fox. "A general purpose sampling algorithm for continuous distributions (the t-walk)." Bayesian Analysis 5.2 (2010): 263-281. -In the sampler two independent points are used to explore the posterior space. -Based on probabilities four different moves are used to generate proposals for the two points. As for the DE sampler this procedure requires no tuning of the proposal distribution for efficient sampling in complex posterior distributions. - - - -```{r, eval = F} -settings = list(iterations = iter, message = FALSE) - -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Twalk", settings = settings) -``` - - -### Convergence checks for MCMCs - -All MCMCs should be checked for convergence. We recommend the standard procedure of Gelmal-Rubin. This procedure requires running several MCMCs (we recommend 3). This can be achieved either directly in the runMCMC (nrChains = 3), or, for runtime reasons, by combining the results of three independent runMCMC evaluations with nrChains = 1. - -```{r, eval = T} -settings <- list(iterations = iter, nrChains = 3, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) - -#chain = getSample(out, coda = T) -gelmanDiagnostics(out, plot = F) -``` - - -## Non-MCMC sampling algorithms - -MCMCs sample the posterior space by creating a chain in parameter space. While this allows "learning" from past steps, it does not permit the parallel execution of a large number of posterior values at the same time. - -An alternative to MCMCs are particle filters, aka Sequential Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for stochastic simulation models - theory and application Ecol. Lett., 2011, 14, 816-827 - - -### Rejection samling - -The easiest option is to simply sample a large number of parameters and accept them according to their posterior value. This option can be emulated with the implemented SMC, setting iterations to 1. - -```{r, results = 'hide', eval = F} -settings <- list(initialParticles = iter, iterations= 1) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) -plot(out) -``` - -### Sequential Monte Carlo (SMC) - -The more sophisticated option is using the implemented SMC, which is basically a particle filter that applies several filter steps. - -```{r, results = 'hide', eval = F} -settings <- list(initialParticles = iter, iterations= 10) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) -plot(out) -``` - - -Note that the use of a number for initialParticles requires that the bayesianSetup includes the possibility to sample from the prior. - - -# Bayesian model comparison and averaging - -There are a number of Bayesian model selection and model comparison methods. The BT implements three of the most common of them, the DIC, the WAIC, and the Bayes factor. - -* On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 - -* An overview on DIC and WAIC is given in Gelman, A.; Hwang, J. & Vehtari, A. (2014) Understanding predictive information criteria for Bayesian models. Statistics and Computing, 24, 997-1016-. On DIC, see also the original reference by Spiegelhalter, D. J.; Best, N. G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. - - -The Bayes factor relies on the calculation of marginal likelihoods, which is numerically not without problems. The BT package currently implements three methods - -* The recommended way is the method "Chib" (Chib and Jeliazkov, 2001). which is based on MCMC samples, but performs additional calculations. Despite being the current recommendation, note there are some numeric issues with this algorithm that may limit reliability for larger dimensions. - -* The harmonic mean approximation, is implemented only for comparison. Note that the method is numerically unrealiable and usually should not be used. - -* The third method is simply sampling from the prior. While in principle unbiased, it will only converge for a large number of samples, and is therefore numerically inefficient. - - -## Example - -Data linear Regression with quadratic and linear effect - -```{r} -sampleSize = 30 -x <- (-(sampleSize-1)/2):((sampleSize-1)/2) -y <- 1 * x + 1*x^2 + rnorm(n=sampleSize,mean=0,sd=10) -plot(x,y, main="Test Data") -``` - -Likelihoods for both - -```{r} -likelihood1 <- function(param){ - pred = param[1] + param[2]*x + param[3] * x^2 - singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) - return(sum(singlelikelihoods)) -} - -likelihood2 <- function(param){ - pred = param[1] + param[2]*x - singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[3]^2), log = T) - return(sum(singlelikelihoods)) -} -``` - - -Posterior definitions - - -```{r} -setUp1 <- createBayesianSetup(likelihood1, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) - -setUp2 <- createBayesianSetup(likelihood2, lower = c(-5,-5,0.01), upper = c(5,5,30)) -``` - -MCMC and marginal likelihood calculation - - - -```{r, results = 'hide'} -settings = list(iterations = 15000, message = FALSE) -out1 <- runMCMC(bayesianSetup = setUp1, sampler = "Metropolis", settings = settings) -#tracePlot(out1, start = 5000) -M1 = marginalLikelihood(out1) -M1 - -settings = list(iterations = 15000, message = FALSE) -out2 <- runMCMC(bayesianSetup = setUp2, sampler = "Metropolis", settings = settings) -#tracePlot(out2, start = 5000) -M2 = marginalLikelihood(out2) -M2 -``` - -### Model comparison via Bayes factor - -Bayes factor (need to reverse the log) - -```{r} -exp(M1$ln.ML - M2$ln.ML) -``` - -BF > 1 means the evidence is in favor of M1. See Kass, R. E. & Raftery, A. E. (1995) Bayes Factors. J. Am. Stat. Assoc., Amer Statist Assn, 90, 773-795. - -Assuming equal prior weights on all models, we can calculate the posterior weight of M1 as - -```{r} -exp(M1$ln.ML) / ( exp(M1$ln.ML) + exp(M2$ln.ML)) -``` - -If models have different model priors, multiply with the prior probabilities of each model. - - -### Model comparison via DIC - -The Deviance information criterion is a commonly applied method to summarize the fit of an MCMC chain. It can be obtained via - -```{r} -DIC(out1)$DIC -DIC(out2)$DIC -``` - -### Model comparison via WAIC - -The Watanabe–Akaike information criterion is another criterion for model comparison. To be able to calculate the WAIC, the model must implement a log-likelihood that density that allows to calculate the log-likelihood point-wise (the likelihood functions requires a "sum" argument that determines whether the summed log-likelihood should be returned). It can be obtained via - -```{r} -# This will not work, since likelihood1 has no sum argument -# WAIC(out1) - -# likelihood with sum argument -likelihood3 <- function(param, sum = TRUE){ - pred <- param[1] + param[2]*x + param[3] * x^2 - singlelikelihoods <- dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) - return(if (sum == TRUE) sum(singlelikelihoods) else singlelikelihoods) -} -setUp3 <- createBayesianSetup(likelihood3, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) -out3 <- runMCMC(bayesianSetup = setUp3, sampler = "Metropolis", settings = settings) - -WAIC(out3) -``` +--- +title: "Bayesian Tools - General-Purpose MCMC and SMC Samplers and Tools for Bayesian Statistics" +output: + rmarkdown::html_vignette: + toc: true +vignette: > + %\VignetteIndexEntry{Manual for the BayesianTools R package} + %\VignetteEngine{knitr::rmarkdown} + \usepackage[utf8]{inputenc} + + +--- + +```{r global_options, include=FALSE} +knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) +``` + +```{r, echo = F, message = F} +set.seed(123) +``` + +# Abstract + +The BayesianTools (BT) package supports model analysis (including sensitivity analysis and uncertainty analysis), Bayesian model calibration, as well as model selection and multi-model inference techniques for system models. + +# Quick start + +The purpose of this first section is to give you a quick overview of the most important functions of the BayesianTools (BT) package. For a more detailed description, see the following sections. + +### Install, load and cite the package + +If you haven't installed the package yet, either run + +```{r, eval = F} +install.packages("BayesianTools") +``` + +or follow the instructions at [https://github.com/florianhartig/BayesianTools](https://github.com/florianhartig/BayesianTools) to install a development version or an older version. + +Loading and citation + +```{r} +library(BayesianTools) +citation("BayesianTools") +``` + +Note: BayesianTools calls a number of secondary packages. Of particular importance is `coda`, which is used in a number of plots and summary statistics. If you use a lot of summary statistics and diagnostic plots, it would be nice to cite coda as well! + +Pro Tip: If you are running a stochastic algorithm such as MCMC, you should always set or record your random seed to make your results reproducible (otherwise the results will change slightly each time you run the code). + +```{r} +set.seed(123) +``` + +In a real application, recording the session info would be helpful in ensuring reproducibility. + +```{r, eval = F} +sessionInfo() +``` + +This session information includes the version number of R and all loaded packages. + +## The Bayesian Setup + +The central object in the `BT` package is the `BayesianSetup`. This class contains the information about the model to be fit (likelihood), and the priors for the model parameters. + +The `createBayesianSetup` function generates a `BayesianSetup` object. The function requires a log-likelihood and a log-prior (optional) as arguments. It then automatically creates the posterior and various convenience functions for the samplers. + +Advantages of the `BayesianSetup` include +1. support for automatic parallelization +2. functions are wrapped in try-catch statements to avoid crashes during long MCMC evaluations +3. and the posterior checks if the parameter is outside the prior first, in which case the likelihood is not evaluated (makes the algorithms faster for slow likelihoods). + +If no prior information is provided, an unbounded flat prior is generated. If no explicit prior is specified, but lower and upper values are given, a standard uniform prior with the respective bounds is created, including the option to sample from this prior, which is useful for SMC and obtaining initial values. This option is used in the following example, which creates a multivariate normal likelihood density and a uniform prior for 3 parameters. + +```{r} +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) +``` + +A more detailed description of the `BayesianSetup` will follow. + +**Hint:** For an example of how to run these steps for a dynamic ecological model, see `?VSEM`. + +## Run MCMC and SMC functions + +After setup, you may need to run a calibration. The `runMCMC` function serves as the main wrapper for all other implemented `MCMC`/`SMC` functions. It always requires the following arguments: + +* `bayesianSetup` (alternatively, the log target function) +* `sampler` name +* list with `settings` for each sampler - if `settings` is not specified, the default value will be applied + +For example, choosing the `sampler` name "Metropolis" calls a versatile Metropolis-type MCMC with options for covariance adjustment, delayed rejection, tempering and Metropolis-within-Gibbs sampling. For details, see the later reference on MCMC samplers. + +```{r} +iter = 10000 +settings = list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +``` + +### Summarize the outputs + +You can plot and summarize all `sampler`s from the console with the standard `print` and `summary` commands. + +```{r} +print(out) +summary(out) +``` + +You can also use built-in plot functions from the package for visualization. The `marginalPlot` can be either plotted as histograms with density overlay (default setting) or as a violin plot (see "?marginalPlot"). + +```{r} +plot(out) # plot internally calls tracePlot(out) +correlationPlot(out) +marginalPlot(out, prior = TRUE) +``` + +Additional functions that may be used on all `sampler`s are model selection scores, including the Deviance Information Criterion (DIC) and the marginal likelihood (see later section for details on calculating the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set of methods are available for calculation of marginal likelihood (refer to "?marginalLikelihood"). + +```{r} +marginalLikelihood(out) +DIC(out) +MAP(out) +``` + +To extract part of the sampled parameter values, you can use the following process: + +```{r, eval = F} +getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) +``` + +For all samplers, you can conveniently perform multiple runs using the `nrChains` argument + +```{r, echo = T} +iter = 1000 +settings = list(iterations = iter, nrChains = 3, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) + +``` + +The result is an object of `mcmcSamplerList`, which should allow you to do everything you can do with an `mcmcSampler` object (sometimes with slightly different output). + +```{r} +print(out) +summary(out) +``` + +For example, in the plot you now see 3 chains. + +```{r} +plot(out) +``` + +There are some additional features that may only be available for lists, such as convergence checks. + +```{r} +#getSample(out, coda = F) +gelmanDiagnostics(out, plot = T) +``` + + +### Which sampler to choose? + +The BT package provides a large class of different MCMC samplers, and it depends on the particular application which one is most suitable. + +In the absence of further information, we currently recommend the `DEz`s sampler. This is also the default in the `runMCMC` function. + + +# BayesianSetup Reference + + +## Reference on creating likelihoods + +The likelihood should be provided as a log density function. + +```{r, eval = F} +ll = logDensity(x) +``` + +See parallelization options below. We will use a simple 3-d multivariate normal density for the demonstration. + +```{r} +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) +``` + +### Parallelization of the likelihood evaluations + +Likelihoods are often costly to compute. If this is the case for you, you should think about parallelization possibilities. The 'createBayesianSetup' function has an input variable 'parallel', with the following options + +* F / FALSE means no parallelization should be used +* T / TRUE means to use R's automatic parallelization options (note: this will not work if your likelihood is writing to file, or using global variables or functions - see R's general help on parallelization) +* "external", assumes that the likelihood is already parallelized. In this case, the function needs to take a matrix with parameters as columns, and rows as the different model runs you want to evaluate. This is the most likely option to use if you have a complicated setup (file I/O, HPC cluster) that cannot be handled with the standard R parallelization. + +Algorithms in the `BayesianTools` package can take advantage of parallelization if this option is specified in the `BayesianSetup`. Note that parallelization is currently used by the following algorithms: `SMC`, `DEzs` and `DREAMzs` sampler. It can also be used through the `BayesianSetup` with the functions of the sensitivity package. + +Here are some more details about the parallelization. + +#### 1. In-build parallelization: + +In-built parallelizing is the easiest way to use parallel computing. The "parallel" argument allows you to select the number of cores to use for parallelization. Alternatively, TRUE or "auto" will use all available cores except one. Now the proposals are evaluated in parallel. Technically, the built-in parallelization uses an R cluster to evaluate the posterior density function. The input to the parallel function is a matrix where each column represents a parameter and each row represents a proposal. This allows the proposals to be evaluated in parallel. For `sampler`s that evaluate only one proposal at a time (namely the Metropolis-based algorithms and DE/DREAM without the `zs` extension), parallelization cannot be used. + +#### 2. External parallelization + +The second option is to use external parallelization. Here, parallelization is attempted in the user-defined likelihood function. To use external parallelization, the likelihood function must take a matrix of proposals and return a vector of likelihood values. In the proposal matrix, each row represents a proposal, and each column represents a parameter. In addition, you will need to specify the "external" parallelization in the "parallel" argument. In simple terms, using external parallelization involves the following steps + +```{r, eval = FALSE} +## Definition of likelihood function +likelihood <- function(matrix){ + # Calculate likelihood in parallel + # Return vector of likelihood values +} + +## Create Bayesian Setup +BS <- createBayesianSetup(likelihood, parallel = "external", ...) + +## Run MCMC +runMCMC(BS, sampler = "SMC", ...) +``` + + + +#### 3. Multi-core and cluster calculations +If you want to run your calculations on a cluster there are several ways to do it. + +In the first case, you want to parallelize n internal (not total chains) on n cores. The argument "parallel = T" in "createBayesianSetup" only allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and `DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` samplers. + +```{r, eval = FALSE} +## n = Number of cores +n=2 +x <- c(1:10) +likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) +bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper = 5) + +## give runMCMC a matrix with n rows of proposals as startValues or sample n times from the previous created sampler +out <- runMCMC(bayesianSetup, settings = list(iterations = 1000)) +``` + +In the second case, you want to parallelize n internal chains on `n` cores with an external parallelized likelihood function. Unlike the previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized this way. + +```{r, eval = FALSE} +### Create cluster with n cores +cl <- parallel::makeCluster(n) + +## Definition of the likelihood +likelihood <- function(X) sum(dnorm(c(1:10), mean = X, log = T)) + +## Definition of the likelihood which will be calculated in parallel. Instead of the parApply function, we could also define a costly parallelized likelihood +pLikelihood <- function(param) parallel::parApply(cl = cl, X = param, MARGIN = 1, FUN = likelihood) + +## export functions, dlls, libraries +# parallel::clusterEvalQ(cl, library(BayesianTools)) +parallel::clusterExport(cl, varlist = list(likelihood)) + +## create BayesianSetup +bayesianSetup <- createBayesianSetup(pLikelihood, lower = -10, upper = 10, parallel = 'external') + +## For this case we want to parallelize the internal chains, therefore we create a n row matrix with startValues, if you parallelize a model in the likelihood, do not set a n*row Matrix for startValue +settings = list(iterations = 100, nrChains = 1, startValue = bayesianSetup$prior$sampler(n)) + +## runMCMC +out <- runMCMC(bayesianSetup, settings, sampler = "DEzs") +``` + +In another case, your likelihood requires a parallelized model. Start your cluster and export your model, the required libraries, and `dll`s. Now you can start your calculations with the argument "parallel = external" in `createBayesianSetup`. + +```{r, eval = FALSE} +### Create cluster with n cores +cl <- parallel::makeCluster(n) + +## export your model +# parallel::clusterExport(cl, varlist = list(complexModel)) + +## Definition of the likelihood +likelihood <- function(param) { + # ll <- complexModel(param) + # return(ll) +} + +## create BayesianSetup and settings +bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = 'external') +settings = list(iterations = 100, nrChains = 1) + +## runMCMC +out <- runMCMC(bayesianSetup, settings) + +``` + +In the last case, you can parallelize over whole chain calculations. However, the likelihood itself is not parallelized. Each chain is run on one core, and the likelihood is calculated on that core. + +```{r, eval = FALSE} +### Definition of likelihood function +x <- c(1:10) +likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) + +## Create BayesianSetup and settings +bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = F) +settings = list(iterations = 100000) + +## Start cluster with n cores for n chains and export BayesianTools library +cl <- parallel::makeCluster(n) +parallel::clusterEvalQ(cl, library(BayesianTools)) + +## calculate parallel n chains, for each chain the likelihood will be calculated on one core +out <- parallel::parLapply(cl, 1:n, fun = function(X, bayesianSetup, settings) runMCMC(bayesianSetup, settings, sampler = "DEzs"), bayesianSetup, settings) + +## Combine the chains +out <- createMcmcSamplerList(out) +``` + + + +** Note: Even though parallelization can significantly reduce the computation time, it is not always useful because of the so-called communication overhead (computational time for distributing and retrieving information from the parallel cores). For models with low computational cost, this procedure may take more time than the actual evaluation of the likelihood. If in doubt, do a small run-time comparison before starting your large sampling. ** + + +## Reference on creating priors + +The prior in the `BayesianSetup` consists of four parts + +* A log density function +* An (optional) sampling function (must be a function without parameters, that returns a draw from the prior) +* lower / upper boundaries +* Additional info - best values, names of the parameters, ... + +This information can be passed by first creating an extra object, via `createPrior`, or via the `createBayesianSetup` function. + +#### Creating priors + +You have 5 options to create a prior + +* Do not set a prior - in this case, an infinite prior will be created +* Set min/max values - a bounded flat prior and the corresponding sampling function will be created +* Use one of the predefinded priors, see `?createPrior` for a list. One of the options here is to use a previous MCMC output as the new prior. Predefined priors will usually come with a sampling function +* Use a user-defined prior, see `?createPrior` +* Create a prior from a previous MCMC sample + +#### Creating user-defined priors + +When creating a user-defined prior, the following information can/should be passed to `createPrior` + +* A log density function, as a function of a parameter vector x, same syntax as the likelihood. +* In addition, you should consider providing a function that samples from the prior, as many samplers (SMC, DE, DREAM) can use this function for initial conditions. If you use one of the predefined priors, the sampling function is already implemented. +* Lower / upper bounds (can be set on top of any prior to create truncation) +* Additional information - best values, parameter names, ... + +#### Creating a prior from a previous MCMC sample + +The following example from the help file illustrates the process + +```{r} +# Create a BayesianSetup +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) + +settings = list(iterations = 2500, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) + + +newPrior = createPriorDensity(out, method = "multivariate", eps = 1e-10, lower = rep(-10, 3), upper = rep(10, 3), best = NULL) +bayesianSetup <- createBayesianSetup(likelihood = ll, prior = newPrior) + +settings = list(iterations = 1000, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) +``` + + +# MCMC sampler reference + +## The runMCMC() function + +The `runMCMC` function is the central function for starting MCMC algorithms in the `BayesianTools` package. It takes a `bayesianSetup`, a choice of `sampler` (default is `DEzs`), and optionally changes to the default settings of the chosen `sampler`. + +```{r, message = F} +runMCMC(bayesianSetup, sampler = "DEzs", settings = NULL) +``` + +You may use an optional argument `nrChains`, which is set to the default value of 1 but can be modified if needed. Increasing its value will lead `runMCMC` to execute multiple runs. + +```{r, message = F} + +ll <- generateTestDensityMultiNormal(sigma = "no correlation") + +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) + +settings = list(iterations = 10000, nrChains= 3, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) + +plot(out) +marginalPlot(out, prior = T) +correlationPlot(out) +gelmanDiagnostics(out, plot=T) + +# option to restart the sampler + +settings = list(iterations = 1000, nrChains= 1, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) + +out2 <- runMCMC(bayesianSetup = out) + +out3 <- runMCMC(bayesianSetup = out2) + +#plot(out) +#plot(out3) + +# create new prior from posterior sample + +newPriorFromPosterior <- createPriorDensity(out2) + +``` + + +## The different MCMC samplers + +For simplicity, we will define a fixed number of iterations. + +```{r} +iter = 10000 +``` + +### The Metropolis MCMC class + +The `BayesianTools` package is able to run a large number of Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can be accessed by the "Metropolis" `sampler` in the `runMCMC` function by specifying the `sampler`'s settings. + +The subsequent code provides an overview of the default settings of the MH `sampler`. + +```{r} +applySettingsDefault(sampler = "Metropolis") +``` + +Here are some examples of how to apply different settings. Activate individual options or combinations as demonstrated. + +### Standard MH MCMC +The following settings run the standard Metropolis Hastings MCMC. + +Refernences: +Hastings, W. K. (1970). Monte carlo sampling methods using markov chains +and their applications. Biometrika 57 (1), 97-109. + +Metropolis, N., A. W. Rosenbluth, M. N. Rosenbluth, A. H. Teller, and E. Teller +(1953). Equation of state calculations by fast computing machines. The journal +of chemical physics 21 (6), 1087 - 1092. + + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = F, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + + +#### Standard MH MCMC, prior optimization +Prior to the sampling process, this `sampler` employs an optimization step. +The purpose of optimization is to improve the initial values and the covariance of the proposal distribution. + + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + + +#### Adaptive MCMC, prior optimization +The adaptive Metropolis sampler (AM) uses the information already obtained during the sampling process to improve (or adapt) the proposal function. The `BayesianTools` package adjusts the covariance of the proposal distribution by utilizing the chain's history. + +References: +Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive metropolis +algorithm. Bernoulli , 223-242. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +#### Standard MCMC, prior optimization, delayed rejection +Although rejection is an essential step in an MCMC algorithm, it can also mean that the proposal distribution is (locally) poorly tuned to the target distribution. In a delayed rejection (DR) sampler, a second (or third, etc.) proposal is made before rejection. This proposal is usually drawn from a different distribution, allowing for greater flexibility of the sampler. In the `BayesianTools` package, the number of delayed rejection steps and the scaling of the proposals can be specified. +** Note that the current version supports only two delayed rejection steps. ** + + +References: +Green, Peter J., and Antonietta Mira. "Delayed rejection in reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = F, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + + + +#### Adaptive MCMC, prior optimization, delayed rejection +The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a combination of the two previous `sampler`s (DR and AM). + +References: +Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." Statistics and Computing 16.4 (2006): 339-354. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = T, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + + +#### Standard MCMC, prior optimization, Gibbs updating +To reduce the dimensions of the target function, a Metropolis-within-Gibbs `sampler` can be run with the can be run with the `BayesianTools` package. This means that only a subset of the parameter vector is updated in each iteration. In the example below, at most two (of the three) parameters are updated at each step, and it is twice as likely to vary one as to vary two. + +** Note that currently adaptive cannot be mixed with Gibbs updating! ** + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = c(1,0.5,0), temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + + +#### Standard MCMC, prior optimization, gibbs updating, tempering +Simulated tempering is closely related to simulated annealing (e.g., Bélisle, 1992) in optimization algorithms. +The idea of tempering is to increase the acceptance rate during burn-in. This should lead to a faster initial scanning of the target function. +To incorporate this, a tempering function must be provided by the user. +The function describes how to influence the acceptance rate during burn-in. In the example below, an exponential decline approaching 1 (= no influence on the acceptance rate) is used. + +References: +Bélisle, C. J. (1992). Convergence theorems for a class of simulated +annealing algorithms on rd. Journal of Applied Probability, 885–895. + +C. J. Geyer (2011) Importance sampling, simulated tempering, and umbrella sampling, in the Handbook of Markov Chain Monte Carlo, S. P. Brooks, et al (eds), Chapman & Hall/CRC. + +```{r, results = 'hide', eval = F} +temperingFunction <- function(x) 5 * exp(-0.01*x) + 1 +settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = c(1,1,0), temperingFunction = temperingFunction, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + + + +### Differential Evolution MCMC + +The BT package implements two differential evolution MCMCs. When in doubt, use the DEzs option. + +The first is the normal DE MCMC, according to Ter Braak, Cajo JF. "A Markov Chain Monte Carlo version of the genetic algorithm Differential Evolution: easy Bayesian computing for real parameter spaces". Statistics and Computing 16.3 (2006): 239-249. +This sampler runs multiple chains in parallel (but not in the sense of parallel computing). The main difference to the Metropolis based algorithms is the generation of the proposal. In general, all `sampler`s use the current position of the chain and add a step in the parameter space to generate a new proposal. While in the Metropolis based `sampler` this step is usually drawn from a multivariate normal distribution (but any distribution is possible), the `DE` `sampler` uses the current position of two other chains to generate the step for each chain. For successful sampling, at least `2*d` chains, where `d` is the number of parameters, must be run in parallel. + + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DE", settings = settings) +plot(out) +``` + +The second is the Differential Evolution MCMC with Snooker update and sampling from past states, according to ter Braak, Cajo JF, and Jasper A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. +This extension covers two differences from the normal `DE` MCMC. First, it uses a snooker update based on a user-defined probability. Second, past states of other chains are taken into account when generating the proposal. These extensions allow fewer chains (i.e., 3 chains are usually sufficient for up to 200 parameters) and parallel computing, since the current position of each chain depends only on the past states of the other chains. + + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) +plot(out) +``` + + +## DREAM sampler + +There are two versions of the DREAM `sampler`. First, the standard DREAM sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte Carlo simulation by differential evolution with self-adaptive randomized subspace sampling". International Journal of Nonlinear Sciences and Numerical Simulation 10.3 (2009): 273-290. + +This sampler is largely based on the DE sampler with some significant changes: +1) More than two chains can be used to generate a proposal. +2) Randomized subspace sampling can be used to improve efficiency for high-dimensional posteriors. Each dimension is updated with a crossover probability CR. To speed up the exploration of the posterior, DREAM adjusts the distribution of CR values during burn-in to favor large jumps over small ones. +3) Outlier chains can be removed during burn-in. + + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAM", settings = settings) +plot(out) +``` + +The second implementation uses the same extension as the DEzs sampler. Namely sampling from past states and a snooker update. Again, this extension allows the use of fewer chains and parallel computing. + +Again, if in doubt, you should prefer "DREAMzs". + +```{r, results = 'hide', eval = FALSE} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAMzs", settings = settings) +plot(out) +``` + + + +## T-walk + +The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and Colin Fox. "A general purpose sampling algorithm for continuous distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. +The sampler uses two independent points to explore the posterior space. +Based on probabilities, four different moves are used to generate proposals for the two points. As with the DE sampler, this procedure does not require tuning of the proposal distribution for efficient sampling in complex posterior distributions. + + +```{r, eval = F} +settings = list(iterations = iter, message = FALSE) + +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Twalk", settings = settings) +``` + + +## Convergence checks for MCMCs + +All MCMCs should be checked for convergence. We recommend the standard Gelmal-Rubin procedure. This procedure requires running multiple MCMCs (we recommend 3). This can be done either directly in `runMCMC` (`nrChains = 3`) or, for runtime reasons, by combining the results of three independent `runMCMC` runs with `nrChains = 1`. + +```{r, eval = T} +settings <- list(iterations = iter, nrChains = 3, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) + +#chain = getSample(out, coda = T) +gelmanDiagnostics(out, plot = F) +``` + + +## Non-MCMC sampling algorithms + +MCMCs sample the posterior space by creating a chain in parameter space. While this allows for "learning" from past steps, it does not allow for running a large number of posteriors in parallel. + +An alternative to MCMCs are particle filters, also known as Sequential Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for stochastic simulation models - theory and application Ecol. Lett., 2011, 14, 816-827 + + +### Rejection sampling + +The simplest option is to sample a large number of parameters and accept them according to their posterior value. This option can be emulated with the implemented SMC by setting iterations to 1. + +```{r, results = 'hide', eval = F} +settings <- list(initialParticles = iter, iterations= 1) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) +plot(out) +``` + +### Sequential Monte Carlo (SMC) + +The more sophisticated option is to use the implemented SMC, which is basically a particle filter that applies multiple filter steps. + +```{r, results = 'hide', eval = F} +settings <- list(initialParticles = iter, iterations= 10) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) +plot(out) +``` + +Note that using a number for `initialParticles` requires that the `bayesianSetup` includes the option to sample from the prior. + + +# Bayesian model comparison and averaging + +There are a number of Bayesian methods for model selection and model comparison. The BT implements three of the most common: DIC, WAIC, and the Bayes factor. + +* On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 + +* For an overview of DIC and WAIC, see Gelman, A.; Hwang, J. & Vehtari, A. (2014) Understanding predictive information criteria for Bayesian models. Statistics and Computing, 24, 997-1016-. On DIC, see also the original reference by Spiegelhalter, D. J.; Best, N. G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. + + +The Bayes factor relies on the estimation of marginal likelihoods, which is numerically challenging. The BT package currently implements three methods + +* The recommended method is the "Chib" method (Chib and Jeliazkov, 2001), which is based on MCMC samples but performs additional calculation. Although this is the current recommendation, note that there are some numerical issues with this algorithm that may limit its reliability for larger dimensions. + +* The harmonic mean approximation is implemented for comparison purposes only. Note that this method is numerically unreliable and should not normally be used. + +* The third method is simply sampling from the prior. While in principle unbiased, it converges only for a large number of samples and is therefore numerically inefficient. + +## Example + +Data linear regression with quadratic and linear effect + +```{r} +sampleSize = 30 +x <- (-(sampleSize-1)/2):((sampleSize-1)/2) +y <- 1 * x + 1*x^2 + rnorm(n=sampleSize,mean=0,sd=10) +plot(x,y, main="Test Data") +``` + +Likelihoods for both + +```{r} +likelihood1 <- function(param){ + pred = param[1] + param[2]*x + param[3] * x^2 + singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) + return(sum(singlelikelihoods)) +} + +likelihood2 <- function(param){ + pred = param[1] + param[2]*x + singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[3]^2), log = T) + return(sum(singlelikelihoods)) +} +``` + + +Posterior definitions + + +```{r} +setUp1 <- createBayesianSetup(likelihood1, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) + +setUp2 <- createBayesianSetup(likelihood2, lower = c(-5,-5,0.01), upper = c(5,5,30)) +``` + +MCMC and marginal likelihood estimation + + +```{r, results = 'hide'} +settings = list(iterations = 15000, message = FALSE) +out1 <- runMCMC(bayesianSetup = setUp1, sampler = "Metropolis", settings = settings) +#tracePlot(out1, start = 5000) +M1 = marginalLikelihood(out1) +M1 + +settings = list(iterations = 15000, message = FALSE) +out2 <- runMCMC(bayesianSetup = setUp2, sampler = "Metropolis", settings = settings) +#tracePlot(out2, start = 5000) +M2 = marginalLikelihood(out2) +M2 +``` + +### Model comparison via Bayes factor + +Bayes factor (need to invert the log) + +```{r} +exp(M1$ln.ML - M2$ln.ML) +``` + +BF > 1 means that the evidence favors M1. See Kass, R. E. & Raftery, A. E. (1995) Bayes Factors. J. Am. Stat. Assoc. Amer Statist Assn, 90, 773-795. + +Assuming equal prior weights for all models, we can calculate the posterior weight of M1 as + +```{r} +exp(M1$ln.ML) / ( exp(M1$ln.ML) + exp(M2$ln.ML)) +``` +If the models have different model priors, then multiply by the prior probability of each of the models. + + +### Comparing Models by DIC + +The Deviance Information Criterion is a commonly used method to summarize the fit of an MCMC chain. It can be calculated using + +```{r} +DIC(out1)$DIC +DIC(out2)$DIC +``` + +### Model Comparison via WAIC + +The Watanabe-Akaike Information Criterion is another criterion for model comparison. To compute the WAIC, the model must implement a log-likelihood density that allows the log-likelihood to be computed pointwise (the likelihood functions require a "sum" argument that determines whether the summed log-likelihood should be returned). It can be obtained via + +```{r} +# This will not work, since likelihood1 has no sum argument +# WAIC(out1) + +# likelihood with sum argument +likelihood3 <- function(param, sum = TRUE){ + pred <- param[1] + param[2]*x + param[3] * x^2 + singlelikelihoods <- dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) + return(if (sum == TRUE) sum(singlelikelihoods) else singlelikelihoods) +} +setUp3 <- createBayesianSetup(likelihood3, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) +out3 <- runMCMC(bayesianSetup = setUp3, sampler = "Metropolis", settings = settings) + +WAIC(out3) +``` diff --git a/BayesianTools/vignettes/InterfacingAModel.Rmd b/BayesianTools/vignettes/InterfacingAModel.Rmd index 636490d..74e9ee7 100644 --- a/BayesianTools/vignettes/InterfacingAModel.Rmd +++ b/BayesianTools/vignettes/InterfacingAModel.Rmd @@ -1,300 +1,307 @@ ---- -title: "Interfacing your model with R" -output: - rmarkdown::html_vignette: - toc: true -vignette: > - %\VignetteIndexEntry{Interfacing your model with R} - \usepackage[utf8]{inputenc} - %\VignetteEngine{knitr::rmarkdown} -abstract: "This tutorial discusses how to interface models written in other programming languages with R, so that they can be fit with BayesianTools" -author: Florian Hartig -editor_options: - chunk_output_type: console ---- - -```{r global_options, include=FALSE} -knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) -``` - -```{r, echo = F, message = F} -set.seed(123) -``` - -# Interfacing a model with BT - step-by-step guide - -## Step 1: Create a runModel(par) function - -A basic requirement to allow calibration in BT is that we need to be able to execute the model with a given set of parameters. Strictly speaking, BT will not see the model as such, but requires a likelihood function with interface likelihood(par), where par is a vector, but in this function, you will then probably run the model with parameters par, where par could stay a vector, or be transformed to another format, e.g. data.frame, matrix or list. - -What happens now depends on how your model is programmed - I have listed the steps in order of convenience / speed. If your model has never been interfaced with R you will likely have to move down to the last option. - -\begin{enumerate} -\item Model in R, or R interface existing -\item Model can be compiled and linked as a dll -\item Model is in C/C++ and can be interfaced with RCPP -\item Model can be compiled as executable and accepts parameters via the command line -\item Model can be compiled as executable reads parameters via parameter file -\item Model parameters are hard-coded in the executable -\end{enumerate} - -### Case 1 - model programmed in R - -Usually, you will have to do nothing. Just make sure you can call your model a in - -```{r, eval = F} -runMyModel(par) -``` - -Typically this function will directly return the model outputs, so step 2 can be skipped. - -### Case 2 - compiled dll, parameters are set via dll interface - -If you have your model prepared as a dll, or you can prepare it that way, you can use the \ref{https://stat.ethz.ch/R-manual/R-devel/library/base/html/dynload.html}{dyn.load()} function to link R to your model - -```{r, eval = F} -dyn.load(model) - -runMyModel(par){ - out = # model call here - # process out - return(out) -} -``` - -Again, if you implement this, you will also typically return the output directly via the dll and not write to file, which means that step 2 can be skipped. - -The tricky thing in this approach is that you have to code the interface to your dll, which technically means in most programming languages to set your variables as external or something similar, so that they can be accessed from the outside. How this works will depend on the programming language. - - -### Case 3 - model programmed in C / C++, interfaced with RCPP - -RCPP is a highly flexible environment to interface between R and C/C++. If your model is coded in C / C++, RCPP offers the most save and powerful way to connect with R (much more flexible than with command line or dll). - -However, doing the interface may need some adjustments to the code, and there can be technical problems that are difficult to solve for beginners. I do not recommend to attempt interfacing an existing C/C++ model unless you have RCPP experience, or at least very food C/C++ experience. - -Again, if you implement this, you will also typically return the output directly via the dll and not write to file, which means that step 2 can be skipped. - -### Case 4 - compiled executable, parameters set via command line (std I/O) - -If your model is written in a compiled or interpreted language, and accepts parameters via std I/O, wrapping is usually nothing more than writing the system call in an R function. An example would be - -```{r, eval = F} -runMyModel(par){ - - # Create here a string with what you would write to call the model from the command line - systemCall <- paste("model.exe", par[1], par[2]) - - out = system(systemCall, intern = TRUE) # intern indicates whether to capture the output of the command as an R character vector - - # write here to convert out in the apprpriate R classes - -} -``` - -Note: If you have problems with the system command, try system2. If the model returns the output via std.out, you can catch this and convert it and skip step 2. If your model writes to file, go to step 2. - -### Case 5 - compiled model, parameters set via parameter file or in any other method - -Many models read parameters with a parameter file. In this case you want to do something like this - -```{r, eval = F} -runMyModel(par, returnData = NULL){ - - writeParameters(par) - - system("Model.exe") - - if(! is.null(returnData)) return(readData(returnData)) # The readData function will be defined later - -} - -writeParameters(par){ - - # e.g. - # read template parameter fil - # replace strings in template file - # write parameter file -} -``` - -Depending on your problem, it can also make sense to define a setup function such as - -```{r, eval = F} -setUpModel <- function(parameterTemplate, site, localConditions){ - - # create the runModel, readData functions (see later) here - - return(list(runModel, readData)) - -} -``` - -How you do the write parameter function depends on the file format you use for the parameters. In general, you probably want to create a template parameter file that you use as a base and from which you change parameters - -* If your parameter file is in an *.xml format*, check out the xml functions in R -* If your parameter file is in a *general text format*, the best option may be to create a template parameter file, place a unique string at the locations of the parameters that you want to replace, and then use string replace functions in R, e.g. [grep](https://stat.ethz.ch/R-manual/R-devel/library/base/html/grep.html) to replace this string. - -### Case 6 - compiled model, parameters cannot be changed - -You have to change your model code to achieve one of the former options. If the model is in C/C++, going directly to RCPP seems the best alternative. - -## Step 2: Reading back data - -If your model returns the output directly (which is highly preferable, ), you can skip this step. - -For simple models, you might consider returning the model output directly with the runMyModel function. This is probably so for cases a) and b) above, i.e. model is already in R, or accepts parameters via command line. - -More complicated models, however, produce a large number of outputs and you typically don't need all of them. It is therefore more useful to make on or several separate readData or getDate function. The only two different cases I will consider here is - -* via dll / RCPP -* via file ouputs - -*Model is a dll* If the model is a dll file, the best thing would probably be to implement appropriate getData functions in the source code that can then be called from R. If your model is in C and in a dll, interfacing this via RCPP would probably be easier, because you can directly return R dataframes and other data structures. - - -*Model writes file output* If the model writes file output, write a getData function that reads in the model outputs and returns the data in the desired format, typically the same that you would use to represent your field data. - - -```{r, eval = F} -getData(type = X){ - - read.csv(xxx) - - # do some transformation - - # return data in desidered format -} -``` - - -\subsection{Testing the approach} - - -From R, you should now be able to do something like that - - -```{r, eval = F} -par = c(1,2,3,4 ..) - -runMyModel(par) - -output <- getData(type = DesiredType) - -plot(output) -``` - - - - -## Step 3 (optional) - creating an R package from your code - -The last step is optional, but we recommend that you take it from the start, because there is really no downside to it. You work with R code in several files that you run by hand, or diretly put all code into an R package. Creating and managing R packages is very easy, and it's easier to pass on your code because everything, including help, is in on package. To create an R package, follow the tutorial \href{http://biometry.github.io/APES/R/R70-PackageDevelopment.html}{here}. Remember to create a good documentation using Roxygen. - - -# Speed optimization and parallelization - -For running sensitivity analyses or calibrations, runtime is often an issue. Before you parallelize, make sure your model is as fast as possible. - -## Easy things - -* Are you compiling with maximum optimization (e.g. -o3 in cpp) -* If you have a spin-up phase, could you increase the time-step during this phase? -* Could you increase the time step generally -* Do you write unnecessary outputs that you could turn off (harddisk I/O is often slow)? - -## Difficult things - -* Make the model directly callable (RCPPor dll) to avoid harddisk I/O -* Is it possible to reduce initialization time (not only spin-up, but also for reading in the forcings / drivers) by avoid ending the model executable after each run, but rather keep it "waiting" for a new run. -* Code optimization: did you use a profiler? Read up on code optimization -* Check for unnecessary calculations in your code / introduce compiler flags where appropriate - -## Parallelization - -A possibility to speed up the run time of your model is to run it on multiple cores (CPU's). To do so, you have two choices: - -1. Parallelize the model itself -2. Parallelize the model call, so that BT can do several model evaluations in parallel - -Which of the two makes more sense depends a lot on your problem. To parallelize the model itself will be interesting in particular for very large models, which could otherwise not be calibrated with MCMCs. However, this approach will typically require to write parallel C/C++ code and require advanced programming skills, which is the reason why we will not further discuss it here. - -The usual advice in parallel computing is anyway to parallelize the outer loops first, to minimize communication overhead, which would suggest to start with parallelizing model evaluations. This is also much easier to program. Even within this, there are two levels of parallelization possible: - -1. Parallelize the call of several MCMC / SMC samplers -2. Parallelize within the MCMC / SMC samplers - -Currently, BT only supports parallelization within MCMCs / SMCs, but it easy to also implement between sampler parallelization by hand. Both approaches are describe below. - -### Within sampler parallelization - -Within-sampler parallelization is particular useful for algorithms that can use a large number of cores in parallel, e.g. sensitivity analyses or SMC sampling. For the MCMCs, it depends on the settings and the algorithm how much parallelization they can make use of. In general, MCMCs are Markovian, as the name says, i.e. the set up a chain of sequential model evaluations, and those calls can therefore not be fully parallelized. However, a number of MCMCs in the BT package uses MCMC algorithms that can be partly parallelized, in particular the population MCMC algorithms DE/DEzs/DREAM/DREAMzs. For all these cases, BT will automatically use parallelization of the BT setup indicates that this is implemented. - -How to do this? A first requirement to do so is to to have your model wrapped into an R function (see PREVIOUS SECTION). If that is the case, R offers a number of options to run functions in parallel. The easiest is to use the parallel package that comes with the R core. For other packages, see the internet and the CRAN task view on [High Performance Computing](https://CRAN.R-project.org/view=HighPerformanceComputing) - -As an example, assume we have the following, very simple model: - -```{r} -mymodel<-function(x){ - output<-0.2*x+0.1^x - return(output) -} -``` - -To start a parallel computation, we will first need to create a cluster object. Here we will initiate a cluster with 2 CPU's. - -```{r, eval = F} - -library(parallel) -cl <- makeCluster(2) - -runParallel<- function(parList){ - parSapply(cl, parList, mymodel) -} - -runParallel(c(1,2)) -``` - -You could use this principle to build your own parallelized likelihood. However, something very similar to the previous loop is automatized in BayesianTools. You can directly create a parallel model evaluation function with the function generateParallelExecuter, or alternatively directly in the createBayesianSetup - -```{r, eval = F} -library(BayesianTools) -parModel <- generateParallelExecuter(mymodel) -``` - -If your model is tread-safe, you should be able to run this out of the box. I therefore recommend using the hand-coded paraellelization only of the model is not thread-safe. - -### Running several MCMCs in parallel - -Additionally to the within-chain parallelization, you can also run several MCMCs in parallel, and combine them later to a single McmcSamplerList - -```{r} -library(BayesianTools) - -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup <- createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) - -settings = list(iterations = 200) - -# run the several MCMCs chains either in seperate R sessions, or via R parallel packages -out1 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) -out2 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) - -res <- createMcmcSamplerList(list(out1, out2)) -plot(res) -``` - - - -### Thread safety - -Thread safety quite generally means that you can execute multiple instances of your code on your hardware. There are various things that can limit Thread safety, for example - -* writing outputs to file (several threads might write to the same file at the same time) - - - - - - - +--- +title: "Interfacing your model with R" +output: + rmarkdown::html_vignette: + toc: true +vignette: > + %\VignetteIndexEntry{Interfacing your model with R} + \usepackage[utf8]{inputenc} + %\VignetteEngine{knitr::rmarkdown} + +author: Florian Hartig +editor_options: + chunk_output_type: console +--- + +```{r global_options, include=FALSE} +knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) +``` + +```{r, echo = F, message = F} +set.seed(123) +``` + +# Abstract + +This tutorial discusses how to interface models written in other programming languages with R, so that they can be fit with BayesianTools. + +# Interfacing a model with BT - step-by-step guide + +## Step 1: Create a runModel(par) function + +To enable calibration in BT, it's essential to run the model with a specified set of parameters. In fact, BT does not see the model as such, but requires a likelihood function with the interface likelihood(par), where par is a vector, but in this function you will probably then run the model with the parameters par, where par could remain a vector or be transformed into some other format, e.g. data.frame, matrix or list. + +What happens next depends on how your model is programmed. The following steps are arranged according to speed and convenience. If your model has not been interfaced with R before, you will most likely have to skip to the last option. + +\begin{enumerate} +\item Model in R, or R interface existing +\item Model can be compiled and linked as a `dll` +\item Model is in C/C++ and can be interfaced with RCPP +\item Model can be compiled as executable and accepts parameters via the command line +\item Model can be compiled as executable reads parameters via parameter file +\item Model parameters are hard-coded in the executable +\end{enumerate} + +### Case 1 - model programmed in R + +Typically, no action is required. Ensure that you are able to call your model. + +```{r, eval = F} +runMyModel(par) +``` + +Usually, this function returns model outputs directly, thus step 2 is unnecessary. + +### Case 2 - compiled dll, parameters are set via dll interface + +If your model is already in the form of a DLL, or if you can prepare it as such, use the function \ref{https://stat.ethz.ch/R-manual/R-devel/library/base/html/dynload.html}{dyn.load()} to link R to your model. + +```{r, eval = F} +dyn.load(model) + +runMyModel(par){ + out = # model call here + # process out + return(out) +} +``` + +If you implement this process, you will also usually return the output directly via the `dll` and not write to a file, which means that step 2 can be skipped. + +The problem with this approach is that you have to code the interface to your `dll`, which in most programming languages technically means setting your variables as external or something like that, so that they can be accessed from outside. The specifics of how this works will vary depending on the programming language being used. + + +### Case 3 - model programmed in C / C++, interfaced with RCPP + +RCPP provides a highly flexible platform to interface between R and C/C++. RCPP provides a secure and powerful way to connect to R if your model is coded in C/C++ (much more flexible than using the command line or a `dll`). + +Nevertheless, code adjustments may be necessary for the interface, and beginners may find it challenging to resolve any technical issues. Attempting to interface an existing C/C++ model without prior experience using RCPP or at least substantial experience with C/C++ is not advisable. + +In addition, step 2 can be skipped if you are implementing this, as you will usually return the output directly via the `dll`, rather than writing to a file. + +### Case 4 - compiled executable, parameters set via command line (std I/O) + +If your model is written in a compiled or interpreted language and accepts parameters via std I/O, wrapping is usually nothing more than writing the system call in an R function. For example + +```{r, eval = F} +runMyModel(par){ + + # Create here a string with what you would write to call the model from the command line + systemCall <- paste("model.exe", par[1], par[2]) + + out = system(systemCall, intern = TRUE) # intern indicates whether to capture the output of the command as an R character vector + + # write here to convert out in the apprpriate R classes + +} +``` + +Note: If you encounter difficulties with the system command, try system2. If the model provides the output via std.out, you can catch and convert it and skip step 2. If your model writes the output to a file, proceed to step 2. + +### Case 5 - compiled model, parameters set via parameter file or in any other method + +Many models use parameter files to read parameters. For this case, you want to do something like the following example + +```{r, eval = F} +runMyModel(par, returnData = NULL){ + + writeParameters(par) + + system("Model.exe") + + if(! is.null(returnData)) return(readData(returnData)) # The readData function will be defined later + +} + +writeParameters(par){ + + # e.g. + # read template parameter fil + # replace strings in template file + # write parameter file +} +``` + +For some problems, it may be useful to create a setup function, as in the example below. + +```{r, eval = F} +setUpModel <- function(parameterTemplate, site, localConditions){ + + # create the runModel, readData functions (see later) here + + return(list(runModel, readData)) + +} +``` + +The way you write a parameter function depends on the file format you are using for the parameters. Usually, creating a template parameter file is recommended as a starting point, and then the parameters can be changed as required. + +* If your parameter file is in an *.xml format*, check out the xml functions in R. +* If your parameter file is in a *general text format*, the best option may be to create a template parameter file, place a unique string at the locations of the parameters that you want to replace, and then use string replace functions in R, e.g. [grep](https://stat.ethz.ch/R-manual/R-devel/library/base/html/grep.html) to replace this string. + +### Case 6 - compiled model, parameters cannot be changed + +To achieve one of the previous options, you must change your model code. If the model is in C/C++, the best alternative is to go directly to RCPP. + +## Step 2: Read back data + +If your model returns the output directly (which is highly preferable, ), you can skip this step. + +You can skip this process if your model directly returns the output (which is highly recommended). + +If you have a simple model, you might consider using the `runMyModel` function to return the model's output directly. This is suitable for cases in a) and b) namely, models that are already in R, or receive parameters via the command line. + +In contrast, more complex models generate a large number of outputs. However, usually you do not need all of them. Therefore, it is more useful to create one or multiple separate `readData` or `getDate` functions. The only two cases I will consider here are + +* via dll / RCPP +* via file ouputs + +*Model is a dll* If the model is a `dll` file, it would probably be best to implement appropriate `getData` functions in the source code that can then be called from R. If your model is in C and in a `dll`, interfacing it via RCPP would probably be easier because you can return R dataframes and other data structures directly. + + +*Model writes file output* If the model generates file output, create a `getData` function that reads the model outputs and returns the data in the desired format, typically the same format you would use to represent your field data. + + + +```{r, eval = F} +getData(type = X){ + + read.csv(xxx) + + # do some transformation + + # return data in desidered format +} +``` + + +\subsection{Testing the approach} + + +You should now see an example from R that looks like this + + +```{r, eval = F} +par = c(1,2,3,4 ..) + +runMyModel(par) + +output <- getData(type = DesiredType) + +plot(output) +``` + + + + +## Step 3 (optional) - creating an R package from your code + +Although the final step is optional, we recommend doing it from the beginning because there is really no downside. You can work with R code in multiple files that can be run manually or incorporated into an R package directly. Creating and managing R packages is a straightforward process and makes it simpler to share your code, as everything, including help guides, is in one package. To create an R package, please refer to the tutorial \href{http://biometry.github.io/APES/R/R70-PackageDevelopment.html}{here}. Please remember to write good documentation using Roxygen. + + +# Speed optimization and parallelization + +Runtime is often a concern when performing sensitivity analyses or calibrations. Ensure that your model has been optimized for maximum speed before parallelization. + +## Easy things + +* Are you compiling with maximum optimization (e.g. -o3 in cpp) +* If there is a spin-up phase, consider increasing the time step during that phase. +* Consider increasing the time step in general. +* Are you producing unnecessary outputs that could be turned off to reduce hard disk I/O, which is often slow? + +## Difficult things + +* Make the model directly callable (RCPP or dll) to avoid harddisk I/O +* Is it possible to reduce the initialization time (not only for spin-up, but also for reading the forcings / drivers) by not terminating the model executable after each run, but keeping it "waiting" for a new run? +* Code optimization: did you use a profiler? Read up on code optimization +* Check for unnecessary calculations in your code / introduce compiler flags where appropriate + +## Parallelization + +One way to speed up the runtime of your model is to run it on multiple cores (CPUs). To do so, you have two choices: + +1. Parallelize the model itself +2. Parallelize the model call so that BT can perform multiple model evaluations in parallel. + +Which of the two makes more sense depends a lot on your problem. Parallelizing the model itself will be especially interesting for very large models that could not otherwise be calibrated with MCMCs. However, this approach typically requires writing parallel C/C++ code and advanced programming skills, which is why we will not discuss it further here. + +The usual advice in parallel computing anyway is to parallelize the outer loops first to minimize the communication overhead, which would suggest starting with parallelizing the model evaluations. This is also much easier to program. Even within that, there are two levels of parallelization possible: + +1. Parallelize the call of multiple MCMC / SMC samplers. +2. Parallelize within the MCMC / SMC samplers + +Currently, BT only supports parallelization within MCMCs / SMCs, but it easy to also implement between sampler parallelization by hand. Both approaches are describe below. + +### Within sampler parallelization + +Within-sampler parallelization is particularly useful for algorithms that can use a large number of cores in parallel, such as sensitivity analysis or SMC sampling. For MCMCs, the amount of parallelization that can be used depends on the settings and the algorithm. In general, MCMCs are, as the name implies, Markovian, i.e., they set up a chain of sequential model evaluations, and these calls cannot be fully parallelized. However, a number of MCMCs in the BT package uses MCMC algorithms that can be partly parallelized, in particular the population MCMC algorithms DE/DEzs/DREAM/DREAMzs. In all these cases, BT will automatically use parallelization of the BT setup to indicate that it is implemented. + +How to do this? A first requirement is that your model is wrapped in an R function (see PREVIOUS SECTION). Once that is the case, R provides a number of ways to run functions in parallel. The easiest is to use the parallel package that comes with the R core. Other packages can be found on the Internet and in the CRAN task view at [High Performance Computing](https://CRAN.R-project.org/view=HighPerformanceComputing) + +As an example, suppose we have the following very simple model: + +```{r} +mymodel<-function(x){ + output<-0.2*x+0.1^x + return(output) +} +``` + +To start a parallel computation, we must first create a cluster object. Here we start a cluster with 2 CPUs. + +```{r, eval = F} + +library(parallel) +cl <- makeCluster(2) + +runParallel<- function(parList){ + parSapply(cl, parList, mymodel) +} + +runParallel(c(1,2)) +``` + +You could use this principle to build your own parallelized likelihood. However, something very similar to the previous loop is automated in `BayesianTools`. You can create a parallel model evaluation function directly with the `generateParallelExecuter` function, or alternatively directly in the `createBayesianSetup` function. + +```{r, eval = F} +library(BayesianTools) +parModel <- generateParallelExecuter(mymodel) +``` + +If your model is thread-safe, you should be able to run it out of the box. Therefore, I recommend using the hand-coded parallelization only if your model is not thread-safe. + +### Running several MCMCs in parallel + +In addition to within-chain parallelization, you can also run multiple MCMCs in parallel and later combine them into a single `McmcSamplerList`. + +```{r} +library(BayesianTools) + +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup <- createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) + +settings = list(iterations = 200) + +# run the several MCMCs chains either in seperate R sessions, or via R parallel packages +out1 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) +out2 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) + +res <- createMcmcSamplerList(list(out1, out2)) +plot(res) +``` + + + +### Thread safety + +Thread safety generally means that you can run multiple instances of your code on your hardware. There are several things that can limit thread safety, such as + +* Writing output to a file (multiple threads can write to the same file at the same time) + + + + + + + From 3ee64e205c580156df58f28ca8f68400c3cf656b Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 24 Aug 2023 13:33:32 +0200 Subject: [PATCH 02/20] Updated help file for BayesianSetupGenerateParallel.R --- .../R/BayesianSetupGenerateParallel.R | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index 4a5cb5a..0851f84 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -2,14 +2,26 @@ #' #' @author Florian Hartig #' @param fun function to be changed to parallel execution -#' @param parallel should a parallel R cluster be used or not. If set to T, cores will be detected automatically and n-1 of the available n cores of the machine will be used. Alternatively, you can set the number of cores used by hand -#' @param parallelOptions list containing three lists. First "packages" determines the R packages necessary to run the likelihood function. Second "variables" the objects in the global environment needed to run the likelihood function and third "dlls" the DLLs needed to run the likelihood function (see Details). -#' @note Can also be used to make functions compatible with library sensitivity -#' @details For parallelization, option T means that an automatic parallelization via R is attempted, or "external", in which case it is assumed that the likelihood is already parallelized. In this case it needs to accept a matrix with parameters as columns. -#' Further you can specify the packages, objects and DLLs that are exported to the cluster. -#' By default a copy of your workspace is exported. However, depending on your workspace this can be very inefficient. -#' -#' Alternatively you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). +#' @param parallel should a parallel R cluster be used? If set to T, machine will +#' automatically detect the available cores and n-1 of the available n cores +#' will be used. Alternatively, you can manually set the number of cores to be used +#' @param parallelOptions a list containing three lists. \n First, "packages": determines +#' the R packages required to run the likelihood function. \n Second, "variables": +#' the objects in the global environment needed to run the likelihood function +#' \n Third, "dlls": the DLLs needed to run the likelihood function (see Details). +#' @note can be used to make functions compatible with library sensitivity +#' @details For parallelization, if option T is selected, an automatic parallelization +#' is tried via R. Alternatively, "external" can be selected on the assumption +#' that the likelihood has already been parallelized. In the latter case, a matrix +#' with parameters as columns must be accepted. +#' +#' You can also specify which packages, objects and DLLs are exported to the cluster. +#' +#' By default, a copy of your workspace is exported, but depending on your workspace, +#' this can be inefficient. +#' +#' As an alternative, you can specify the environments and packages in the +#' likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). #' @export #' @example /inst/examples/generateParallelExecuter.R @@ -28,7 +40,7 @@ generateParallelExecuter <- function(fun, parallel = F, parallelOptions = list(v #library(iterators) # library(parallel) - if (parallel == T | parallel == "auto"){ + { cores <- parallel::detectCores() - 1 } else if (is.numeric(parallel)){ cores <- parallel From 6f0fd05c5f0a23c29cb3c174e7bc22cf97d9852c Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 24 Aug 2023 14:22:29 +0200 Subject: [PATCH 03/20] Update BayesianTools.Rmd --- BayesianTools/vignettes/BayesianTools.Rmd | 1717 ++++++++++++--------- 1 file changed, 952 insertions(+), 765 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index f11ecc3..2fb37d8 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -1,765 +1,952 @@ ---- -title: "Bayesian Tools - General-Purpose MCMC and SMC Samplers and Tools for Bayesian Statistics" -output: - rmarkdown::html_vignette: - toc: true -vignette: > - %\VignetteIndexEntry{Manual for the BayesianTools R package} - %\VignetteEngine{knitr::rmarkdown} - \usepackage[utf8]{inputenc} - - ---- - -```{r global_options, include=FALSE} -knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) -``` - -```{r, echo = F, message = F} -set.seed(123) -``` - -# Abstract - -The BayesianTools (BT) package supports model analysis (including sensitivity analysis and uncertainty analysis), Bayesian model calibration, as well as model selection and multi-model inference techniques for system models. - -# Quick start - -The purpose of this first section is to give you a quick overview of the most important functions of the BayesianTools (BT) package. For a more detailed description, see the following sections. - -### Install, load and cite the package - -If you haven't installed the package yet, either run - -```{r, eval = F} -install.packages("BayesianTools") -``` - -or follow the instructions at [https://github.com/florianhartig/BayesianTools](https://github.com/florianhartig/BayesianTools) to install a development version or an older version. - -Loading and citation - -```{r} -library(BayesianTools) -citation("BayesianTools") -``` - -Note: BayesianTools calls a number of secondary packages. Of particular importance is `coda`, which is used in a number of plots and summary statistics. If you use a lot of summary statistics and diagnostic plots, it would be nice to cite coda as well! - -Pro Tip: If you are running a stochastic algorithm such as MCMC, you should always set or record your random seed to make your results reproducible (otherwise the results will change slightly each time you run the code). - -```{r} -set.seed(123) -``` - -In a real application, recording the session info would be helpful in ensuring reproducibility. - -```{r, eval = F} -sessionInfo() -``` - -This session information includes the version number of R and all loaded packages. - -## The Bayesian Setup - -The central object in the `BT` package is the `BayesianSetup`. This class contains the information about the model to be fit (likelihood), and the priors for the model parameters. - -The `createBayesianSetup` function generates a `BayesianSetup` object. The function requires a log-likelihood and a log-prior (optional) as arguments. It then automatically creates the posterior and various convenience functions for the samplers. - -Advantages of the `BayesianSetup` include -1. support for automatic parallelization -2. functions are wrapped in try-catch statements to avoid crashes during long MCMC evaluations -3. and the posterior checks if the parameter is outside the prior first, in which case the likelihood is not evaluated (makes the algorithms faster for slow likelihoods). - -If no prior information is provided, an unbounded flat prior is generated. If no explicit prior is specified, but lower and upper values are given, a standard uniform prior with the respective bounds is created, including the option to sample from this prior, which is useful for SMC and obtaining initial values. This option is used in the following example, which creates a multivariate normal likelihood density and a uniform prior for 3 parameters. - -```{r} -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) -``` - -A more detailed description of the `BayesianSetup` will follow. - -**Hint:** For an example of how to run these steps for a dynamic ecological model, see `?VSEM`. - -## Run MCMC and SMC functions - -After setup, you may need to run a calibration. The `runMCMC` function serves as the main wrapper for all other implemented `MCMC`/`SMC` functions. It always requires the following arguments: - -* `bayesianSetup` (alternatively, the log target function) -* `sampler` name -* list with `settings` for each sampler - if `settings` is not specified, the default value will be applied - -For example, choosing the `sampler` name "Metropolis" calls a versatile Metropolis-type MCMC with options for covariance adjustment, delayed rejection, tempering and Metropolis-within-Gibbs sampling. For details, see the later reference on MCMC samplers. - -```{r} -iter = 10000 -settings = list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -``` - -### Summarize the outputs - -You can plot and summarize all `sampler`s from the console with the standard `print` and `summary` commands. - -```{r} -print(out) -summary(out) -``` - -You can also use built-in plot functions from the package for visualization. The `marginalPlot` can be either plotted as histograms with density overlay (default setting) or as a violin plot (see "?marginalPlot"). - -```{r} -plot(out) # plot internally calls tracePlot(out) -correlationPlot(out) -marginalPlot(out, prior = TRUE) -``` - -Additional functions that may be used on all `sampler`s are model selection scores, including the Deviance Information Criterion (DIC) and the marginal likelihood (see later section for details on calculating the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set of methods are available for calculation of marginal likelihood (refer to "?marginalLikelihood"). - -```{r} -marginalLikelihood(out) -DIC(out) -MAP(out) -``` - -To extract part of the sampled parameter values, you can use the following process: - -```{r, eval = F} -getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) -``` - -For all samplers, you can conveniently perform multiple runs using the `nrChains` argument - -```{r, echo = T} -iter = 1000 -settings = list(iterations = iter, nrChains = 3, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) - -``` - -The result is an object of `mcmcSamplerList`, which should allow you to do everything you can do with an `mcmcSampler` object (sometimes with slightly different output). - -```{r} -print(out) -summary(out) -``` - -For example, in the plot you now see 3 chains. - -```{r} -plot(out) -``` - -There are some additional features that may only be available for lists, such as convergence checks. - -```{r} -#getSample(out, coda = F) -gelmanDiagnostics(out, plot = T) -``` - - -### Which sampler to choose? - -The BT package provides a large class of different MCMC samplers, and it depends on the particular application which one is most suitable. - -In the absence of further information, we currently recommend the `DEz`s sampler. This is also the default in the `runMCMC` function. - - -# BayesianSetup Reference - - -## Reference on creating likelihoods - -The likelihood should be provided as a log density function. - -```{r, eval = F} -ll = logDensity(x) -``` - -See parallelization options below. We will use a simple 3-d multivariate normal density for the demonstration. - -```{r} -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) -``` - -### Parallelization of the likelihood evaluations - -Likelihoods are often costly to compute. If this is the case for you, you should think about parallelization possibilities. The 'createBayesianSetup' function has an input variable 'parallel', with the following options - -* F / FALSE means no parallelization should be used -* T / TRUE means to use R's automatic parallelization options (note: this will not work if your likelihood is writing to file, or using global variables or functions - see R's general help on parallelization) -* "external", assumes that the likelihood is already parallelized. In this case, the function needs to take a matrix with parameters as columns, and rows as the different model runs you want to evaluate. This is the most likely option to use if you have a complicated setup (file I/O, HPC cluster) that cannot be handled with the standard R parallelization. - -Algorithms in the `BayesianTools` package can take advantage of parallelization if this option is specified in the `BayesianSetup`. Note that parallelization is currently used by the following algorithms: `SMC`, `DEzs` and `DREAMzs` sampler. It can also be used through the `BayesianSetup` with the functions of the sensitivity package. - -Here are some more details about the parallelization. - -#### 1. In-build parallelization: - -In-built parallelizing is the easiest way to use parallel computing. The "parallel" argument allows you to select the number of cores to use for parallelization. Alternatively, TRUE or "auto" will use all available cores except one. Now the proposals are evaluated in parallel. Technically, the built-in parallelization uses an R cluster to evaluate the posterior density function. The input to the parallel function is a matrix where each column represents a parameter and each row represents a proposal. This allows the proposals to be evaluated in parallel. For `sampler`s that evaluate only one proposal at a time (namely the Metropolis-based algorithms and DE/DREAM without the `zs` extension), parallelization cannot be used. - -#### 2. External parallelization - -The second option is to use external parallelization. Here, parallelization is attempted in the user-defined likelihood function. To use external parallelization, the likelihood function must take a matrix of proposals and return a vector of likelihood values. In the proposal matrix, each row represents a proposal, and each column represents a parameter. In addition, you will need to specify the "external" parallelization in the "parallel" argument. In simple terms, using external parallelization involves the following steps - -```{r, eval = FALSE} -## Definition of likelihood function -likelihood <- function(matrix){ - # Calculate likelihood in parallel - # Return vector of likelihood values -} - -## Create Bayesian Setup -BS <- createBayesianSetup(likelihood, parallel = "external", ...) - -## Run MCMC -runMCMC(BS, sampler = "SMC", ...) -``` - - - -#### 3. Multi-core and cluster calculations -If you want to run your calculations on a cluster there are several ways to do it. - -In the first case, you want to parallelize n internal (not total chains) on n cores. The argument "parallel = T" in "createBayesianSetup" only allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and `DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` samplers. - -```{r, eval = FALSE} -## n = Number of cores -n=2 -x <- c(1:10) -likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) -bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper = 5) - -## give runMCMC a matrix with n rows of proposals as startValues or sample n times from the previous created sampler -out <- runMCMC(bayesianSetup, settings = list(iterations = 1000)) -``` - -In the second case, you want to parallelize n internal chains on `n` cores with an external parallelized likelihood function. Unlike the previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized this way. - -```{r, eval = FALSE} -### Create cluster with n cores -cl <- parallel::makeCluster(n) - -## Definition of the likelihood -likelihood <- function(X) sum(dnorm(c(1:10), mean = X, log = T)) - -## Definition of the likelihood which will be calculated in parallel. Instead of the parApply function, we could also define a costly parallelized likelihood -pLikelihood <- function(param) parallel::parApply(cl = cl, X = param, MARGIN = 1, FUN = likelihood) - -## export functions, dlls, libraries -# parallel::clusterEvalQ(cl, library(BayesianTools)) -parallel::clusterExport(cl, varlist = list(likelihood)) - -## create BayesianSetup -bayesianSetup <- createBayesianSetup(pLikelihood, lower = -10, upper = 10, parallel = 'external') - -## For this case we want to parallelize the internal chains, therefore we create a n row matrix with startValues, if you parallelize a model in the likelihood, do not set a n*row Matrix for startValue -settings = list(iterations = 100, nrChains = 1, startValue = bayesianSetup$prior$sampler(n)) - -## runMCMC -out <- runMCMC(bayesianSetup, settings, sampler = "DEzs") -``` - -In another case, your likelihood requires a parallelized model. Start your cluster and export your model, the required libraries, and `dll`s. Now you can start your calculations with the argument "parallel = external" in `createBayesianSetup`. - -```{r, eval = FALSE} -### Create cluster with n cores -cl <- parallel::makeCluster(n) - -## export your model -# parallel::clusterExport(cl, varlist = list(complexModel)) - -## Definition of the likelihood -likelihood <- function(param) { - # ll <- complexModel(param) - # return(ll) -} - -## create BayesianSetup and settings -bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = 'external') -settings = list(iterations = 100, nrChains = 1) - -## runMCMC -out <- runMCMC(bayesianSetup, settings) - -``` - -In the last case, you can parallelize over whole chain calculations. However, the likelihood itself is not parallelized. Each chain is run on one core, and the likelihood is calculated on that core. - -```{r, eval = FALSE} -### Definition of likelihood function -x <- c(1:10) -likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) - -## Create BayesianSetup and settings -bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = F) -settings = list(iterations = 100000) - -## Start cluster with n cores for n chains and export BayesianTools library -cl <- parallel::makeCluster(n) -parallel::clusterEvalQ(cl, library(BayesianTools)) - -## calculate parallel n chains, for each chain the likelihood will be calculated on one core -out <- parallel::parLapply(cl, 1:n, fun = function(X, bayesianSetup, settings) runMCMC(bayesianSetup, settings, sampler = "DEzs"), bayesianSetup, settings) - -## Combine the chains -out <- createMcmcSamplerList(out) -``` - - - -** Note: Even though parallelization can significantly reduce the computation time, it is not always useful because of the so-called communication overhead (computational time for distributing and retrieving information from the parallel cores). For models with low computational cost, this procedure may take more time than the actual evaluation of the likelihood. If in doubt, do a small run-time comparison before starting your large sampling. ** - - -## Reference on creating priors - -The prior in the `BayesianSetup` consists of four parts - -* A log density function -* An (optional) sampling function (must be a function without parameters, that returns a draw from the prior) -* lower / upper boundaries -* Additional info - best values, names of the parameters, ... - -This information can be passed by first creating an extra object, via `createPrior`, or via the `createBayesianSetup` function. - -#### Creating priors - -You have 5 options to create a prior - -* Do not set a prior - in this case, an infinite prior will be created -* Set min/max values - a bounded flat prior and the corresponding sampling function will be created -* Use one of the predefinded priors, see `?createPrior` for a list. One of the options here is to use a previous MCMC output as the new prior. Predefined priors will usually come with a sampling function -* Use a user-defined prior, see `?createPrior` -* Create a prior from a previous MCMC sample - -#### Creating user-defined priors - -When creating a user-defined prior, the following information can/should be passed to `createPrior` - -* A log density function, as a function of a parameter vector x, same syntax as the likelihood. -* In addition, you should consider providing a function that samples from the prior, as many samplers (SMC, DE, DREAM) can use this function for initial conditions. If you use one of the predefined priors, the sampling function is already implemented. -* Lower / upper bounds (can be set on top of any prior to create truncation) -* Additional information - best values, parameter names, ... - -#### Creating a prior from a previous MCMC sample - -The following example from the help file illustrates the process - -```{r} -# Create a BayesianSetup -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) - -settings = list(iterations = 2500, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) - - -newPrior = createPriorDensity(out, method = "multivariate", eps = 1e-10, lower = rep(-10, 3), upper = rep(10, 3), best = NULL) -bayesianSetup <- createBayesianSetup(likelihood = ll, prior = newPrior) - -settings = list(iterations = 1000, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) -``` - - -# MCMC sampler reference - -## The runMCMC() function - -The `runMCMC` function is the central function for starting MCMC algorithms in the `BayesianTools` package. It takes a `bayesianSetup`, a choice of `sampler` (default is `DEzs`), and optionally changes to the default settings of the chosen `sampler`. - -```{r, message = F} -runMCMC(bayesianSetup, sampler = "DEzs", settings = NULL) -``` - -You may use an optional argument `nrChains`, which is set to the default value of 1 but can be modified if needed. Increasing its value will lead `runMCMC` to execute multiple runs. - -```{r, message = F} - -ll <- generateTestDensityMultiNormal(sigma = "no correlation") - -bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) - -settings = list(iterations = 10000, nrChains= 3, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) - -plot(out) -marginalPlot(out, prior = T) -correlationPlot(out) -gelmanDiagnostics(out, plot=T) - -# option to restart the sampler - -settings = list(iterations = 1000, nrChains= 1, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) - -out2 <- runMCMC(bayesianSetup = out) - -out3 <- runMCMC(bayesianSetup = out2) - -#plot(out) -#plot(out3) - -# create new prior from posterior sample - -newPriorFromPosterior <- createPriorDensity(out2) - -``` - - -## The different MCMC samplers - -For simplicity, we will define a fixed number of iterations. - -```{r} -iter = 10000 -``` - -### The Metropolis MCMC class - -The `BayesianTools` package is able to run a large number of Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can be accessed by the "Metropolis" `sampler` in the `runMCMC` function by specifying the `sampler`'s settings. - -The subsequent code provides an overview of the default settings of the MH `sampler`. - -```{r} -applySettingsDefault(sampler = "Metropolis") -``` - -Here are some examples of how to apply different settings. Activate individual options or combinations as demonstrated. - -### Standard MH MCMC -The following settings run the standard Metropolis Hastings MCMC. - -Refernences: -Hastings, W. K. (1970). Monte carlo sampling methods using markov chains -and their applications. Biometrika 57 (1), 97-109. - -Metropolis, N., A. W. Rosenbluth, M. N. Rosenbluth, A. H. Teller, and E. Teller -(1953). Equation of state calculations by fast computing machines. The journal -of chemical physics 21 (6), 1087 - 1092. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = F, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Standard MH MCMC, prior optimization -Prior to the sampling process, this `sampler` employs an optimization step. -The purpose of optimization is to improve the initial values and the covariance of the proposal distribution. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Adaptive MCMC, prior optimization -The adaptive Metropolis sampler (AM) uses the information already obtained during the sampling process to improve (or adapt) the proposal function. The `BayesianTools` package adjusts the covariance of the proposal distribution by utilizing the chain's history. - -References: -Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive metropolis -algorithm. Bernoulli , 223-242. - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - -#### Standard MCMC, prior optimization, delayed rejection -Although rejection is an essential step in an MCMC algorithm, it can also mean that the proposal distribution is (locally) poorly tuned to the target distribution. In a delayed rejection (DR) sampler, a second (or third, etc.) proposal is made before rejection. This proposal is usually drawn from a different distribution, allowing for greater flexibility of the sampler. In the `BayesianTools` package, the number of delayed rejection steps and the scaling of the proposals can be specified. -** Note that the current version supports only two delayed rejection steps. ** - - -References: -Green, Peter J., and Antonietta Mira. "Delayed rejection in reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = F, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - - -#### Adaptive MCMC, prior optimization, delayed rejection -The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a combination of the two previous `sampler`s (DR and AM). - -References: -Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." Statistics and Computing 16.4 (2006): 339-354. - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = T, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Standard MCMC, prior optimization, Gibbs updating -To reduce the dimensions of the target function, a Metropolis-within-Gibbs `sampler` can be run with the can be run with the `BayesianTools` package. This means that only a subset of the parameter vector is updated in each iteration. In the example below, at most two (of the three) parameters are updated at each step, and it is twice as likely to vary one as to vary two. - -** Note that currently adaptive cannot be mixed with Gibbs updating! ** - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = c(1,0.5,0), temperingFunction = NULL, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - -#### Standard MCMC, prior optimization, gibbs updating, tempering -Simulated tempering is closely related to simulated annealing (e.g., Bélisle, 1992) in optimization algorithms. -The idea of tempering is to increase the acceptance rate during burn-in. This should lead to a faster initial scanning of the target function. -To incorporate this, a tempering function must be provided by the user. -The function describes how to influence the acceptance rate during burn-in. In the example below, an exponential decline approaching 1 (= no influence on the acceptance rate) is used. - -References: -Bélisle, C. J. (1992). Convergence theorems for a class of simulated -annealing algorithms on rd. Journal of Applied Probability, 885–895. - -C. J. Geyer (2011) Importance sampling, simulated tempering, and umbrella sampling, in the Handbook of Markov Chain Monte Carlo, S. P. Brooks, et al (eds), Chapman & Hall/CRC. - -```{r, results = 'hide', eval = F} -temperingFunction <- function(x) 5 * exp(-0.01*x) + 1 -settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = c(1,1,0), temperingFunction = temperingFunction, optimize = T, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) -``` - - - -### Differential Evolution MCMC - -The BT package implements two differential evolution MCMCs. When in doubt, use the DEzs option. - -The first is the normal DE MCMC, according to Ter Braak, Cajo JF. "A Markov Chain Monte Carlo version of the genetic algorithm Differential Evolution: easy Bayesian computing for real parameter spaces". Statistics and Computing 16.3 (2006): 239-249. -This sampler runs multiple chains in parallel (but not in the sense of parallel computing). The main difference to the Metropolis based algorithms is the generation of the proposal. In general, all `sampler`s use the current position of the chain and add a step in the parameter space to generate a new proposal. While in the Metropolis based `sampler` this step is usually drawn from a multivariate normal distribution (but any distribution is possible), the `DE` `sampler` uses the current position of two other chains to generate the step for each chain. For successful sampling, at least `2*d` chains, where `d` is the number of parameters, must be run in parallel. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DE", settings = settings) -plot(out) -``` - -The second is the Differential Evolution MCMC with Snooker update and sampling from past states, according to ter Braak, Cajo JF, and Jasper A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. -This extension covers two differences from the normal `DE` MCMC. First, it uses a snooker update based on a user-defined probability. Second, past states of other chains are taken into account when generating the proposal. These extensions allow fewer chains (i.e., 3 chains are usually sufficient for up to 200 parameters) and parallel computing, since the current position of each chain depends only on the past states of the other chains. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) -plot(out) -``` - - -## DREAM sampler - -There are two versions of the DREAM `sampler`. First, the standard DREAM sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte Carlo simulation by differential evolution with self-adaptive randomized subspace sampling". International Journal of Nonlinear Sciences and Numerical Simulation 10.3 (2009): 273-290. - -This sampler is largely based on the DE sampler with some significant changes: -1) More than two chains can be used to generate a proposal. -2) Randomized subspace sampling can be used to improve efficiency for high-dimensional posteriors. Each dimension is updated with a crossover probability CR. To speed up the exploration of the posterior, DREAM adjusts the distribution of CR values during burn-in to favor large jumps over small ones. -3) Outlier chains can be removed during burn-in. - - -```{r, results = 'hide', eval = F} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAM", settings = settings) -plot(out) -``` - -The second implementation uses the same extension as the DEzs sampler. Namely sampling from past states and a snooker update. Again, this extension allows the use of fewer chains and parallel computing. - -Again, if in doubt, you should prefer "DREAMzs". - -```{r, results = 'hide', eval = FALSE} -settings <- list(iterations = iter, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAMzs", settings = settings) -plot(out) -``` - - - -## T-walk - -The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and Colin Fox. "A general purpose sampling algorithm for continuous distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. -The sampler uses two independent points to explore the posterior space. -Based on probabilities, four different moves are used to generate proposals for the two points. As with the DE sampler, this procedure does not require tuning of the proposal distribution for efficient sampling in complex posterior distributions. - - -```{r, eval = F} -settings = list(iterations = iter, message = FALSE) - -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Twalk", settings = settings) -``` - - -## Convergence checks for MCMCs - -All MCMCs should be checked for convergence. We recommend the standard Gelmal-Rubin procedure. This procedure requires running multiple MCMCs (we recommend 3). This can be done either directly in `runMCMC` (`nrChains = 3`) or, for runtime reasons, by combining the results of three independent `runMCMC` runs with `nrChains = 1`. - -```{r, eval = T} -settings <- list(iterations = iter, nrChains = 3, message = FALSE) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) -plot(out) - -#chain = getSample(out, coda = T) -gelmanDiagnostics(out, plot = F) -``` - - -## Non-MCMC sampling algorithms - -MCMCs sample the posterior space by creating a chain in parameter space. While this allows for "learning" from past steps, it does not allow for running a large number of posteriors in parallel. - -An alternative to MCMCs are particle filters, also known as Sequential Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for stochastic simulation models - theory and application Ecol. Lett., 2011, 14, 816-827 - - -### Rejection sampling - -The simplest option is to sample a large number of parameters and accept them according to their posterior value. This option can be emulated with the implemented SMC by setting iterations to 1. - -```{r, results = 'hide', eval = F} -settings <- list(initialParticles = iter, iterations= 1) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) -plot(out) -``` - -### Sequential Monte Carlo (SMC) - -The more sophisticated option is to use the implemented SMC, which is basically a particle filter that applies multiple filter steps. - -```{r, results = 'hide', eval = F} -settings <- list(initialParticles = iter, iterations= 10) -out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) -plot(out) -``` - -Note that using a number for `initialParticles` requires that the `bayesianSetup` includes the option to sample from the prior. - - -# Bayesian model comparison and averaging - -There are a number of Bayesian methods for model selection and model comparison. The BT implements three of the most common: DIC, WAIC, and the Bayes factor. - -* On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 - -* For an overview of DIC and WAIC, see Gelman, A.; Hwang, J. & Vehtari, A. (2014) Understanding predictive information criteria for Bayesian models. Statistics and Computing, 24, 997-1016-. On DIC, see also the original reference by Spiegelhalter, D. J.; Best, N. G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. - - -The Bayes factor relies on the estimation of marginal likelihoods, which is numerically challenging. The BT package currently implements three methods - -* The recommended method is the "Chib" method (Chib and Jeliazkov, 2001), which is based on MCMC samples but performs additional calculation. Although this is the current recommendation, note that there are some numerical issues with this algorithm that may limit its reliability for larger dimensions. - -* The harmonic mean approximation is implemented for comparison purposes only. Note that this method is numerically unreliable and should not normally be used. - -* The third method is simply sampling from the prior. While in principle unbiased, it converges only for a large number of samples and is therefore numerically inefficient. - -## Example - -Data linear regression with quadratic and linear effect - -```{r} -sampleSize = 30 -x <- (-(sampleSize-1)/2):((sampleSize-1)/2) -y <- 1 * x + 1*x^2 + rnorm(n=sampleSize,mean=0,sd=10) -plot(x,y, main="Test Data") -``` - -Likelihoods for both - -```{r} -likelihood1 <- function(param){ - pred = param[1] + param[2]*x + param[3] * x^2 - singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) - return(sum(singlelikelihoods)) -} - -likelihood2 <- function(param){ - pred = param[1] + param[2]*x - singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[3]^2), log = T) - return(sum(singlelikelihoods)) -} -``` - - -Posterior definitions - - -```{r} -setUp1 <- createBayesianSetup(likelihood1, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) - -setUp2 <- createBayesianSetup(likelihood2, lower = c(-5,-5,0.01), upper = c(5,5,30)) -``` - -MCMC and marginal likelihood estimation - - -```{r, results = 'hide'} -settings = list(iterations = 15000, message = FALSE) -out1 <- runMCMC(bayesianSetup = setUp1, sampler = "Metropolis", settings = settings) -#tracePlot(out1, start = 5000) -M1 = marginalLikelihood(out1) -M1 - -settings = list(iterations = 15000, message = FALSE) -out2 <- runMCMC(bayesianSetup = setUp2, sampler = "Metropolis", settings = settings) -#tracePlot(out2, start = 5000) -M2 = marginalLikelihood(out2) -M2 -``` - -### Model comparison via Bayes factor - -Bayes factor (need to invert the log) - -```{r} -exp(M1$ln.ML - M2$ln.ML) -``` - -BF > 1 means that the evidence favors M1. See Kass, R. E. & Raftery, A. E. (1995) Bayes Factors. J. Am. Stat. Assoc. Amer Statist Assn, 90, 773-795. - -Assuming equal prior weights for all models, we can calculate the posterior weight of M1 as - -```{r} -exp(M1$ln.ML) / ( exp(M1$ln.ML) + exp(M2$ln.ML)) -``` -If the models have different model priors, then multiply by the prior probability of each of the models. - - -### Comparing Models by DIC - -The Deviance Information Criterion is a commonly used method to summarize the fit of an MCMC chain. It can be calculated using - -```{r} -DIC(out1)$DIC -DIC(out2)$DIC -``` - -### Model Comparison via WAIC - -The Watanabe-Akaike Information Criterion is another criterion for model comparison. To compute the WAIC, the model must implement a log-likelihood density that allows the log-likelihood to be computed pointwise (the likelihood functions require a "sum" argument that determines whether the summed log-likelihood should be returned). It can be obtained via - -```{r} -# This will not work, since likelihood1 has no sum argument -# WAIC(out1) - -# likelihood with sum argument -likelihood3 <- function(param, sum = TRUE){ - pred <- param[1] + param[2]*x + param[3] * x^2 - singlelikelihoods <- dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) - return(if (sum == TRUE) sum(singlelikelihoods) else singlelikelihoods) -} -setUp3 <- createBayesianSetup(likelihood3, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) -out3 <- runMCMC(bayesianSetup = setUp3, sampler = "Metropolis", settings = settings) - -WAIC(out3) -``` +--- +title: "Bayesian Tools - General-Purpose MCMC and SMC Samplers and Tools for Bayesian Statistics" +output: + rmarkdown::html_vignette: + toc: true +vignette: > + %\VignetteIndexEntry{Manual for the BayesianTools R package} + \usepackage[utf8]{inputenc} + %\VignetteEngine{knitr::rmarkdown} +editor_options: + markdown: + wrap: 72 + chunk_output_type: console +--- + +```{r global_options, include=FALSE} +knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) +``` + +```{r, echo = F, message = F} +set.seed(123) +``` + +# Abstract + +The BayesianTools (BT) package supports model analysis (including +sensitivity analysis and uncertainty analysis), Bayesian model +calibration, as well as model selection and multi-model inference +techniques for system models. + +# Quick start + +The purpose of this first section is to give you a quick overview of the +most important functions of the BayesianTools (BT) package. For a more +detailed description, see the following sections. + +### Install, load and cite the package + +If you haven't installed the package yet, either run + +```{r, eval = F} +install.packages("BayesianTools") +``` + +or follow the instructions at + to install a +development version or an older version. + +Loading and citation + +```{r} +library(BayesianTools) +citation("BayesianTools") +``` + +Note: BayesianTools calls a number of secondary packages. Of particular +importance is `coda`, which is used in a number of plots and summary +statistics. If you use a lot of summary statistics and diagnostic plots, +it would be nice to cite coda as well! + +Pro Tip: If you are running a stochastic algorithm such as MCMC, you +should always set or record your random seed to make your results +reproducible (otherwise the results will change slightly each time you +run the code). + +```{r} +set.seed(123) +``` + +In a real application, recording the session info would be helpful in +ensuring reproducibility. + +```{r, eval = F} +sessionInfo() +``` + +This session information includes the version number of R and all loaded +packages. + +## The Bayesian Setup + +The central object in the `BT` package is the `BayesianSetup`. This +class contains the information about the model to be fit (likelihood), +and the priors for the model parameters. + +The `createBayesianSetup` function generates a `BayesianSetup` object. +The function requires a log-likelihood and a log-prior (optional) as +arguments. It then automatically creates the posterior and various +convenience functions for the samplers. + +Advantages of the `BayesianSetup` include 1. support for automatic +parallelization 2. functions are wrapped in try-catch statements to +avoid crashes during long MCMC evaluations 3. and the posterior checks +if the parameter is outside the prior first, in which case the +likelihood is not evaluated (makes the algorithms faster for slow +likelihoods). + +If no prior information is provided, an unbounded flat prior is +generated. If no explicit prior is specified, but lower and upper values +are given, a standard uniform prior with the respective bounds is +created, including the option to sample from this prior, which is useful +for SMC and obtaining initial values. This option is used in the +following example, which creates a multivariate normal likelihood +density and a uniform prior for 3 parameters. + +```{r} +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) +``` + +A more detailed description of the `BayesianSetup` will follow. + +**Hint:** For an example of how to run these steps for a dynamic +ecological model, see `?VSEM`. + +## Run MCMC and SMC functions + +After setup, you may need to run a calibration. The `runMCMC` function +serves as the main wrapper for all other implemented `MCMC`/`SMC` +functions. It always requires the following arguments: + +- `bayesianSetup` (alternatively, the log target function) +- `sampler` name +- list with `settings` for each sampler - if `settings` is not + specified, the default value will be applied + +For example, choosing the `sampler` name "Metropolis" calls a versatile +Metropolis-type MCMC with options for covariance adjustment, delayed +rejection, tempering and Metropolis-within-Gibbs sampling. For details, +see the later reference on MCMC samplers. When in doubt about the choice +of MCMC sampler, we recommend using the default "DEzs". + +```{r} +iter = 1000 +settings = list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +``` + +## Convergence checks for MCMCs + +Before interpreting the results, MCMCs should be checked for +convergence. We recommend the Gelman-Rubin convergence diagnostics, +which are the standard used in most publications. The Gelman-Rubin +diagnostics requires running multiple MCMCs (we recommend 3-5). + +For all samplers, you can conveniently perform multiple runs using the +`nrChains` argument. Alternatively, for runtime reasons, you can combine +the results of three independent `runMCMC` runs with `nrChains = 1` +using `combineChains` + +```{r, echo = T} +settings = list(iterations = iter, nrChains = 3, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) + +``` + +The result is an object of `mcmcSamplerList`, which should allow you to +do everything you can do with an `mcmcSampler` object (sometimes with +slightly different output). + +Basic convergence is checked via so-called trace plots, which show the 3 MCMC chains in different colors. + +```{r} +plot(out) +``` + +The trace plot is inspected for major problems (chains look different, drift), and to decide for the burn-in, i.e. the point where the MCMC has reached the area of sampling (i.e. the chains are not systematically goin into one direction any more). Here, they are have basically immediately reached this point, so we could also set the burn-in to 0, but I choose 100, i.e. discarding the first 100 samples in all further plots. + +If the trace plots look good, we can look at the Gelman-Rubin convergence diagnostics. Note that you have to discard the burn-in. + +```{r} +gelmanDiagnostics(out, plot = F, start = 100) +``` +Usually, a value < 1.05 for each parameter and a msrf < 1.1 of 1.2 are considered sufficient for convergence. + +### Summarize the outputs + +If we are happy with the convergence, we can plot and summarize all `sampler`s from the console with the +standard `print` and `summary` commands. + +```{r} +print(out, start = 100) +summary(out, start = 100) +``` + +You can also use built-in plot functions from the package for +visualization. The `marginalPlot` can be either plotted as histograms +with density overlay (default setting) or as a violin plot (see +"?marginalPlot"). + +```{r} +correlationPlot(out) +marginalPlot(out, prior = TRUE) +``` + +Additional functions that may be used on all `sampler`s are model +selection scores, including the Deviance Information Criterion (DIC) and +the marginal likelihood (see later section for details on calculating +the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set +of methods are available for calculation of marginal likelihood (refer +to "?marginalLikelihood"). + +```{r} +marginalLikelihood(out) +DIC(out) +MAP(out) +``` + +To extract part of the sampled parameter values, you can use the +following process: + +```{r, eval = F} +getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) +``` + +### Which sampler to choose? + +The BT package provides a large class of different MCMC samplers, and it +depends on the particular application which one is most suitable. + +In the absence of further information, we currently recommend the `DEz`s +sampler. This is also the default in the `runMCMC` function. + +# BayesianSetup Reference + +## Reference on creating likelihoods + +The likelihood should be provided as a log density function. + +```{r, eval = F} +ll = logDensity(x) +``` + +See parallelization options below. We will use a simple 3-d multivariate +normal density for the demonstration. + +```{r} +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) +``` + +### Parallelization of the likelihood evaluations + +Likelihoods are often costly to compute. If this is the case for you, +you should think about parallelization possibilities. The +'createBayesianSetup' function has an input variable 'parallel', with +the following options + +- F / FALSE means no parallelization should be used +- T / TRUE means to use R's automatic parallelization options (note: + this will not work if your likelihood is writing to file, or using + global variables or functions - see R's general help on + parallelization) +- "external", assumes that the likelihood is already parallelized. In + this case, the function needs to take a matrix with parameters as + columns, and rows as the different model runs you want to evaluate. + This is the most likely option to use if you have a complicated + setup (file I/O, HPC cluster) that cannot be handled with the + standard R parallelization. + +Algorithms in the `BayesianTools` package can take advantage of +parallelization if this option is specified in the `BayesianSetup`. Note +that parallelization is currently used by the following algorithms: +`SMC`, `DEzs` and `DREAMzs` sampler. It can also be used through the +`BayesianSetup` with the functions of the sensitivity package. + +Here are some more details about the parallelization. + +#### 1. In-build parallelization: + +In-built parallelizing is the easiest way to use parallel computing. The +"parallel" argument allows you to select the number of cores to use for +parallelization. Alternatively, TRUE or "auto" will use all available +cores except one. Now the proposals are evaluated in parallel. +Technically, the built-in parallelization uses an R cluster to evaluate +the posterior density function. The input to the parallel function is a +matrix where each column represents a parameter and each row represents +a proposal. This allows the proposals to be evaluated in parallel. For +`sampler`s that evaluate only one proposal at a time (namely the +Metropolis-based algorithms and DE/DREAM without the `zs` extension), +parallelization cannot be used. + +#### 2. External parallelization + +The second option is to use external parallelization. Here, +parallelization is attempted in the user-defined likelihood function. To +use external parallelization, the likelihood function must take a matrix +of proposals and return a vector of likelihood values. In the proposal +matrix, each row represents a proposal, and each column represents a +parameter. In addition, you will need to specify the "external" +parallelization in the "parallel" argument. In simple terms, using +external parallelization involves the following steps + +```{r, eval = FALSE} +## Definition of likelihood function +likelihood <- function(matrix){ + # Calculate likelihood in parallel + # Return vector of likelihood values +} + +## Create Bayesian Setup +BS <- createBayesianSetup(likelihood, parallel = "external", ...) + +## Run MCMC +runMCMC(BS, sampler = "SMC", ...) +``` + +#### 3. Multi-core and cluster calculations + +If you want to run your calculations on a cluster there are several ways +to do it. + +In the first case, you want to parallelize n internal (not total chains) +on n cores. The argument "parallel = T" in "createBayesianSetup" only +allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and +`DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" +to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be +parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` +samplers. + +```{r, eval = FALSE} +## n = Number of cores +n=2 +x <- c(1:10) +likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) +bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper = 5) + +## give runMCMC a matrix with n rows of proposals as startValues or sample n times from the previous created sampler +out <- runMCMC(bayesianSetup, settings = list(iterations = 1000)) +``` + +In the second case, you want to parallelize n internal chains on `n` +cores with an external parallelized likelihood function. Unlike the +previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized +this way. + +```{r, eval = FALSE} +### Create cluster with n cores +cl <- parallel::makeCluster(n) + +## Definition of the likelihood +likelihood <- function(X) sum(dnorm(c(1:10), mean = X, log = T)) + +## Definition of the likelihood which will be calculated in parallel. Instead of the parApply function, we could also define a costly parallelized likelihood +pLikelihood <- function(param) parallel::parApply(cl = cl, X = param, MARGIN = 1, FUN = likelihood) + +## export functions, dlls, libraries +# parallel::clusterEvalQ(cl, library(BayesianTools)) +parallel::clusterExport(cl, varlist = list(likelihood)) + +## create BayesianSetup +bayesianSetup <- createBayesianSetup(pLikelihood, lower = -10, upper = 10, parallel = 'external') + +## For this case we want to parallelize the internal chains, therefore we create a n row matrix with startValues, if you parallelize a model in the likelihood, do not set a n*row Matrix for startValue +settings = list(iterations = 100, nrChains = 1, startValue = bayesianSetup$prior$sampler(n)) + +## runMCMC +out <- runMCMC(bayesianSetup, settings, sampler = "DEzs") +``` + +In another case, your likelihood requires a parallelized model. Start +your cluster and export your model, the required libraries, and `dll`s. +Now you can start your calculations with the argument "parallel = +external" in `createBayesianSetup`. + +```{r, eval = FALSE} +### Create cluster with n cores +cl <- parallel::makeCluster(n) + +## export your model +# parallel::clusterExport(cl, varlist = list(complexModel)) + +## Definition of the likelihood +likelihood <- function(param) { + # ll <- complexModel(param) + # return(ll) +} + +## create BayesianSetup and settings +bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = 'external') +settings = list(iterations = 100, nrChains = 1) + +## runMCMC +out <- runMCMC(bayesianSetup, settings) + +``` + +In the last case, you can parallelize over whole chain calculations. +However, the likelihood itself is not parallelized. Each chain is run on +one core, and the likelihood is calculated on that core. + +```{r, eval = FALSE} +### Definition of likelihood function +x <- c(1:10) +likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) + +## Create BayesianSetup and settings +bayesianSetup <- createBayesianSetup(likelihood, lower = -10, upper = 10, parallel = F) +settings = list(iterations = 100000) + +## Start cluster with n cores for n chains and export BayesianTools library +cl <- parallel::makeCluster(n) +parallel::clusterEvalQ(cl, library(BayesianTools)) + +## calculate parallel n chains, for each chain the likelihood will be calculated on one core +out <- parallel::parLapply(cl, 1:n, fun = function(X, bayesianSetup, settings) runMCMC(bayesianSetup, settings, sampler = "DEzs"), bayesianSetup, settings) + +## Combine the chains +out <- createMcmcSamplerList(out) +``` + +\*\* Note: Even though parallelization can significantly reduce the +computation time, it is not always useful because of the so-called +communication overhead (computational time for distributing and +retrieving information from the parallel cores). For models with low +computational cost, this procedure may take more time than the actual +evaluation of the likelihood. If in doubt, do a small run-time +comparison before starting your large sampling. \*\* + +## Reference on creating priors + +The prior in the `BayesianSetup` consists of four parts + +- A log density function +- An (optional) sampling function (must be a function without + parameters, that returns a draw from the prior) +- lower / upper boundaries +- Additional info - best values, names of the parameters, ... + +This information can be passed by first creating an extra object, via +`createPrior`, or via the `createBayesianSetup` function. + +#### Creating priors + +You have 5 options to create a prior + +- Do not set a prior - in this case, an infinite prior will be created +- Set min/max values - a bounded flat prior and the corresponding + sampling function will be created +- Use one of the predefinded priors, see `?createPrior` for a list. + One of the options here is to use a previous MCMC output as the new + prior. Predefined priors will usually come with a sampling function +- Use a user-defined prior, see `?createPrior` +- Create a prior from a previous MCMC sample + +#### Creating user-defined priors + +When creating a user-defined prior, the following information can/should +be passed to `createPrior` + +- A log density function, as a function of a parameter vector x, same + syntax as the likelihood. +- In addition, you should consider providing a function that samples + from the prior, as many samplers (SMC, DE, DREAM) can use this + function for initial conditions. If you use one of the predefined + priors, the sampling function is already implemented. +- Lower / upper bounds (can be set on top of any prior to create + truncation) +- Additional information - best values, parameter names, ... + +#### Creating a prior from a previous MCMC sample + +The following example from the help file illustrates the process + +```{r} +# Create a BayesianSetup +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) + +settings = list(iterations = 2500, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) + + +newPrior = createPriorDensity(out, method = "multivariate", eps = 1e-10, lower = rep(-10, 3), upper = rep(10, 3), best = NULL) +bayesianSetup <- createBayesianSetup(likelihood = ll, prior = newPrior) + +settings = list(iterations = 1000, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) +``` + +# MCMC sampler reference + +## The runMCMC() function + +The `runMCMC` function is the central function for starting MCMC +algorithms in the `BayesianTools` package. It takes a `bayesianSetup`, a +choice of `sampler` (default is `DEzs`), and optionally changes to the +default settings of the chosen `sampler`. + +```{r, message = F} +runMCMC(bayesianSetup, sampler = "DEzs", settings = NULL) +``` + +You may use an optional argument `nrChains`, which is set to the default +value of 1 but can be modified if needed. Increasing its value will lead +`runMCMC` to execute multiple runs. + +```{r, message = F} + +ll <- generateTestDensityMultiNormal(sigma = "no correlation") + +bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) + +settings = list(iterations = 10000, nrChains= 3, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) + +plot(out) +marginalPlot(out, prior = T) +correlationPlot(out) +gelmanDiagnostics(out, plot=T) + +# option to restart the sampler + +settings = list(iterations = 1000, nrChains= 1, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) + +out2 <- runMCMC(bayesianSetup = out) + +out3 <- runMCMC(bayesianSetup = out2) + +#plot(out) +#plot(out3) + +# create new prior from posterior sample + +newPriorFromPosterior <- createPriorDensity(out2) + +``` + +## The different MCMC samplers + +For simplicity, we will define a fixed number of iterations. + +```{r} +iter = 10000 +``` + +### The Metropolis MCMC class + +The `BayesianTools` package is able to run a large number of +Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can +be accessed by the "Metropolis" `sampler` in the `runMCMC` function by +specifying the `sampler`'s settings. + +The subsequent code provides an overview of the default settings of the +MH `sampler`. + +```{r} +applySettingsDefault(sampler = "Metropolis") +``` + +Here are some examples of how to apply different settings. Activate +individual options or combinations as demonstrated. + +### Standard MH MCMC + +The following settings run the standard Metropolis Hastings MCMC. + +Refernences: Hastings, W. K. (1970). Monte carlo sampling methods using +markov chains and their applications. Biometrika 57 (1), 97-109. + +Metropolis, N., A. W. Rosenbluth, M. N. Rosenbluth, A. H. Teller, and E. +Teller (1953). Equation of state calculations by fast computing +machines. The journal of chemical physics 21 (6), 1087 - 1092. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = F, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +#### Standard MH MCMC, prior optimization + +Prior to the sampling process, this `sampler` employs an optimization +step. The purpose of optimization is to improve the initial values and +the covariance of the proposal distribution. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +#### Adaptive MCMC, prior optimization + +The adaptive Metropolis sampler (AM) uses the information already +obtained during the sampling process to improve (or adapt) the proposal +function. The `BayesianTools` package adjusts the covariance of the +proposal distribution by utilizing the chain's history. + +References: Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive +metropolis algorithm. Bernoulli , 223-242. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +#### Standard MCMC, prior optimization, delayed rejection + +Although rejection is an essential step in an MCMC algorithm, it can +also mean that the proposal distribution is (locally) poorly tuned to +the target distribution. In a delayed rejection (DR) sampler, a second +(or third, etc.) proposal is made before rejection. This proposal is +usually drawn from a different distribution, allowing for greater +flexibility of the sampler. In the `BayesianTools` package, the number +of delayed rejection steps and the scaling of the proposals can be +specified. \*\* Note that the current version supports only two delayed +rejection steps. \*\* + +References: Green, Peter J., and Antonietta Mira. "Delayed rejection in +reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = F, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +#### Adaptive MCMC, prior optimization, delayed rejection + +The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a +combination of the two previous `sampler`s (DR and AM). + +References: Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." +Statistics and Computing 16.4 (2006): 339-354. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = T, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +#### Standard MCMC, prior optimization, Gibbs updating + +To reduce the dimensions of the target function, a +Metropolis-within-Gibbs `sampler` can be run with the can be run with +the `BayesianTools` package. This means that only a subset of the +parameter vector is updated in each iteration. In the example below, at +most two (of the three) parameters are updated at each step, and it is +twice as likely to vary one as to vary two. + +\*\* Note that currently adaptive cannot be mixed with Gibbs updating! +\*\* + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = c(1,0.5,0), temperingFunction = NULL, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +#### Standard MCMC, prior optimization, gibbs updating, tempering + +Simulated tempering is closely related to simulated annealing (e.g., +Bélisle, 1992) in optimization algorithms. The idea of tempering is to +increase the acceptance rate during burn-in. This should lead to a +faster initial scanning of the target function. To incorporate this, a +tempering function must be provided by the user. The function describes +how to influence the acceptance rate during burn-in. In the example +below, an exponential decline approaching 1 (= no influence on the +acceptance rate) is used. + +References: Bélisle, C. J. (1992). Convergence theorems for a class of +simulated annealing algorithms on rd. Journal of Applied Probability, +885--895. + +C. J. Geyer (2011) Importance sampling, simulated tempering, and +umbrella sampling, in the Handbook of Markov Chain Monte Carlo, S. P. +Brooks, et al (eds), Chapman & Hall/CRC. + +```{r, results = 'hide', eval = F} +temperingFunction <- function(x) 5 * exp(-0.01*x) + 1 +settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = c(1,1,0), temperingFunction = temperingFunction, optimize = T, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings) +plot(out) +``` + +### Differential Evolution MCMC + +The BT package implements two differential evolution MCMCs. When in +doubt, use the DEzs option. + +The first is the normal DE MCMC, according to Ter Braak, Cajo JF. "A +Markov Chain Monte Carlo version of the genetic algorithm Differential +Evolution: easy Bayesian computing for real parameter spaces". +Statistics and Computing 16.3 (2006): 239-249. This sampler runs +multiple chains in parallel (but not in the sense of parallel +computing). The main difference to the Metropolis based algorithms is +the generation of the proposal. In general, all `sampler`s use the +current position of the chain and add a step in the parameter space to +generate a new proposal. While in the Metropolis based `sampler` this +step is usually drawn from a multivariate normal distribution (but any +distribution is possible), the `DE` `sampler` uses the current position +of two other chains to generate the step for each chain. For successful +sampling, at least `2*d` chains, where `d` is the number of parameters, +must be run in parallel. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DE", settings = settings) +plot(out) +``` + +The second is the Differential Evolution MCMC with Snooker update and +sampling from past states, according to ter Braak, Cajo JF, and Jasper +A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and +Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. This +extension covers two differences from the normal `DE` MCMC. First, it +uses a snooker update based on a user-defined probability. Second, past +states of other chains are taken into account when generating the +proposal. These extensions allow fewer chains (i.e., 3 chains are +usually sufficient for up to 200 parameters) and parallel computing, +since the current position of each chain depends only on the past states +of the other chains. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) +plot(out) +``` + +## DREAM sampler + +There are two versions of the DREAM `sampler`. First, the standard DREAM +sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte +Carlo simulation by differential evolution with self-adaptive randomized +subspace sampling". International Journal of Nonlinear Sciences and +Numerical Simulation 10.3 (2009): 273-290. + +This sampler is largely based on the DE sampler with some significant +changes: 1) More than two chains can be used to generate a proposal. 2) +Randomized subspace sampling can be used to improve efficiency for +high-dimensional posteriors. Each dimension is updated with a crossover +probability CR. To speed up the exploration of the posterior, DREAM +adjusts the distribution of CR values during burn-in to favor large +jumps over small ones. 3) Outlier chains can be removed during burn-in. + +```{r, results = 'hide', eval = F} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAM", settings = settings) +plot(out) +``` + +The second implementation uses the same extension as the DEzs sampler. +Namely sampling from past states and a snooker update. Again, this +extension allows the use of fewer chains and parallel computing. + +Again, if in doubt, you should prefer "DREAMzs". + +```{r, results = 'hide', eval = FALSE} +settings <- list(iterations = iter, message = FALSE) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAMzs", settings = settings) +plot(out) +``` + +## T-walk + +The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and +Colin Fox. "A general purpose sampling algorithm for continuous +distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. The +sampler uses two independent points to explore the posterior space. +Based on probabilities, four different moves are used to generate +proposals for the two points. As with the DE sampler, this procedure +does not require tuning of the proposal distribution for efficient +sampling in complex posterior distributions. + +```{r, eval = F} +settings = list(iterations = iter, message = FALSE) + +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Twalk", settings = settings) +``` + +## Non-MCMC sampling algorithms + +MCMCs sample the posterior space by creating a chain in parameter space. +While this allows for "learning" from past steps, it does not allow for +running a large number of posteriors in parallel. + +An alternative to MCMCs are particle filters, also known as Sequential +Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; +Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for +stochastic simulation models - theory and application Ecol. Lett., 2011, +14, 816-827 + +### Rejection sampling + +The simplest option is to sample a large number of parameters and accept +them according to their posterior value. This option can be emulated +with the implemented SMC by setting iterations to 1. + +```{r, results = 'hide', eval = F} +settings <- list(initialParticles = iter, iterations= 1) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) +plot(out) +``` + +### Sequential Monte Carlo (SMC) + +The more sophisticated option is to use the implemented SMC, which is +basically a particle filter that applies multiple filter steps. + +```{r, results = 'hide', eval = F} +settings <- list(initialParticles = iter, iterations= 10) +out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settings) +plot(out) +``` + +Note that using a number for `initialParticles` requires that the +`bayesianSetup` includes the option to sample from the prior. + +# Bayesian model comparison and averaging + +There are a number of Bayesian methods for model selection and model +comparison. The BT implements three of the most common: DIC, WAIC, and +the Bayes factor. + +- On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes + Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 + +- For an overview of DIC and WAIC, see Gelman, A.; Hwang, J. & + Vehtari, A. (2014) Understanding predictive information criteria for + Bayesian models. Statistics and Computing, 24, 997-1016-. On DIC, + see also the original reference by Spiegelhalter, D. J.; Best, N. + G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of + model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. + +The Bayes factor relies on the estimation of marginal likelihoods, which +is numerically challenging. The BT package currently implements three +methods + +- The recommended method is the "Chib" method (Chib and Jeliazkov, + 2001), which is based on MCMC samples but performs additional + calculation. Although this is the current recommendation, note that + there are some numerical issues with this algorithm that may limit + its reliability for larger dimensions. + +- The harmonic mean approximation is implemented for comparison + purposes only. Note that this method is numerically unreliable and + should not normally be used. + +- The third method is simply sampling from the prior. While in + principle unbiased, it converges only for a large number of samples + and is therefore numerically inefficient. + +## Example + +Data linear regression with quadratic and linear effect + +```{r} +sampleSize = 30 +x <- (-(sampleSize-1)/2):((sampleSize-1)/2) +y <- 1 * x + 1*x^2 + rnorm(n=sampleSize,mean=0,sd=10) +plot(x,y, main="Test Data") +``` + +Likelihoods for both + +```{r} +likelihood1 <- function(param){ + pred = param[1] + param[2]*x + param[3] * x^2 + singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) + return(sum(singlelikelihoods)) +} + +likelihood2 <- function(param){ + pred = param[1] + param[2]*x + singlelikelihoods = dnorm(y, mean = pred, sd = 1/(param[3]^2), log = T) + return(sum(singlelikelihoods)) +} +``` + +Posterior definitions + +```{r} +setUp1 <- createBayesianSetup(likelihood1, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) + +setUp2 <- createBayesianSetup(likelihood2, lower = c(-5,-5,0.01), upper = c(5,5,30)) +``` + +MCMC and marginal likelihood estimation + +```{r, results = 'hide'} +settings = list(iterations = 15000, message = FALSE) +out1 <- runMCMC(bayesianSetup = setUp1, sampler = "Metropolis", settings = settings) +#tracePlot(out1, start = 5000) +M1 = marginalLikelihood(out1) +M1 + +settings = list(iterations = 15000, message = FALSE) +out2 <- runMCMC(bayesianSetup = setUp2, sampler = "Metropolis", settings = settings) +#tracePlot(out2, start = 5000) +M2 = marginalLikelihood(out2) +M2 +``` + +### Model comparison via Bayes factor + +Bayes factor (need to invert the log) + +```{r} +exp(M1$ln.ML - M2$ln.ML) +``` + +BF \> 1 means that the evidence favors M1. See Kass, R. E. & Raftery, A. +E. (1995) Bayes Factors. J. Am. Stat. Assoc. Amer Statist Assn, 90, +773-795. + +Assuming equal prior weights for all models, we can calculate the +posterior weight of M1 as + +```{r} +exp(M1$ln.ML) / ( exp(M1$ln.ML) + exp(M2$ln.ML)) +``` + +If the models have different model priors, then multiply by the prior +probability of each of the models. + +### Comparing Models by DIC + +The Deviance Information Criterion is a commonly used method to +summarize the fit of an MCMC chain. It can be calculated using + +```{r} +DIC(out1)$DIC +DIC(out2)$DIC +``` + +### Model Comparison via WAIC + +The Watanabe-Akaike Information Criterion is another criterion for model +comparison. To compute the WAIC, the model must implement a +log-likelihood density that allows the log-likelihood to be computed +pointwise (the likelihood functions require a "sum" argument that +determines whether the summed log-likelihood should be returned). It can +be obtained via + +```{r} +# This will not work, since likelihood1 has no sum argument +# WAIC(out1) + +# likelihood with sum argument +likelihood3 <- function(param, sum = TRUE){ + pred <- param[1] + param[2]*x + param[3] * x^2 + singlelikelihoods <- dnorm(y, mean = pred, sd = 1/(param[4]^2), log = T) + return(if (sum == TRUE) sum(singlelikelihoods) else singlelikelihoods) +} +setUp3 <- createBayesianSetup(likelihood3, lower = c(-5,-5,-5,0.01), upper = c(5,5,5,30)) +out3 <- runMCMC(bayesianSetup = setUp3, sampler = "Metropolis", settings = settings) + +WAIC(out3) +``` From eef89328afb3c8707681c4a7b411ed1ec76228c8 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 24 Aug 2023 14:32:25 +0200 Subject: [PATCH 04/20] Update BayesianTools.Rmd --- BayesianTools/vignettes/BayesianTools.Rmd | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index 2fb37d8..f494cbe 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -154,29 +154,33 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ``` -The result is an object of `mcmcSamplerList`, which should allow you to -do everything you can do with an `mcmcSampler` object (sometimes with +The result is an object of `mcmcSamplerList`, which should allow you to do everything you can do with an `mcmcSampler` object (sometimes with slightly different output). -Basic convergence is checked via so-called trace plots, which show the 3 MCMC chains in different colors. +Basic convergence is checked via so-called trace plots, which show the 3 +MCMC chains in different colors. ```{r} plot(out) ``` -The trace plot is inspected for major problems (chains look different, drift), and to decide for the burn-in, i.e. the point where the MCMC has reached the area of sampling (i.e. the chains are not systematically goin into one direction any more). Here, they are have basically immediately reached this point, so we could also set the burn-in to 0, but I choose 100, i.e. discarding the first 100 samples in all further plots. +The trace plot is examined for major problems (chains look different, systematic trends) and to decide on the burn-in, i.e. the point at which the MCMC has reached the sampling range (i.e. the chains no longer systematically go in one direction). Here, they have basically reached this point immediately, so we could set the burn-in to 0, but I choose 100, i.e. discard the first 100 samples in all further plots. -If the trace plots look good, we can look at the Gelman-Rubin convergence diagnostics. Note that you have to discard the burn-in. +If the trace plots look good, we can look at the Gelman-Rubin +convergence diagnostics. Note that you have to discard the burn-in. ```{r} gelmanDiagnostics(out, plot = F, start = 100) ``` -Usually, a value < 1.05 for each parameter and a msrf < 1.1 of 1.2 are considered sufficient for convergence. + +Usually, a value \< 1.05 for each parameter and a msrf \< 1.1 of 1.2 are +considered sufficient for convergence. ### Summarize the outputs -If we are happy with the convergence, we can plot and summarize all `sampler`s from the console with the -standard `print` and `summary` commands. +If we are happy with the convergence, we can plot and summarize all +`sampler`s from the console with the standard `print` and `summary` +commands. ```{r} print(out, start = 100) From 44416ab0d1f4e67ae3d01a2fd67cd99b458f6b0d Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Fri, 22 Sep 2023 11:24:26 +0200 Subject: [PATCH 05/20] Changed mistakes and removed space in help file. --- .../R/BayesianSetupGenerateParallel.R | 25 +++---------------- BayesianTools/man/generateParallelExecuter.Rd | 12 +++------ 2 files changed, 8 insertions(+), 29 deletions(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index 0851f84..f195f4c 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -2,26 +2,10 @@ #' #' @author Florian Hartig #' @param fun function to be changed to parallel execution -#' @param parallel should a parallel R cluster be used? If set to T, machine will -#' automatically detect the available cores and n-1 of the available n cores -#' will be used. Alternatively, you can manually set the number of cores to be used -#' @param parallelOptions a list containing three lists. \n First, "packages": determines -#' the R packages required to run the likelihood function. \n Second, "variables": -#' the objects in the global environment needed to run the likelihood function -#' \n Third, "dlls": the DLLs needed to run the likelihood function (see Details). +#' @param parallel should a parallel R cluster be used? If set to T, machine will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used +#' @param parallelOptions a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function \n Third, "dlls": the DLLs needed to run the likelihood function (see Details). #' @note can be used to make functions compatible with library sensitivity -#' @details For parallelization, if option T is selected, an automatic parallelization -#' is tried via R. Alternatively, "external" can be selected on the assumption -#' that the likelihood has already been parallelized. In the latter case, a matrix -#' with parameters as columns must be accepted. -#' -#' You can also specify which packages, objects and DLLs are exported to the cluster. -#' -#' By default, a copy of your workspace is exported, but depending on your workspace, -#' this can be inefficient. -#' -#' As an alternative, you can specify the environments and packages in the -#' likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). +#' @details For parallelization, if option T is selected, an automatic parallelization is tried via R. Alternatively, "external" can be selected on the assumption that the likelihood has already been parallelized. In the latter case, a matrix with parameters as columns must be accepted. You can also specify which packages, objects and DLLs are exported to the cluster. By default, a copy of your workspace is exported, but depending on your workspace, this can be inefficient. As an alternative, you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). #' @export #' @example /inst/examples/generateParallelExecuter.R @@ -39,8 +23,7 @@ generateParallelExecuter <- function(fun, parallel = F, parallelOptions = list(v #library(foreach) #library(iterators) # library(parallel) - - { + if (parallel == T | parallel == "auto"){ cores <- parallel::detectCores() - 1 } else if (is.numeric(parallel)){ cores <- parallel diff --git a/BayesianTools/man/generateParallelExecuter.Rd b/BayesianTools/man/generateParallelExecuter.Rd index 82b7a37..88c0050 100644 --- a/BayesianTools/man/generateParallelExecuter.Rd +++ b/BayesianTools/man/generateParallelExecuter.Rd @@ -13,22 +13,18 @@ generateParallelExecuter( \arguments{ \item{fun}{function to be changed to parallel execution} -\item{parallel}{should a parallel R cluster be used or not. If set to T, cores will be detected automatically and n-1 of the available n cores of the machine will be used. Alternatively, you can set the number of cores used by hand} +\item{parallel}{should a parallel R cluster be used? If set to T, machine will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used} -\item{parallelOptions}{list containing three lists. First "packages" determines the R packages necessary to run the likelihood function. Second "variables" the objects in the global environment needed to run the likelihood function and third "dlls" the DLLs needed to run the likelihood function (see Details).} +\item{parallelOptions}{a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function \n Third, "dlls": the DLLs needed to run the likelihood function (see Details).} } \description{ Factory to generate a parallel executor of an existing function } \details{ -For parallelization, option T means that an automatic parallelization via R is attempted, or "external", in which case it is assumed that the likelihood is already parallelized. In this case it needs to accept a matrix with parameters as columns. -Further you can specify the packages, objects and DLLs that are exported to the cluster. -By default a copy of your workspace is exported. However, depending on your workspace this can be very inefficient. - -Alternatively you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). +For parallelization, if option T is selected, an automatic parallelization is tried via R. Alternatively, "external" can be selected on the assumption that the likelihood has already been parallelized. In the latter case, a matrix with parameters as columns must be accepted. You can also specify which packages, objects and DLLs are exported to the cluster. By default, a copy of your workspace is exported, but depending on your workspace, this can be inefficient. As an alternative, you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). } \note{ -Can also be used to make functions compatible with library sensitivity +can be used to make functions compatible with library sensitivity } \examples{ From 9ce2daf3fedb9f4de5c5564214b4b1646253acf9 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Fri, 22 Sep 2023 12:28:04 +0200 Subject: [PATCH 06/20] Update BayesianSetupGenerateParallel.R --- BayesianTools/R/BayesianSetupGenerateParallel.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index f195f4c..0c8e77f 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -2,7 +2,7 @@ #' #' @author Florian Hartig #' @param fun function to be changed to parallel execution -#' @param parallel should a parallel R cluster be used? If set to T, machine will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used +#' @param parallel should a parallel R cluster be used? If set to T, the operating system will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used #' @param parallelOptions a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function \n Third, "dlls": the DLLs needed to run the likelihood function (see Details). #' @note can be used to make functions compatible with library sensitivity #' @details For parallelization, if option T is selected, an automatic parallelization is tried via R. Alternatively, "external" can be selected on the assumption that the likelihood has already been parallelized. In the latter case, a matrix with parameters as columns must be accepted. You can also specify which packages, objects and DLLs are exported to the cluster. By default, a copy of your workspace is exported, but depending on your workspace, this can be inefficient. As an alternative, you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). From 55b19f378556c5ea26b5d0699ab1d1318bc42ebd Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Fri, 22 Sep 2023 12:29:49 +0200 Subject: [PATCH 07/20] Update BayesianTools.Rmd --- BayesianTools/vignettes/BayesianTools.Rmd | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index f494cbe..1488c7d 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -23,16 +23,11 @@ set.seed(123) # Abstract -The BayesianTools (BT) package supports model analysis (including -sensitivity analysis and uncertainty analysis), Bayesian model -calibration, as well as model selection and multi-model inference -techniques for system models. +The BayesianTools (BT) package supports model analysis (including sensitivity analysis and uncertainty analysis), Bayesian model calibration, as well as model selection and multi-model inference techniques for system models. # Quick start -The purpose of this first section is to give you a quick overview of the -most important functions of the BayesianTools (BT) package. For a more -detailed description, see the following sections. +The purpose of this first section is to give you a quick overview of the most important functions of the BayesianTools (BT) package. For a more detailed description, see the following sections. ### Install, load and cite the package @@ -42,9 +37,7 @@ If you haven't installed the package yet, either run install.packages("BayesianTools") ``` -or follow the instructions at - to install a -development version or an older version. +or follow the instructions at to install a development version or an older version. Loading and citation @@ -53,15 +46,9 @@ library(BayesianTools) citation("BayesianTools") ``` -Note: BayesianTools calls a number of secondary packages. Of particular -importance is `coda`, which is used in a number of plots and summary -statistics. If you use a lot of summary statistics and diagnostic plots, -it would be nice to cite coda as well! +Note: BayesianTools calls a number of secondary packages. Of particular importance is `coda`, which is used in a number of plots and summarystatistics. If you use a lot of summary statistics and diagnostic plots, it would be nice to cite coda as well! -Pro Tip: If you are running a stochastic algorithm such as MCMC, you -should always set or record your random seed to make your results -reproducible (otherwise the results will change slightly each time you -run the code). +Pro Tip: If you are running a stochastic algorithm such as MCMC, you should always set or record your random seed to make your results reproducible (otherwise the results will change slightly each time you run the code). ```{r} set.seed(123) From 704842ffbccefbb32ac7c98029e77e3364aac664 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Fri, 22 Sep 2023 12:30:59 +0200 Subject: [PATCH 08/20] Update BayesianTools.Rmd --- BayesianTools/vignettes/BayesianTools.Rmd | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index 1488c7d..4c7d1d4 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -54,8 +54,7 @@ Pro Tip: If you are running a stochastic algorithm such as MCMC, you should alwa set.seed(123) ``` -In a real application, recording the session info would be helpful in -ensuring reproducibility. +In a real application, recording the session info would be helpful in ensuring reproducibility. ```{r, eval = F} sessionInfo() From daee48d9fe5ccca9d9e4453bb78c18ce166a3b2c Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 28 Sep 2023 10:04:05 +0200 Subject: [PATCH 09/20] update --- BayesianTools/vignettes/BayesianTools.Rmd | 3 +- BayesianTools/vignettes/InterfacingAModel.Rmd | 614 +++++++++--------- 2 files changed, 308 insertions(+), 309 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index 4c7d1d4..95f1b02 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -65,8 +65,7 @@ packages. ## The Bayesian Setup -The central object in the `BT` package is the `BayesianSetup`. This -class contains the information about the model to be fit (likelihood), +The central object in the `BT` package is the `BayesianSetup`. This class contains the information about the model to be fit (likelihood), and the priors for the model parameters. The `createBayesianSetup` function generates a `BayesianSetup` object. diff --git a/BayesianTools/vignettes/InterfacingAModel.Rmd b/BayesianTools/vignettes/InterfacingAModel.Rmd index 74e9ee7..c089da4 100644 --- a/BayesianTools/vignettes/InterfacingAModel.Rmd +++ b/BayesianTools/vignettes/InterfacingAModel.Rmd @@ -1,307 +1,307 @@ ---- -title: "Interfacing your model with R" -output: - rmarkdown::html_vignette: - toc: true -vignette: > - %\VignetteIndexEntry{Interfacing your model with R} - \usepackage[utf8]{inputenc} - %\VignetteEngine{knitr::rmarkdown} - -author: Florian Hartig -editor_options: - chunk_output_type: console ---- - -```{r global_options, include=FALSE} -knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) -``` - -```{r, echo = F, message = F} -set.seed(123) -``` - -# Abstract - -This tutorial discusses how to interface models written in other programming languages with R, so that they can be fit with BayesianTools. - -# Interfacing a model with BT - step-by-step guide - -## Step 1: Create a runModel(par) function - -To enable calibration in BT, it's essential to run the model with a specified set of parameters. In fact, BT does not see the model as such, but requires a likelihood function with the interface likelihood(par), where par is a vector, but in this function you will probably then run the model with the parameters par, where par could remain a vector or be transformed into some other format, e.g. data.frame, matrix or list. - -What happens next depends on how your model is programmed. The following steps are arranged according to speed and convenience. If your model has not been interfaced with R before, you will most likely have to skip to the last option. - -\begin{enumerate} -\item Model in R, or R interface existing -\item Model can be compiled and linked as a `dll` -\item Model is in C/C++ and can be interfaced with RCPP -\item Model can be compiled as executable and accepts parameters via the command line -\item Model can be compiled as executable reads parameters via parameter file -\item Model parameters are hard-coded in the executable -\end{enumerate} - -### Case 1 - model programmed in R - -Typically, no action is required. Ensure that you are able to call your model. - -```{r, eval = F} -runMyModel(par) -``` - -Usually, this function returns model outputs directly, thus step 2 is unnecessary. - -### Case 2 - compiled dll, parameters are set via dll interface - -If your model is already in the form of a DLL, or if you can prepare it as such, use the function \ref{https://stat.ethz.ch/R-manual/R-devel/library/base/html/dynload.html}{dyn.load()} to link R to your model. - -```{r, eval = F} -dyn.load(model) - -runMyModel(par){ - out = # model call here - # process out - return(out) -} -``` - -If you implement this process, you will also usually return the output directly via the `dll` and not write to a file, which means that step 2 can be skipped. - -The problem with this approach is that you have to code the interface to your `dll`, which in most programming languages technically means setting your variables as external or something like that, so that they can be accessed from outside. The specifics of how this works will vary depending on the programming language being used. - - -### Case 3 - model programmed in C / C++, interfaced with RCPP - -RCPP provides a highly flexible platform to interface between R and C/C++. RCPP provides a secure and powerful way to connect to R if your model is coded in C/C++ (much more flexible than using the command line or a `dll`). - -Nevertheless, code adjustments may be necessary for the interface, and beginners may find it challenging to resolve any technical issues. Attempting to interface an existing C/C++ model without prior experience using RCPP or at least substantial experience with C/C++ is not advisable. - -In addition, step 2 can be skipped if you are implementing this, as you will usually return the output directly via the `dll`, rather than writing to a file. - -### Case 4 - compiled executable, parameters set via command line (std I/O) - -If your model is written in a compiled or interpreted language and accepts parameters via std I/O, wrapping is usually nothing more than writing the system call in an R function. For example - -```{r, eval = F} -runMyModel(par){ - - # Create here a string with what you would write to call the model from the command line - systemCall <- paste("model.exe", par[1], par[2]) - - out = system(systemCall, intern = TRUE) # intern indicates whether to capture the output of the command as an R character vector - - # write here to convert out in the apprpriate R classes - -} -``` - -Note: If you encounter difficulties with the system command, try system2. If the model provides the output via std.out, you can catch and convert it and skip step 2. If your model writes the output to a file, proceed to step 2. - -### Case 5 - compiled model, parameters set via parameter file or in any other method - -Many models use parameter files to read parameters. For this case, you want to do something like the following example - -```{r, eval = F} -runMyModel(par, returnData = NULL){ - - writeParameters(par) - - system("Model.exe") - - if(! is.null(returnData)) return(readData(returnData)) # The readData function will be defined later - -} - -writeParameters(par){ - - # e.g. - # read template parameter fil - # replace strings in template file - # write parameter file -} -``` - -For some problems, it may be useful to create a setup function, as in the example below. - -```{r, eval = F} -setUpModel <- function(parameterTemplate, site, localConditions){ - - # create the runModel, readData functions (see later) here - - return(list(runModel, readData)) - -} -``` - -The way you write a parameter function depends on the file format you are using for the parameters. Usually, creating a template parameter file is recommended as a starting point, and then the parameters can be changed as required. - -* If your parameter file is in an *.xml format*, check out the xml functions in R. -* If your parameter file is in a *general text format*, the best option may be to create a template parameter file, place a unique string at the locations of the parameters that you want to replace, and then use string replace functions in R, e.g. [grep](https://stat.ethz.ch/R-manual/R-devel/library/base/html/grep.html) to replace this string. - -### Case 6 - compiled model, parameters cannot be changed - -To achieve one of the previous options, you must change your model code. If the model is in C/C++, the best alternative is to go directly to RCPP. - -## Step 2: Read back data - -If your model returns the output directly (which is highly preferable, ), you can skip this step. - -You can skip this process if your model directly returns the output (which is highly recommended). - -If you have a simple model, you might consider using the `runMyModel` function to return the model's output directly. This is suitable for cases in a) and b) namely, models that are already in R, or receive parameters via the command line. - -In contrast, more complex models generate a large number of outputs. However, usually you do not need all of them. Therefore, it is more useful to create one or multiple separate `readData` or `getDate` functions. The only two cases I will consider here are - -* via dll / RCPP -* via file ouputs - -*Model is a dll* If the model is a `dll` file, it would probably be best to implement appropriate `getData` functions in the source code that can then be called from R. If your model is in C and in a `dll`, interfacing it via RCPP would probably be easier because you can return R dataframes and other data structures directly. - - -*Model writes file output* If the model generates file output, create a `getData` function that reads the model outputs and returns the data in the desired format, typically the same format you would use to represent your field data. - - - -```{r, eval = F} -getData(type = X){ - - read.csv(xxx) - - # do some transformation - - # return data in desidered format -} -``` - - -\subsection{Testing the approach} - - -You should now see an example from R that looks like this - - -```{r, eval = F} -par = c(1,2,3,4 ..) - -runMyModel(par) - -output <- getData(type = DesiredType) - -plot(output) -``` - - - - -## Step 3 (optional) - creating an R package from your code - -Although the final step is optional, we recommend doing it from the beginning because there is really no downside. You can work with R code in multiple files that can be run manually or incorporated into an R package directly. Creating and managing R packages is a straightforward process and makes it simpler to share your code, as everything, including help guides, is in one package. To create an R package, please refer to the tutorial \href{http://biometry.github.io/APES/R/R70-PackageDevelopment.html}{here}. Please remember to write good documentation using Roxygen. - - -# Speed optimization and parallelization - -Runtime is often a concern when performing sensitivity analyses or calibrations. Ensure that your model has been optimized for maximum speed before parallelization. - -## Easy things - -* Are you compiling with maximum optimization (e.g. -o3 in cpp) -* If there is a spin-up phase, consider increasing the time step during that phase. -* Consider increasing the time step in general. -* Are you producing unnecessary outputs that could be turned off to reduce hard disk I/O, which is often slow? - -## Difficult things - -* Make the model directly callable (RCPP or dll) to avoid harddisk I/O -* Is it possible to reduce the initialization time (not only for spin-up, but also for reading the forcings / drivers) by not terminating the model executable after each run, but keeping it "waiting" for a new run? -* Code optimization: did you use a profiler? Read up on code optimization -* Check for unnecessary calculations in your code / introduce compiler flags where appropriate - -## Parallelization - -One way to speed up the runtime of your model is to run it on multiple cores (CPUs). To do so, you have two choices: - -1. Parallelize the model itself -2. Parallelize the model call so that BT can perform multiple model evaluations in parallel. - -Which of the two makes more sense depends a lot on your problem. Parallelizing the model itself will be especially interesting for very large models that could not otherwise be calibrated with MCMCs. However, this approach typically requires writing parallel C/C++ code and advanced programming skills, which is why we will not discuss it further here. - -The usual advice in parallel computing anyway is to parallelize the outer loops first to minimize the communication overhead, which would suggest starting with parallelizing the model evaluations. This is also much easier to program. Even within that, there are two levels of parallelization possible: - -1. Parallelize the call of multiple MCMC / SMC samplers. -2. Parallelize within the MCMC / SMC samplers - -Currently, BT only supports parallelization within MCMCs / SMCs, but it easy to also implement between sampler parallelization by hand. Both approaches are describe below. - -### Within sampler parallelization - -Within-sampler parallelization is particularly useful for algorithms that can use a large number of cores in parallel, such as sensitivity analysis or SMC sampling. For MCMCs, the amount of parallelization that can be used depends on the settings and the algorithm. In general, MCMCs are, as the name implies, Markovian, i.e., they set up a chain of sequential model evaluations, and these calls cannot be fully parallelized. However, a number of MCMCs in the BT package uses MCMC algorithms that can be partly parallelized, in particular the population MCMC algorithms DE/DEzs/DREAM/DREAMzs. In all these cases, BT will automatically use parallelization of the BT setup to indicate that it is implemented. - -How to do this? A first requirement is that your model is wrapped in an R function (see PREVIOUS SECTION). Once that is the case, R provides a number of ways to run functions in parallel. The easiest is to use the parallel package that comes with the R core. Other packages can be found on the Internet and in the CRAN task view at [High Performance Computing](https://CRAN.R-project.org/view=HighPerformanceComputing) - -As an example, suppose we have the following very simple model: - -```{r} -mymodel<-function(x){ - output<-0.2*x+0.1^x - return(output) -} -``` - -To start a parallel computation, we must first create a cluster object. Here we start a cluster with 2 CPUs. - -```{r, eval = F} - -library(parallel) -cl <- makeCluster(2) - -runParallel<- function(parList){ - parSapply(cl, parList, mymodel) -} - -runParallel(c(1,2)) -``` - -You could use this principle to build your own parallelized likelihood. However, something very similar to the previous loop is automated in `BayesianTools`. You can create a parallel model evaluation function directly with the `generateParallelExecuter` function, or alternatively directly in the `createBayesianSetup` function. - -```{r, eval = F} -library(BayesianTools) -parModel <- generateParallelExecuter(mymodel) -``` - -If your model is thread-safe, you should be able to run it out of the box. Therefore, I recommend using the hand-coded parallelization only if your model is not thread-safe. - -### Running several MCMCs in parallel - -In addition to within-chain parallelization, you can also run multiple MCMCs in parallel and later combine them into a single `McmcSamplerList`. - -```{r} -library(BayesianTools) - -ll <- generateTestDensityMultiNormal(sigma = "no correlation") -bayesianSetup <- createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) - -settings = list(iterations = 200) - -# run the several MCMCs chains either in seperate R sessions, or via R parallel packages -out1 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) -out2 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) - -res <- createMcmcSamplerList(list(out1, out2)) -plot(res) -``` - - - -### Thread safety - -Thread safety generally means that you can run multiple instances of your code on your hardware. There are several things that can limit thread safety, such as - -* Writing output to a file (multiple threads can write to the same file at the same time) - - - - - - - +--- +title: "Interfacing your model with R" +output: + rmarkdown::html_vignette: + toc: true +vignette: > + %\VignetteIndexEntry{Interfacing your model with R} + \usepackage[utf8]{inputenc} + %\VignetteEngine{knitr::rmarkdown} + +author: Florian Hartig +editor_options: + chunk_output_type: console +--- + +```{r global_options, include=FALSE} +knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) +``` + +```{r, echo = F, message = F} +set.seed(123) +``` + +# Abstract + +This tutorial discusses how to interface models written in other programming languages with R, so that they can be fit with BayesianTools. + +# Interfacing a model with BT - step-by-step guide + +## Step 1: Create a runModel(par) function + +To enable calibration in BT, it's essential to run the model with a specified set of parameters. In fact, BT does not see the model as such, but requires a likelihood function with the interface likelihood(par), where par is a vector, but in this function you will probably then run the model with the parameters par, where par could remain a vector or be transformed into some other format, e.g. data.frame, matrix or list. + +What happens next depends on how your model is programmed. The following steps are arranged according to speed and convenience. If your model has not been interfaced with R before, you will most likely have to skip to the last option. + +\begin{enumerate} +\item Model in R, or R interface existing +\item Model can be compiled and linked as a `dll` +\item Model is in C/C++ and can be interfaced with RCPP +\item Model can be compiled as executable and accepts parameters via the command line +\item Model can be compiled as executable reads parameters via parameter file +\item Model parameters are hard-coded in the executable +\end{enumerate} + +### Case 1 - model programmed in R + +Typically, no action is required. Ensure that you are able to call your model. + +```{r, eval = F} +runMyModel(par) +``` + +Usually, this function returns model outputs directly, thus step 2 is unnecessary. + +### Case 2 - compiled dll, parameters are set via dll interface + +If your model is already in the form of a DLL, or if you can prepare it as such, use the function \ref{https://stat.ethz.ch/R-manual/R-devel/library/base/html/dynload.html}{dyn.load()} to link R to your model. + +```{r, eval = F} +dyn.load(model) + +runMyModel(par){ + out = # model call here + # process out + return(out) +} +``` + +If you implement this process, you will also usually return the output directly via the `dll` and not write to a file, which means that step 2 can be skipped. + +The problem with this approach is that you have to code the interface to your `dll`, which in most programming languages technically means setting your variables as external or something like that, so that they can be accessed from outside. The specifics of how this works will vary depending on the programming language being used. + + +### Case 3 - model programmed in C / C++, interfaced with RCPP + +RCPP provides a highly flexible platform to interface between R and C/C++. RCPP provides a secure and powerful way to connect to R if your model is coded in C/C++ (much more flexible than using the command line or a `dll`). + +Nevertheless, code adjustments may be necessary for the interface, and beginners may find it challenging to resolve any technical issues. Attempting to interface an existing C/C++ model without prior experience using RCPP or at least substantial experience with C/C++ is not advisable. + +In addition, step 2 can be skipped if you are implementing this, as you will usually return the output directly via the `dll`, rather than writing to a file. + +### Case 4 - compiled executable, parameters set via command line (std I/O) + +If your model is written in a compiled or interpreted language and accepts parameters via std I/O, wrapping is usually nothing more than writing the system call in an R function. For example + +```{r, eval = F} +runMyModel(par){ + + # Create here a string with what you would write to call the model from the command line + systemCall <- paste("model.exe", par[1], par[2]) + + out = system(systemCall, intern = TRUE) # intern indicates whether to capture the output of the command as an R character vector + + # write here to convert out in the apprpriate R classes + +} +``` + +Note: If you encounter difficulties with the system command, try system2. If the model provides the output via std.out, you can catch and convert it and skip step 2. If your model writes the output to a file, proceed to step 2. + +### Case 5 - compiled model, parameters set via parameter file or in any other method + +Many models use parameter files to read parameters. For this case, you want to do something like the following example + +```{r, eval = F} +runMyModel(par, returnData = NULL){ + + writeParameters(par) + + system("Model.exe") + + if(! is.null(returnData)) return(readData(returnData)) # The readData function will be defined later + +} + +writeParameters(par){ + + # e.g. + # read template parameter fil + # replace strings in template file + # write parameter file +} +``` + +For some problems, it may be useful to create a setup function, as in the example below. + +```{r, eval = F} +setUpModel <- function(parameterTemplate, site, localConditions){ + + # create the runModel, readData functions (see later) here + + return(list(runModel, readData)) + +} +``` + +The way you write a parameter function depends on the file format you are using for the parameters. Usually, creating a template parameter file is recommended as a starting point, and then the parameters can be changed as required. + +* If your parameter file is in an *.xml format*, check out the xml functions in R. +* If your parameter file is in a *general text format*, the best option may be to create a template parameter file, place a unique string at the locations of the parameters that you want to replace, and then use string replace functions in R, e.g. [grep](https://stat.ethz.ch/R-manual/R-devel/library/base/html/grep.html) to replace this string. + +### Case 6 - compiled model, parameters cannot be changed + +To achieve one of the previous options, you must change your model code. If the model is in C/C++, the best alternative is to go directly to RCPP. + +## Step 2: Read back data + +If your model returns the output directly (which is highly preferable, ), you can skip this step. + +You can skip this process if your model directly returns the output (which is highly recommended). + +If you have a simple model, you might consider using the `runMyModel` function to return the model's output directly. This is suitable for cases in a) and b) namely, models that are already in R, or receive parameters via the command line. + +In contrast, more complex models generate a large number of outputs. However, usually you do not need all of them. Therefore, it is more useful to create one or multiple separate `readData` or `getDate` functions. The only two cases I will consider here are + +* via dll / RCPP +* via file ouputs + +*Model is a dll* If the model is a `dll` file, it would probably be best to implement appropriate `getData` functions in the source code that can then be called from R. If your model is in C and in a `dll`, interfacing it via RCPP would probably be easier because you can return R dataframes and other data structures directly. + + +*Model writes file output* If the model generates file output, create a `getData` function that reads the model outputs and returns the data in the desired format, typically the same format you would use to represent your field data. + + + +```{r, eval = F} +getData(type = X){ + + read.csv(xxx) + + # do some transformation + + # return data in desidered format +} +``` + + +\subsection{Testing the approach} + + +You should now see an example from R that looks like this + + +```{r, eval = F} +par = c(1,2,3,4 ..) + +runMyModel(par) + +output <- getData(type = DesiredType) + +plot(output) +``` + + + + +## Step 3 (optional) - creating an R package from your code + +Although the final step is optional, we recommend doing it from the beginning because there is really no downside. You can work with R code in multiple files that can be run manually or incorporated into an R package directly. Creating and managing R packages is a straightforward process and makes it simpler to share your code, as everything, including help guides, is in one package. To create an R package, please refer to the tutorial \href{http://biometry.github.io/APES/R/R70-PackageDevelopment.html}{here}. Please remember to write good documentation using Roxygen. + + +# Speed optimization and parallelization + +Runtime is often a concern when performing sensitivity analyses or calibrations. Ensure that your model has been optimized for maximum speed before parallelization. + +## Easy things + +* Are you compiling with maximum optimization (e.g. -o3 in cpp) +* If there is a spin-up phase, consider increasing the time step during that phase. +* Consider increasing the time step in general. +* Are you producing unnecessary outputs that could be turned off to reduce hard disk I/O, which is often slow? + +## Difficult things + +* Make the model directly callable (RCPP or dll) to avoid harddisk I/O +* Is it possible to reduce the initialization time (not only for spin-up, but also for reading the forcings / drivers) by not terminating the model executable after each run, but keeping it "waiting" for a new run? +* Code optimization: did you use a profiler? Read up on code optimization +* Check for unnecessary calculations in your code / introduce compiler flags where appropriate + +## Parallelization + +One way to speed up the runtime of your model is to run it on multiple cores (CPUs). To do so, you have two choices: + +1. Parallelize the model itself +2. Parallelize the model call so that BT can perform multiple model evaluations in parallel. + +Which of the two makes more sense depends a lot on your problem. Parallelizing the model itself will be especially interesting for very large models that could not otherwise be calibrated with MCMCs. However, this approach typically requires writing parallel C/C++ code and advanced programming skills, which is why we will not discuss it further here. + +The usual advice in parallel computing anyway is to parallelize the outer loops first to minimize the communication overhead, which would suggest starting with parallelizing the model evaluations. This is also much easier to program. Even within that, there are two levels of parallelization possible: + +1. Parallelize the call of multiple MCMC / SMC samplers. +2. Parallelize within the MCMC / SMC samplers + +Currently, BT only supports parallelization within MCMCs / SMCs, but it easy to also implement between sampler parallelization by hand. Both approaches are describe below. + +### Within sampler parallelization + +Within-sampler parallelization is particularly useful for algorithms that can use a large number of cores in parallel, such as sensitivity analysis or SMC sampling. For MCMCs, the amount of parallelization that can be used depends on the settings and the algorithm. In general, MCMCs are, as the name implies, Markovian, i.e., they set up a chain of sequential model evaluations, and these calls cannot be fully parallelized. However, a number of MCMCs in the BT package uses MCMC algorithms that can be partly parallelized, in particular the population MCMC algorithms DE/DEzs/DREAM/DREAMzs. In all these cases, BT will automatically use parallelization of the BT setup to indicate that it is implemented. + +How to do this? A first requirement is that your model is wrapped in an R function (see PREVIOUS SECTION). Once that is the case, R provides a number of ways to run functions in parallel. The easiest is to use the parallel package that comes with the R core. Other packages can be found on the Internet and in the CRAN task view at [High Performance Computing](https://CRAN.R-project.org/view=HighPerformanceComputing) + +As an example, suppose we have the following very simple model: + +```{r} +mymodel<-function(x){ + output<-0.2*x+0.1^x + return(output) +} +``` + +To start a parallel computation, we must first create a cluster object. Here we start a cluster with 2 CPUs. + +```{r, eval = F} + +library(parallel) +cl <- makeCluster(2) + +runParallel<- function(parList){ + parSapply(cl, parList, mymodel) +} + +runParallel(c(1,2)) +``` + +You could use this principle to build your own parallelized likelihood. However, something very similar to the previous loop is automated in `BayesianTools`. You can create a parallel model evaluation function directly with the `generateParallelExecuter` function, or alternatively directly in the `createBayesianSetup` function. + +```{r, eval = F} +library(BayesianTools) +parModel <- generateParallelExecuter(mymodel) +``` + +If your model is thread-safe, you should be able to run it out of the box. Therefore, I recommend using the hand-coded parallelization only if your model is not thread-safe. + +### Running several MCMCs in parallel + +In addition to within-chain parallelization, you can also run multiple MCMCs in parallel and later combine them into a single `McmcSamplerList`. + +```{r} +library(BayesianTools) + +ll <- generateTestDensityMultiNormal(sigma = "no correlation") +bayesianSetup <- createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper = rep(10, 3)) + +settings = list(iterations = 200) + +# run the several MCMCs chains either in seperate R sessions, or via R parallel packages +out1 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) +out2 <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DEzs", settings = settings) + +res <- createMcmcSamplerList(list(out1, out2)) +plot(res) +``` + + + +### Thread safety + +Thread safety generally means that you can run multiple instances of your code on your hardware. There are several things that can limit thread safety, such as + +* Writing output to a file (multiple threads can write to the same file at the same time) + + + + + + + From 18c39746a523bf376661ff5ce2f0dd370ebb051e Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 28 Sep 2023 10:44:28 +0200 Subject: [PATCH 10/20] update --- BayesianTools/vignettes/BayesianTools.Rmd | 39 ++++-- BayesianTools/vignettes/InterfacingAModel.Rmd | 121 +++++++----------- 2 files changed, 76 insertions(+), 84 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index 95f1b02..3d9fc99 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -7,6 +7,7 @@ vignette: > %\VignetteIndexEntry{Manual for the BayesianTools R package} \usepackage[utf8]{inputenc} %\VignetteEngine{knitr::rmarkdown} +abstract: "The BayesianTools (BT) package supports model analysis (including sensitivity analysis and uncertainty analysis), Bayesian model calibration, as well as model selection and multi-model inference techniques for system models." editor_options: markdown: wrap: 72 @@ -21,13 +22,11 @@ knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) set.seed(123) ``` -# Abstract - -The BayesianTools (BT) package supports model analysis (including sensitivity analysis and uncertainty analysis), Bayesian model calibration, as well as model selection and multi-model inference techniques for system models. - # Quick start -The purpose of this first section is to give you a quick overview of the most important functions of the BayesianTools (BT) package. For a more detailed description, see the following sections. +The purpose of this first section is to give you a quick overview of the +most important functions of the BayesianTools (BT) package. For a more +detailed description, see the following sections. ### Install, load and cite the package @@ -37,7 +36,9 @@ If you haven't installed the package yet, either run install.packages("BayesianTools") ``` -or follow the instructions at to install a development version or an older version. +or follow the instructions at + to install a +development version or an older version. Loading and citation @@ -46,15 +47,22 @@ library(BayesianTools) citation("BayesianTools") ``` -Note: BayesianTools calls a number of secondary packages. Of particular importance is `coda`, which is used in a number of plots and summarystatistics. If you use a lot of summary statistics and diagnostic plots, it would be nice to cite coda as well! +Note: BayesianTools calls a number of secondary packages. Of particular +importance is `coda`, which is used in a number of plots and +summarystatistics. If you use a lot of summary statistics and diagnostic +plots, it would be nice to cite coda as well! -Pro Tip: If you are running a stochastic algorithm such as MCMC, you should always set or record your random seed to make your results reproducible (otherwise the results will change slightly each time you run the code). +Pro Tip: If you are running a stochastic algorithm such as MCMC, you +should always set or record your random seed to make your results +reproducible (otherwise the results will change slightly each time you +run the code). ```{r} set.seed(123) ``` -In a real application, recording the session info would be helpful in ensuring reproducibility. +In a real application, recording the session info would be helpful in +ensuring reproducibility. ```{r, eval = F} sessionInfo() @@ -65,7 +73,8 @@ packages. ## The Bayesian Setup -The central object in the `BT` package is the `BayesianSetup`. This class contains the information about the model to be fit (likelihood), +The central object in the `BT` package is the `BayesianSetup`. This +class contains the information about the model to be fit (likelihood), and the priors for the model parameters. The `createBayesianSetup` function generates a `BayesianSetup` object. @@ -139,7 +148,8 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ``` -The result is an object of `mcmcSamplerList`, which should allow you to do everything you can do with an `mcmcSampler` object (sometimes with +The result is an object of `mcmcSamplerList`, which should allow you to +do everything you can do with an `mcmcSampler` object (sometimes with slightly different output). Basic convergence is checked via so-called trace plots, which show the 3 @@ -149,7 +159,12 @@ MCMC chains in different colors. plot(out) ``` -The trace plot is examined for major problems (chains look different, systematic trends) and to decide on the burn-in, i.e. the point at which the MCMC has reached the sampling range (i.e. the chains no longer systematically go in one direction). Here, they have basically reached this point immediately, so we could set the burn-in to 0, but I choose 100, i.e. discard the first 100 samples in all further plots. +The trace plot is examined for major problems (chains look different, +systematic trends) and to decide on the burn-in, i.e. the point at which +the MCMC has reached the sampling range (i.e. the chains no longer +systematically go in one direction). Here, they have basically reached +this point immediately, so we could set the burn-in to 0, but I choose +100, i.e. discard the first 100 samples in all further plots. If the trace plots look good, we can look at the Gelman-Rubin convergence diagnostics. Note that you have to discard the burn-in. diff --git a/BayesianTools/vignettes/InterfacingAModel.Rmd b/BayesianTools/vignettes/InterfacingAModel.Rmd index c089da4..d370c48 100644 --- a/BayesianTools/vignettes/InterfacingAModel.Rmd +++ b/BayesianTools/vignettes/InterfacingAModel.Rmd @@ -7,7 +7,7 @@ vignette: > %\VignetteIndexEntry{Interfacing your model with R} \usepackage[utf8]{inputenc} %\VignetteEngine{knitr::rmarkdown} - +abstract: "This tutorial discusses how to interface models written in other programming languages with R, so that they can be fit with BayesianTools" author: Florian Hartig editor_options: chunk_output_type: console @@ -21,21 +21,18 @@ knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) set.seed(123) ``` -# Abstract - -This tutorial discusses how to interface models written in other programming languages with R, so that they can be fit with BayesianTools. - # Interfacing a model with BT - step-by-step guide ## Step 1: Create a runModel(par) function -To enable calibration in BT, it's essential to run the model with a specified set of parameters. In fact, BT does not see the model as such, but requires a likelihood function with the interface likelihood(par), where par is a vector, but in this function you will probably then run the model with the parameters par, where par could remain a vector or be transformed into some other format, e.g. data.frame, matrix or list. +To enable calibration in BT, it's essential to run the model with a specified set of parameters. In fact, BT does not see the model as such, but requires a likelihood function with the interface likelihood(par), where par is a vector, but in this function you will probably then run the model with the parameters par, where par could remain a vector or be transformed into some other format, e.g. data.frame, matrix or list. + +What happens next depends on how your model is programmed. The following steps are arranged according to speed and convenience. If your model has not been interfaced with R before, you will most likely have to skip to the last option. -What happens next depends on how your model is programmed. The following steps are arranged according to speed and convenience. If your model has not been interfaced with R before, you will most likely have to skip to the last option. \begin{enumerate} \item Model in R, or R interface existing -\item Model can be compiled and linked as a `dll` +\item Model can be compiled and linked as a dll \item Model is in C/C++ and can be interfaced with RCPP \item Model can be compiled as executable and accepts parameters via the command line \item Model can be compiled as executable reads parameters via parameter file @@ -44,13 +41,13 @@ What happens next depends on how your model is programmed. The following steps a ### Case 1 - model programmed in R -Typically, no action is required. Ensure that you are able to call your model. +Typically, no action is required. Ensure that you are able to call your model. ```{r, eval = F} runMyModel(par) ``` -Usually, this function returns model outputs directly, thus step 2 is unnecessary. +Usually, this function returns model outputs directly, thus step 2 is unnecessary. ### Case 2 - compiled dll, parameters are set via dll interface @@ -66,22 +63,21 @@ runMyModel(par){ } ``` -If you implement this process, you will also usually return the output directly via the `dll` and not write to a file, which means that step 2 can be skipped. - -The problem with this approach is that you have to code the interface to your `dll`, which in most programming languages technically means setting your variables as external or something like that, so that they can be accessed from outside. The specifics of how this works will vary depending on the programming language being used. +If you implement this process, you will also usually return the output directly via the `dll` and not write to a file, which means that step 2 can be skipped. +The problem with this approach is that you have to code the interface to your `dll`, which in most programming languages technically means setting your variables as external or something like that, so that they can be accessed from outside. The specifics of how this works will vary depending on the programming language being used. ### Case 3 - model programmed in C / C++, interfaced with RCPP -RCPP provides a highly flexible platform to interface between R and C/C++. RCPP provides a secure and powerful way to connect to R if your model is coded in C/C++ (much more flexible than using the command line or a `dll`). +RCPP provides a highly flexible platform to interface between R and C/C++. RCPP provides a secure and powerful way to connect to R if your model is coded in C/C++ (much more flexible than using the command line or a `dll`). -Nevertheless, code adjustments may be necessary for the interface, and beginners may find it challenging to resolve any technical issues. Attempting to interface an existing C/C++ model without prior experience using RCPP or at least substantial experience with C/C++ is not advisable. +Nevertheless, code adjustments may be necessary for the interface, and beginners may find it challenging to resolve any technical issues. Attempting to interface an existing C/C++ model without prior experience using RCPP or at least substantial experience with C/C++ is not advisable. -In addition, step 2 can be skipped if you are implementing this, as you will usually return the output directly via the `dll`, rather than writing to a file. +In addition, step 2 can be skipped if you are implementing this, as you will usually return the output directly via the `dll`, rather than writing to a file. ### Case 4 - compiled executable, parameters set via command line (std I/O) -If your model is written in a compiled or interpreted language and accepts parameters via std I/O, wrapping is usually nothing more than writing the system call in an R function. For example +If your model is written in a compiled or interpreted language and accepts parameters via std I/O, wrapping is usually nothing more than writing the system call in an R function. For example ```{r, eval = F} runMyModel(par){ @@ -96,7 +92,7 @@ runMyModel(par){ } ``` -Note: If you encounter difficulties with the system command, try system2. If the model provides the output via std.out, you can catch and convert it and skip step 2. If your model writes the output to a file, proceed to step 2. +Note: If you encounter difficulties with the system command, try system2. If the model provides the output via std.out, you can catch and convert it and skip step 2. If your model writes the output to a file, proceed to step 2. ### Case 5 - compiled model, parameters set via parameter file or in any other method @@ -134,34 +130,31 @@ setUpModel <- function(parameterTemplate, site, localConditions){ } ``` -The way you write a parameter function depends on the file format you are using for the parameters. Usually, creating a template parameter file is recommended as a starting point, and then the parameters can be changed as required. +The way you write a parameter function depends on the file format you are using for the parameters. Usually, creating a template parameter file is recommended as a starting point, and then the parameters can be changed as required. -* If your parameter file is in an *.xml format*, check out the xml functions in R. -* If your parameter file is in a *general text format*, the best option may be to create a template parameter file, place a unique string at the locations of the parameters that you want to replace, and then use string replace functions in R, e.g. [grep](https://stat.ethz.ch/R-manual/R-devel/library/base/html/grep.html) to replace this string. +- If your parameter file is in an *.xml format*, check out the xml functions in R. +- If your parameter file is in a *general text format*, the best option may be to create a template parameter file, place a unique string at the locations of the parameters that you want to replace, and then use string replace functions in R, e.g. [grep](https://stat.ethz.ch/R-manual/R-devel/library/base/html/grep.html) to replace this string. ### Case 6 - compiled model, parameters cannot be changed -To achieve one of the previous options, you must change your model code. If the model is in C/C++, the best alternative is to go directly to RCPP. +To achieve one of the previous options, you must change your model code. If the model is in C/C++, the best alternative is to go directly to RCPP. ## Step 2: Read back data -If your model returns the output directly (which is highly preferable, ), you can skip this step. - -You can skip this process if your model directly returns the output (which is highly recommended). - -If you have a simple model, you might consider using the `runMyModel` function to return the model's output directly. This is suitable for cases in a) and b) namely, models that are already in R, or receive parameters via the command line. +If your model returns the output directly (which is highly preferable, ), you can skip this step. -In contrast, more complex models generate a large number of outputs. However, usually you do not need all of them. Therefore, it is more useful to create one or multiple separate `readData` or `getDate` functions. The only two cases I will consider here are +You can skip this process if your model directly returns the output (which is highly recommended). -* via dll / RCPP -* via file ouputs +If you have a simple model, you might consider using the `runMyModel` function to return the model's output directly. This is suitable for cases in a) and b) namely, models that are already in R, or receive parameters via the command line. -*Model is a dll* If the model is a `dll` file, it would probably be best to implement appropriate `getData` functions in the source code that can then be called from R. If your model is in C and in a `dll`, interfacing it via RCPP would probably be easier because you can return R dataframes and other data structures directly. +In contrast, more complex models generate a large number of outputs. However, usually you do not need all of them. Therefore, it is more useful to create one or multiple separate `readData` or `getDate` functions. The only two cases I will consider here are +- via dll / RCPP +- via file ouputs -*Model writes file output* If the model generates file output, create a `getData` function that reads the model outputs and returns the data in the desired format, typically the same format you would use to represent your field data. - +*Model is a dll* If the model is a `dll` file, it would probably be best to implement appropriate `getData` functions in the source code that can then be called from R. If your model is in C and in a `dll`, interfacing it via RCPP would probably be easier because you can return R dataframes and other data structures directly. +*Model writes file output* If the model generates file output, create a `getData` function that reads the model outputs and returns the data in the desired format, typically the same format you would use to represent your field data. ```{r, eval = F} getData(type = X){ @@ -174,13 +167,10 @@ getData(type = X){ } ``` - -\subsection{Testing the approach} - +\subsection{Testing the approach} You should now see an example from R that looks like this - ```{r, eval = F} par = c(1,2,3,4 ..) @@ -191,51 +181,47 @@ output <- getData(type = DesiredType) plot(output) ``` - - - ## Step 3 (optional) - creating an R package from your code -Although the final step is optional, we recommend doing it from the beginning because there is really no downside. You can work with R code in multiple files that can be run manually or incorporated into an R package directly. Creating and managing R packages is a straightforward process and makes it simpler to share your code, as everything, including help guides, is in one package. To create an R package, please refer to the tutorial \href{http://biometry.github.io/APES/R/R70-PackageDevelopment.html}{here}. Please remember to write good documentation using Roxygen. - +Although the final step is optional, we recommend doing it from the beginning because there is really no downside. You can work with R code in multiple files that can be run manually or incorporated into an R package directly. Creating and managing R packages is a straightforward process and makes it simpler to share your code, as everything, including help guides, is in one package. To create an R package, please refer to the tutorial \href{http://biometry.github.io/APES/R/R70-PackageDevelopment.html}{here}. Please remember to write good documentation using Roxygen. # Speed optimization and parallelization -Runtime is often a concern when performing sensitivity analyses or calibrations. Ensure that your model has been optimized for maximum speed before parallelization. +Runtime is often a concern when performing sensitivity analyses or calibrations. Ensure that your model has been optimized for maximum speed before parallelization. ## Easy things -* Are you compiling with maximum optimization (e.g. -o3 in cpp) -* If there is a spin-up phase, consider increasing the time step during that phase. -* Consider increasing the time step in general. -* Are you producing unnecessary outputs that could be turned off to reduce hard disk I/O, which is often slow? +- Are you compiling with maximum optimization (e.g. -o3 in cpp) +- If there is a spin-up phase, consider increasing the time step during that phase. +- Consider increasing the time step in general. +- Are you producing unnecessary outputs that could be turned off to reduce hard disk I/O, which is often slow? ## Difficult things -* Make the model directly callable (RCPP or dll) to avoid harddisk I/O -* Is it possible to reduce the initialization time (not only for spin-up, but also for reading the forcings / drivers) by not terminating the model executable after each run, but keeping it "waiting" for a new run? -* Code optimization: did you use a profiler? Read up on code optimization -* Check for unnecessary calculations in your code / introduce compiler flags where appropriate +- Make the model directly callable (RCPP or dll) to avoid harddisk I/O +- Is it possible to reduce the initialization time (not only for spin-up, but also for reading the forcings / drivers) by not terminating the model executable after each run, but keeping it "waiting" for a new run? +- Code optimization: did you use a profiler? Read up on code optimization +- Check for unnecessary calculations in your code / introduce compiler flags where appropriate ## Parallelization One way to speed up the runtime of your model is to run it on multiple cores (CPUs). To do so, you have two choices: -1. Parallelize the model itself -2. Parallelize the model call so that BT can perform multiple model evaluations in parallel. +1. Parallelize the model itself +2. Parallelize the model call so that BT can perform multiple model evaluations in parallel. -Which of the two makes more sense depends a lot on your problem. Parallelizing the model itself will be especially interesting for very large models that could not otherwise be calibrated with MCMCs. However, this approach typically requires writing parallel C/C++ code and advanced programming skills, which is why we will not discuss it further here. +Which of the two makes more sense depends a lot on your problem. Parallelizing the model itself will be especially interesting for very large models that could not otherwise be calibrated with MCMCs. However, this approach typically requires writing parallel C/C++ code and advanced programming skills, which is why we will not discuss it further here. -The usual advice in parallel computing anyway is to parallelize the outer loops first to minimize the communication overhead, which would suggest starting with parallelizing the model evaluations. This is also much easier to program. Even within that, there are two levels of parallelization possible: +The usual advice in parallel computing anyway is to parallelize the outer loops first to minimize the communication overhead, which would suggest starting with parallelizing the model evaluations. This is also much easier to program. Even within that, there are two levels of parallelization possible: -1. Parallelize the call of multiple MCMC / SMC samplers. -2. Parallelize within the MCMC / SMC samplers +1. Parallelize the call of multiple MCMC / SMC samplers. +2. Parallelize within the MCMC / SMC samplers -Currently, BT only supports parallelization within MCMCs / SMCs, but it easy to also implement between sampler parallelization by hand. Both approaches are describe below. +Currently, BT only supports parallelization within MCMCs / SMCs, but it easy to also implement between sampler parallelization by hand. Both approaches are describe below. -### Within sampler parallelization +### Within sampler parallelization -Within-sampler parallelization is particularly useful for algorithms that can use a large number of cores in parallel, such as sensitivity analysis or SMC sampling. For MCMCs, the amount of parallelization that can be used depends on the settings and the algorithm. In general, MCMCs are, as the name implies, Markovian, i.e., they set up a chain of sequential model evaluations, and these calls cannot be fully parallelized. However, a number of MCMCs in the BT package uses MCMC algorithms that can be partly parallelized, in particular the population MCMC algorithms DE/DEzs/DREAM/DREAMzs. In all these cases, BT will automatically use parallelization of the BT setup to indicate that it is implemented. +Within-sampler parallelization is particularly useful for algorithms that can use a large number of cores in parallel, such as sensitivity analysis or SMC sampling. For MCMCs, the amount of parallelization that can be used depends on the settings and the algorithm. In general, MCMCs are, as the name implies, Markovian, i.e., they set up a chain of sequential model evaluations, and these calls cannot be fully parallelized. However, a number of MCMCs in the BT package uses MCMC algorithms that can be partly parallelized, in particular the population MCMC algorithms DE/DEzs/DREAM/DREAMzs. In all these cases, BT will automatically use parallelization of the BT setup to indicate that it is implemented. How to do this? A first requirement is that your model is wrapped in an R function (see PREVIOUS SECTION). Once that is the case, R provides a number of ways to run functions in parallel. The easiest is to use the parallel package that comes with the R core. Other packages can be found on the Internet and in the CRAN task view at [High Performance Computing](https://CRAN.R-project.org/view=HighPerformanceComputing) @@ -269,7 +255,7 @@ library(BayesianTools) parModel <- generateParallelExecuter(mymodel) ``` -If your model is thread-safe, you should be able to run it out of the box. Therefore, I recommend using the hand-coded parallelization only if your model is not thread-safe. +If your model is thread-safe, you should be able to run it out of the box. Therefore, I recommend using the hand-coded parallelization only if your model is not thread-safe. ### Running several MCMCs in parallel @@ -291,17 +277,8 @@ res <- createMcmcSamplerList(list(out1, out2)) plot(res) ``` - - ### Thread safety -Thread safety generally means that you can run multiple instances of your code on your hardware. There are several things that can limit thread safety, such as - -* Writing output to a file (multiple threads can write to the same file at the same time) - - - - - - +Thread safety generally means that you can run multiple instances of your code on your hardware. There are several things that can limit thread safety, such as +- Writing output to a file (multiple threads can write to the same file at the same time) From 2fac074c46250d1d7acffa756205d33fed671967 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 28 Sep 2023 11:05:29 +0200 Subject: [PATCH 11/20] update --- BayesianTools/vignettes/BayesianTools.Rmd | 284 +++++----------------- 1 file changed, 64 insertions(+), 220 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index 3d9fc99..f40406e 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -73,28 +73,18 @@ packages. ## The Bayesian Setup -The central object in the `BT` package is the `BayesianSetup`. This -class contains the information about the model to be fit (likelihood), +The central object in the `BT` package is the `BayesianSetup`. This class contains the information about the model to be fit (likelihood), and the priors for the model parameters. -The `createBayesianSetup` function generates a `BayesianSetup` object. -The function requires a log-likelihood and a log-prior (optional) as -arguments. It then automatically creates the posterior and various -convenience functions for the samplers. +The `createBayesianSetup` function generates a `BayesianSetup` object. The function requires a log-likelihood and a log-prior (optional) as +arguments. It then automatically creates the posterior and various convenience functions for the samplers. -Advantages of the `BayesianSetup` include 1. support for automatic -parallelization 2. functions are wrapped in try-catch statements to -avoid crashes during long MCMC evaluations 3. and the posterior checks -if the parameter is outside the prior first, in which case the -likelihood is not evaluated (makes the algorithms faster for slow +Advantages of the `BayesianSetup` include 1. support for automatic parallelization 2. functions are wrapped in try-catch statements to avoid crashes during long MCMC evaluations 3. and the posterior checks if the parameter is outside the prior first, in which case the likelihood is not evaluated (makes the algorithms faster for slow likelihoods). -If no prior information is provided, an unbounded flat prior is -generated. If no explicit prior is specified, but lower and upper values -are given, a standard uniform prior with the respective bounds is -created, including the option to sample from this prior, which is useful -for SMC and obtaining initial values. This option is used in the -following example, which creates a multivariate normal likelihood +If no prior information is provided, an unbounded flat prior is generated. If no explicit prior is specified, but lower and upper values +are given, a standard uniform prior with the respective bounds is created, including the option to sample from this prior, which is useful +for SMC and obtaining initial values. This option is used in the following example, which creates a multivariate normal likelihood density and a uniform prior for 3 parameters. ```{r} @@ -109,19 +99,15 @@ ecological model, see `?VSEM`. ## Run MCMC and SMC functions -After setup, you may need to run a calibration. The `runMCMC` function -serves as the main wrapper for all other implemented `MCMC`/`SMC` -functions. It always requires the following arguments: +After setup, you may need to run a calibration. The `runMCMC` function serves as the main wrapper for all other implemented `MCMC`/`SMC` functions. It always requires the following arguments: - `bayesianSetup` (alternatively, the log target function) - `sampler` name - list with `settings` for each sampler - if `settings` is not specified, the default value will be applied -For example, choosing the `sampler` name "Metropolis" calls a versatile -Metropolis-type MCMC with options for covariance adjustment, delayed -rejection, tempering and Metropolis-within-Gibbs sampling. For details, -see the later reference on MCMC samplers. When in doubt about the choice +For example, choosing the `sampler` name "Metropolis" calls a versatile Metropolis-type MCMC with options for covariance adjustment, delayed +rejection, tempering and Metropolis-within-Gibbs sampling. For details, see the later reference on MCMC samplers. When in doubt about the choice of MCMC sampler, we recommend using the default "DEzs". ```{r} @@ -132,15 +118,9 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ## Convergence checks for MCMCs -Before interpreting the results, MCMCs should be checked for -convergence. We recommend the Gelman-Rubin convergence diagnostics, -which are the standard used in most publications. The Gelman-Rubin -diagnostics requires running multiple MCMCs (we recommend 3-5). +Before interpreting the results, MCMCs should be checked for convergence. We recommend the Gelman-Rubin convergence diagnostics,which are the standard used in most publications. The Gelman-Rubin diagnostics requires running multiple MCMCs (we recommend 3-5). -For all samplers, you can conveniently perform multiple runs using the -`nrChains` argument. Alternatively, for runtime reasons, you can combine -the results of three independent `runMCMC` runs with `nrChains = 1` -using `combineChains` +For all samplers, you can conveniently perform multiple runs using the `nrChains` argument. Alternatively, for runtime reasons, you can combine the results of three independent `runMCMC` runs with `nrChains = 1` using `combineChains` ```{r, echo = T} settings = list(iterations = iter, nrChains = 3, message = FALSE) @@ -148,48 +128,36 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ``` -The result is an object of `mcmcSamplerList`, which should allow you to -do everything you can do with an `mcmcSampler` object (sometimes with +The result is an object of `mcmcSamplerList`, which should allow you to do everything you can do with an `mcmcSampler` object (sometimes with slightly different output). -Basic convergence is checked via so-called trace plots, which show the 3 -MCMC chains in different colors. +Basic convergence is checked via so-called trace plots, which show the 3 MCMC chains in different colors. ```{r} plot(out) ``` -The trace plot is examined for major problems (chains look different, -systematic trends) and to decide on the burn-in, i.e. the point at which -the MCMC has reached the sampling range (i.e. the chains no longer -systematically go in one direction). Here, they have basically reached -this point immediately, so we could set the burn-in to 0, but I choose -100, i.e. discard the first 100 samples in all further plots. +The trace plot is examined for major problems (chains look different, systematic trends) and to decide on the burn-in, i.e. the point at which the MCMC has reached the sampling range (i.e. the chains no longer systematically go in one direction). Here, they have basically reached +this point immediately, so we could set the burn-in to 0, but I choose 100, i.e. discard the first 100 samples in all further plots. -If the trace plots look good, we can look at the Gelman-Rubin -convergence diagnostics. Note that you have to discard the burn-in. +If the trace plots look good, we can look at the Gelman-Rubin convergence diagnostics. Note that you have to discard the burn-in. ```{r} gelmanDiagnostics(out, plot = F, start = 100) ``` -Usually, a value \< 1.05 for each parameter and a msrf \< 1.1 of 1.2 are -considered sufficient for convergence. +Usually, a value \< 1.05 for each parameter and a msrf \< 1.1 of 1.2 are considered sufficient for convergence. ### Summarize the outputs -If we are happy with the convergence, we can plot and summarize all -`sampler`s from the console with the standard `print` and `summary` -commands. +If we are happy with the convergence, we can plot and summarize all `sampler`s from the console with the standard `print` and `summary` commands. ```{r} print(out, start = 100) summary(out, start = 100) ``` -You can also use built-in plot functions from the package for -visualization. The `marginalPlot` can be either plotted as histograms -with density overlay (default setting) or as a violin plot (see +You can also use built-in plot functions from the package for visualization. The `marginalPlot` can be either plotted as histograms with density overlay (default setting) or as a violin plot (see "?marginalPlot"). ```{r} @@ -197,12 +165,8 @@ correlationPlot(out) marginalPlot(out, prior = TRUE) ``` -Additional functions that may be used on all `sampler`s are model -selection scores, including the Deviance Information Criterion (DIC) and -the marginal likelihood (see later section for details on calculating -the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set -of methods are available for calculation of marginal likelihood (refer -to "?marginalLikelihood"). +Additional functions that may be used on all `sampler`s are model selection scores, including the Deviance Information Criterion (DIC) and the marginal likelihood (see later section for details on calculating the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set +of methods are available for calculation of marginal likelihood (refer to "?marginalLikelihood"). ```{r} marginalLikelihood(out) @@ -210,8 +174,7 @@ DIC(out) MAP(out) ``` -To extract part of the sampled parameter values, you can use the -following process: +To extract part of the sampled parameter values, you can use the following process: ```{r, eval = F} getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) @@ -219,11 +182,9 @@ getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) ### Which sampler to choose? -The BT package provides a large class of different MCMC samplers, and it -depends on the particular application which one is most suitable. +The BT package provides a large class of different MCMC samplers, and it depends on the particular application which one is most suitable. -In the absence of further information, we currently recommend the `DEz`s -sampler. This is also the default in the `runMCMC` function. +In the absence of further information, we currently recommend the `DEz`s sampler. This is also the default in the `runMCMC` function. # BayesianSetup Reference @@ -245,10 +206,7 @@ bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper ### Parallelization of the likelihood evaluations -Likelihoods are often costly to compute. If this is the case for you, -you should think about parallelization possibilities. The -'createBayesianSetup' function has an input variable 'parallel', with -the following options +Likelihoods are often costly to compute. If this is the case for you, you should think about parallelization possibilities. The 'createBayesianSetup' function has an input variable 'parallel', with the following options - F / FALSE means no parallelization should be used - T / TRUE means to use R's automatic parallelization options (note: @@ -272,28 +230,11 @@ Here are some more details about the parallelization. #### 1. In-build parallelization: -In-built parallelizing is the easiest way to use parallel computing. The -"parallel" argument allows you to select the number of cores to use for -parallelization. Alternatively, TRUE or "auto" will use all available -cores except one. Now the proposals are evaluated in parallel. -Technically, the built-in parallelization uses an R cluster to evaluate -the posterior density function. The input to the parallel function is a -matrix where each column represents a parameter and each row represents -a proposal. This allows the proposals to be evaluated in parallel. For -`sampler`s that evaluate only one proposal at a time (namely the -Metropolis-based algorithms and DE/DREAM without the `zs` extension), -parallelization cannot be used. +In-built parallelizing is the easiest way to use parallel computing. The "parallel" argument allows you to select the number of cores to use for parallelization. Alternatively, TRUE or "auto" will use all availablecores except one. Now the proposals are evaluated in parallel. Technically, the built-in parallelization uses an R cluster to evaluate the posterior density function. The input to the parallel function is a matrix where each column represents a parameter and each row represents a proposal. This allows the proposals to be evaluated in parallel. For `sampler`s that evaluate only one proposal at a time (namely the Metropolis-based algorithms and DE/DREAM without the `zs` extension), parallelization cannot be used. #### 2. External parallelization -The second option is to use external parallelization. Here, -parallelization is attempted in the user-defined likelihood function. To -use external parallelization, the likelihood function must take a matrix -of proposals and return a vector of likelihood values. In the proposal -matrix, each row represents a proposal, and each column represents a -parameter. In addition, you will need to specify the "external" -parallelization in the "parallel" argument. In simple terms, using -external parallelization involves the following steps +The second option is to use external parallelization. Here, parallelization is attempted in the user-defined likelihood function. To use external parallelization, the likelihood function must take a matrix of proposals and return a vector of likelihood values. In the proposal matrix, each row represents a proposal, and each column represents a parameter. In addition, you will need to specify the "external" parallelization in the "parallel" argument. In simple terms, using external parallelization involves the following steps ```{r, eval = FALSE} ## Definition of likelihood function @@ -311,16 +252,11 @@ runMCMC(BS, sampler = "SMC", ...) #### 3. Multi-core and cluster calculations -If you want to run your calculations on a cluster there are several ways -to do it. +If you want to run your calculations on a cluster there are several ways to do it. -In the first case, you want to parallelize n internal (not total chains) -on n cores. The argument "parallel = T" in "createBayesianSetup" only -allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and -`DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" -to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be -parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` -samplers. +In the first case, you want to parallelize n internal (not total chains) on n cores. The argument "parallel = T" in "createBayesianSetup" only +allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and `DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" +to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` samplers. ```{r, eval = FALSE} ## n = Number of cores @@ -333,10 +269,7 @@ bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper out <- runMCMC(bayesianSetup, settings = list(iterations = 1000)) ``` -In the second case, you want to parallelize n internal chains on `n` -cores with an external parallelized likelihood function. Unlike the -previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized -this way. +In the second case, you want to parallelize n internal chains on `n` cores with an external parallelized likelihood function. Unlike the previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized this way. ```{r, eval = FALSE} ### Create cluster with n cores @@ -362,10 +295,7 @@ settings = list(iterations = 100, nrChains = 1, startValue = bayesianSetup$prior out <- runMCMC(bayesianSetup, settings, sampler = "DEzs") ``` -In another case, your likelihood requires a parallelized model. Start -your cluster and export your model, the required libraries, and `dll`s. -Now you can start your calculations with the argument "parallel = -external" in `createBayesianSetup`. +In another case, your likelihood requires a parallelized model. Start your cluster and export your model, the required libraries, and `dll`s. Now you can start your calculations with the argument "parallel = external" in `createBayesianSetup`. ```{r, eval = FALSE} ### Create cluster with n cores @@ -413,13 +343,7 @@ out <- parallel::parLapply(cl, 1:n, fun = function(X, bayesianSetup, settings) r out <- createMcmcSamplerList(out) ``` -\*\* Note: Even though parallelization can significantly reduce the -computation time, it is not always useful because of the so-called -communication overhead (computational time for distributing and -retrieving information from the parallel cores). For models with low -computational cost, this procedure may take more time than the actual -evaluation of the likelihood. If in doubt, do a small run-time -comparison before starting your large sampling. \*\* +\*\* Note: Even though parallelization can significantly reduce the computation time, it is not always useful because of the so-called communication overhead (computational time for distributing and retrieving information from the parallel cores). For models with low computational cost, this procedure may take more time than the actual evaluation of the likelihood. If in doubt, do a small run-time comparison before starting your large sampling. \*\* ## Reference on creating priors @@ -541,20 +465,15 @@ iter = 10000 ### The Metropolis MCMC class -The `BayesianTools` package is able to run a large number of -Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can -be accessed by the "Metropolis" `sampler` in the `runMCMC` function by -specifying the `sampler`'s settings. +The `BayesianTools` package is able to run a large number of Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can be accessed by the "Metropolis" `sampler` in the `runMCMC` function by specifying the `sampler`'s settings. -The subsequent code provides an overview of the default settings of the -MH `sampler`. +The subsequent code provides an overview of the default settings of the MH `sampler`. ```{r} applySettingsDefault(sampler = "Metropolis") ``` -Here are some examples of how to apply different settings. Activate -individual options or combinations as demonstrated. +Here are some examples of how to apply different settings. Activate individual options or combinations as demonstrated. ### Standard MH MCMC @@ -575,9 +494,7 @@ plot(out) #### Standard MH MCMC, prior optimization -Prior to the sampling process, this `sampler` employs an optimization -step. The purpose of optimization is to improve the initial values and -the covariance of the proposal distribution. +Prior to the sampling process, this `sampler` employs an optimization step. The purpose of optimization is to improve the initial values and the covariance of the proposal distribution. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) @@ -587,10 +504,8 @@ plot(out) #### Adaptive MCMC, prior optimization -The adaptive Metropolis sampler (AM) uses the information already -obtained during the sampling process to improve (or adapt) the proposal -function. The `BayesianTools` package adjusts the covariance of the -proposal distribution by utilizing the chain's history. +The adaptive Metropolis sampler (AM) uses the information already obtained during the sampling process to improve (or adapt) the proposal +function. The `BayesianTools` package adjusts the covariance of the proposal distribution by utilizing the chain's history. References: Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive metropolis algorithm. Bernoulli , 223-242. @@ -603,15 +518,8 @@ plot(out) #### Standard MCMC, prior optimization, delayed rejection -Although rejection is an essential step in an MCMC algorithm, it can -also mean that the proposal distribution is (locally) poorly tuned to -the target distribution. In a delayed rejection (DR) sampler, a second -(or third, etc.) proposal is made before rejection. This proposal is -usually drawn from a different distribution, allowing for greater -flexibility of the sampler. In the `BayesianTools` package, the number -of delayed rejection steps and the scaling of the proposals can be -specified. \*\* Note that the current version supports only two delayed -rejection steps. \*\* +Although rejection is an essential step in an MCMC algorithm, it can also mean that the proposal distribution is (locally) poorly tuned to the target distribution. In a delayed rejection (DR) sampler, a second (or third, etc.) proposal is made before rejection. This proposal is usually drawn from a different distribution, allowing for greater flexibility of the sampler. In the `BayesianTools` package, the number of delayed rejection steps and the scaling of the proposals can be specified. +\*\* Note that the current version supports only two delayed rejection steps. \*\* References: Green, Peter J., and Antonietta Mira. "Delayed rejection in reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. @@ -624,8 +532,7 @@ plot(out) #### Adaptive MCMC, prior optimization, delayed rejection -The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a -combination of the two previous `sampler`s (DR and AM). +The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a combination of the two previous `sampler`s (DR and AM). References: Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." Statistics and Computing 16.4 (2006): 339-354. @@ -638,15 +545,9 @@ plot(out) #### Standard MCMC, prior optimization, Gibbs updating -To reduce the dimensions of the target function, a -Metropolis-within-Gibbs `sampler` can be run with the can be run with -the `BayesianTools` package. This means that only a subset of the -parameter vector is updated in each iteration. In the example below, at -most two (of the three) parameters are updated at each step, and it is -twice as likely to vary one as to vary two. +To reduce the dimensions of the target function, a Metropolis-within-Gibbs `sampler` can be run with the can be run with the `BayesianTools` package. This means that only a subset of the parameter vector is updated in each iteration. In the example below, at most two (of the three) parameters are updated at each step, and it is twice as likely to vary one as to vary two. -\*\* Note that currently adaptive cannot be mixed with Gibbs updating! -\*\* +\*\* Note that currently adaptive cannot be mixed with Gibbs updating! \*\* ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = c(1,0.5,0), temperingFunction = NULL, optimize = T, message = FALSE) @@ -656,14 +557,7 @@ plot(out) #### Standard MCMC, prior optimization, gibbs updating, tempering -Simulated tempering is closely related to simulated annealing (e.g., -Bélisle, 1992) in optimization algorithms. The idea of tempering is to -increase the acceptance rate during burn-in. This should lead to a -faster initial scanning of the target function. To incorporate this, a -tempering function must be provided by the user. The function describes -how to influence the acceptance rate during burn-in. In the example -below, an exponential decline approaching 1 (= no influence on the -acceptance rate) is used. +Simulated tempering is closely related to simulated annealing (e.g., Bélisle, 1992) in optimization algorithms. The idea of tempering is to increase the acceptance rate during burn-in. This should lead to a faster initial scanning of the target function. To incorporate this, a tempering function must be provided by the user. The function describes how to influence the acceptance rate during burn-in. In the example below, an exponential decline approaching 1 (= no influence on the acceptance rate) is used. References: Bélisle, C. J. (1992). Convergence theorems for a class of simulated annealing algorithms on rd. Journal of Applied Probability, @@ -706,17 +600,8 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DE", settings = setting plot(out) ``` -The second is the Differential Evolution MCMC with Snooker update and -sampling from past states, according to ter Braak, Cajo JF, and Jasper -A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and -Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. This -extension covers two differences from the normal `DE` MCMC. First, it -uses a snooker update based on a user-defined probability. Second, past -states of other chains are taken into account when generating the -proposal. These extensions allow fewer chains (i.e., 3 chains are -usually sufficient for up to 200 parameters) and parallel computing, -since the current position of each chain depends only on the past states -of the other chains. +The second is the Differential Evolution MCMC with Snooker update and sampling from past states, according to ter Braak, Cajo JF, and Jasper +A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. This extension covers two differences from the normal `DE` MCMC. First, it uses a snooker update based on a user-defined probability. Second, past states of other chains are taken into account when generating the proposal. These extensions allow fewer chains (i.e., 3 chains are usually sufficient for up to 200 parameters) and parallel computing, since the current position of each chain depends only on the past states of the other chains. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, message = FALSE) @@ -726,19 +611,9 @@ plot(out) ## DREAM sampler -There are two versions of the DREAM `sampler`. First, the standard DREAM -sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte -Carlo simulation by differential evolution with self-adaptive randomized -subspace sampling". International Journal of Nonlinear Sciences and -Numerical Simulation 10.3 (2009): 273-290. +There are two versions of the DREAM `sampler`. First, the standard DREAM sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte Carlo simulation by differential evolution with self-adaptive randomized subspace sampling". International Journal of Nonlinear Sciences and Numerical Simulation 10.3 (2009): 273-290. -This sampler is largely based on the DE sampler with some significant -changes: 1) More than two chains can be used to generate a proposal. 2) -Randomized subspace sampling can be used to improve efficiency for -high-dimensional posteriors. Each dimension is updated with a crossover -probability CR. To speed up the exploration of the posterior, DREAM -adjusts the distribution of CR values during burn-in to favor large -jumps over small ones. 3) Outlier chains can be removed during burn-in. +This sampler is largely based on the DE sampler with some significant changes: 1) More than two chains can be used to generate a proposal. 2) Randomized subspace sampling can be used to improve efficiency for high-dimensional posteriors. Each dimension is updated with a crossover probability CR. To speed up the exploration of the posterior, DREAM adjusts the distribution of CR values during burn-in to favor large jumps over small ones. 3) Outlier chains can be removed during burn-in. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, message = FALSE) @@ -746,9 +621,7 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAM", settings = sett plot(out) ``` -The second implementation uses the same extension as the DEzs sampler. -Namely sampling from past states and a snooker update. Again, this -extension allows the use of fewer chains and parallel computing. +The second implementation uses the same extension as the DEzs sampler. Namely sampling from past states and a snooker update. Again, this extension allows the use of fewer chains and parallel computing. Again, if in doubt, you should prefer "DREAMzs". @@ -760,14 +633,7 @@ plot(out) ## T-walk -The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and -Colin Fox. "A general purpose sampling algorithm for continuous -distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. The -sampler uses two independent points to explore the posterior space. -Based on probabilities, four different moves are used to generate -proposals for the two points. As with the DE sampler, this procedure -does not require tuning of the proposal distribution for efficient -sampling in complex posterior distributions. +The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and Colin Fox. "A general purpose sampling algorithm for continuous distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. The sampler uses two independent points to explore the posterior space. Based on probabilities, four different moves are used to generate proposals for the two points. As with the DE sampler, this procedure does not require tuning of the proposal distribution for efficient sampling in complex posterior distributions. ```{r, eval = F} settings = list(iterations = iter, message = FALSE) @@ -777,21 +643,13 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Twalk", settings = sett ## Non-MCMC sampling algorithms -MCMCs sample the posterior space by creating a chain in parameter space. -While this allows for "learning" from past steps, it does not allow for -running a large number of posteriors in parallel. +MCMCs sample the posterior space by creating a chain in parameter space. While this allows for "learning" from past steps, it does not allow for running a large number of posteriors in parallel. -An alternative to MCMCs are particle filters, also known as Sequential -Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; -Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for -stochastic simulation models - theory and application Ecol. Lett., 2011, -14, 816-827 +An alternative to MCMCs are particle filters, also known as Sequential Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for stochastic simulation models - theory and application Ecol. Lett., 2011, 14, 816-827 ### Rejection sampling -The simplest option is to sample a large number of parameters and accept -them according to their posterior value. This option can be emulated -with the implemented SMC by setting iterations to 1. +The simplest option is to sample a large number of parameters and accept them according to their posterior value. This option can be emulated with the implemented SMC by setting iterations to 1. ```{r, results = 'hide', eval = F} settings <- list(initialParticles = iter, iterations= 1) @@ -801,8 +659,7 @@ plot(out) ### Sequential Monte Carlo (SMC) -The more sophisticated option is to use the implemented SMC, which is -basically a particle filter that applies multiple filter steps. +The more sophisticated option is to use the implemented SMC, which is basically a particle filter that applies multiple filter steps. ```{r, results = 'hide', eval = F} settings <- list(initialParticles = iter, iterations= 10) @@ -810,14 +667,11 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settin plot(out) ``` -Note that using a number for `initialParticles` requires that the -`bayesianSetup` includes the option to sample from the prior. +Note that using a number for `initialParticles` requires that the `bayesianSetup` includes the option to sample from the prior. # Bayesian model comparison and averaging -There are a number of Bayesian methods for model selection and model -comparison. The BT implements three of the most common: DIC, WAIC, and -the Bayes factor. +There are a number of Bayesian methods for model selection and model comparison. The BT implements three of the most common: DIC, WAIC, and the Bayes factor. - On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 @@ -829,9 +683,7 @@ the Bayes factor. G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. -The Bayes factor relies on the estimation of marginal likelihoods, which -is numerically challenging. The BT package currently implements three -methods +The Bayes factor relies on the estimation of marginal likelihoods, which is numerically challenging. The BT package currently implements three methods - The recommended method is the "Chib" method (Chib and Jeliazkov, 2001), which is based on MCMC samples but performs additional @@ -910,20 +762,17 @@ BF \> 1 means that the evidence favors M1. See Kass, R. E. & Raftery, A. E. (1995) Bayes Factors. J. Am. Stat. Assoc. Amer Statist Assn, 90, 773-795. -Assuming equal prior weights for all models, we can calculate the -posterior weight of M1 as +Assuming equal prior weights for all models, we can calculate the posterior weight of M1 as ```{r} exp(M1$ln.ML) / ( exp(M1$ln.ML) + exp(M2$ln.ML)) ``` -If the models have different model priors, then multiply by the prior -probability of each of the models. +If the models have different model priors, then multiply by the prior probability of each of the models. ### Comparing Models by DIC -The Deviance Information Criterion is a commonly used method to -summarize the fit of an MCMC chain. It can be calculated using +The Deviance Information Criterion is a commonly used method to summarize the fit of an MCMC chain. It can be calculated using ```{r} DIC(out1)$DIC @@ -932,12 +781,7 @@ DIC(out2)$DIC ### Model Comparison via WAIC -The Watanabe-Akaike Information Criterion is another criterion for model -comparison. To compute the WAIC, the model must implement a -log-likelihood density that allows the log-likelihood to be computed -pointwise (the likelihood functions require a "sum" argument that -determines whether the summed log-likelihood should be returned). It can -be obtained via +The Watanabe-Akaike Information Criterion is another criterion for model comparison. To compute the WAIC, the model must implement a log-likelihood density that allows the log-likelihood to be computed pointwise (the likelihood functions require a "sum" argument that determines whether the summed log-likelihood should be returned). It can be obtained via ```{r} # This will not work, since likelihood1 has no sum argument From 11e13ebab4564cc69b14dbf00ca8da950098aa83 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 28 Sep 2023 11:14:08 +0200 Subject: [PATCH 12/20] update --- BayesianTools/R/BayesianSetupGenerateParallel.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index 0c8e77f..97f4b56 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -8,7 +8,7 @@ #' @details For parallelization, if option T is selected, an automatic parallelization is tried via R. Alternatively, "external" can be selected on the assumption that the likelihood has already been parallelized. In the latter case, a matrix with parameters as columns must be accepted. You can also specify which packages, objects and DLLs are exported to the cluster. By default, a copy of your workspace is exported, but depending on your workspace, this can be inefficient. As an alternative, you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). #' @export #' @example /inst/examples/generateParallelExecuter.R - +#' generateParallelExecuter <- function(fun, parallel = F, parallelOptions = list(variables = "all", packages = "all", dlls = NULL)){ if (parallel == F){ From 2c1286f25d0af93d73cbf090977404e987e97055 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Thu, 28 Sep 2023 11:15:38 +0200 Subject: [PATCH 13/20] update --- BayesianTools/man/generateParallelExecuter.Rd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BayesianTools/man/generateParallelExecuter.Rd b/BayesianTools/man/generateParallelExecuter.Rd index 88c0050..65e0b31 100644 --- a/BayesianTools/man/generateParallelExecuter.Rd +++ b/BayesianTools/man/generateParallelExecuter.Rd @@ -13,7 +13,7 @@ generateParallelExecuter( \arguments{ \item{fun}{function to be changed to parallel execution} -\item{parallel}{should a parallel R cluster be used? If set to T, machine will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used} +\item{parallel}{should a parallel R cluster be used? If set to T, the operating system will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used} \item{parallelOptions}{a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function \n Third, "dlls": the DLLs needed to run the likelihood function (see Details).} } From 931a453917f7834ca17b0d08d13b7ae479cd4282 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Wed, 25 Oct 2023 10:34:34 +0200 Subject: [PATCH 14/20] Update BayesianSetupGenerateParallel.R --- BayesianTools/R/BayesianSetupGenerateParallel.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index 97f4b56..f063eb5 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -3,7 +3,7 @@ #' @author Florian Hartig #' @param fun function to be changed to parallel execution #' @param parallel should a parallel R cluster be used? If set to T, the operating system will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used -#' @param parallelOptions a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function \n Third, "dlls": the DLLs needed to run the likelihood function (see Details). +#' @param parallelOptions a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function - Third, "dlls": the DLLs needed to run the likelihood function (see Details). #' @note can be used to make functions compatible with library sensitivity #' @details For parallelization, if option T is selected, an automatic parallelization is tried via R. Alternatively, "external" can be selected on the assumption that the likelihood has already been parallelized. In the latter case, a matrix with parameters as columns must be accepted. You can also specify which packages, objects and DLLs are exported to the cluster. By default, a copy of your workspace is exported, but depending on your workspace, this can be inefficient. As an alternative, you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). #' @export From d5beeadc2daacdda6c91ed49ab6fb684a08bf074 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Wed, 25 Oct 2023 10:38:07 +0200 Subject: [PATCH 15/20] Update BayesianSetupGenerateParallel.R --- BayesianTools/R/BayesianSetupGenerateParallel.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index f063eb5..60ef826 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -3,7 +3,7 @@ #' @author Florian Hartig #' @param fun function to be changed to parallel execution #' @param parallel should a parallel R cluster be used? If set to T, the operating system will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used -#' @param parallelOptions a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function - Third, "dlls": the DLLs needed to run the likelihood function (see Details). +#' @param parallelOptions a list containing three lists. First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function - Third, "dlls": the DLLs needed to run the likelihood function (see Details). #' @note can be used to make functions compatible with library sensitivity #' @details For parallelization, if option T is selected, an automatic parallelization is tried via R. Alternatively, "external" can be selected on the assumption that the likelihood has already been parallelized. In the latter case, a matrix with parameters as columns must be accepted. You can also specify which packages, objects and DLLs are exported to the cluster. By default, a copy of your workspace is exported, but depending on your workspace, this can be inefficient. As an alternative, you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). #' @export From 610db24894fa1111b43e77200cec0b5a5102c8c7 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Wed, 25 Oct 2023 12:08:55 +0200 Subject: [PATCH 16/20] deleted white space and run check --- BayesianTools/R/BayesianSetupGenerateParallel.R | 2 +- BayesianTools/man/generateParallelExecuter.Rd | 2 +- BayesianTools/vignettes/BayesianTools.Rmd | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index 60ef826..9a2c6a3 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -3,7 +3,7 @@ #' @author Florian Hartig #' @param fun function to be changed to parallel execution #' @param parallel should a parallel R cluster be used? If set to T, the operating system will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used -#' @param parallelOptions a list containing three lists. First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function - Third, "dlls": the DLLs needed to run the likelihood function (see Details). +#' @param parallelOptions a list containing three lists. \itemize{\item First, "packages": determines the R packages required to run the likelihood function. \item Second, "variables": the objects in the global environment needed to run the likelihood function. \item Third, "dlls": the DLLs needed to run the likelihood function (see Details).} #' @note can be used to make functions compatible with library sensitivity #' @details For parallelization, if option T is selected, an automatic parallelization is tried via R. Alternatively, "external" can be selected on the assumption that the likelihood has already been parallelized. In the latter case, a matrix with parameters as columns must be accepted. You can also specify which packages, objects and DLLs are exported to the cluster. By default, a copy of your workspace is exported, but depending on your workspace, this can be inefficient. As an alternative, you can specify the environments and packages in the likelihood function (e.g. BayesianTools::VSEM() instead of VSEM()). #' @export diff --git a/BayesianTools/man/generateParallelExecuter.Rd b/BayesianTools/man/generateParallelExecuter.Rd index 65e0b31..c41ae3f 100644 --- a/BayesianTools/man/generateParallelExecuter.Rd +++ b/BayesianTools/man/generateParallelExecuter.Rd @@ -15,7 +15,7 @@ generateParallelExecuter( \item{parallel}{should a parallel R cluster be used? If set to T, the operating system will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used} -\item{parallelOptions}{a list containing three lists. \n First, "packages": determines the R packages required to run the likelihood function. \n Second, "variables": the objects in the global environment needed to run the likelihood function \n Third, "dlls": the DLLs needed to run the likelihood function (see Details).} +\item{parallelOptions}{a list containing three lists. \itemize{\item First, "packages": determines the R packages required to run the likelihood function. \item Second, "variables": the objects in the global environment needed to run the likelihood function. \item Third, "dlls": the DLLs needed to run the likelihood function (see Details).}} } \description{ Factory to generate a parallel executor of an existing function diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index cdffad7..0205251 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -63,6 +63,7 @@ The central object in the BT package is the BayesianSetup. This class contains t A BayesianSetup is created by the createBayesianSetup function. The function expects a log-likelihood and (optional) a log-prior. It then automatically creates the posterior and various convenience functions for the samplers. Advantages of the BayesianSetup include + 1. support for automatic parallelization 2. functions are wrapped in try-catch statements to avoid crashes during long MCMC evaluations 3. and the posterior checks if the parameter is outside the prior first, in which case the likelihood is not evaluated (makes the algorithms faster for slow likelihoods). @@ -223,7 +224,7 @@ In the first case you want to parallize n internal (not overall chains) on n cor ```{r, eval = FALSE} ## n = Number of cores -n=2 +n = 2 x <- c(1:10) likelihood <- function(param) return(sum(dnorm(x, mean = param, log = T))) bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper = 5) From e735140aaf55f0462b7e55295242da42545d86f7 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Fri, 27 Oct 2023 16:05:46 +0200 Subject: [PATCH 17/20] update --- BayesianTools/R/classBayesianSetup.R | 1 + 1 file changed, 1 insertion(+) diff --git a/BayesianTools/R/classBayesianSetup.R b/BayesianTools/R/classBayesianSetup.R index 6cd6d1a..f7dbc8b 100644 --- a/BayesianTools/R/classBayesianSetup.R +++ b/BayesianTools/R/classBayesianSetup.R @@ -1,3 +1,4 @@ + #' Creates a standardized collection of prior, likelihood and posterior functions, including error checks etc. #' @author Florian Hartig, Tankred Ott #' @param likelihood log likelihood density function From 96e13127a5679e9f3cc5b586eaac2f237756790e Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Fri, 27 Oct 2023 16:07:06 +0200 Subject: [PATCH 18/20] update --- BayesianTools/R/BayesianSetupGenerateParallel.R | 1 - 1 file changed, 1 deletion(-) diff --git a/BayesianTools/R/BayesianSetupGenerateParallel.R b/BayesianTools/R/BayesianSetupGenerateParallel.R index 9a2c6a3..766538f 100644 --- a/BayesianTools/R/BayesianSetupGenerateParallel.R +++ b/BayesianTools/R/BayesianSetupGenerateParallel.R @@ -1,5 +1,4 @@ #' Factory to generate a parallel executor of an existing function -#' #' @author Florian Hartig #' @param fun function to be changed to parallel execution #' @param parallel should a parallel R cluster be used? If set to T, the operating system will automatically detect the available cores and n-1 of the available n cores will be used. Alternatively, you can manually set the number of cores to be used From de0b5fb7c1daa408f1ffff436a54d0e7a0d837a3 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Mon, 30 Oct 2023 14:19:32 +0100 Subject: [PATCH 19/20] update --- BayesianTools/vignettes/BayesianTools.Rmd | 284 ++++++++++++++---- BayesianTools/vignettes/InterfacingAModel.Rmd | 1 + 2 files changed, 221 insertions(+), 64 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index f40406e..ea32791 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -73,18 +73,28 @@ packages. ## The Bayesian Setup -The central object in the `BT` package is the `BayesianSetup`. This class contains the information about the model to be fit (likelihood), +The central object in the `BT` package is the `BayesianSetup`. This +class contains the information about the model to be fit (likelihood), and the priors for the model parameters. -The `createBayesianSetup` function generates a `BayesianSetup` object. The function requires a log-likelihood and a log-prior (optional) as -arguments. It then automatically creates the posterior and various convenience functions for the samplers. +The `createBayesianSetup` function generates a `BayesianSetup` object. +The function requires a log-likelihood and a log-prior (optional) as +arguments. It then automatically creates the posterior and various +convenience functions for the samplers. -Advantages of the `BayesianSetup` include 1. support for automatic parallelization 2. functions are wrapped in try-catch statements to avoid crashes during long MCMC evaluations 3. and the posterior checks if the parameter is outside the prior first, in which case the likelihood is not evaluated (makes the algorithms faster for slow +Advantages of the `BayesianSetup` include 1. support for automatic +parallelization 2. functions are wrapped in try-catch statements to +avoid crashes during long MCMC evaluations 3. and the posterior checks +if the parameter is outside the prior first, in which case the +likelihood is not evaluated (makes the algorithms faster for slow likelihoods). -If no prior information is provided, an unbounded flat prior is generated. If no explicit prior is specified, but lower and upper values -are given, a standard uniform prior with the respective bounds is created, including the option to sample from this prior, which is useful -for SMC and obtaining initial values. This option is used in the following example, which creates a multivariate normal likelihood +If no prior information is provided, an unbounded flat prior is +generated. If no explicit prior is specified, but lower and upper values +are given, a standard uniform prior with the respective bounds is +created, including the option to sample from this prior, which is useful +for SMC and obtaining initial values. This option is used in the +following example, which creates a multivariate normal likelihood density and a uniform prior for 3 parameters. ```{r} @@ -99,15 +109,19 @@ ecological model, see `?VSEM`. ## Run MCMC and SMC functions -After setup, you may need to run a calibration. The `runMCMC` function serves as the main wrapper for all other implemented `MCMC`/`SMC` functions. It always requires the following arguments: +After setup, you may need to run a calibration. The `runMCMC` function +serves as the main wrapper for all other implemented `MCMC`/`SMC` +functions. It always requires the following arguments: - `bayesianSetup` (alternatively, the log target function) - `sampler` name - list with `settings` for each sampler - if `settings` is not specified, the default value will be applied -For example, choosing the `sampler` name "Metropolis" calls a versatile Metropolis-type MCMC with options for covariance adjustment, delayed -rejection, tempering and Metropolis-within-Gibbs sampling. For details, see the later reference on MCMC samplers. When in doubt about the choice +For example, choosing the `sampler` name "Metropolis" calls a versatile +Metropolis-type MCMC with options for covariance adjustment, delayed +rejection, tempering and Metropolis-within-Gibbs sampling. For details, +see the later reference on MCMC samplers. When in doubt about the choice of MCMC sampler, we recommend using the default "DEzs". ```{r} @@ -118,9 +132,15 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ## Convergence checks for MCMCs -Before interpreting the results, MCMCs should be checked for convergence. We recommend the Gelman-Rubin convergence diagnostics,which are the standard used in most publications. The Gelman-Rubin diagnostics requires running multiple MCMCs (we recommend 3-5). +Before interpreting the results, MCMCs should be checked for +convergence. We recommend the Gelman-Rubin convergence diagnostics,which +are the standard used in most publications. The Gelman-Rubin diagnostics +requires running multiple MCMCs (we recommend 3-5). -For all samplers, you can conveniently perform multiple runs using the `nrChains` argument. Alternatively, for runtime reasons, you can combine the results of three independent `runMCMC` runs with `nrChains = 1` using `combineChains` +For all samplers, you can conveniently perform multiple runs using the +`nrChains` argument. Alternatively, for runtime reasons, you can combine +the results of three independent `runMCMC` runs with `nrChains = 1` +using `combineChains` ```{r, echo = T} settings = list(iterations = iter, nrChains = 3, message = FALSE) @@ -128,36 +148,48 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ``` -The result is an object of `mcmcSamplerList`, which should allow you to do everything you can do with an `mcmcSampler` object (sometimes with +The result is an object of `mcmcSamplerList`, which should allow you to +do everything you can do with an `mcmcSampler` object (sometimes with slightly different output). -Basic convergence is checked via so-called trace plots, which show the 3 MCMC chains in different colors. +Basic convergence is checked via so-called trace plots, which show the 3 +MCMC chains in different colors. ```{r} plot(out) ``` -The trace plot is examined for major problems (chains look different, systematic trends) and to decide on the burn-in, i.e. the point at which the MCMC has reached the sampling range (i.e. the chains no longer systematically go in one direction). Here, they have basically reached -this point immediately, so we could set the burn-in to 0, but I choose 100, i.e. discard the first 100 samples in all further plots. +The trace plot is examined for major problems (chains look different, +systematic trends) and to decide on the burn-in, i.e. the point at which +the MCMC has reached the sampling range (i.e. the chains no longer +systematically go in one direction). Here, they have basically reached +this point immediately, so we could set the burn-in to 0, but I choose +100, i.e. discard the first 100 samples in all further plots. -If the trace plots look good, we can look at the Gelman-Rubin convergence diagnostics. Note that you have to discard the burn-in. +If the trace plots look good, we can look at the Gelman-Rubin +convergence diagnostics. Note that you have to discard the burn-in. ```{r} gelmanDiagnostics(out, plot = F, start = 100) ``` -Usually, a value \< 1.05 for each parameter and a msrf \< 1.1 of 1.2 are considered sufficient for convergence. +Usually, a value \< 1.05 for each parameter and a msrf \< 1.1 of 1.2 are +considered sufficient for convergence. ### Summarize the outputs -If we are happy with the convergence, we can plot and summarize all `sampler`s from the console with the standard `print` and `summary` commands. +If we are happy with the convergence, we can plot and summarize all +`sampler`s from the console with the standard `print` and `summary` +commands. ```{r} print(out, start = 100) summary(out, start = 100) ``` -You can also use built-in plot functions from the package for visualization. The `marginalPlot` can be either plotted as histograms with density overlay (default setting) or as a violin plot (see +You can also use built-in plot functions from the package for +visualization. The `marginalPlot` can be either plotted as histograms +with density overlay (default setting) or as a violin plot (see "?marginalPlot"). ```{r} @@ -165,8 +197,12 @@ correlationPlot(out) marginalPlot(out, prior = TRUE) ``` -Additional functions that may be used on all `sampler`s are model selection scores, including the Deviance Information Criterion (DIC) and the marginal likelihood (see later section for details on calculating the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set -of methods are available for calculation of marginal likelihood (refer to "?marginalLikelihood"). +Additional functions that may be used on all `sampler`s are model +selection scores, including the Deviance Information Criterion (DIC) and +the marginal likelihood (see later section for details on calculating +the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set +of methods are available for calculation of marginal likelihood (refer +to "?marginalLikelihood"). ```{r} marginalLikelihood(out) @@ -174,7 +210,8 @@ DIC(out) MAP(out) ``` -To extract part of the sampled parameter values, you can use the following process: +To extract part of the sampled parameter values, you can use the +following process: ```{r, eval = F} getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) @@ -182,9 +219,11 @@ getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) ### Which sampler to choose? -The BT package provides a large class of different MCMC samplers, and it depends on the particular application which one is most suitable. +The BT package provides a large class of different MCMC samplers, and it +depends on the particular application which one is most suitable. -In the absence of further information, we currently recommend the `DEz`s sampler. This is also the default in the `runMCMC` function. +In the absence of further information, we currently recommend the `DEz`s +sampler. This is also the default in the `runMCMC` function. # BayesianSetup Reference @@ -206,7 +245,10 @@ bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper ### Parallelization of the likelihood evaluations -Likelihoods are often costly to compute. If this is the case for you, you should think about parallelization possibilities. The 'createBayesianSetup' function has an input variable 'parallel', with the following options +Likelihoods are often costly to compute. If this is the case for you, +you should think about parallelization possibilities. The +'createBayesianSetup' function has an input variable 'parallel', with +the following options - F / FALSE means no parallelization should be used - T / TRUE means to use R's automatic parallelization options (note: @@ -230,11 +272,28 @@ Here are some more details about the parallelization. #### 1. In-build parallelization: -In-built parallelizing is the easiest way to use parallel computing. The "parallel" argument allows you to select the number of cores to use for parallelization. Alternatively, TRUE or "auto" will use all availablecores except one. Now the proposals are evaluated in parallel. Technically, the built-in parallelization uses an R cluster to evaluate the posterior density function. The input to the parallel function is a matrix where each column represents a parameter and each row represents a proposal. This allows the proposals to be evaluated in parallel. For `sampler`s that evaluate only one proposal at a time (namely the Metropolis-based algorithms and DE/DREAM without the `zs` extension), parallelization cannot be used. +In-built parallelizing is the easiest way to use parallel computing. The +"parallel" argument allows you to select the number of cores to use for +parallelization. Alternatively, TRUE or "auto" will use all +availablecores except one. Now the proposals are evaluated in parallel. +Technically, the built-in parallelization uses an R cluster to evaluate +the posterior density function. The input to the parallel function is a +matrix where each column represents a parameter and each row represents +a proposal. This allows the proposals to be evaluated in parallel. For +`sampler`s that evaluate only one proposal at a time (namely the +Metropolis-based algorithms and DE/DREAM without the `zs` extension), +parallelization cannot be used. #### 2. External parallelization -The second option is to use external parallelization. Here, parallelization is attempted in the user-defined likelihood function. To use external parallelization, the likelihood function must take a matrix of proposals and return a vector of likelihood values. In the proposal matrix, each row represents a proposal, and each column represents a parameter. In addition, you will need to specify the "external" parallelization in the "parallel" argument. In simple terms, using external parallelization involves the following steps +The second option is to use external parallelization. Here, +parallelization is attempted in the user-defined likelihood function. To +use external parallelization, the likelihood function must take a matrix +of proposals and return a vector of likelihood values. In the proposal +matrix, each row represents a proposal, and each column represents a +parameter. In addition, you will need to specify the "external" +parallelization in the "parallel" argument. In simple terms, using +external parallelization involves the following steps ```{r, eval = FALSE} ## Definition of likelihood function @@ -252,11 +311,16 @@ runMCMC(BS, sampler = "SMC", ...) #### 3. Multi-core and cluster calculations -If you want to run your calculations on a cluster there are several ways to do it. +If you want to run your calculations on a cluster there are several ways +to do it. -In the first case, you want to parallelize n internal (not total chains) on n cores. The argument "parallel = T" in "createBayesianSetup" only -allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and `DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" -to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` samplers. +In the first case, you want to parallelize n internal (not total chains) +on n cores. The argument "parallel = T" in "createBayesianSetup" only +allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and +`DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" +to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be +parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` +samplers. ```{r, eval = FALSE} ## n = Number of cores @@ -269,7 +333,10 @@ bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper out <- runMCMC(bayesianSetup, settings = list(iterations = 1000)) ``` -In the second case, you want to parallelize n internal chains on `n` cores with an external parallelized likelihood function. Unlike the previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized this way. +In the second case, you want to parallelize n internal chains on `n` +cores with an external parallelized likelihood function. Unlike the +previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized +this way. ```{r, eval = FALSE} ### Create cluster with n cores @@ -295,7 +362,10 @@ settings = list(iterations = 100, nrChains = 1, startValue = bayesianSetup$prior out <- runMCMC(bayesianSetup, settings, sampler = "DEzs") ``` -In another case, your likelihood requires a parallelized model. Start your cluster and export your model, the required libraries, and `dll`s. Now you can start your calculations with the argument "parallel = external" in `createBayesianSetup`. +In another case, your likelihood requires a parallelized model. Start +your cluster and export your model, the required libraries, and `dll`s. +Now you can start your calculations with the argument "parallel = +external" in `createBayesianSetup`. ```{r, eval = FALSE} ### Create cluster with n cores @@ -343,7 +413,13 @@ out <- parallel::parLapply(cl, 1:n, fun = function(X, bayesianSetup, settings) r out <- createMcmcSamplerList(out) ``` -\*\* Note: Even though parallelization can significantly reduce the computation time, it is not always useful because of the so-called communication overhead (computational time for distributing and retrieving information from the parallel cores). For models with low computational cost, this procedure may take more time than the actual evaluation of the likelihood. If in doubt, do a small run-time comparison before starting your large sampling. \*\* +\*\* Note: Even though parallelization can significantly reduce the +computation time, it is not always useful because of the so-called +communication overhead (computational time for distributing and +retrieving information from the parallel cores). For models with low +computational cost, this procedure may take more time than the actual +evaluation of the likelihood. If in doubt, do a small run-time +comparison before starting your large sampling. \*\* ## Reference on creating priors @@ -465,15 +541,20 @@ iter = 10000 ### The Metropolis MCMC class -The `BayesianTools` package is able to run a large number of Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can be accessed by the "Metropolis" `sampler` in the `runMCMC` function by specifying the `sampler`'s settings. +The `BayesianTools` package is able to run a large number of +Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can +be accessed by the "Metropolis" `sampler` in the `runMCMC` function by +specifying the `sampler`'s settings. -The subsequent code provides an overview of the default settings of the MH `sampler`. +The subsequent code provides an overview of the default settings of the +MH `sampler`. ```{r} applySettingsDefault(sampler = "Metropolis") ``` -Here are some examples of how to apply different settings. Activate individual options or combinations as demonstrated. +Here are some examples of how to apply different settings. Activate +individual options or combinations as demonstrated. ### Standard MH MCMC @@ -494,7 +575,9 @@ plot(out) #### Standard MH MCMC, prior optimization -Prior to the sampling process, this `sampler` employs an optimization step. The purpose of optimization is to improve the initial values and the covariance of the proposal distribution. +Prior to the sampling process, this `sampler` employs an optimization +step. The purpose of optimization is to improve the initial values and +the covariance of the proposal distribution. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) @@ -504,8 +587,10 @@ plot(out) #### Adaptive MCMC, prior optimization -The adaptive Metropolis sampler (AM) uses the information already obtained during the sampling process to improve (or adapt) the proposal -function. The `BayesianTools` package adjusts the covariance of the proposal distribution by utilizing the chain's history. +The adaptive Metropolis sampler (AM) uses the information already +obtained during the sampling process to improve (or adapt) the proposal +function. The `BayesianTools` package adjusts the covariance of the +proposal distribution by utilizing the chain's history. References: Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive metropolis algorithm. Bernoulli , 223-242. @@ -518,8 +603,15 @@ plot(out) #### Standard MCMC, prior optimization, delayed rejection -Although rejection is an essential step in an MCMC algorithm, it can also mean that the proposal distribution is (locally) poorly tuned to the target distribution. In a delayed rejection (DR) sampler, a second (or third, etc.) proposal is made before rejection. This proposal is usually drawn from a different distribution, allowing for greater flexibility of the sampler. In the `BayesianTools` package, the number of delayed rejection steps and the scaling of the proposals can be specified. -\*\* Note that the current version supports only two delayed rejection steps. \*\* +Although rejection is an essential step in an MCMC algorithm, it can +also mean that the proposal distribution is (locally) poorly tuned to +the target distribution. In a delayed rejection (DR) sampler, a second +(or third, etc.) proposal is made before rejection. This proposal is +usually drawn from a different distribution, allowing for greater +flexibility of the sampler. In the `BayesianTools` package, the number +of delayed rejection steps and the scaling of the proposals can be +specified. \*\* Note that the current version supports only two delayed +rejection steps. \*\* References: Green, Peter J., and Antonietta Mira. "Delayed rejection in reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. @@ -532,7 +624,8 @@ plot(out) #### Adaptive MCMC, prior optimization, delayed rejection -The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a combination of the two previous `sampler`s (DR and AM). +The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a +combination of the two previous `sampler`s (DR and AM). References: Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." Statistics and Computing 16.4 (2006): 339-354. @@ -545,9 +638,15 @@ plot(out) #### Standard MCMC, prior optimization, Gibbs updating -To reduce the dimensions of the target function, a Metropolis-within-Gibbs `sampler` can be run with the can be run with the `BayesianTools` package. This means that only a subset of the parameter vector is updated in each iteration. In the example below, at most two (of the three) parameters are updated at each step, and it is twice as likely to vary one as to vary two. +To reduce the dimensions of the target function, a +Metropolis-within-Gibbs `sampler` can be run with the can be run with +the `BayesianTools` package. This means that only a subset of the +parameter vector is updated in each iteration. In the example below, at +most two (of the three) parameters are updated at each step, and it is +twice as likely to vary one as to vary two. -\*\* Note that currently adaptive cannot be mixed with Gibbs updating! \*\* +\*\* Note that currently adaptive cannot be mixed with Gibbs updating! +\*\* ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = c(1,0.5,0), temperingFunction = NULL, optimize = T, message = FALSE) @@ -557,7 +656,14 @@ plot(out) #### Standard MCMC, prior optimization, gibbs updating, tempering -Simulated tempering is closely related to simulated annealing (e.g., Bélisle, 1992) in optimization algorithms. The idea of tempering is to increase the acceptance rate during burn-in. This should lead to a faster initial scanning of the target function. To incorporate this, a tempering function must be provided by the user. The function describes how to influence the acceptance rate during burn-in. In the example below, an exponential decline approaching 1 (= no influence on the acceptance rate) is used. +Simulated tempering is closely related to simulated annealing (e.g., +Bélisle, 1992) in optimization algorithms. The idea of tempering is to +increase the acceptance rate during burn-in. This should lead to a +faster initial scanning of the target function. To incorporate this, a +tempering function must be provided by the user. The function describes +how to influence the acceptance rate during burn-in. In the example +below, an exponential decline approaching 1 (= no influence on the +acceptance rate) is used. References: Bélisle, C. J. (1992). Convergence theorems for a class of simulated annealing algorithms on rd. Journal of Applied Probability, @@ -600,8 +706,17 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DE", settings = setting plot(out) ``` -The second is the Differential Evolution MCMC with Snooker update and sampling from past states, according to ter Braak, Cajo JF, and Jasper -A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. This extension covers two differences from the normal `DE` MCMC. First, it uses a snooker update based on a user-defined probability. Second, past states of other chains are taken into account when generating the proposal. These extensions allow fewer chains (i.e., 3 chains are usually sufficient for up to 200 parameters) and parallel computing, since the current position of each chain depends only on the past states of the other chains. +The second is the Differential Evolution MCMC with Snooker update and +sampling from past states, according to ter Braak, Cajo JF, and Jasper +A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and +Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. This +extension covers two differences from the normal `DE` MCMC. First, it +uses a snooker update based on a user-defined probability. Second, past +states of other chains are taken into account when generating the +proposal. These extensions allow fewer chains (i.e., 3 chains are +usually sufficient for up to 200 parameters) and parallel computing, +since the current position of each chain depends only on the past states +of the other chains. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, message = FALSE) @@ -611,9 +726,19 @@ plot(out) ## DREAM sampler -There are two versions of the DREAM `sampler`. First, the standard DREAM sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte Carlo simulation by differential evolution with self-adaptive randomized subspace sampling". International Journal of Nonlinear Sciences and Numerical Simulation 10.3 (2009): 273-290. +There are two versions of the DREAM `sampler`. First, the standard DREAM +sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte +Carlo simulation by differential evolution with self-adaptive randomized +subspace sampling". International Journal of Nonlinear Sciences and +Numerical Simulation 10.3 (2009): 273-290. -This sampler is largely based on the DE sampler with some significant changes: 1) More than two chains can be used to generate a proposal. 2) Randomized subspace sampling can be used to improve efficiency for high-dimensional posteriors. Each dimension is updated with a crossover probability CR. To speed up the exploration of the posterior, DREAM adjusts the distribution of CR values during burn-in to favor large jumps over small ones. 3) Outlier chains can be removed during burn-in. +This sampler is largely based on the DE sampler with some significant +changes: 1) More than two chains can be used to generate a proposal. 2) +Randomized subspace sampling can be used to improve efficiency for +high-dimensional posteriors. Each dimension is updated with a crossover +probability CR. To speed up the exploration of the posterior, DREAM +adjusts the distribution of CR values during burn-in to favor large +jumps over small ones. 3) Outlier chains can be removed during burn-in. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, message = FALSE) @@ -621,7 +746,9 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAM", settings = sett plot(out) ``` -The second implementation uses the same extension as the DEzs sampler. Namely sampling from past states and a snooker update. Again, this extension allows the use of fewer chains and parallel computing. +The second implementation uses the same extension as the DEzs sampler. +Namely sampling from past states and a snooker update. Again, this +extension allows the use of fewer chains and parallel computing. Again, if in doubt, you should prefer "DREAMzs". @@ -633,7 +760,14 @@ plot(out) ## T-walk -The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and Colin Fox. "A general purpose sampling algorithm for continuous distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. The sampler uses two independent points to explore the posterior space. Based on probabilities, four different moves are used to generate proposals for the two points. As with the DE sampler, this procedure does not require tuning of the proposal distribution for efficient sampling in complex posterior distributions. +The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and +Colin Fox. "A general purpose sampling algorithm for continuous +distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. The +sampler uses two independent points to explore the posterior space. +Based on probabilities, four different moves are used to generate +proposals for the two points. As with the DE sampler, this procedure +does not require tuning of the proposal distribution for efficient +sampling in complex posterior distributions. ```{r, eval = F} settings = list(iterations = iter, message = FALSE) @@ -643,13 +777,21 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Twalk", settings = sett ## Non-MCMC sampling algorithms -MCMCs sample the posterior space by creating a chain in parameter space. While this allows for "learning" from past steps, it does not allow for running a large number of posteriors in parallel. +MCMCs sample the posterior space by creating a chain in parameter space. +While this allows for "learning" from past steps, it does not allow for +running a large number of posteriors in parallel. -An alternative to MCMCs are particle filters, also known as Sequential Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for stochastic simulation models - theory and application Ecol. Lett., 2011, 14, 816-827 +An alternative to MCMCs are particle filters, also known as Sequential +Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; +Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for +stochastic simulation models - theory and application Ecol. Lett., 2011, +14, 816-827 ### Rejection sampling -The simplest option is to sample a large number of parameters and accept them according to their posterior value. This option can be emulated with the implemented SMC by setting iterations to 1. +The simplest option is to sample a large number of parameters and accept +them according to their posterior value. This option can be emulated +with the implemented SMC by setting iterations to 1. ```{r, results = 'hide', eval = F} settings <- list(initialParticles = iter, iterations= 1) @@ -659,7 +801,8 @@ plot(out) ### Sequential Monte Carlo (SMC) -The more sophisticated option is to use the implemented SMC, which is basically a particle filter that applies multiple filter steps. +The more sophisticated option is to use the implemented SMC, which is +basically a particle filter that applies multiple filter steps. ```{r, results = 'hide', eval = F} settings <- list(initialParticles = iter, iterations= 10) @@ -667,11 +810,14 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settin plot(out) ``` -Note that using a number for `initialParticles` requires that the `bayesianSetup` includes the option to sample from the prior. +Note that using a number for `initialParticles` requires that the +`bayesianSetup` includes the option to sample from the prior. # Bayesian model comparison and averaging -There are a number of Bayesian methods for model selection and model comparison. The BT implements three of the most common: DIC, WAIC, and the Bayes factor. +There are a number of Bayesian methods for model selection and model +comparison. The BT implements three of the most common: DIC, WAIC, and +the Bayes factor. - On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 @@ -683,7 +829,9 @@ There are a number of Bayesian methods for model selection and model comparison. G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. -The Bayes factor relies on the estimation of marginal likelihoods, which is numerically challenging. The BT package currently implements three methods +The Bayes factor relies on the estimation of marginal likelihoods, which +is numerically challenging. The BT package currently implements three +methods - The recommended method is the "Chib" method (Chib and Jeliazkov, 2001), which is based on MCMC samples but performs additional @@ -762,17 +910,20 @@ BF \> 1 means that the evidence favors M1. See Kass, R. E. & Raftery, A. E. (1995) Bayes Factors. J. Am. Stat. Assoc. Amer Statist Assn, 90, 773-795. -Assuming equal prior weights for all models, we can calculate the posterior weight of M1 as +Assuming equal prior weights for all models, we can calculate the +posterior weight of M1 as ```{r} exp(M1$ln.ML) / ( exp(M1$ln.ML) + exp(M2$ln.ML)) ``` -If the models have different model priors, then multiply by the prior probability of each of the models. +If the models have different model priors, then multiply by the prior +probability of each of the models. ### Comparing Models by DIC -The Deviance Information Criterion is a commonly used method to summarize the fit of an MCMC chain. It can be calculated using +The Deviance Information Criterion is a commonly used method to +summarize the fit of an MCMC chain. It can be calculated using ```{r} DIC(out1)$DIC @@ -781,7 +932,12 @@ DIC(out2)$DIC ### Model Comparison via WAIC -The Watanabe-Akaike Information Criterion is another criterion for model comparison. To compute the WAIC, the model must implement a log-likelihood density that allows the log-likelihood to be computed pointwise (the likelihood functions require a "sum" argument that determines whether the summed log-likelihood should be returned). It can be obtained via +The Watanabe-Akaike Information Criterion is another criterion for model +comparison. To compute the WAIC, the model must implement a +log-likelihood density that allows the log-likelihood to be computed +pointwise (the likelihood functions require a "sum" argument that +determines whether the summed log-likelihood should be returned). It can +be obtained via ```{r} # This will not work, since likelihood1 has no sum argument diff --git a/BayesianTools/vignettes/InterfacingAModel.Rmd b/BayesianTools/vignettes/InterfacingAModel.Rmd index d370c48..7d6244c 100644 --- a/BayesianTools/vignettes/InterfacingAModel.Rmd +++ b/BayesianTools/vignettes/InterfacingAModel.Rmd @@ -21,6 +21,7 @@ knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) set.seed(123) ``` + # Interfacing a model with BT - step-by-step guide ## Step 1: Create a runModel(par) function From 48b6179b197532be48ee82da70e1477922b74471 Mon Sep 17 00:00:00 2001 From: TahminaMojumder Date: Fri, 3 Nov 2023 11:45:21 +0100 Subject: [PATCH 20/20] update --- BayesianTools/vignettes/BayesianTools.Rmd | 403 ++++-------------- BayesianTools/vignettes/InterfacingAModel.Rmd | 5 +- 2 files changed, 91 insertions(+), 317 deletions(-) diff --git a/BayesianTools/vignettes/BayesianTools.Rmd b/BayesianTools/vignettes/BayesianTools.Rmd index ea32791..f56c53b 100644 --- a/BayesianTools/vignettes/BayesianTools.Rmd +++ b/BayesianTools/vignettes/BayesianTools.Rmd @@ -24,9 +24,7 @@ set.seed(123) # Quick start -The purpose of this first section is to give you a quick overview of the -most important functions of the BayesianTools (BT) package. For a more -detailed description, see the following sections. +The purpose of this first section is to give you a quick overview of the most important functions of the BayesianTools (BT) package. For a more detailed description, see the following sections. ### Install, load and cite the package @@ -47,55 +45,35 @@ library(BayesianTools) citation("BayesianTools") ``` -Note: BayesianTools calls a number of secondary packages. Of particular -importance is `coda`, which is used in a number of plots and -summarystatistics. If you use a lot of summary statistics and diagnostic -plots, it would be nice to cite coda as well! +Note: BayesianTools calls a number of secondary packages. Of particular importance is `coda`, which is used in a number of plots and summarystatistics. If you use a lot of summary statistics and diagnostic plots, it would be nice to cite coda as well! -Pro Tip: If you are running a stochastic algorithm such as MCMC, you -should always set or record your random seed to make your results -reproducible (otherwise the results will change slightly each time you -run the code). +Pro Tip: If you are running a stochastic algorithm such as MCMC, you should always set or record your random seed to make your results reproducible (otherwise the results will change slightly each time you run the code). ```{r} set.seed(123) ``` -In a real application, recording the session info would be helpful in -ensuring reproducibility. +In a real application, recording the session info would be helpful in ensuring reproducibility. ```{r, eval = F} sessionInfo() ``` -This session information includes the version number of R and all loaded -packages. +This session information includes the version number of R and all loaded packages. ## The Bayesian Setup -The central object in the `BT` package is the `BayesianSetup`. This -class contains the information about the model to be fit (likelihood), -and the priors for the model parameters. - -The `createBayesianSetup` function generates a `BayesianSetup` object. -The function requires a log-likelihood and a log-prior (optional) as -arguments. It then automatically creates the posterior and various -convenience functions for the samplers. - -Advantages of the `BayesianSetup` include 1. support for automatic -parallelization 2. functions are wrapped in try-catch statements to -avoid crashes during long MCMC evaluations 3. and the posterior checks -if the parameter is outside the prior first, in which case the -likelihood is not evaluated (makes the algorithms faster for slow -likelihoods). - -If no prior information is provided, an unbounded flat prior is -generated. If no explicit prior is specified, but lower and upper values -are given, a standard uniform prior with the respective bounds is -created, including the option to sample from this prior, which is useful -for SMC and obtaining initial values. This option is used in the -following example, which creates a multivariate normal likelihood -density and a uniform prior for 3 parameters. +The central object in the `BT` package is the `BayesianSetup`. This class contains the information about the model to be fit (likelihood), and the priors for the model parameters. + +The `createBayesianSetup` function generates a `BayesianSetup` object. The function requires a log-likelihood and a log-prior (optional) as arguments. It then automatically creates the posterior and variousn convenience functions for the samplers. + +Advantages of the `BayesianSetup` include + + 1. support for automatic parallelization + 2. functions are wrapped in try-catch statements to avoid crashes during long MCMC evaluations + 3. and the posterior checks if the parameter is outside the prior first, in which case the likelihood is not evaluated (makes the algorithms faster for slow likelihoods). + +If no prior information is provided, an unbounded flat prior is generated. If no explicit prior is specified, but lower and upper values are given, a standard uniform prior with the respective bounds is created, including the option to sample from this prior, which is useful for SMC and obtaining initial values. This option is used in the following example, which creates a multivariate normal likelihood density and a uniform prior for 3 parameters. ```{r} ll <- generateTestDensityMultiNormal(sigma = "no correlation") @@ -104,8 +82,7 @@ bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper A more detailed description of the `BayesianSetup` will follow. -**Hint:** For an example of how to run these steps for a dynamic -ecological model, see `?VSEM`. +**Hint:** For an example of how to run these steps for a dynamic ecological model, see `?VSEM`. ## Run MCMC and SMC functions @@ -118,11 +95,7 @@ functions. It always requires the following arguments: - list with `settings` for each sampler - if `settings` is not specified, the default value will be applied -For example, choosing the `sampler` name "Metropolis" calls a versatile -Metropolis-type MCMC with options for covariance adjustment, delayed -rejection, tempering and Metropolis-within-Gibbs sampling. For details, -see the later reference on MCMC samplers. When in doubt about the choice -of MCMC sampler, we recommend using the default "DEzs". +For example, choosing the `sampler` name "Metropolis" calls a versatile Metropolis-type MCMC with options for covariance adjustment, delayed rejection, tempering and Metropolis-within-Gibbs sampling. For details, see the later reference on MCMC samplers. When in doubt about the choice of MCMC sampler, we recommend using the default "DEzs". ```{r} iter = 1000 @@ -132,15 +105,9 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ## Convergence checks for MCMCs -Before interpreting the results, MCMCs should be checked for -convergence. We recommend the Gelman-Rubin convergence diagnostics,which -are the standard used in most publications. The Gelman-Rubin diagnostics -requires running multiple MCMCs (we recommend 3-5). +Before interpreting the results, MCMCs should be checked for convergence. We recommend the Gelman-Rubin convergence diagnostics,which are the standard used in most publications. The Gelman-Rubin diagnostics requires running multiple MCMCs (we recommend 3-5). -For all samplers, you can conveniently perform multiple runs using the -`nrChains` argument. Alternatively, for runtime reasons, you can combine -the results of three independent `runMCMC` runs with `nrChains = 1` -using `combineChains` +For all samplers, you can conveniently perform multiple runs using the `nrChains` argument. Alternatively, for runtime reasons, you can combine the results of three independent `runMCMC` runs with `nrChains = 1` using `combineChains` ```{r, echo = T} settings = list(iterations = iter, nrChains = 3, message = FALSE) @@ -148,61 +115,41 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = ``` -The result is an object of `mcmcSamplerList`, which should allow you to -do everything you can do with an `mcmcSampler` object (sometimes with -slightly different output). +The result is an object of `mcmcSamplerList`, which should allow you to do everything you can do with an `mcmcSampler` object (sometimes with slightly different output). -Basic convergence is checked via so-called trace plots, which show the 3 -MCMC chains in different colors. +Basic convergence is checked via so-called trace plots, which show the 3 MCMC chains in different colors. ```{r} plot(out) ``` -The trace plot is examined for major problems (chains look different, -systematic trends) and to decide on the burn-in, i.e. the point at which -the MCMC has reached the sampling range (i.e. the chains no longer -systematically go in one direction). Here, they have basically reached -this point immediately, so we could set the burn-in to 0, but I choose -100, i.e. discard the first 100 samples in all further plots. +The trace plot is examined for major problems (chains look different, systematic trends) and to decide on the burn-in, i.e. the point at which the MCMC has reached the sampling range (i.e. the chains no longer systematically go in one direction). Here, they have basically reached this point immediately, so we could set the burn-in to 0, but I choose 100, i.e. discard the first 100 samples in all further plots. -If the trace plots look good, we can look at the Gelman-Rubin -convergence diagnostics. Note that you have to discard the burn-in. +If the trace plots look good, we can look at the Gelman-Rubin convergence diagnostics. Note that you have to discard the burn-in. ```{r} gelmanDiagnostics(out, plot = F, start = 100) ``` -Usually, a value \< 1.05 for each parameter and a msrf \< 1.1 of 1.2 are -considered sufficient for convergence. +Usually, a value \< 1.05 for each parameter and a msrf \< 1.1 of 1.2 are considered sufficient for convergence. ### Summarize the outputs -If we are happy with the convergence, we can plot and summarize all -`sampler`s from the console with the standard `print` and `summary` -commands. +If we are happy with the convergence, we can plot and summarize all `sampler`s from the console with the standard `print` and `summary` commands. ```{r} print(out, start = 100) summary(out, start = 100) ``` -You can also use built-in plot functions from the package for -visualization. The `marginalPlot` can be either plotted as histograms -with density overlay (default setting) or as a violin plot (see -"?marginalPlot"). +You can also use built-in plot functions from the package for visualization. The `marginalPlot` can be either plotted as histograms with density overlay (default setting) or as a violin plot (see "?marginalPlot"). ```{r} correlationPlot(out) marginalPlot(out, prior = TRUE) ``` -Additional functions that may be used on all `sampler`s are model -selection scores, including the Deviance Information Criterion (DIC) and -the marginal likelihood (see later section for details on calculating -the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set -of methods are available for calculation of marginal likelihood (refer -to "?marginalLikelihood"). +Additional functions that may be used on all `sampler`s are model selection scores, including the Deviance Information Criterion (DIC) and the marginal likelihood (see later section for details on calculating the Bayes factor), alongside the Maximum A Posteriori (MAP) value. A set of methods are available for calculation of marginal likelihood (refer to "?marginalLikelihood"). ```{r} marginalLikelihood(out) @@ -210,8 +157,7 @@ DIC(out) MAP(out) ``` -To extract part of the sampled parameter values, you can use the -following process: +To extract part of the sampled parameter values, you can use the following process: ```{r, eval = F} getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) @@ -219,11 +165,9 @@ getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2) ### Which sampler to choose? -The BT package provides a large class of different MCMC samplers, and it -depends on the particular application which one is most suitable. +The BT package provides a large class of different MCMC samplers, and it depends on the particular application which one is most suitable. -In the absence of further information, we currently recommend the `DEz`s -sampler. This is also the default in the `runMCMC` function. +In the absence of further information, we currently recommend the `DEz`s sampler. This is also the default in the `runMCMC` function. # BayesianSetup Reference @@ -235,8 +179,7 @@ The likelihood should be provided as a log density function. ll = logDensity(x) ``` -See parallelization options below. We will use a simple 3-d multivariate -normal density for the demonstration. +See parallelization options below. We will use a simple 3-d multivariate normal density for the demonstration. ```{r} ll <- generateTestDensityMultiNormal(sigma = "no correlation") @@ -245,10 +188,7 @@ bayesianSetup = createBayesianSetup(likelihood = ll, lower = rep(-10, 3), upper ### Parallelization of the likelihood evaluations -Likelihoods are often costly to compute. If this is the case for you, -you should think about parallelization possibilities. The -'createBayesianSetup' function has an input variable 'parallel', with -the following options +Likelihoods are often costly to compute. If this is the case for you, you should think about parallelization possibilities. The 'createBayesianSetup' function has an input variable 'parallel', with the following options - F / FALSE means no parallelization should be used - T / TRUE means to use R's automatic parallelization options (note: @@ -262,38 +202,17 @@ the following options setup (file I/O, HPC cluster) that cannot be handled with the standard R parallelization. -Algorithms in the `BayesianTools` package can take advantage of -parallelization if this option is specified in the `BayesianSetup`. Note -that parallelization is currently used by the following algorithms: -`SMC`, `DEzs` and `DREAMzs` sampler. It can also be used through the -`BayesianSetup` with the functions of the sensitivity package. +Algorithms in the `BayesianTools` package can take advantage of parallelization if this option is specified in the `BayesianSetup`. Note that parallelization is currently used by the following algorithms: `SMC`, `DEzs` and `DREAMzs` sampler. It can also be used through the `BayesianSetup` with the functions of the sensitivity package. Here are some more details about the parallelization. #### 1. In-build parallelization: -In-built parallelizing is the easiest way to use parallel computing. The -"parallel" argument allows you to select the number of cores to use for -parallelization. Alternatively, TRUE or "auto" will use all -availablecores except one. Now the proposals are evaluated in parallel. -Technically, the built-in parallelization uses an R cluster to evaluate -the posterior density function. The input to the parallel function is a -matrix where each column represents a parameter and each row represents -a proposal. This allows the proposals to be evaluated in parallel. For -`sampler`s that evaluate only one proposal at a time (namely the -Metropolis-based algorithms and DE/DREAM without the `zs` extension), -parallelization cannot be used. +In-built parallelizing is the easiest way to use parallel computing. The "parallel" argument allows you to select the number of cores to use for parallelization. Alternatively, TRUE or "auto" will use all availablecores except one. Now the proposals are evaluated in parallel. Technically, the built-in parallelization uses an R cluster to evaluate the posterior density function. The input to the parallel function is a matrix where each column represents a parameter and each row represents a proposal. This allows the proposals to be evaluated in parallel. For `sampler`s that evaluate only one proposal at a time (namely the Metropolis-based algorithms and DE/DREAM without the `zs` extension), parallelization cannot be used. #### 2. External parallelization -The second option is to use external parallelization. Here, -parallelization is attempted in the user-defined likelihood function. To -use external parallelization, the likelihood function must take a matrix -of proposals and return a vector of likelihood values. In the proposal -matrix, each row represents a proposal, and each column represents a -parameter. In addition, you will need to specify the "external" -parallelization in the "parallel" argument. In simple terms, using -external parallelization involves the following steps +The second option is to use external parallelization. Here, parallelization is attempted in the user-defined likelihood function. To use external parallelization, the likelihood function must take a matrix of proposals and return a vector of likelihood values. In the proposal matrix, each row represents a proposal, and each column represents a parameter. In addition, you will need to specify the "external" parallelization in the "parallel" argument. In simple terms, using external parallelization involves the following steps ```{r, eval = FALSE} ## Definition of likelihood function @@ -311,16 +230,9 @@ runMCMC(BS, sampler = "SMC", ...) #### 3. Multi-core and cluster calculations -If you want to run your calculations on a cluster there are several ways -to do it. +If you want to run your calculations on a cluster there are several ways to do it. -In the first case, you want to parallelize n internal (not total chains) -on n cores. The argument "parallel = T" in "createBayesianSetup" only -allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and -`DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" -to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be -parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` -samplers. +In the first case, you want to parallelize n internal (not total chains) on n cores. The argument "parallel = T" in "createBayesianSetup" only allows parallelization on a maximum of 3 cores for the `SMC`, `DEzs` and `DreamsSamplers`. But by setting "parallel = n" in "createBayesianSetup" to `n` cores, the internal chains of `DEzs` and `DREAMzs` will be parallelized on `n` cores. This only works for `DEzs` and `DREAMzs` samplers. ```{r, eval = FALSE} ## n = Number of cores @@ -333,10 +245,7 @@ bayesianSetup <- createBayesianSetup(likelihood, parallel = n, lower = -5, upper out <- runMCMC(bayesianSetup, settings = list(iterations = 1000)) ``` -In the second case, you want to parallelize n internal chains on `n` -cores with an external parallelized likelihood function. Unlike the -previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized -this way. +In the second case, you want to parallelize n internal chains on `n` cores with an external parallelized likelihood function. Unlike the previous case, `DEzs`, `DREAMzs`, and `SMC` samplers can be parallelized this way. ```{r, eval = FALSE} ### Create cluster with n cores @@ -362,9 +271,7 @@ settings = list(iterations = 100, nrChains = 1, startValue = bayesianSetup$prior out <- runMCMC(bayesianSetup, settings, sampler = "DEzs") ``` -In another case, your likelihood requires a parallelized model. Start -your cluster and export your model, the required libraries, and `dll`s. -Now you can start your calculations with the argument "parallel = +In another case, your likelihood requires a parallelized model. Start your cluster and export your model, the required libraries, and `dll`s. Now you can start your calculations with the argument "parallel = external" in `createBayesianSetup`. ```{r, eval = FALSE} @@ -389,9 +296,7 @@ out <- runMCMC(bayesianSetup, settings) ``` -In the last case, you can parallelize over whole chain calculations. -However, the likelihood itself is not parallelized. Each chain is run on -one core, and the likelihood is calculated on that core. +In the last case, you can parallelize over whole chain calculations. However, the likelihood itself is not parallelized. Each chain is run on one core, and the likelihood is calculated on that core. ```{r, eval = FALSE} ### Definition of likelihood function @@ -413,13 +318,7 @@ out <- parallel::parLapply(cl, 1:n, fun = function(X, bayesianSetup, settings) r out <- createMcmcSamplerList(out) ``` -\*\* Note: Even though parallelization can significantly reduce the -computation time, it is not always useful because of the so-called -communication overhead (computational time for distributing and -retrieving information from the parallel cores). For models with low -computational cost, this procedure may take more time than the actual -evaluation of the likelihood. If in doubt, do a small run-time -comparison before starting your large sampling. \*\* +\*\* Note: Even though parallelization can significantly reduce the computation time, it is not always useful because of the so-called communication overhead (computational time for distributing and retrieving information from the parallel cores). For models with low computational cost, this procedure may take more time than the actual evaluation of the likelihood. If in doubt, do a small run-time comparison before starting your large sampling. \*\* ## Reference on creating priors @@ -431,8 +330,7 @@ The prior in the `BayesianSetup` consists of four parts - lower / upper boundaries - Additional info - best values, names of the parameters, ... -This information can be passed by first creating an extra object, via -`createPrior`, or via the `createBayesianSetup` function. +This information can be passed by first creating an extra object, via `createPrior`, or via the `createBayesianSetup` function. #### Creating priors @@ -449,8 +347,7 @@ You have 5 options to create a prior #### Creating user-defined priors -When creating a user-defined prior, the following information can/should -be passed to `createPrior` +When creating a user-defined prior, the following information can/should be passed to `createPrior` - A log density function, as a function of a parameter vector x, same syntax as the likelihood. @@ -486,18 +383,13 @@ out <- runMCMC(bayesianSetup = bayesianSetup, settings = settings) ## The runMCMC() function -The `runMCMC` function is the central function for starting MCMC -algorithms in the `BayesianTools` package. It takes a `bayesianSetup`, a -choice of `sampler` (default is `DEzs`), and optionally changes to the -default settings of the chosen `sampler`. +The `runMCMC` function is the central function for starting MCMC algorithms in the `BayesianTools` package. It takes a `bayesianSetup`, a choice of `sampler` (default is `DEzs`), and optionally changes to the default settings of the chosen `sampler`. ```{r, message = F} runMCMC(bayesianSetup, sampler = "DEzs", settings = NULL) ``` -You may use an optional argument `nrChains`, which is set to the default -value of 1 but can be modified if needed. Increasing its value will lead -`runMCMC` to execute multiple runs. +You may use an optional argument `nrChains`, which is set to the default value of 1 but can be modified if needed. Increasing its value will lead `runMCMC` to execute multiple runs. ```{r, message = F} @@ -541,13 +433,10 @@ iter = 10000 ### The Metropolis MCMC class -The `BayesianTools` package is able to run a large number of -Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can -be accessed by the "Metropolis" `sampler` in the `runMCMC` function by +The `BayesianTools` package is able to run a large number of Metropolis-Hastings (MH) based algorithms. All of these `sampler`s can be accessed by the "Metropolis" `sampler` in the `runMCMC` function by specifying the `sampler`'s settings. -The subsequent code provides an overview of the default settings of the -MH `sampler`. +The subsequent code provides an overview of the default settings of the MH `sampler`. ```{r} applySettingsDefault(sampler = "Metropolis") @@ -560,12 +449,9 @@ individual options or combinations as demonstrated. The following settings run the standard Metropolis Hastings MCMC. -Refernences: Hastings, W. K. (1970). Monte carlo sampling methods using -markov chains and their applications. Biometrika 57 (1), 97-109. +Refernences: Hastings, W. K. (1970). Monte carlo sampling methods using markov chains and their applications. Biometrika 57 (1), 97-109. -Metropolis, N., A. W. Rosenbluth, M. N. Rosenbluth, A. H. Teller, and E. -Teller (1953). Equation of state calculations by fast computing -machines. The journal of chemical physics 21 (6), 1087 - 1092. +Metropolis, N., A. W. Rosenbluth, M. N. Rosenbluth, A. H. Teller, and E. Teller (1953). Equation of state calculations by fast computing machines. The journal of chemical physics 21 (6), 1087 - 1092. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = F, message = FALSE) @@ -575,9 +461,7 @@ plot(out) #### Standard MH MCMC, prior optimization -Prior to the sampling process, this `sampler` employs an optimization -step. The purpose of optimization is to improve the initial values and -the covariance of the proposal distribution. +Prior to the sampling process, this `sampler` employs an optimization step. The purpose of optimization is to improve the initial values and the covariance of the proposal distribution. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = F, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) @@ -587,13 +471,9 @@ plot(out) #### Adaptive MCMC, prior optimization -The adaptive Metropolis sampler (AM) uses the information already -obtained during the sampling process to improve (or adapt) the proposal -function. The `BayesianTools` package adjusts the covariance of the -proposal distribution by utilizing the chain's history. +The adaptive Metropolis sampler (AM) uses the information already obtained during the sampling process to improve (or adapt) the proposal function. The `BayesianTools` package adjusts the covariance of the proposal distribution by utilizing the chain's history. -References: Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive -metropolis algorithm. Bernoulli , 223-242. +References: Haario, H., E. Saksman, and J. Tamminen (2001). An adaptive metropolis algorithm. Bernoulli , 223-242. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = T, DRlevels = 1, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) @@ -603,18 +483,9 @@ plot(out) #### Standard MCMC, prior optimization, delayed rejection -Although rejection is an essential step in an MCMC algorithm, it can -also mean that the proposal distribution is (locally) poorly tuned to -the target distribution. In a delayed rejection (DR) sampler, a second -(or third, etc.) proposal is made before rejection. This proposal is -usually drawn from a different distribution, allowing for greater -flexibility of the sampler. In the `BayesianTools` package, the number -of delayed rejection steps and the scaling of the proposals can be -specified. \*\* Note that the current version supports only two delayed -rejection steps. \*\* +Although rejection is an essential step in an MCMC algorithm, it can also mean that the proposal distribution is (locally) poorly tuned to the target distribution. In a delayed rejection (DR) sampler, a second (or third, etc.) proposal is made before rejection. This proposal is usually drawn from a different distribution, allowing for greater flexibility of the sampler. In the `BayesianTools` package, the number of delayed rejection steps and the scaling of the proposals can be specified. \*\* Note that the current version supports only two delayed rejection steps. \*\* -References: Green, Peter J., and Antonietta Mira. "Delayed rejection in -reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. +References: Green, Peter J., and Antonietta Mira. "Delayed rejection in reversible jump Metropolis-Hastings." Biometrika (2001): 1035-1053. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = F, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) @@ -624,11 +495,9 @@ plot(out) #### Adaptive MCMC, prior optimization, delayed rejection -The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a -combination of the two previous `sampler`s (DR and AM). +The Delayed Rejection Adaptive Metropolis (DRAM) `sampler` is simply a combination of the two previous `sampler`s (DR and AM). -References: Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." -Statistics and Computing 16.4 (2006): 339-354. +References: Haario, Heikki, et al. "DRAM: efficient adaptive MCMC." Statistics and Computing 16.4 (2006): 339-354. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, adapt = T, DRlevels = 2, gibbsProbabilities = NULL, temperingFunction = NULL, optimize = T, message = FALSE) @@ -638,12 +507,7 @@ plot(out) #### Standard MCMC, prior optimization, Gibbs updating -To reduce the dimensions of the target function, a -Metropolis-within-Gibbs `sampler` can be run with the can be run with -the `BayesianTools` package. This means that only a subset of the -parameter vector is updated in each iteration. In the example below, at -most two (of the three) parameters are updated at each step, and it is -twice as likely to vary one as to vary two. +To reduce the dimensions of the target function, a Metropolis-within-Gibbs `sampler` can be run with the can be run with the `BayesianTools` package. This means that only a subset of the parameter vector is updated in each iteration. In the example below, at most two (of the three) parameters are updated at each step, and it is twice as likely to vary one as to vary two. \*\* Note that currently adaptive cannot be mixed with Gibbs updating! \*\* @@ -656,22 +520,11 @@ plot(out) #### Standard MCMC, prior optimization, gibbs updating, tempering -Simulated tempering is closely related to simulated annealing (e.g., -Bélisle, 1992) in optimization algorithms. The idea of tempering is to -increase the acceptance rate during burn-in. This should lead to a -faster initial scanning of the target function. To incorporate this, a -tempering function must be provided by the user. The function describes -how to influence the acceptance rate during burn-in. In the example -below, an exponential decline approaching 1 (= no influence on the -acceptance rate) is used. +Simulated tempering is closely related to simulated annealing (e.g., Bélisle, 1992) in optimization algorithms. The idea of tempering is to increase the acceptance rate during burn-in. This should lead to a faster initial scanning of the target function. To incorporate this, a tempering function must be provided by the user. The function describes how to influence the acceptance rate during burn-in. In the example below, an exponential decline approaching 1 (= no influence on the acceptance rate) is used. -References: Bélisle, C. J. (1992). Convergence theorems for a class of -simulated annealing algorithms on rd. Journal of Applied Probability, -885--895. +References: Bélisle, C. J. (1992). Convergence theorems for a class of simulated annealing algorithms on rd. Journal of Applied Probability, 885--895. -C. J. Geyer (2011) Importance sampling, simulated tempering, and -umbrella sampling, in the Handbook of Markov Chain Monte Carlo, S. P. -Brooks, et al (eds), Chapman & Hall/CRC. +C. J. Geyer (2011) Importance sampling, simulated tempering, and umbrella sampling, in the Handbook of Markov Chain Monte Carlo, S. P. Brooks, et al (eds), Chapman & Hall/CRC. ```{r, results = 'hide', eval = F} temperingFunction <- function(x) 5 * exp(-0.01*x) + 1 @@ -682,23 +535,9 @@ plot(out) ### Differential Evolution MCMC -The BT package implements two differential evolution MCMCs. When in -doubt, use the DEzs option. - -The first is the normal DE MCMC, according to Ter Braak, Cajo JF. "A -Markov Chain Monte Carlo version of the genetic algorithm Differential -Evolution: easy Bayesian computing for real parameter spaces". -Statistics and Computing 16.3 (2006): 239-249. This sampler runs -multiple chains in parallel (but not in the sense of parallel -computing). The main difference to the Metropolis based algorithms is -the generation of the proposal. In general, all `sampler`s use the -current position of the chain and add a step in the parameter space to -generate a new proposal. While in the Metropolis based `sampler` this -step is usually drawn from a multivariate normal distribution (but any -distribution is possible), the `DE` `sampler` uses the current position -of two other chains to generate the step for each chain. For successful -sampling, at least `2*d` chains, where `d` is the number of parameters, -must be run in parallel. +The BT package implements two differential evolution MCMCs. When in doubt, use the DEzs option. + +The first is the normal DE MCMC, according to Ter Braak, Cajo JF. "A Markov Chain Monte Carlo version of the genetic algorithm Differential Evolution: easy Bayesian computing for real parameter spaces". Statistics and Computing 16.3 (2006): 239-249. This sampler runs multiple chains in parallel (but not in the sense of parallel computing). The main difference to the Metropolis based algorithms is the generation of the proposal. In general, all `sampler`s use the current position of the chain and add a step in the parameter space to generate a new proposal. While in the Metropolis based `sampler` this step is usually drawn from a multivariate normal distribution (but any distribution is possible), the `DE` `sampler` uses the current position of two other chains to generate the step for each chain. For successful sampling, at least `2*d` chains, where `d` is the number of parameters, must be run in parallel. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, message = FALSE) @@ -706,17 +545,7 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DE", settings = setting plot(out) ``` -The second is the Differential Evolution MCMC with Snooker update and -sampling from past states, according to ter Braak, Cajo JF, and Jasper -A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and -Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. This -extension covers two differences from the normal `DE` MCMC. First, it -uses a snooker update based on a user-defined probability. Second, past -states of other chains are taken into account when generating the -proposal. These extensions allow fewer chains (i.e., 3 chains are -usually sufficient for up to 200 parameters) and parallel computing, -since the current position of each chain depends only on the past states -of the other chains. +The second is the Differential Evolution MCMC with Snooker update and sampling from past states, according to ter Braak, Cajo JF, and Jasper A. Vrugt. "Differential Evolution Markov Chain with Snooker Updater and Fewer Chains". Statistics and Computing 18.4 (2008): 435-446. This extension covers two differences from the normal `DE` MCMC. First, it uses a snooker update based on a user-defined probability. Second, past states of other chains are taken into account when generating the proposal. These extensions allow fewer chains (i.e., 3 chains are usually sufficient for up to 200 parameters) and parallel computing, since the current position of each chain depends only on the past states of the other chains. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, message = FALSE) @@ -726,19 +555,12 @@ plot(out) ## DREAM sampler -There are two versions of the DREAM `sampler`. First, the standard DREAM -sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte -Carlo simulation by differential evolution with self-adaptive randomized -subspace sampling". International Journal of Nonlinear Sciences and -Numerical Simulation 10.3 (2009): 273-290. +There are two versions of the DREAM `sampler`. First, the standard DREAM sampler, see Vrugt, Jasper A., et al. "Accelerating Markov chain Monte Carlo simulation by differential evolution with self-adaptive randomized subspace sampling". International Journal of Nonlinear Sciences and Numerical Simulation 10.3 (2009): 273-290. + +This sampler is largely based on the DE sampler with some significant changes: -This sampler is largely based on the DE sampler with some significant -changes: 1) More than two chains can be used to generate a proposal. 2) -Randomized subspace sampling can be used to improve efficiency for -high-dimensional posteriors. Each dimension is updated with a crossover -probability CR. To speed up the exploration of the posterior, DREAM -adjusts the distribution of CR values during burn-in to favor large -jumps over small ones. 3) Outlier chains can be removed during burn-in. + 1) More than two chains can be used to generate a proposal. + 2) Randomized subspace sampling can be used to improve efficiency for high-dimensional posteriors. Each dimension is updated with a crossover probability CR. To speed up the exploration of the posterior, DREAM adjusts the distribution of CR values during burn-in to favor large jumps over small ones. 3) Outlier chains can be removed during burn-in. ```{r, results = 'hide', eval = F} settings <- list(iterations = iter, message = FALSE) @@ -746,9 +568,7 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "DREAM", settings = sett plot(out) ``` -The second implementation uses the same extension as the DEzs sampler. -Namely sampling from past states and a snooker update. Again, this -extension allows the use of fewer chains and parallel computing. +The second implementation uses the same extension as the DEzs sampler. Namely sampling from past states and a snooker update. Again, this extension allows the use of fewer chains and parallel computing. Again, if in doubt, you should prefer "DREAMzs". @@ -760,14 +580,7 @@ plot(out) ## T-walk -The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and -Colin Fox. "A general purpose sampling algorithm for continuous -distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. The -sampler uses two independent points to explore the posterior space. -Based on probabilities, four different moves are used to generate -proposals for the two points. As with the DE sampler, this procedure -does not require tuning of the proposal distribution for efficient -sampling in complex posterior distributions. +The t-walk is an MCMC algorithm developed by Christen, J. Andrés, and Colin Fox. "A general purpose sampling algorithm for continuous distributions (the t-walk)". Bayesian Analysis 5.2 (2010): 263-281. The sampler uses two independent points to explore the posterior space. Based on probabilities, four different moves are used to generate proposals for the two points. As with the DE sampler, this procedure does not require tuning of the proposal distribution for efficient sampling in complex posterior distributions. ```{r, eval = F} settings = list(iterations = iter, message = FALSE) @@ -777,21 +590,13 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Twalk", settings = sett ## Non-MCMC sampling algorithms -MCMCs sample the posterior space by creating a chain in parameter space. -While this allows for "learning" from past steps, it does not allow for -running a large number of posteriors in parallel. +MCMCs sample the posterior space by creating a chain in parameter space. While this allows for "learning" from past steps, it does not allow for running a large number of posteriors in parallel. -An alternative to MCMCs are particle filters, also known as Sequential -Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; -Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for -stochastic simulation models - theory and application Ecol. Lett., 2011, -14, 816-827 +An alternative to MCMCs are particle filters, also known as Sequential Monte-Carlo (SMC) algorithms. See Hartig, F.; Calabrese, J. M.; Reineking, B.; Wiegand, T. & Huth, A. Statistical inference for stochastic simulation models - theory and application Ecol. Lett., 2011, 14, 816-827 ### Rejection sampling -The simplest option is to sample a large number of parameters and accept -them according to their posterior value. This option can be emulated -with the implemented SMC by setting iterations to 1. +The simplest option is to sample a large number of parameters and accept them according to their posterior value. This option can be emulated with the implemented SMC by setting iterations to 1. ```{r, results = 'hide', eval = F} settings <- list(initialParticles = iter, iterations= 1) @@ -801,8 +606,7 @@ plot(out) ### Sequential Monte Carlo (SMC) -The more sophisticated option is to use the implemented SMC, which is -basically a particle filter that applies multiple filter steps. +The more sophisticated option is to use the implemented SMC, which is basically a particle filter that applies multiple filter steps. ```{r, results = 'hide', eval = F} settings <- list(initialParticles = iter, iterations= 10) @@ -810,42 +614,23 @@ out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "SMC", settings = settin plot(out) ``` -Note that using a number for `initialParticles` requires that the -`bayesianSetup` includes the option to sample from the prior. +Note that using a number for `initialParticles` requires that the `bayesianSetup` includes the option to sample from the prior. # Bayesian model comparison and averaging -There are a number of Bayesian methods for model selection and model -comparison. The BT implements three of the most common: DIC, WAIC, and -the Bayes factor. +There are a number of Bayesian methods for model selection and model comparison. The BT implements three of the most common: DIC, WAIC, and the Bayes factor. -- On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes - Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 +- On the Bayes factor, see Kass, R. E. & Raftery, A. E. Bayes Factors J. Am. Stat. Assoc., Amer Statist Assn, 1995, 90, 773-795 -- For an overview of DIC and WAIC, see Gelman, A.; Hwang, J. & - Vehtari, A. (2014) Understanding predictive information criteria for - Bayesian models. Statistics and Computing, 24, 997-1016-. On DIC, - see also the original reference by Spiegelhalter, D. J.; Best, N. - G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of - model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. +- For an overview of DIC and WAIC, see Gelman, A.; Hwang, J. & Vehtari, A. (2014) Understanding predictive information criteria for Bayesian models. Statistics and Computing, 24, 997-1016-. On DIC, see also the original reference by Spiegelhalter, D. J.; Best, N. G.; Carlin, B. P. & van der Linde, A. (2002) Bayesian measures of model complexity and fit. J. Roy. Stat. Soc. B, 64, 583-639. -The Bayes factor relies on the estimation of marginal likelihoods, which -is numerically challenging. The BT package currently implements three -methods +The Bayes factor relies on the estimation of marginal likelihoods, which is numerically challenging. The BT package currently implements three methods -- The recommended method is the "Chib" method (Chib and Jeliazkov, - 2001), which is based on MCMC samples but performs additional - calculation. Although this is the current recommendation, note that - there are some numerical issues with this algorithm that may limit - its reliability for larger dimensions. +- The recommended method is the "Chib" method (Chib and Jeliazkov, 2001), which is based on MCMC samples but performs additional calculation. Although this is the current recommendation, note that there are some numerical issues with this algorithm that may limit its reliability for larger dimensions. -- The harmonic mean approximation is implemented for comparison - purposes only. Note that this method is numerically unreliable and - should not normally be used. +- The harmonic mean approximation is implemented for comparison purposes only. Note that this method is numerically unreliable and should not normally be used. -- The third method is simply sampling from the prior. While in - principle unbiased, it converges only for a large number of samples - and is therefore numerically inefficient. +- The third method is simply sampling from the prior. While in principle unbiased, it converges only for a large number of samples and is therefore numerically inefficient. ## Example @@ -906,24 +691,19 @@ Bayes factor (need to invert the log) exp(M1$ln.ML - M2$ln.ML) ``` -BF \> 1 means that the evidence favors M1. See Kass, R. E. & Raftery, A. -E. (1995) Bayes Factors. J. Am. Stat. Assoc. Amer Statist Assn, 90, -773-795. +BF \> 1 means that the evidence favors M1. See Kass, R. E. & Raftery, A. E. (1995) Bayes Factors. J. Am. Stat. Assoc. Amer Statist Assn, 90, 773-795. -Assuming equal prior weights for all models, we can calculate the -posterior weight of M1 as +Assuming equal prior weights for all models, we can calculate the posterior weight of M1 as ```{r} exp(M1$ln.ML) / ( exp(M1$ln.ML) + exp(M2$ln.ML)) ``` -If the models have different model priors, then multiply by the prior -probability of each of the models. +If the models have different model priors, then multiply by the prior probability of each of the models. ### Comparing Models by DIC -The Deviance Information Criterion is a commonly used method to -summarize the fit of an MCMC chain. It can be calculated using +The Deviance Information Criterion is a commonly used method to summarize the fit of an MCMC chain. It can be calculated using ```{r} DIC(out1)$DIC @@ -932,12 +712,7 @@ DIC(out2)$DIC ### Model Comparison via WAIC -The Watanabe-Akaike Information Criterion is another criterion for model -comparison. To compute the WAIC, the model must implement a -log-likelihood density that allows the log-likelihood to be computed -pointwise (the likelihood functions require a "sum" argument that -determines whether the summed log-likelihood should be returned). It can -be obtained via +The Watanabe-Akaike Information Criterion is another criterion for model comparison. To compute the WAIC, the model must implement a log-likelihood density that allows the log-likelihood to be computed pointwise (the likelihood functions require a "sum" argument that determines whether the summed log-likelihood should be returned). It can be obtained via ```{r} # This will not work, since likelihood1 has no sum argument diff --git a/BayesianTools/vignettes/InterfacingAModel.Rmd b/BayesianTools/vignettes/InterfacingAModel.Rmd index 7d6244c..92f0fd4 100644 --- a/BayesianTools/vignettes/InterfacingAModel.Rmd +++ b/BayesianTools/vignettes/InterfacingAModel.Rmd @@ -21,7 +21,6 @@ knitr::opts_chunk$set(fig.width=5, fig.height=5, warning=FALSE, cache = F) set.seed(123) ``` - # Interfacing a model with BT - step-by-step guide ## Step 1: Create a runModel(par) function @@ -30,7 +29,7 @@ To enable calibration in BT, it's essential to run the model with a specified se What happens next depends on how your model is programmed. The following steps are arranged according to speed and convenience. If your model has not been interfaced with R before, you will most likely have to skip to the last option. - +```{=tex} \begin{enumerate} \item Model in R, or R interface existing \item Model can be compiled and linked as a dll @@ -39,7 +38,7 @@ What happens next depends on how your model is programmed. The following steps a \item Model can be compiled as executable reads parameters via parameter file \item Model parameters are hard-coded in the executable \end{enumerate} - +``` ### Case 1 - model programmed in R Typically, no action is required. Ensure that you are able to call your model.