*! version 1.1.1 27sep2013

Title

st2openbugsana -- Analysis of OpenBUGS simulations processed
by st2openbugs

Syntax

st2openbugsana varlist, [st2openbugsana_options]

st2openbugsana_options

thin(#) Thinning of trace plots; default is thin(1)

grbplot Gelman-Rubin-Brooks (GRB) plots

nbins(#) Number of bins for GRB plot; default is nbins(10)

savegraphs Save graphs

wdpath(path) Path of the directory where graphs are saved and
log file is located

prefix(literal) Prefix added to the name of dta and log files
used and to the name of graphs to be saved.

varlist is a list of variables created by the st2openbugs command.

Description

st2openbugsana computes numerical summaries and draws plots from the CODA
output produced by the MCMC simulation performed by OpenBUGS and processed by
the st2openbugs
command.

Options

thin(#) performs thinning of trace plots, i.e. for each chain the plot
is drawn using only every #th value of the simulated sequence starting with the
first. The default is thin(1), which amounts to usign all the simulated
sequence.

grbplot displays Gelman-Rubin-Brooks (GRB) plots. For details on this plot,
useful for diagnosing convergence, see Brooks and Gelman (1998).

nbins(#) sets the number of bins taken for computing the GRB plot, when
the grbplot option has been used. The number of iterations by chain
(discarding 'burn-in') must be a multiple of its value. The default is 10.

savegraphs saves all the graphs plotted.

wdpath(path) specifies the path of the directory where the graphs will be
saved (if the option savegraphs has been used) and the log file is
located. Note that (unlike st2openbugs) the tilde (~) can be used to
refer to the user's home directory.

prefix(literal) specifies the common prefix added to the name of the
'CODA.dta' and 'log.log' files used (the last one is needed for computing DIC),
and to the name of the graphs saved if the option savegraphs is used; by
default names have no prefix.

Remarks

For each node of the varlist, the following summary measures are
computed from the simulations, and collected in a table: posterior mean and
standard deviation, Monte Carlo standard error of the mean, 2.5th, 50th (median)
and 97.5th posterior quantiles, and, if more than one chain has been simulated,
the corrected scale reduction factor (CSRF). For details on CSRF see Brooks and Gelman (1998)
and Gelman and Rubin (1992).
Also included in the ouput is a table with measures which are useful in model
comparison (see, for example, Carlin and Louis (2009):
the posterior mean deviance (Dbar), the effective number of parameters (pD) and
the Deviance Information Criterion (DIC). Actually, the three are read from the
log file created by OpenBUGS when is called by the related command st2openbugs
(see st2openbugs).

Some plots useful in diagnosing convergence are displayed (and optionally saved):
trace and density plots for each node, and, as an option, Gelman-Rubin-Brooks
plots. A warning must be given that, when a moderate to large number of nodes
is monitored, the screen may rapidly become cluttered with plots. The
functionality of the graph combine command should be enough to permit
the user to tailor them to his/her needs.

Examples

Suppose that the third example of the help for the
st2openbugs command has been run. The result is that a) the 'RatsCODA.dta'
file is saved in the disk and loaded in the memory; and b) the 'Ratslog.log'
file is saved (both files located in the default directory set by OpenBUGS).

Summary tables, and trace and density plots for the first three nodes of 'alpha'
and for 'sigma':

. st2openbugsana alpha_1-alpha_3 sigma, p(Rats)

A GRB plot for 'sigma', taking 20 bins; this and the default trace-density plot
are saved:

. st2openbugsana sigma, g n(20) s p(Rats)

Like the previous example, but the trace plot is 'thinned' by considering only
the first of every 50 values of each chain:

. st2openbugsana sigma, t(50) g n(20) s p(Rats)

If the fourth example of the help for
st2openbugs has been run previously, the wdpath(path) option must
be used to give the path to the needed files. Also note that a) the
gbrplot option cannot be used, because only one chain was simulated, b)
the plots will be saved in the directory given by the path, and c) since the
prefix 'Rats' was not added in that example, now it is not needed:

. st2openbugsana sigma, t(50) s w(~/bugs)

Stored results

st2openbugsana stores the following in r():

Scalars

r(nchain) number of chains

r(nburnin) number of 'burn-in' iterations

r(niteration) number of iterations by chain (discarding 'burn-in')

Macros
r(varlist) nodes monitored

Matrices
r(summarymat) matrix of summary measures by node, with columns:

mean, mean

sd, standard deviation

MC_error, Monte Carlo standard error of the mean

2dot5%, 2.5%th percentile

median, 50%th percentile or median

97dot5%, 97.5%th percentile

CSRF, (omitted if there is 1 chain) corrected scale reduction factor (CSRF)

r(DIC) matrix of deviance-related measures (omitted when Openbugs
cannot calculate DIC), with columns:

Dbar, mean deviance

DIC, deviance information criterion (DIC)

pD, effective number of parameters

r(GRBmatplot) matrix (omitted when the grbplot option is not
used) with the information needed for drawing GRB plots; its columns are:

node, number coding the node by its position in r(varlist)

nstart, starting iteration for each bin

CSRF, CSRF estimate

Author

Ignacio López de Ullibarri

Department of Mathematics

University of A Coruña, Spain

E-mail: ilu@udc.es

References

Brooks SP and Gelman A (1998). General methods for monitoring convergence of
iterative simulations, Journal of Computational and Graphical Statistics, 7: 434-455

Carlin BP and Louis TA (2009). Bayesian Methods for Data Analysis. 3rd
Edition. Boca Raton: Chapman & Hall/CRC

Gelman A and Rubin DB (1992). Inference from iterative simulation using multiple
sequences Statistical Science, 7:457-472