wb: Commands for Running Stata from WinBUGSStata and for examining the resulting MCMC simulations. The plots used to illustrate the commands described in this document are taken from

wb: Commands for Running Statafrom WinBUGS

John ThompsonDepartment of Health Sciences

Univeristy of [email protected]

June 21, 2006

1 Introduction

wb is a collection of Stata commands for running WinBUGS1.4.1 from within

Stata and for examining the resulting MCMC simulations.

The plots used to illustrate the commands described in this document

are taken from the analysis of the Oxford case-control study, one of the

WinBUGS examples. The full analysis of that example based on the wb

commands is available as a pdf from

www.hs.le.ac/research/HCG/winbugsfromstata

and the same website also includes a general introduction to running WinBUGS

from within Stata .

1

Table 1: List of commands

command descriptionWriting data to WinBUGSwbarray write data as a WinBUGS arraywbdata write a mixed list of datawbscalar write a list of scalarswbstructure write a list containing a two-way structurewbvector write a list of vectorsRunning WinBUGSwbrun run WinBUGS from within Stata

wbscript write a WinBUGS script fileReading WinBUGS resultswbcoda read results from WinBUGS into Stata

Assessing convergence & mixingwbac autocorrelation plotswbbgr Brooks-Gelman-Rubin convergence plotwbgeweke convergence test based on meanswbintervals interval estimates for sections of a chainwbsection convergence check based on density estimateswbtrace trace plot of MCMC simulationsSummarizing MCMC simulationswbstats summary statistics from MCMC simulationswbdensity posterior density estimateswbhull bivariate posterior contour plotsReading list data into Statawbdecode read lists directly into Stata

2

Titlewbac - plot the autocorrelations of a WinBUGS chain

Syntax

wbac varlist [if] [in] [ , options ]

options descriptionpac partial autocorrelation plotsacoptions(string) options passed directly to ac or pacgoptions(string) graphics options for the individual plotscgoptions(string) options combining plotssaving(string,replace) graphics file (.gph) for the final plotexport(string,replace) graphics file with non-standard formatsdsaving(string,replace) .dta file for the autocorrelations

Description

calculates and plots the autocorrelations (correlogram) or partial autocorre-

lations of an MCMC simulation

Options

pac plot partial autocorrelations rather than the default of autocorrelations.

acoptions(string) wbac is a wrapper for the Stata commands ac and pac.

The string given to acoptions is passed directly to these Stata commands.

See help for ac and pac for possible options.

goptions(string) passes its string as graphics options when the autocorre-

lations are plotted

cgoptions(string) passes its string directly to graph combine whenever

varlist contains more than one parameter in which case the autocorrelation

plots are combined into a single graph.

3

saving(string,replace) specifies a filename for saving the final graph in

.gph format.

export(string,replace) specifies a filename for exporting the final graph

in a non-Stata format such as eps or png. The format depends on the ex-

tension given to the filename

dsaving(string,replace) specifies a filename (.dta) for saving the auto-

correlations or partial autocorrelations as plotted on the graphs.

Remarks

The autocorrelations of a parameter from an MCMC run give an indica-

tion of the speed of mixing of the chain for that parameter. The slower the

mixing, the higher the autocorrelations and the longer the chain will need

to be before it converges. The plots can be used to identify slowly mixing

parameters and may suggest when a model needs re-parameterising in order

to speed its convergence.

For Markov chain methods proposals are dependent on the previous value

of the chain and the higher-order autocorrelations are merely a result of this

first-order correlation. This effect can be seen by plotting the partial auto-

correlations.

wbac is merely a wrapper for calling the Stata commands ac and pac.

The following examples illustrate the use of wbac

. wbac alpha, ac(lag(20))

. wbac alpha, g(ylabel(,angle(0)))

. wbac alpha beta, cg(rows(2))

. wbac alpha beta, sav(ac.gph,replace)

. wbac alpha beta, ex(ac.eps,replace)

4

Figure 1: : Example produced by . wbac alpha beta1 beta2 sigma

