BGXGENSTAT procedure

Runs WinBUGS from GenStat in batch mode using scripts (D.A. Murray).

Options

PRINT = strings

Controls printed output (bugslog, nodestatistics, dic); default node

WPATH = text

Path specifying the location of the WinBUGS executable

WEXE = text

Name of the WinBUGS or OpenBUGS executable to run; default 'WinBUGS14.exe'

MODELFILE = text

Name of a file containing the model in WinBUGS code; the file should have an extension of .txt

DATA = pointer

A pointer to the data used by the WinBUGS model

IDATANAMES = text

A text containing the names for the data

MONITOR = text

The names of the variables that are to monitored

NCHAINS = scalar

Number of Markov chains; default 3

NBURNIN = scalar

Length of burn-in per chain; default 1000

NSAMPLES = scalar

Number of samples to run after burn-in; default 5000

THIN = scalar

Thinning rate where the samples from every kth iteration are stored; default 1

INAMES = text

The names for the initial parameters

DIC = string

Whether to calculate the deviance information criterion (yes, no); default no

SEED = scalar

Specifies a seed to use for the random number generator in BUGS; default uses a pseudo-random number generated from the uniform distribution

WORKDIRECTORY = texts

Working directory to use; default current GenStat working directory

BUGS = string

Whether to use WinBUGS or OpenBUGS (winbugs, openbugs); default winb

VIEWBUGS = string

Whether to leave WinBUGS open after the run (yes, no); default no

CONTINUE = string

Whether to continue GenStat server without waiting for WinBUGS to complete; (yes, no); default no

CODA = string

Whether to save CODA files (yes, no); default no

WLOG = text

Name of file to save log from WinBUGS or OpenBUGS

Parameters

INITIAL = pointers

List of pointers, one for each set of initial values for each Markov chain

SIMULATIONS = pointers

List of pointers to save simulations, one for each Markov chain

Description

WinBUGS (Bayesian inference Using Gibbs Sampling, Spiegelhalter, Thomas, Best & Lund 2003) is an application that can be used for the Bayesian analysis of complex models using Markov Chain Monte Carlo (MCMC) methods. WinBUGS is available free at

http://www.mrc-bsu.cam.ac.uk/bugs/

and an open-source version of the core BUGS code (OpenBUGS) is also available at

http://mathstat.helsinki.fi/openbugs/

BGXGENSTAT can be used to run WinBUGS or OpenBUGS from GenStat in batch mode using scripts. To execute commands within WinBUGS, BGXGENSTAT automatically creates a data and script file containing the necessary commands for the MCMC. These files are passed to WinBUGS and, once it has completed execution, the results can be imported into GenStat.

To use BGXGENSTAT either WinBUGS or OpenBUGS must be installed on the current system. The control of whether WinBUGS or OpenBUGS is to be run is set using the BUGS option. The executable used when submitting the script is specified using the WEXE option, by default this uses WinBUGS14.exe for WinBUGS and Winbugs.exe for OpenBUGS. The location of the BUGS executable used to run the script should be specified using the WPATH option. The directory for the path should be specified as a text containing the absolute pathname, for example in Windows the default directory for the executable for WinBUGS 1.4 would be

C:/Program Files/WinBUGS14

WinBUGS requires the script file to be written to the directory containing the executable. Therefore, you must have write permission to this directory to be able to run BGXGENSTAT.

The model to run in WinBUGS should be supplied using WinBUGS code, within a file supplied using the MODELFILE option. The data are supplied in a pointer using the DATA option. Each element of the pointer should represent a different data structure used in the model, and can be a scalar or a variate or, for 2-D data, a matrix or pointer to variates. The names for the data structures are supplied using the IDATANAMES option, and should be in the same order as that in which the data occur in the DATA pointer. The names of the variables of interest that are to be monitored are supplied within a text using the MONITOR option. By default three Markov chains are run, but this can be changed by the NCHAINS option. The number of burn-in iterations and the number of samples to run after the burn-in are specified using the NBURNIN and NSAMPLES options respectively. A thinning rate can be specified using the THIN option, where the samples from every kth iteration are stored. The initial values for the chains are supplied in a list pointers using the INITIAL parameter. The elements of each pointer can be either a scalar or variate, and must be in the same order in all the pointers. The names of the variables for the initial values are supplied using the INAMES option where the names are in the same order as the data within the pointers for the INITIAL parameter. Each run of WinBUGS produces CODA output files containing the Markov Chain Monte Carlo output in CODA format. The data from the CODA files can be imported into GenStat using the SIMULATIONS parameter. By default the CODA files are deleted, but you can set CODA=yes to save these in the working directory. The CODA files consist of an output file for each chain, showing the iteration number and value. In addition there is an index file containing a description of which lines of the output files correspond to which variable. BGXGENSTAT saves the index file using the name WBGCODAIndex.txt and the output files are saved as WBGCODA1.txt, WBGCODA2.txt, etc.

When WinBUGS is run, the GenStat server is suspended until the WinBUGS script has run. If you do not want to wait until the WinBUGS script has run before continuing with GenStat, you can set the option CONTINUE=yes. However, when this option is set to yes, the CODA and PRINT options, and SIMULATION parameter will be ignored. If errors occur within the WinBUGS script, the VIEWBUGS option can be used to keep WinBUGS open after the run.

Running WinBUGS produces a log file which can be saved using the WLOG option. By default, the working directory will be the current directory. However, an alternative directory can be supplied using the WORKDIRECTORY parameter.

The PRINT option controls printed output, with the settings:

bugslog

to print the contents of the log file,

nodestatistics

to display summary statistics for the nodes, and

dic

to display the deviance information criterion (the DIC option must then be set).

Options: PRINT, WPATH, WEXE, MODELFILE, DATA, IDATANAMES, MONITOR, NCHAINS, NBURNIN, NSAMPLES, THIN, INAMES, DIC, SEED, WORKDIRECTORY, BUGS, VIEWBUGS, CONTINUE, CODA, WLOG.

Parameters: INITITAL, SIMULATIONS.

Method

To execute commands within WinBUGS, BGXGENSTAT automatically creates a data and script file containing the necessary commands. In Windows the commands are submitted to WinBUGS by creating a bat file containing a command line and then executes this within a windows command processor. Once WinBUGS has completed GenStat uses the log file and CODA files generated by WinBUGS to retrieve the results. The node statistics are read directly from the log file, and the SIMULATIONS are imported from the coda files.

Action with RESTRICT

Any data restrictions will be ignored.

References

Gelman, A., Carlin J., Stern H. & Rubin, D. (2003). Bayesian Data Analysis. CRC Press, London.

Spiegelhalter, D.J., Thomas, A., Best, N.G. & Lund, D. (2003). WinBUGS Version 1.4 Users Manual. MRC Biostatistics Unit, Cambridge.

URL http://www.mrc-bsu.cam.ac.uk/bugs/

Spiegelhalter, D.J., Thomas, A., Best, N.G. & Lund, D. (2004). WinBUGS Version 2.0 Users Manual. MRC Biostatistics Unit, Cambridge.

URL http://www.mrc-bsu.cam.ac.uk/openbugs/