The package bmk
The packagebmkcontains functions for diagnosing the convergence properties of Markov chains (see Krachey and Boone, 2012). The package is hosted on CRAN and is written purely in theRlanguage. It does not exploit any class/method scheme and hence can be considered as a collection of Rfunctions. It has dependencies on the packages coda,plyr, andfunctional(see Plummer et al., 2006, Wickham, 2011, Danenberg, 2014, respectively). The former package will be discussed in the next subsection. Furthermore, bmk is endowed with five data sets for elucidating the application of the diagnostic functions. The functionsbmkconverge(),bmk- sensitive(), andbmksummary()are exported via directives in the package’s NAMESPACEand will be described next.
The convergence of a Markov chain can be assessed by the function bmkcon- verge(), which exploits the concept of the Hellinger distance between two dis- tributions (see Boone et al., 2014, Hellinger, 1909). For two discrete probability distributionsP= (p1,ã ã ã,pN)andQ= (q1,ã ã ã,qN), the Hellinger distanceH(P,Q) is defined as
H(P,Q) = 1
√2
√√
√√∑N
i=1
(√ pi−√
qi)2. (14.14)
The measure takes values in the interval[0,1]and the maximum distance is achieved if one distribution assigns zero probability to every set to which the other distribution assigns a positive probability. Hence, for evaluating the convergence in the context of Markov chains, a user should be interested in distance measures close to zero.
k k The function’s arguments areinputlist1andbinsize. The MCMC samples
are passed to the former argument and the latter determines by how many samples (length of the bins) the chain should be split. The distances are then computed for consecutive bins and hence the length of the chain should equal an integer multiple of the bin size. In the function’s body the Hellinger distance is computed within the non-exported function HWconverg1(), which can, however, be accessed by ex- ploiting the triple colon operator, that is, bmk:::HWconverg1(). The distance measure itself is defined in the functionHDistNoSize(), which is also not ex- ported, but can be considered as the workhorse function inbmk.
The sensitivity of two Markov chains with respect to the specification of the as- sumed parameters’ prior distributions and/or the hyper-parameters of the statistical model in question can be assessed by computing the Hellinger distance between the two by the functionbmksensitive(). This function has two arguments, namely inputlist1andinputlist2for the two Markov chains with differing input settings.
Finally, the functionbmksummary()returns descriptive statistics of the param- eters’ distributions, the Hellinger distance measures between two consecutive state samples, and Gelman and Rubin’s convergence diagnostic (see Gelman and Rubin, 1992). The latter will be described in the next subsection, asbmkexploits the im- plementation incoda. The functionbmksummary()takes one argument, namely inputlist, for providing the MCMC.
The package coda
The packagecodais the most encompassing package on CRAN with respect to the assessment of MCMC (see Plummer et al., 2006). It is listed in the CRAN Task Views
“Bayesian” and “gR,” and considered a core package in the former. The package is written solely in theRlanguage and utilizes theS3class/methods framework. The package has no dependencies to other contributed packages, but imports thelattice package (see Sarkar, 2008) for certain graphical displays of MCMC. The functions and methods provided bycodacan be grouped loosely into the categories plotting and diagnostic testing. In the following, key functions of each category will be presented.
Before we proceed, it is worth mentioning that objects of informal classmcmccan be created by callingmcmc(). This function is endowed with the argumentsdata for thevector/matrixobject of an MCMC output,startandendfor defining the iteration number of the first and last state samples, andthinfor the thinning interval between the state space samples of the chain. Some of the availableRpack- ages and the ones presented in this subsection provide the option for coercing the MCMC output to an object of this class, and hence there is no need to callmcmc() explicitly. As an aside,codaoffers a coercion methodas.mcmc(), such thatvec- tor/matrixobjects can be converted tomcmc-class objects. Whether an object belongs to this class can be checked by callingis.mcmc(). Similarly, for parallel runs of MCMC theS3classmcmc.listis made available and objects thereof can be created by callingmcmc.list(). This creator function has the ellipsis as sole ar- gument and expects objects of informal classmcmc. Objects can be coerced to and/or
k k checked for this class by the methodsas.mcmc.list()andis.mcmc.list(),
respectively.
For the graphical display of Markov chain(s) the methods/functions au- tocorr.plot(), crosscorr.plot(), cumplot(), densplot(), gelman.plot(), geweke.plot(), plot.mcmc(), traceplot(), and trellisplot()are available (in alphabetical order). The first resort for summa- rizing MCMC output graphically is to call theplot()method formcmcobjects.
This method will produce for each parameter a trace plot of the chain’s progression and a density plot, by default. Either set of plots can be suppressed by setting the argumentstrace = FALSEordensity = FALSE, respectively. The trace and density plots are created within theplot()method by calling thetraceplot() densplot()functions. The mixing properties of a Markov chain can be inspected by the auto- and cross-correlation of/between the parameters. These can be computed with the functions autocoor()andcrosscorr(), respectively. The plots of these ACF and CCF can be produced with the corresponding plot() methods, that is, autocorr.plot() andcrosscorr.plot(). All of these functions take as first argumentxan object of classmcmc. As the complexity of the graphical output increases with the count of parameters, space-conserving trellis-plots are made available via the S3 methods acfplot() for mcmc and mcmc.list objects. In addition to the functions and methods that graphically depict the mixing properties of a Markov chain, the effective sample size—that is, the one implied by the autocorrelation adjustment—is returned by the functioneffectiveSize().
Its sole argument x expects an mcmc object. The progression for a recursive computation of the test statistics for Gelman and Rubin’s convergence test and/or the approach chosen by Geweke is displayed by the functions gelman.plot() andgeweke.plot, respectively. These two forms of assessing the convergence of an MCMC chain will be discussed in the next paragraph.
Diagnostic checking of the chain’s stationarity condition and/or mixing behav- ior can be conducted with the functions gelman.diag(), geweke.diag(), heidel.diag(),HPDinterval(), and raftery.diag()(in alphabetical order).
Gelman and Rubin’s convergence diagnostic (see Gelman and Rubin, 1992) is im- plemented as functiongelman.diag(). This convergence test can only be applied to parallel runs of MCMC and hence the first function argumentxmust be ofS3class mcmc.list. Furthermore, the test is applicable to normally distributed targets and is similar to a classical analysis of variance (ANOVA) for single parameters. That is, the variances of a parameter per MCMC output is compared to the overall dis- persion for all Markov chains. Under the assumption of a normal target distribution, the resultant test statistic is Student’stdistributed, where the degrees of freedom are estimated by the method of moments. Values of the test statistic greater than one indi- cate a lack of convergence. A multivariate extension of this convergence measure has been introduced into the literature by Brooks and Gelamn (1998), and its computation is conducted by default, but can be suppressed if the argumentmultivariateis set toFALSE. The function returns an object ofS3classgelman.diagwhich is endowed with aprint()method.
k k The next diagnostic test to be presented is Geweke’s convergence diagnostic (see
Geweke, 1992). This test is made available as functiongeweke.diag(). The test compares the means of a parameter computed from data points at the beginning and at the end of a chain. Convergence to the stationary distribution is given, if these two estimates statistically coincide. By default, the first batch of values for computing the location is set to 10% of the chain length, but can be changed by the argument frac1. The count of state samples at the end of the chain is set to 50% of the Markov chain length by default and can be changed by providing a different fraction for the argumentfrac2. The test statistic itself is a Z-score for a test of equality of means between the first and last part of the Markov chain. This test is conducted for each parameter in the chain.
The convergence diagnostic proposed by Heidelberger and Welch is based on the Cramér–von Mises statistic to test the null hypothesis that the sampled state values are stemming from a stationary distribution (see Heidelberger and Welch, 1983). The test procedure is to compute the test statistic on the state samples for each parameter for the complete chain length and then subsequently reducing the chain length by 10%. If the null hypothesis has to be rejected after the half-life of the chain, non-convergence to the stationary distribution is implied. In this case, the authors suggest increasing the chain length by a factor of 1.5. This testing procedure is implemented as function heidel.diag(), which takes as first argumentxan object ofS3classmcmc. The significance level is set by the argumentpvalueto a default value of 0.05. The target value for the ratio between the half width and the sample mean is determined by the argumentepsand takes a default value of 0.1.
The highest posterior density (HPD) interval for each parameter is returned by the functionHPDinterval(). The function takes as input argumentobj an object of eitherS3classmcmcor mcmc.list. The nominal width of the interval is set by the argumentprob, with a default value of 0.95. The HPD is based on the em- pirical cumulative distribution function and returns the lower and upper ends of the quantiles, such that the probability mass between these two points coincides with the nominal probability and the width of the interval is the narrowest, that is, the most concentrated.
The last diagnostic test to be presented is the one introduced into the literature by Raftery and Lewis (1992), Raftery and Lewis (1995). The purpose of this test is twofold. First, the test gives hindsight as to whether a Markov chain has converged to the stationary distribution. Second, the test provides bounds for the accuracy of the estimated quantiles for the functions of the parameters. This diagnostic test is implemented as functionraftery.diag(). The function’s closure takes five ar- guments, namelydatafor themcmcobject, qfor the quantile of the distribution for a parameter with a default value of 0.025, r for the desired margin of error around the quantile,sfor the confidence level of obtaining an estimate in the interval (q±r), with a default probability of 0.95, andconverge.epsfor setting the re- quired precision, with a default of 0.001. Assuming independence between the state space samples, a minimum number of runs can be established for a given quantile with lower and upper bounds for a given confidence level (that is, from the input val- ues of the argumentsq,r, ands). If the supplied MCMC output falls short of this
k k minimum length, the testing cannot be accomplished and an indicative error mes-
sage is returned indicating how long the chain must be. In general, the length of the Markov chain must be greater than this minimum length due to the positive auto- correlations between the sampled states. A dependence factor,I, that takes the size of autocorrelation into account indicates by how much the length of the chain must be changed to meet the desired accuracy. Incidentally, for negatively autocorrelated states the dependence factor will be less than one and hence the required length of a chain is less than the minimum required length as deduced from independence. The authors suggest that values ofI>=5 should be considered as an indication of strong autocorrelation that might have been caused by either the starting values of the chain, or high correlations between the posterior distributions, or a too-narrow search in the state space. In any case, a rerun of the MCMC is required. The function returns an object ofS3classraftery.diagwhich is endowed with aprint()method.
Finally, it is worth mentioning the functioncodamenu(), which provides a sim- ple user interface for choosing between the implemented plotting and diagnostic facilities contained in the package.