. wbac alpha beta, dsav(ac.dta,replace)

Saved Results

The full set of saved autocorrelations for all of the plots can be saved as a

Stata dataset using the dsaving option.

Also See

[TS] corrgram [G] graph intro [G] graph combine

5

Titlewbarray - write a rectangular dataset as a WinBUGS array

Syntax

wbarray varlist [if] [in] [ , options ]

1.1 Options

option descriptionformats(string) formats for the datasaving(string,replace) text file (.txt) for the datanoprint do not print the data to the results window

Description

writes data with rectangular structure as a WinBUGS array. The data can be

written to the screen or to a text file from where it can be read directly into

WinBUGS .

Options

formats(string) gives the formats used for writing the data. The default

is %8.3f. Formats cycle so that f(%4.0f %3.1f) would write the data using

%4.0f %3.1f %4.0f . . .

saving(string,replace) name of the text file to which the array is written.

If not specified the array is only written to the results window.

noprint suppresses the display of the array in the results window

6

Remarks

Although lists are a very flexible way of writing data that is to be read

by WinBUGS , arrays are a convenient alternative when all of the variables

have the same length. As WinBUGS can read more than one data file, it is

possible to write some of the data as an array and the rest as a list and to

put these into different text files.

wbarray automatically replaces missing values with NA as required by

WinBUGS .

Example: assuming that Stata has variables called x1, x2 and x3

. wbarray x1 x2 x3, format(%4.0f %6.1f %8.4f)

would produce

x1[] x2[] x3[]34 16.4 3.45089 NA 1.2004

17 2.9 1.9308. . . . . . . . .

END

Also See

Commands for writing lists: wbscalar wbvector wbstructure and wbdata

7

Titlewbbgr - Brooks-Gelman-Rubin plot

Syntax

wbbgr varname [if] [in] , id(varname) [ options ]

