User manual

Chapter 15: ESS for JAGS 78
15 ESS for JAGS
ESS[BUGS] was originally designed for use with BUGS software. Later, it evolved to support
JAGS as a dialect of the BUGS language via ESS[JAGS]. Since BUGS and JAGS are quite
similar, ESS[BUGS] and ESS[JAGS] are necessarily similar. ESS[JAGS] provides 4 features.
First, JAGS syntax is described to allow for proper fontification of statements, distributions,
functions, commands and comments in JAGS model files, command files and log files.
Second, ESS creates templates for the command file from the model file so that a JAGS
batch process can be defined by a single file. Third, ESS provides a JAGS batch script that
allows ESS to set JAGS batch parameters. Fourth, key sequences are defined to create a
command file and submit a JAGS batch process.
15.1 ESS[JAGS]–Model files
Model files with the ‘.bug’ extension are edited in ESS[BUGS] mode if (require ’ess-
bugs-d) was performed or edited in ESS[JAGS] mode if (require ’ess-jags-d). Three
keys are bound for your use in ESS[BUGS], F2, C-c C-c and =. F2 performs the same action
as it does in ESS[SAS], See Section 13.5 [ESS(SAS)–Function keys for batch processing],
page 71. C-c C-c performs the function ess-bugs-next-action which you will use a lot.
Pressing it in an empty buffer for a model file will produce a template for you. = inserts
the set operator, <-.
ESS[JAGS] does not support "replacement" variables which were part of ESS[BUGS].
Although, "replacement" variables are an extremely convenient feature, creating the elisp
code for their operation was challenging. So, a more elisp-ish approach was adopted for
ESS[JAGS]: elisp local variables. These variables are created as part of the template, i.e.
with the first press of C-c C-c in an empty buffer. For your ‘.bug’ file, they are named
ess-jags-chains, ess-jags-monitor, ess-jags-thin, ess-jags-burnin and ess-jags-
update; they appear in the Local Variables section. When you are finished editing your
model file, pressing C-c C-c will perform the necessary actions to build your command file
for you.
The ess-jags-chains variable is the number of chains that you want to initialize and
sample from; defaults to 1. The ess-jags-monitor variable is a list of variables that you
want monitored: encase each variable in double quotes. When you press C-c C-c, the
appropriate statements are created in the command file to monitor the list of variables. By
default, no variables are explicitly monitored which means JAGS will implicitly monitor all
“default” variables. The ess-jags-thin variable is the thinning parameter. By default,
the thinning parameter is set to 1, i.e. no thinning. The ess-jags-burnin variable is the
number of initial samples to discard. By default, the burnin parameter is set to 10000.
The ess-jags-update variable is the number of post-burnin samples to keep. By default,
the update parameter is set to 10000. Both ess-jags-burnin and ess-jags-update are
multiplied by ess-jags-thin since JAGS does not do it automatically.
15.2 ESS[JAGS]–Command files
To avoid extension name collision, ‘.bmd’ is used for BUGS command files and ‘.jmd’ for
JAGS command files. For your ‘.jmd’ file, there is only one variable, ess-jags-command,
in the Local Variables section. When you have finished editing your model file and press