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
install.packages("BayesianTools")Or follow the instructions on https://github.com/florianhartig/BayesianTools to install a development or an older version.
Loading and citation
library(BayesianTools)
citation("BayesianTools")##
## To cite package 'BayesianTools' in publications use:
##
## Hartig F, Minunno F, Paul S (2023). _BayesianTools: General-Purpose
## MCMC and SMC Samplers and Tools for Bayesian Statistics_. R package
## version 0.1.8, <https://github.com/florianhartig/BayesianTools>.
##
## A BibTeX entry for LaTeX users is
##
## @Manual{,
## title = {BayesianTools: General-Purpose MCMC and SMC Samplers and Tools for Bayesian Statistics},
## author = {Florian Hartig and Francesco Minunno and Stefan { Paul}},
## year = {2023},
## note = {R package version 0.1.8},
## url = {https://github.com/florianhartig/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)
set.seed(123)In a real application, to ensure reproducibility, it would also be useful to record the session info,
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.
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
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
print(out)## [1] "mcmcSampler - you can use the following methods to summarize, plot or reduce this class:"
## [1] getSample plot print summary
## see '?methods' for accessing help and source codesummary(out)## # # # # # # # # # # # # # # # # # # # # # # # # #
## ## MCMC chain summary ##
## # # # # # # # # # # # # # # # # # # # # # # # # #
##
## # MCMC sampler: Metropolis
## # Nr. Chains: 1
## # Iterations per chain: 10000
## # Rejection rate: 0.684
## # Effective sample size: 1005
## # Runtime: 2.883 sec.
##
## # Parameters
## MAP 2.5% median 97.5%
## par 1 0 -1.991 0.016 2.034
## par 2 0 -1.931 -0.077 1.802
## par 3 0 -1.970 -0.007 1.850
##
## ## DIC: 11.153
## ## Convergence
## Gelman Rubin multivariate psrf: Only one chain; convergence cannot be determined!
##
## ## Correlations
## par 1 par 2 par 3
## par 1 1.000 -0.019 -0.029
## par 2 -0.019 1.000 0.011
## par 3 -0.029 0.011 1.000and 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”).
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”).
marginalLikelihood(out)## $ln.ML
## [1] -9.07554
##
## $ln.lik.star
## [1] -2.756816
##
## $ln.pi.star
## [1] -8.987197
##
## $ln.pi.hat
## [1] -2.668472
##
## $method
## [1] "Chib"DIC(out)## $DIC
## [1] 11.15333
##
## $IC
## [1] 13.96971
##
## $pD
## [1] 2.816389
##
## $pV
## [1] 2.8407
##
## $Dbar
## [1] 8.336937
##
## $Dhat
## [1] 5.520548MAP(out)## $parametersMAP
## par 1 par 2 par 3
## 4.650153e-04 -1.707961e-04 -6.534865e-05
##
## $valuesMAP
## Lposterior Llikelihood Lprior
## -11.744013 -2.756816 -8.987197You can extract (a part of) the sampled parameter values by
getSample(out, start = 100, end = NULL, thin = 5, whichParameters = 1:2)For all samplers, you can conveniently perform multiple runs via the nrChains argument
iter = 1000
settings = list(iterations = iter, nrChains = 3, message = FALSE)
out <- runMCMC(bayesianSetup = bayesianSetup, sampler = "Metropolis", settings = settings)## Parameter(s) currentChain not used in Metropolis
##
## Parameter(s) currentChain not used in Metropolis
##
## Parameter(s) currentChain not used in MetropolisThe result is an object of mcmcSamplerList, which should allow to do everything one can do with an mcmcSampler object (with slightly different output sometimes).
print(out)## [1] "mcmcSamplerList - you can use the following methods to summarize, plot or reduce this class:"
## [1] getSample plot print summary
## see '?methods' for accessing help and source codesummary(out)## # # # # # # # # # # # # # # # # # # # # # # # # #
## ## MCMC chain summary ##
## # # # # # # # # # # # # # # # # # # # # # # # # #
##
## # MCMC sampler: Metropolis
## # Nr. Chains: 3
## # Iterations per chain: 1000
## # Rejection rate: 0.688
## # Effective sample size: 308
## # Runtime: 1.034 sec.
##
## # Parameters
## psf MAP 2.5% median 97.5%
## par 1 1.011 0 -2.172 0.005 1.876
## par 2 1.023 0 -1.853 0.103 1.936
## par 3 1.013 0 -1.795 0.027 2.180
##
## ## DIC: 11.187
## ## Convergence
## Gelman Rubin multivariate psrf: 1.024
##
## ## Correlations
## par 1 par 2 par 3
## par 1 1.000 0.006 0.085
## par 2 0.006 1.000 -0.030
## par 3 0.085 -0.030 1.000For example, in the plot you now see 3 chains.
plot(out)
There are a few additional functions that may only be available for lists, for example convergence checks
#getSample(out, coda = F)
gelmanDiagnostics(out, plot = T)
## Potential scale reduction factors:
##
## Point est. Upper C.I.
## par 1 1.01 1.01
## par 2 1.02 1.07
## par 3 1.01 1.04
##
## Multivariate psrf
##
## 1.02Which 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.
