doc/help-bugs.texi

   1 @ESS{[BUGS]} was originally designed for use with BUGS software.  It
   2 was developed by Rodney A. Sparapani and has some similarities with
   3 @ESS{[SAS]}.  Later, it evolved to support JAGS as a dialect of the
   4 BUGS language via @ESS{[JAGS]}.  Unless otherwise noted, whenever this
   5 documentation says BUGS, you can assume that it applies to JAGS as
   6 well.  @ESS{} provides 5 features.  First, BUGS syntax is described to
   7 allow for proper fontification of statements, distributions,
   8 functions, commands and comments in BUGS model files, command files
   9 and log files.  Second, @ESS{} creates templates for the command file
  10 from the model file so that a BUGS batch process can be defined by a
  11 single file.  Third, @ESS{} provides a BUGS batch script that allows @ESS{}
  12 to set BUGS batch parameters.  Fourth, key sequences are defined to
  13 create a command file and submit a BUGS batch process.  Lastly,
  14 interactive submission of BUGS commands is also supported.
  15
  16 @comment  node-name,  next,  previous,  up
  17 @node ESS(BUGS)--Model files, ESS(BUGS)--Command files, ESS for BUGS, ESS for BUGS
  18 @section ESS[BUGS]--Model files
  19
  20 Model files with the @file{.bug} extension are edited in @ESS{[BUGS]} mode
  21 if @code{(require 'essd-bugs)} was performed or edited in @ESS{[JAGS]} mode
  22 if @code{(require 'essd-jags)}.
  23 Two keys are bound for your use in @ESS{[BUGS]}, @kbd{F2} and @kbd{C-c C-c}.
  24 @kbd{F2} performs the same action as it does in @ESS{[SAS]},
  25 @xref{ESS(SAS)--Function keys for batch processing}.  @kbd{C-c C-c} performs the
  26 function @code{ess-bugs-next-action} which you will use a lot.  Pressing it
  27 in an empty buffer for a model file will produce a template for you.
  28
  29 @ESS{[BUGS]} supports "replacement" variables.  These variables are
  30 created as part of the template, i.e. with the first press of @kbd{C-c C-c}
  31 in an empty buffer.  They are named by all capitals and start
  32 with @code{%}: @code{%N}, @code{%DATA}, @code{%INIT}, @code{%MONITOR} and @code{%STATS}.  When you are
  33 finished editing your model file, pressing @kbd{C-c C-c} will perform
  34 the necessary replacements and build your command file for you.  Note
  35 that @ESS{[JAGS]} only supports @code{%MONITOR} since none of the other
  36 variables are compatible with the JAGS dialect.
  37
  38 The @code{%DATA} variable appears in the line @code{data in "%DATA";}.  On the
  39 second press of @kbd{C-c C-c}, @code{%DATA} will be replaced by the model file name
  40 except it will have the @file{.dat} extension.  If your data file is named
  41 something else, then change @code{%DATA} in the template to the appropriate
  42 file name and no replacement will occur.
  43
  44 The @code{%INIT} variable appears in the line @code{inits in "%INIT";}.
  45 On the second press of @kbd{C-c C-c}, @code{%INIT} will be
  46 replaced by the model file name except it will have the .in extension.
  47 If your model will be generating it's own initial values, place a
  48 comment character, @code{#}, at the beginning of the line.  Or, if your init
  49 file is named something else, then change @code{%INIT} in the template to the
  50 appropriate file name.
  51
  52 The @code{%N} variable appears in the line @code{const N = 0;#%N}.
  53 Although it is commented, it is still active.  Notice that later on in
  54 the template you have the line @code{for (i in 1:N)}.  The BUGS
  55 constant @code{N} is the number of rows in your data file.  When you
  56 press @kbd{C-c C-c}, the data file is read and the number of lines are
  57 counted (after @code{%DATA} is resolved, if necessary).  The number of
  58 lines replace the zero in the @code{const N = 0;} statement.
  59
  60 The @code{%MONITOR} variable appears on a line by itself.  Although it
  61 is commented, it is still active.  This line is a list of variables
  62 that you want monitored.  When you press @kbd{C-c C-c}, the
  63 appropriate statements are created in the command file to monitor the
  64 list of variables.  If the line is blank, then the list is populated
  65 with the variables from the @code{var} statement.
  66
  67 The @code{%STATS} variable is similar to the @code{%MONITOR} variable.
  68 It is a list of variables for which summary statistics will be
  69 calculated.  When you press @kbd{C-c C-c}, the appropriate statements
  70 will be generated in your command file.
  71
  72 Please note that the @code{%DATA} and @code{%INIT} variables are only
  73 replaced on the second press of @kbd{C-c C-c}, but the actions for
  74 @code{%N}, @code{%MONITOR} and @code{%STATS} are performed on each
  75 press of @kbd{C-c C-c} if you re-visit the model file.
  76
  77 @comment  node-name,  next,  previous,  up
  78 @node ESS(BUGS)--Command files, ESS(BUGS)--Log files, ESS(BUGS)--Model files, ESS for BUGS
  79 @section ESS[BUGS]--Command files
  80
  81 To avoid extension name collision, @file{.bmd} is used for BUGS
  82 command files and @file{.jmd} for JAGS command files.  When you have
  83 finished editing your model file and press @kbd{C-c C-c}, a command
  84 file is created if one does not already exist.  However, the command
  85 file was created, it recognizes two "replacement" variables:
  86 @code{%MONITOR} and @code{%STATS}.
  87
  88 Two @code{%MONITOR} variables appears on lines by themselves.
  89 Although they are commented, they are still active.  Between them
  90 appears the necessary statements to monitor the list of variables
  91 specified in the model file.  The behavior of the @code{%STATS}
  92 variable is similar.
  93
  94 When you are finished editing your command file, pressing @kbd{C-c C-c}
  95 again will submit your command file as a batch job.  BUGS batch
  96 scripts are provided for both Unix and DOS in the @file{etc}
  97 sub-directory of the @ESS{} distribution.  The Unix script is
  98 @file{backbugs} for BUGS major version 0.6 and @file{backbug5} for
  99 0.5. The DOS script is @file{BACKBUGS.BAT} for BUGS major version 0.6
 100 only.  These scripts allows @ESS{} access to BUGS batch features that
 101 are not readily available with the batch scripts that come with BUGS.
 102
 103 @comment  node-name,  next,  previous,  up
 104 @node ESS(BUGS)--Log files, , ESS(BUGS)--Command files, ESS for BUGS
 105 @section ESS[BUGS]--Log files
 106
 107 To avoid extension name collision, @file{.bog} is used for BUGS log
 108 files.  The BUGS batch script provided with @ESS{} creates the
 109 @file{.bog} file from the @file{.log} file when the batch process
 110 completes.  If you need to look at the @file{.log} file while the
 111 batch process is running, it will not appear in @ESS{[BUGS]} mode.
 112 You may find @kbd{F2} useful to refresh the @file{.log} if the batch
 113 process over-writes or appends it.
 114