options descriptionid(varname) chain identifiertime(varname) order of the simulationsbin(#) plotting bin sizevariance plot based on variance rather than 80% intervalsbychain plot chain specific variances or intervalsgoptions(string) graphics options for the individual plotscgoptions(string) options combining plotssaving(string,replace) graphics file (.gph) for the final plotexport(string,replace) graphics file with non-standard formatsdsaving(string,replace) .dta file for the autocorrelations

Description

Creates a Brooks-Gelman-Rubin plot for assessing convergence from multiple

parallel chains

Options

id(varname) variable taking the values 1,2,3. . . to identify the chains

time(varname) variable giving the order of the values within each chain

bin(#) step size controlling the number of plotting points. The default cre-

ates a plot from 20 evenly spaced points by setting bin to be the length of

the chain divided by 20.

variance requests a plot based on within and between chain variances rather

than the default plot based on non-parametric 80% intervals

8

bychain show each individual chain in the lower plot, rather than the aver-

age across the chains.

goptions(string) passes its string as graphics options when the plots are

created.

cgoptions(string) passes its string directly to graph combine for combin-

ing the upper and lower plots.


.gph format.



tension to the given filename

dsaving(string,replace) specifies a filename (.dta) for saving the plotting

points.

Remarks

wbbgr creates a Brooks-Gelman-Rubin plot for assessing the convergence

of parallel chains. The plot assumes that the chains start from different and

over-dispersed initial values. As the chains come closer into agreement the

variability of the pooled chains should be similar to the average variability

of the individual chains.

The original suggestion was for a plot based on two estimates of the vari-

ance of the posterior, one pooling all of the chains and the other averaging

the within chain variance. The ratio of the two variances was called R. wbbgr

incorporates the degrees of freedom correction suggested by Brooks and Gel-

9

man(1998) even though it appears to make little difference in practice; the

number of degrees of freedom is usually large and it is poorly estimated

unless there are many chains. Anyway, doubt was expressed about the in-

terpretation of this measure when the posterior is non-normal and a robust

alternative was suggested based on the 80% interval between the 10% and

90% centiles, in that case,

R =interval from all of the simulations

average of the intervals of the separate chains(1)

Either way R is calculated for increasing chain sizes. For a subchain consist-

ing of the first N values, R is calculated from the second half of the subchain

and then plotted against N. N is taken to be 1,2... times ’bin’.

In both plots R should approach 1 if the chains have converged. A second

plot shows the variance or interval based on all chains pooled (solid line) and

on the average of the subchains (dashed line). These should stabilise into

horizontal lines once the chains have converged.

Saved Results

The plotting points can be saved as a Stata dataset using the dsaving op-

tion.

References

Gelman A & Rubin DB,

Inference from iterative simulation using mutliple sequences

Statistical Science,1992:7;457-511.

Brooks S & Gelman A,

General methods for monitoring convergence of iterative simulations

Journal of Computational and Graphical Statistics,1998:7;434-455.

10

Figure 2: : Example produced by . wbbgr sigma , id(chain)

Figure 3: : Example produced by . wbbgr sigma , id(chain) variance

11

Also See

[G] graph intro [G] graph combine

12

Titlewbcoda - read data from Coda formatted files

Syntax

wbcoda , root(string) clear [ options ]

options descriptionroot(string) root name (with path) of the file(s)clear permission to clear existing dataid(varname) name for the chain identifierchains(#) chain number or number of chainsmultichain read multiple chainsthin(#) only read every nth valuekeep(string) parameters to keepnoreshape leave all parmeters in a single variable

Description

Reads Coda formatted data saved from a WinBUGS analysis directly into

Stata

Options

root(string) specifies the root used by WinBUGS when creating the index

file and the file(s) of simulated values.

clear permission to clear any existing data from Stata .

id(varname) name for the variable that is created to denote the separate

chains when there are multiple parallel chains.

chains(#) number of the chain that is to be read when the user wants to

read one chain from several that has been created. Alternatively, if the mul-

tichain option is set, then ’chain’ gives the total number of chains.

13

multichain requests that multiple chains are read and stacked within Stata

thin(#) read every nth value.

keep(string) parameters to keep. The string is expanded in the same way

as a newvarlist.

noreshape leave the simulated values stacked in a single variable instead of

reshaping them into separable variables for each parameter.

Remarks

wbcoda reads data from coda-style text files, as created by WinBUGS ,

directly into Stata .

The MCMC simulations produced by WinBUGS are output in the format

required by the convergence checking program Coda. An index file is created

listing the parameter names and data files are created, one for each chain,

containing the simulated values. wbcoda can read single or multiple chains.

Any existing data in Stata will be lost so you must specify the clear option.

WinBUGS programmers often use a full stop as part of a parameter name

as in y.sigma. Variable names in Stata cannot contain full stops and so the

name is changed to y sigma when the data are read into Stata . When

vectors of parameters are saved by WinBUGS the names are also editted;

thus alpha[2] would become alpha 2 in Stata. In theory this would result

in WinBUGS parameters alpha.2 and alpha[2] being given the same name in

Stata , which would cause wbcoda to fail. We decided that avoiding this

problem would result in rather ugly or unpredictable variable names and

so recommend avoiding such clashes, which will be rare, when choosing the

WinBUGS parameter names.

14

For large problems with many (10,000s) simulations and lots (100s) of

parameters it can take a long time to reshape the simulations so that each

parameter’s simulations are in a different variable. If you do not need all of

the simulations then you can use the thin and keep options to reduce the

number of values prior to reshaping. This can speed up the command appre-

ciably. The noreshape option leave the simulated values stacked in a single

variable, which is also quicker.

15

Titlewbdata - write a mixed list of data

Syntax

wbdata , contents(string) [ options ]

options descriptioncontents calls to wbscalar, wbvector & wbstructuresaving(string,replace) text file (.txt) for the datanoprint do not print the data to the results window

Description

writes a list of mixed data structures by combining calls to wbscalar, wbvector

& wbstructure

Options

contents(string) data to be placed in the list structure specified by calls

to wbscalar, wbvector and/or wbstructure. The calls must be joined by

+ signs.

saving(string,replace) specifies a text filename for saving list of data.

noprint suppresses diaplay of the list in the results window.

Remarks

wbdata writes data to the results window and/or a text file as an R style

mixed list of data types ready to be read into WinBUGS. The contents of the

list are specified by combining calls to wbscalar, wbvector and wbstructure

separating them by +’s in the string supplied to the contents option.

16

With appropriate data in Stata , the command

. wbdata , c(wbscalar a,b + wbvector x y, f(%3.0f))

would produce

list( a= 1.000, b=4.500, x=c( 4, 2, -1, NA) y=c( 3, 6, 12, 4) )

Also See

wbscalar wbvector wbstructure

17

Titlewbdecode - read lists of data directly into Stata

Syntax

wbdecode , filename(string) clear

options descriptionfilename(string) text file containing the list structureclear permission to clear the current dataarray read an array rather than a list

Description

wbdecode reads data from a text file in which the data are stored in Win-

BUGS format, that is, as a list structure or an array.

Options

filename(string) name of the file containing the list or array that is to be

read.

clear permission to clear current data from Stata .

array read a WinBUGS array rather than the default which is to read a list.

Remarks

wbdecode reads data from a text file containing a WinBUGS formatted list

or array. If the data are part of a compound document they must be copied

to a text file before using wbdecode.

wbdecode is especially useful for reading the data from the examples

supplied with WinBUGS so enabling the examples can be analysed in Stata.

18

However it would also read data from R or S-plus structures.

Any existing data in Stata will be lost so you must specify the clear option.

If mylist.txt contains a WinBUGS style list structure , then in can be read into

Stata using

. wbdecode , file(mylist.txt) clear

Users need to be aware that wbdecode reads list structures by searching

for the next ’=’ and then locating the variable name that preceeds it and the

structure type that follows. Spreading this information over more that one

line would cause wbdecode to misread the data. So

y = c(

1 ,2 ,3 )

is OK. But

y

= c(1, 2, 3)

would fail

19

Titlewbdensity - posterior density estimates

Syntax

wbdensity varlist [if][in] [ , options ]

options descriptionlow(string) lower bounds for parameter rangeshigh(string) upper bounds for parameter rangeskoptions(string) options passed to kdensitygoptions(string) graphics options for the individual plotscgoptions(string) options combining plotssaving(string,replace) graphics file (.gph) for the final plotexport(string,replace) graphics file with non-standard formatsdsaving(string,replace) .dta file for the autocorrelations

Description

plots smooth density estimates of posterior distributions based on MCMC

simulations

Options

low(string) a lower bound for the range of each parameter or a missing

value if the parameter is unbounded, for instance with three parameters in

varlist we might specify low(. . 0) in order to bound the third parameter. If

the option is omitted then no lower bounds are set.

high(string) an upper bound for the range of each parameter or a missing

value if the parameter is unbounded. If the option is omitted then no upper

bounds are set.

koptions(string) passes its string as options for the Stata command,

textttkdensity that is used to create the density estimates.

20

goptions(string) passes its string as graphics options when the density

estimates are plotted.


varlist contains more than one parameter.


.gph format.




dsaving(string,replace) specifies a filename (.dta) for saving the points

used when plotting the graph.

Remarks

wbdensity plots a smooth density estimate of the posterior distribution of

a parameter using MCMC simulations. This command is a wrapper that calls

the Stata command kdensity. However it will additionally allow bounds

to be set. Thus, as the posterior of a standard deviation is known to be pos-

itive, it is possible to get a smooth density estimate that does not allocate

probability to negative values by setting the options low=0 and high=. The

boundary is imposed by reflecting the data as described in Silverman(1986),

page 30.

. wbdensity alpha

. wbdensity alpha sigma , low(. 0)

Saved Results

21

Figure 4: Density estimates created by wbdensity. Sigma has a lower boundof zero.

plotting points can be saved using the dsaving option.

Also See

wbsection

Reference

Silverman, B(1986) Density Estimation Chapman & Hall

22

Titlewbgeweke - Geweke test for convergence

Syntax

wbgeweke varlist [if][in] [ , percentages(string) ]

options descriptionpercentages lower and upper percentage of the chain to be compared

Description

performs Geweke’s test of the mean of the early section of a chain against

the mean of a late section of the same chain.

Options

percentages(string) lower and upper percentage of the chain to be com-

pared. The default is to compare the first 10% of the chain with the last 50%

ie p(10 50)

Remarks

wbgeweke is a version of the Geweke convergence test that uses prais

regression to estimate the standard errors. The test is of limited use but it

may detect the effect of initial values on the early part of a chain. The z-test

(normal approximation) compares the mean of the early part of a chain (de-

fault 10%) with the mean of the late part of a chain (default 50%). wbgeweke

is byable in order to make it is easy to analyse multiple chains.

. wbgeweke alpha beta if chain==1

. sort chain order

. by chain: wbgeweke alpha beta

23

Saved Results

wbgeweke returns six values for each parameter. Thus for parameter 1 it

returns

m1 1 the mean of the early section of the chainse1 1 the standard error of the early section of the chainm2 1 the mean of the late section of the chainse2 1 the standard error of the late section of the chainz 1 the test statisticp 1 p-values for test comparing the means

Also See

[TS] prais

Reference

Geweke J

Evaluating the accuracy of sampling-based approaches to the calculation of

posterior moments

In Bayesian Statistics 4 (Editors: Bernardo JM, Berger AP, Dawid AP,

Smith AFM)

Oxford University Press, Oxford 1992;169-193

24

Titlewbhull - bivariate posterior contour plots

Syntax

wbhull varlist [if][in] [ , options ]

options descriptionpeels(numlist) peel numbers to be plottedhull(varname) variable to store peel number of each pointthin(#) thinning number top limit the chain sizegoptions(string) graphics options for the individual plotscgoptions(string) options combining plotssaving(string,replace) graphics file (.gph) for the final plotexport(string,replace) graphics file with non-standard formats

Description

Plots convex hulls from the simulations of pairs of parameters in order to

give an impression of their bivariate posterior distribution.

Options

peels(numlist) numbers of the peels that are to be plotted. The outer hull

is peel 1, then next is peel 2, etc.

hull(varname) variable to save an identifier showing the peel to which each

point belongs

thin(#) thin the data by taking every nth value. This can speed up the

routine when the MCMC sequence is very long.



25




.gph format.



tension to the given filename

Remarks

wbhull plots the convex hulls of pairs of parameters in order to give a

visual impression of the joint distribution of two of the parameters. ’varlist’

can contain the names of between 2 and 4 parameters. The peels for every

pair are calculated and plotted together in a matrix plot.

When the MCMC run is very long it can take a long time to calculate

each peel. What is more, if the 20th peel is requested then this has to be

calculated by finding the first peel and discarding it, then finding the second

peel and discarding that, until the 20th peel is reached. So deep peels with

large sets of simulations can be slow.

. wbhull alpha, peels(5 10)

References

wbhull incorporates a section of code taken from the Stata ado file conhull.ado,

which is itself described in

Gray JP & McGuire T,

Convex hull programs

Stata Technical Bulletin 23,1995:59-66.

26

Figure 5: Peels 5, 15 and 25 for four parameters

27

Titlewbintervals - interval estimates for sections of a chain

Syntax

wbintervals varlist [if][in] [ , options ]

options descriptionm(#) number of sectionslevel(#) percentage within the intervalbychain(varname) plot for each chaingoptions(string) graphics options for the individual plotscgoptions(string) options combining plotssaving(string,replace) graphics file (.gph) for the final plotexport(string,replace) graphics file with non-standard formatsdsaving(string,replace) .dta file for the autocorrelations

Description

plots interval estimates for ordered sections of a set of MCMC simulations

Options

m(#) number of sections into which the chains are divided. Default 10

level(#) percentage within the symmetric interval. Default 80%, ie between

the 10th and 90th centiles.

bychain(varname) name of a variable identifying the chains as 1, 2,. . . Requests

separate intervals for each chain.




28



.gph format.




dsaving(string,replace) specifies a filename (.dta) for saving the points

used when plotting the graph.

Remarks

wbintervals is similar to wbtrace in that it plots the history of a chain.

However, instead of plotting individual simulations, wbintervals plots me-

dians and 80% intervals for ordered sections of the simulations. The default

is to divide the chain into 10 ordered sections and to plot the 80% interval

for each of the 10 sections

. wbintervals alpha

. wbintervals alpha sigma , bychain(id)

Saved Results

plotting points can be saved using the dsaving option.

Also See

wbsection wbtrace

29

Figure 6: Interval plots for 4 parameters and 3 chains created by. wbintervals alpha beta1 beta2 sigma, bych(id)

30

Titlewbrun - run WinBUGS from with Stata

Syntax

wbrun , script(string) winbugs(string) [ batch ]

options descriptionscript name of text file containing the scriptwinbugs name of WinBUGS executablebatch run WinBUGS in the background

Description

runs WinBUGS from within Stata

Options

script name of a text file containing the script that controls WinBUGS .

winbugs name (with path) of the WinBUGS executable

batch run WinBUGS in the background returning control to Stata . The

default is for Stata to freeze until WinBUGS has finished.

Remarks

wbrun runs a WinBUGS script from within Stata . If the script ends with

quit() then WinBUGS closes after the script has executed and control is re-

turned to Stata . Without quit() in the script file, WinBUGS remains open

and may be used interactively. When eventually closed, control will return

to Stata .

. wbrun , sc(script.txt) w(c:/program files/winbug14.exe)

31

Titlewbscalar - write a list of scalars

Syntax

wbscalar , scalars(string) [ options ]

options descriptionscalars(string) list of scalars formats(string)formats for the datasaving(string,replace) text file (.txt) for the datanoprint do not print the data to the results window

Description

creates a text file containing a list structure made up of scalars

Options

scalars(string) list of the names of Stata scalars that are to be included

in the list.



%4.0f %3.1f %4.0f . . .

saving(string,replace) gives the name of the text file used to write the

array. If non-specified the array is only written to the results window.


Remarks

writes the selected scalars to the results window and/or a text file as an R

(S-Plus) list ready to be read into WinBUGS. Likely to be used for specifying

32

initial values for a chain or within wbdata

wbarray automatically replaces missing values with NA as required by

WinBUGS .

Assuming that Stata has scalars a,b and ns with values 1, 2.5 and 17

. wbscalar ,sc(a b ns)

would produce

list( a= 1.000, b= 2.500, ns= 17.000)

33

Titlewbscript - write a WinBUGS script file

Syntax

wbscript , options

options descriptionEssentialmodelfile(string) name of the text file containg the modeldatafile(string) name(s) of the data file(s)initsfile(string) name of the initial value filescodafile(string) root of the name for the coda filesset(string) parameters to be savedOptionallogfile name for saving the log fileburnin(#) size of the burn-inupdates(#) length of the MCMC runchains(#) number of parallel chainsthin(#) save every nth simulationdic write the DIC to the logquit close WinBUGS on completionnoprint do not write the script to the results windowsaving(sting,replace text file for saving the script

Description

writes a script file for fitting a given model in WinBUGS

Options

modelfile(string) full path name of a text file containing the WinBUGS

model.

datafile(string) full path names of the data file(s). When there are sev-

eral data files they should all be included in this option separated by +’s.

34

initsfile(string) full path name of root to the file(s) of initial values. A

separate set of initial values is required for each chain. This options gives

the root to the names opf these files, thus of we specified the option to be

d:/temp/in and there were 3 chains then the script would look to read files

d:/temp/in1.txt, d:/temp/in2.txt and d:/temp/in3.txt. A command

is automatically included in the script that asks WinBUGS to attemp to gen-

erate random initial values for any parameters not given in the initial values

files.

codafile(string) full path name to the root of the coda file. WinBUGS out-

puts an index file and data file(s) (one for each chain) with names derived

from this root (see wbcoda).

set(string) list of parameters that are to be saved.

logfile(string) full path name for saving the log file, a record of the steps

in the WinBUGS analysis.

burnin(#) length of the burnin, that is, the initial set of simulations that

are discarded. Default 0 (no burn-in).

updates(#) length of the chains. Default 1000.

chains(#) number of chains. Default 1.

thin(#) save every nth simulation. Default no thinning.

dic write the deviance information criterion to the logfile.

quit quit WinBUGS as soon as the analysis is completed.

noprint do not display the script in the results window.

35

saving(string,replace) text file for saving the script.

Remarks

wbscript writes a simple script file for a standard WinBUGS analysis.

There are more WinBUGS options than are available through wbscript and

if these are required then the script should be prepared using a text editor,

perhaps by modifying a basic script created by wbscript.

wbscript , sav(script.txt,replace) ///

model(d:/temp/model.txt) data(d:/temp/data.txt) ///

inits(d:/temp/inits1.txt) burn(1000) update(10000) ///

coda(d:/temp/oxford/out) set(alpha beta1 beta2 sigma) quit

would produce a script file script.txt containing

display(’log’)

check(’d:/temp/model.txt’)

data(’d:/temp/data.txt’)

compile(1)

inits(1,’d:/temp/inits1.txt’)

gen.inits()

update(1000)

set(’alpha’)

set(’beta1’)

set(’beta2’)

set(’sigma’)

update(10000)

coda(*,’d:d:/temp//out’)

quit()

36

Titlewbsection - convergence checking by comparing posterior densities

Syntax

wbsection varlist [if][in] [ , options ]

options descriptionm(#) number of sectionsbychain(varname) plot for each chainkoptions(string) options passed to kdensitygoptions(string) graphics options for the individual plotscgoptions(string) options combining plotssaving(string,replace) graphics file (.gph) for the final plotexport(string,replace) graphics file with non-standard formatsdsaving(string,replace) .dta file for the plotting points

Description

posterior density estimates for comparing subsections of a chain

Options

m(#) number of sections that are plotted separately. Default 2.

bychain(varname) gives the chain identifier and requests separate densities

for the whole length of each chain rather than by section. If the option m is

specified together with bychain then m is ignored.

koptions(string) passes its string as options for the Stata command,

textttkdensity that is used to create the density estimates.

goptions(string) passes its string as graphics options when densities are

plotted.

37




.gph format.




dsaving(string,replace) specifies a filename (.dta) for saving the plotting

points.

Remarks

wbsection plots smoothed density estimates for the whole MCMC chain

(solid) and for m fractions of the chain (dashed). For instance, when m=3

wbsection plots three smoothed densities for the first, middle and last thirds

of the chain. Densities calculated using kdensity.

The measure D represents the maximum difference of two densities as a per-

centage of the maximum height of the density of the whole chain. D < 20

usually looks like reasonable agreement, D < 10 is good. If varlist contains

more than 1 parameter the separate plots are combined.

. wbsection alpha beta, cg(rows(2))

. wbsection alpha beta, m(3)

. wbsection alpha beta, bychain(id)

If the bychain option is used the plot will compare different chains rather

than sections of the same chain.

Saved Results

38

Figure 7: Plot produced by . wbsection alpha beta1 beta2 sigma

dsaving can be used to save the plotting positions.

Also See

wbdensity

39

Titlewbstats - summary statistics for an MCMC run

Syntax

wbstats varlist [if][in] [ , options ]

options descriptionhpd highest posterior density intervals instead of credibility intervalslevel() percentage for the interval estimates. Default 95

Description

wbstats summarises the results from a WinBUGS MCMC simulation. By

listing

statistic descriptionn number of values included in the calculationmean average simulated valuesd standard deviation of the simulated valuesse approximate standard error of the mean (by prais regression)median median simulated valuecredible interval interval estimated from centiles of the chain

Options

hpd requests Highest Posterior Density intervals rather than credible inter-

vals. The calculation requires a density estimate and could fail with multi-

model distributions if the HPD interval consists of several disjoint regions.

level(#) percentage for the interval estimate. Default 95.

Remarks

40

wbstats writes a table summarising the MCMC simulations. The stan-

dard error is calculated using prais regression. wbstats is byable and returns

its summary statistics.

. wbstata alpha beta if chain==1

. by chain, wbstata alpha beta

Saved Results

For each parameter wbstats returns 8 values. Thus for parameter 1 we

have,

par 1 the parameter namen 1 the number of simulationmn 1 the meansd 1 the standard deviationse 1 the standard errormd 1 the standard errorlb 1 the interval lower boundub 1 the interval upper bound

41

Titlewbstructure - write a list of twoway structures

Syntax

wbstructure varlist [if][in] [ , options ]

options descriptionformats(string) formats for the datasaving(string,replace) text file (.txt) for the datanoprint do not print the data to the results window

Description

writes a WinBUGS list structure containing a two-way array.

Options



%4.0f %3.1f %4.0f . . .




Remarks

writes the selected data to the results window and/or a text file as a

twoway R style list structure ready to be read into WinBUGS. wbstructure

automatically replaces missing values with NA as required by WinBUGS .

. wbstructure x y z, name(X)

42

Titlewbtrace - trace plot of a MCMC run

Syntax

wbtrace varlist [if][in] [ , options ]

options descriptionthin(#) plot every nth valueorder(varname) variable giving the ordering of simulationsbychain(varname) variable identifying the chainoverlay request parallel chains are overlayedgoptions(string) graphics options for the individual plotscgoptions(string) options combining plotssaving(string,replace) graphics file (.gph) for the final plotexport(string,replace) graphics file with non-standard formats

Description

wbtrace produces a trace or history plot of MCMC simulations.

Options

thin(#) thin the plot by only showing every nth value. Default no thinning.

order(varname) gives the variable denoting the order of simulations within

each chain. If not stated they are numbered 1,2,3. . . in the order they occur

in the dataset.

bychain(varname) gives the chain identifier and requests separate traces for

each chain.

overlay(varname) used together with bychain to request that the traces

from each chain be overlayed on a single plot.

43

goptions(string) passes its string as graphics options when densities are

plotted.




.gph format.




Remarks

wbtrace plots the consecutive values from an MCMC run as a time se-

ries. Also shows the median and the 95% credible interval. If more than one

variable is specified then the separate plots will be combined and placed next

to or above one another. If there is more than one chain they can either be

plotted separately or overlayed so that they will appear superimposed on the

same plot.

. wbtrace alpha beta, cg(row(2))

. wbtrace alpha, bychain(id) overlay

. wbtrace alpha, bychain(id) cg(row(3))

44

Figure 8: trace plot produced by. wbtrace alpha beta1 bet2 sigma, thin(20)

45

Titlewbvector - write a list of vectors

Syntax

wbvector varlist [if][in] [ , options ]

options descriptionformats(string) formats for the datasaving(string,replace) text file (.txt) for the datanoprint do not print the data to the results window

Description

writes vectors of data to a data list

Options



%4.0f %3.1f %4.0f . . .




Remarks

wbvector writes vectors to WinBUGS style list structures. It automati-

cally replaces missing values with NA as required by WinBUGS . wbvector

can be used in conjunction with wbdata in order to produce mixed lists of

vectors, scalars and two-way structires.

46

With appropriate data defined in Stata

. wbvector x y, f(%2.0f)

would produce

. list( x=c( 2, 3,-1, 0) y=( 5,NA, 1, 1) )

Also See

wbarray wbdata wbscalar wbstructure

47

Documents

wb: Commands for Running Stata from WinBUGSStata and for examining the resulting MCMC simulations. The plots used to illustrate the commands described in this document are taken from