The package adaptMCMC
In the packageadaptMCMCan implementation of the robust adaptive Metropolis sampler as proposed by Vihola (2012) is provided (see Scheidegger, 2012). The pack- age is hosted on CRAN and is purely written inR. A class/method scheme has not been utilized; the package is a collection ofRfunctions only.
The main function isMCMC(). The function for the log probability density has to be provided as argumentp. The chain length is set by the argumentnand initial values for the parameters of the density have to be provided by the argumentinit. Whether adaptive or the classic Metropolis sampling will be conducted is controlled by the logical argumentadapt: if set toTRUE, the user can define a desired ac- ceptance rate by means of the argument acc.rate. Achievement of the desired acceptance rate is accomplished by a self-adapting jump distribution for the parame- ters. By default, its variance-covariance matrix is initialized as an identity matrix, but differing initial elements for the main diagonal can be provided by the argu- mentscale. Furthermore, the user can control the adaption speed by the argument gamma. The range is𝛾∈ [0.5,1], whereby lower values lead to a faster adaption. A caveat of this MCMC implementation is that it is only available for distributions with at least two parameters.
k k Aside from the cornerstone functionMCMC(), within the package there are utility
functions for adding more samples to a chain (MCMC.add.samples()), populat- ing several independent chains in parallel (MCMC.parallel()), and converting the object returned byMCMC()to an object of either classmcmcormcmc.listwith the functionconvert.to.coda()such that the MCMC can be analyzed by the facilities provided in the packagecoda(see Plummer et al., 2006, and Section 14.4.2).
The package mcmc
In the packagemcmca random walk Metropolis algorithm has been implemented (see Geyer and Johnson, 2015). The package is hosted on CRAN and considered a core package in the “Bayesian” Task View. Within the package,S3classes and meth- ods are implemented. The computationally burdensome routines are interfaced from functions written in theClanguage. The package is accompanied by four vignettes and two data sets containing simulated data from a logistics regression model.
With respect to conducting MCMC, the package contains the generic function metrop(). The random walk Metropolis algorithm is implemented via the method metrop.metropolis(). The generic function is specified with eight arguments.
The first,obj, expects anRfunction that evaluates the logarithm of the unnormal- ized probability density. The function has to be specified such that its first argument is the state vector of the equilibrium distribution. Additional arguments—aside from the state vector—can be passed down to the Rfunction provided forobj via the ellipsis argument of metrop(). The MCMC is started from an initial state ac- cording to the real vector provided as a second argumentinitialtometrop().
The shape of the MCMC is defined by the argumentsnbatchfor the number of batches,blenfor the length of batches, andnspacfor the spacing of the itera- tions (thinning). The latter two arguments have default values of 1. The proposal step size for the state vector—that is, how fast the chain will progress through the state space—can be controlled by the argumentscalewith a default of 1. Smaller values lead in general to a higher acceptance rate and vice versa. It is further possi- ble to specify a vector and/or a matrix forscale, and the random draws from the standard normal distribution are multiplied by this object for calculating the newly proposed state. User-defined transformations of the MCMC are computed by provid- ing a function to the argumentoutfun. If this argument is left unspecified, then the mean values of the states are computed. Finally, the function closure of the generic is endowed with a logical switchdebugthat will return additional information if set toTRUE; its default value isFALSE. The MCMC calculations are conducted by in- terfacing theCroutinemetropin a call to.Call()within the function body of metrop.metropolis().
The function returns an S3 class list object with class attributes mcmc and metropolis. The two important elements of this list areacceptandbatch to store the acceptance rate and the result of the MCMC, respectively. This can be either an (nbatch×p) matrix, wherepequals the dimension of the state vector, or the result of the user-provided functionoutfun. The remaininglistelements are
k k pertinent to the call of the functionmetrop()and the initial and final random seeds
of the MCMC run.
The package MCMCpack
The package MCMCpack is primarily dedicated to Bayesian inference on poste- rior simulations of predefined statistical model classes (see Martin et al., 2011). The package is contained in the CRAN “Bayesian,” “Distributions,” “Multivariate,” “Psy- chometrics,” and “Survival” Task Views. It is considered a core package in the first of these. Akin tomcmc, the computationally intensive routines are interfaced from routines written in a higher programming language. In the case ofMCMCpack, the Scythe Statistical Library is employed and the routines are written inC++(see Pem- stein et al., 2011).
With respect to the concept of probabilistic utility, the function MCMC- metrop1R() can be used for exploring the density. Similar to the previously described methodmetrop.metropolis() contained inmcmc, withinMCMC- metrop1R()a random walk Metropolis algorithm has been implemented. TheR function of the unnormalized density has to be provided as argumentfun. Whether the returned value thereof should be treated as the logarithm of this density or not can be set by the logical argument logfun. Its default argument is TRUE and hence, by not specifying otherwise, the returned value of the function for argument funis treated as the logarithm of the density. The initial values for the state space have to be supplied as argumenttheta.init. The length of the chain and how many values should be treated as burn-in samples, that is, the count of state space samples that should be discarded, can be controlled by the argument mcmc and burnin, respectively. To ameliorate autoregressive dependencies between the sampled states, a thinning parameterthincan be set. Its default value is 1, so that no thinning will take place unless otherwise specified. Additional information about the chain’s progression is provided by assigning an integer value greater than zero to the argumentverbose; that is, for each multiple integer ofverbosethe values of the state space vector, the value of the density, and the Metropolis acceptance rate is printed on-screen. In addition, a random seed can be specified via the argument seed, and how progressively proposed steps of the state space are created is controlled by the argument V, which is a shorthand for the variance-covariance matrix for the Gaussian proposal distribution. Finally, the function’s closure of MCMCmetrop1R() includes arguments optim.method, optim.lower, optim.upper, andoptim.controlthat are passed tooptim()for an initial maximization stage. In case this optimization should fail, an MCMC can still be generated by setting the argument force.samp to TRUE; its default value is FALSE. The progression of the MCMC samples is computed by interfacing with the C++routineMCMCmetrop1R_ccof the Scythe Statistical Library in the function’s body. The functionMCMCmetrop1R()returns alistobject of informalS3class mcmc, such that it can be utilized by the methods provided in the packagecoda(see Plummer et al., 2006, and Section 14.4.2).
k k The package rstan
The rstanpackage is a user interface to theStanlibrary (see Stan Development Team, 2015). The latter is a programming language itself (see Stan: A C++Library for Probability and Sampling, Version 2.7.0 2015). This language is targeted at full Bayesian statistical inference via MCMC techniques. TheRpackagestanaccesses theC++header files ofStanwhich are contained in theRpackageStanHeaders (see Goodrich et al., 2016). Having said this, a caveat for theRuser is the need to provide a model formulation in theStanlanguage. However, theRuser is rewarded by employing a feature-rich language that is pretty powerful. The language is well documented in its user guide and reference manual (see Stan Modeling Language Users Guide and Reference Manual, Version 2.7.0 2015). TheRpackagerstanis hosted on CRAN and is shipped with a vignette by which the user is guided on how to interfaceStanfromR. The package employsS4classes and methods.
The cornerstone function ofrstanisstan(). The purpose of this function is to fit a model in theStanmodelling language, and it returns anS4object of classstan- fit. The definition of a Stanmodel can be provided by different means. First, the code for theStanmodel can reside in a separate file, passed tostan()by its argumentfile. Second, the model definition can also be passed to the function as a character string via the function’s argumentmodel_code. Afterstan()is in- voked, theStanmodel is compiled and executed. The returned object can also be reused for running an MCMC with a different MCMC specification by providing the stanfitobject as argumentfit. Data items that are used in theStanmodel have to be passed as a namedlistobject tostan()by itsdataargument. If one is interested in the results for a subset of the model’s parameters only, one can specify the names of these as a character vector and pass it to the function as argumentpars. For instance, if a location vector is namedmuand a dispersion matrixSigma, and if one is only interested on the MCMC result for the location vector, one could curtail the results by callingstan()withpars = "mu", for instance. The specification on how the MCMC is populated is controlled by the argumentsalgorithm,iter, warmup,chains,init,thin, andseed. The user can choose between two al- gorithms for searching the state space, namely the “No-U-Turn” sampler ("NUTS") and Hybrid Monte Carlo ("HMC"). The length of the chain is set by the argument iter, and how many state simulations of these should be discarded as burn-in pe- riod is controlled by the argumentwarmup. The latter takes as default value half of the chain length. Furthermore, the user can specify how many chains should be populated independently from each other by the argumentchains. The speed of running multiple MCMCs can be increased by utilizing the function’s in-built par- allelization facility through the argumentcores. Parameter initialization is defined by the argumentinit. Here, the user can set initial values to be either zero (init
= 0, orinit = "0"), or randomly drawn (init = "random"), or defined as a function that returns a namedlistobject, or, finally, alistobject of named lists.
For obtaining replicate results a random seed can be provided by the argumentseed.
Finally, for ameliorating the degree of autoregressive dependencies between consec- utive state samples, a thinning parameterthincan be provided. Its default value is
k k 1; that is, every sampled state will be returned and no thinning is accomplished. The
remaining arguments ofstan()are dedicated to fine-tuning the algorithm’s behav- ior, to the provision of detailed information about the MCMC progression, and/or whether to use the alternativeC++libraries Boost and Eigen. By default, the ones shipped within the packagesBHandRcppEigenwill be utilized, respectively (see Eddelbuettel et al., 2016, Bates and Eddelbuettel, 2013).
The functionstan()returns an object ofS4classstanfit. For this kind of object, methodsshow(),summary(),pairs(),plot(),traceplot(), and numerous extractor functions are available. For instance, the posterior means can be extracted by calling get_posterior_mean()and anmcmcobject for further analysis within the facilities provided by the packagecodacan be coerced from a stanfitobject by the routineas.mcmc.list().
Finally, worth mentioning is the function lookup()which serves as a dictio- nary for looking up the equivalent of Rfunctions in the context of theStanmod- elling language. This function comes in handy for novice users ofStanwho want to have a concise overview of how anRstatement can be expressed inStan. The function takes as argument a character string of anRfunction name and returns a data.frameif the second argumentReturnTypeis set to"ANY". Otherwise, the argument expects a validStandata type as character, for example,"matrix".