Runs WinBUGS or OpenBUGS from Genstat in batch mode using scripts (D.A. Murray).
Options
PRINT = string tokens |
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 token |
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 token |
Whether to use WinBUGS or OpenBUGS (winbugs, openbugs); default winb |
VIEWBUGS = string token |
Whether to leave WinBUGS open after the run (yes, no); default no |
CONTINUE = string token |
Whether to continue Genstat server without waiting for WinBUGS to complete; (yes, no); default no |
CODA = string token |
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.
https://www.mrc-bsu.cam.ac.uk/software/bugs/the-bugs-project-winbugs/
Spiegelhalter, D.J., Thomas, A., Best, N.G. & Lund, D. (2004). WinBUGS Version 2.0 Users Manual. MRC Biostatistics Unit, Cambridge.
https://www.mrc-bsu.cam.ac.uk/software/bugs/openbugs/
See also
Procedures: BGIMPORT, BGPLOT, DEMC.
Commands for: Bayesian methods.
Example
CAPTION 'BGXGENSTAT Example','Example from WinBUGS.',\
!t('Binary dose-response data published by Bliss (1935), in which',\
'the numbers of beetles killed after 5 hour exposure to carbon',\
'disulphide at N=8 different concentrations are recorded.',\
'Data analysed by logit model using WinBUGs.'),
!t('Note that WinBUGS or OpenBUGs must be installed on your system',\
'to run this example.'); style=meta,3(plain)
" Specify WinBUGS model "
TEXT tmodel; VALUES=!t(\
'model',\
'{',\
' for( i in 1 : N ) {',\
' r[i] ~ dbin(p[i],n[i])',\
' logit(p[i]) <- alpha + beta * (x[i] - mean(x[]))',\
' rhat[i] <- n[i] * p[i]',\
' phat[i] <- r[i]/n[i]',\
' }',\
' beta ~ dnorm(0.0,0.00001)',\
' alpha ~ dnorm(0.0,0.00001)',\
'}')
" Write the WinBUGS model to a file "
OPEN 'beetles-model.txt'; CHAN=2; FILE=output
PRINT [CHANNEL=2; IPRINT=*; SQUASH=yes] tmodel; JUST=left
CLOSE 2; FILETYPE=output
" Data "
SCALAR N; VALUE=8
VARIATE x; VALUES=!(1.6907,1.7242,1.7552,1.7842,1.8113,1.8369,1.8610,1.8839)
VARIATE n; VALUES=!(59,60,62,56,63,59,62,60)
VARIATE r; VALUES=!(6,13,18,28,52,53,61,60)
TEXT dnames; VALUES=!t(N,x,n,r)
POINTER [VALUES=N,x,n,r] data
" Initial values "
TEXT ipnames; VALUES=!T('alpha','beta')
POINTER [NVALUES=ipnames] init
SCALAR init1[1...2]; VALUE=100,-100
SCALAR init2[1...2]; VALUE=-100,100
" Run WinBugs"
BGXGENSTAT [PRINT=node; MONITOR=ipnames;\
MODELFILE='beetles-model.txt';\
DATA=data; IDATANAMES=dnames; NSAMPLES=5000;\
INAMES=ipnames; NCHAIN=2] init1,init2; SIMULATIONS=sim[1...2]
" Plots "
BGPLOT [PRINT=summary; PLOT=trace; ARRANGEMENT=multiple] sim[]