11. ESS for BUGS

11.1 ESS[BUGS]--Model files

Model files (with the .bug extension) are edited in ESS[BUGS] mode. Two keys are bound for your use in ESS[BUGS], F2 and F12. F2 performs the same action as it does in ESS[SAS], See section 10.5 ESS[SAS]--Function keys for batch processing. F12 performs the function ess-bugs-next-action which you will use a lot. Pressing F12 in an empty buffer for a model file will produce a template for you.

ESS[BUGS] supports "replacement" variables. These variables are created as part of the template, i.e. with the first press of F12 in an empty buffer. They are named by all capitals and start with '%': %N, %DATA, %INIT, %MONITOR and %STATS. When you are finished editing your model file, pressing F12 will perform the necessary replacements and build your command file for you.

The %DATA variable appears in the line 'data in "%DATA";'. On the second press of F12, %DATA will be replaced by the model file name except it will have the .dat extension. If your data file is named something else, then change %DATA in the template to the appropriate file name and no replacement will occur.

The %INIT variable appears in the line 'inits in "%INIT";'. On the second press of F12, %INIT will be replaced by the model file name except it will have the .in extension. If your model will be generating it's own initial values, place a comment character, #, at the beginning of the line. Or, if your init file is named something else, then change %INIT in the template to the appropriate file name.

The %N variable appears in the line 'const N = 0;#%N'. Although it is commented, it is still active. Notice that later on in the template you have the line 'for (i in 1:N)'. The BUGS constant N is the number of rows in your data file. When you press F12, the data file is read and the number of lines are counted (after %DATA is resolved, if necessary). The number of lines replace the zero in the 'const N = 0' statement.

The %MONITOR variable appears on a line by itself. Although it is commented, it is still active. This line is a list of variables that you want monitored. When you press F12, the appropriate statements are created in the command file to monitor the list of variables. If the line is blank, then the list is populated with the variables from the 'var' statement.

The %STATS variable is similar to the %MONITOR variable. It is a list of variables for which summary statistics will be calculated. When you press F12, the appropriate statements will be generated in your command file.

Please note that the %DATA and %INIT variables are only replaced on the second press of F12, but the actions for %N, %MONITOR and %STATS are performed on each press of F12 if you re-visit the model file.

11.2 ESS[BUGS]--Command files

To avoid extension name collision, .bmd is used for BUGS command files. When you have finished editing your model file and press F12, a command file is created if one does not already exist. However, the command file was created, it recognizes two "replacement" variables: %MONITOR and %STATS.

Two %MONITOR variables appears on lines by themselves. Although they are commented, they are still active. Between them appears the necessary statements to monitor the list of variables specified in the model file. The behavior of the %STATS variable is similar.

When you are finished editing your command file, pressing F12 again will submit your command file as a batch job. Batch scripts are provided for both DOS and Unix in the etc sub-directory of the ESS distribution. The DOS script is called "BACKBUGS.BAT" and the Unix script is "backbugs". These scripts allow you to change the number of bins to use in the Griddy algorithm (Metropolis sampling). That is handled by the variable ess-bugs-default-bins which defaults to 32.

11.3 ESS[BUGS]--Log files

To avoid extension name collision, .bog is used for BUGS log files. The BUGS batch script provided with ESS creates the .bog file from the .log file when the batch process completes. If you need to look at the .log file while the batch process is running, it will not appear in ESS[BUGS] mode unless you modify the auto-mode-alist variable. If you have done so, then you may find F2 useful to refresh the .log if the batch process over-writes or appends it.