bugs                package:R2WinBUGS                R Documentation

_R_u_n _W_i_n_B_U_G_S _f_r_o_m _R

_D_e_s_c_r_i_p_t_i_o_n:

     The 'bugs' function takes data and starting values as input. It
     automatically writes a WinBUGS script, calls the model, and saves
     the simulations for easy access in R.

_U_s_a_g_e:

     bugs(data, inits, parameters.to.save, model.file = "model.txt",
         n.chains = 3, n.iter = 2000, n.burnin = floor(n.iter/2),
         n.thin = max(1, floor(n.chains * (n.iter - n.burnin)/1000)),
         debug = FALSE, DIC = TRUE, digits = 5, codaPkg = FALSE,
         bugs.directory = "c:/Program Files/WinBUGS14/",
         working.directory = NULL)

_A_r_g_u_m_e_n_t_s:

    data: either a named list (names corresponding to variable names in
          the 'model.file')  of the data for the WinBUGS model, _or_ a
          vector or list of the names of the data objects used by the
          model. If 'data = "data.txt"', it is assumed that data have
          already been written to the working directory in a file
          called 'data.txt', e.g. by the function 'bugs.data'.

   inits: a list with 'n.chains' elements; each element of the list is
          itself a list of starting values for the WinBUGS model, _or_
          a function creating (possibly random) initial values.
          Alternatively, if 'inits = NULL', initial values are
          generated by WinBUGS

parameters.to.save: character vector of the names of the parameters to
          save which should be monitored

model.file: file containing the model written in WinBUGS code. The
          extension can be either '.bug' or '.txt'. If '.bug', a copy
          of the file with extension '.txt' will be created in the
          'bugs()' call and removed afterwards. Note that similarly
          named '.txt' files will be overwritten.

n.chains: number of Markov chains (default: 3)

  n.iter: number of total iterations per chain (including burn in;
          default: 2000)

n.burnin: length of burn in, i.e. number of iterations to discard at
          the beginning. Default is 'n.iter/2', that is, discarding the
          first half of the simulations.

  n.thin: thinning rate.  Must be a positive integer. Set 'n.thin' > 1
          to save memory and computation time if 'n.iter' is large.
          Default is 'max(1, floor(n.chains * (n.iter-n.burnin) /
          1000))' which will only thin if there are at least 2000
          simulations.

   debug: if 'FALSE' (default), WinBUGS is closed automatically when
          the script has finished running, otherwise WinBUGS remains
          open for further investigation

     DIC: logical; if 'TRUE' (default), compute deviance, pD, and DIC

  digits: number of significant digits used for WinBUGS input, see
          'formatC'

 codaPkg: logical; if 'FALSE' (default) a 'bugs' object is returned, if
          'TRUE' file names of WinBUGS output are returned for easy
          access by the 'coda' package.

bugs.directory: directory that contains the WinBUGS executable

working.directory: sets working directory during execution of this
          function; WinBUGS' in- and output will be stored in this
          directory; if 'NULL', the current working directory is
          chosen.

_D_e_t_a_i_l_s:

     To run:

        1.  Write a WinBUGS model in a ASCII file.

        2.  Go into R.

        3.  Prepare the inputs to the 'bugs' function and run it (see
           Example).

        4.  A WinBUGS window will pop up amd R will freeze up. The
           model will now run in WinBUGS. It might take awhile. You
           will see things happening in the Log window within WinBUGS.
           When WinBugs is done, its window will close and R will work
           again.

        5.  If an error message appears, re-run with 'debug = TRUE'.

_V_a_l_u_e:

     If 'codaPkg = TRUE' the returned values are the names (without
     file extension) of files written by WinBUGS containing the Markov
     Chain Monte Carlo output in the CODA format and corresponding
     index files. This is useful for direct access with 'read.bugs'
     from package 'coda'.

     If 'codaPkg = FALSE', the following values are returned: 

n.chains: see Section 'Arguments'

  n.iter: see Section 'Arguments'

n.burnin: see Section 'Arguments'

  n.thin: see Section 'Arguments'

  n.keep: number of iterations kept per chain (equal to
          '(n.iter-n.burnin) / n.thin')

  n.sims: number of posterior simulations (equal to 'n.chains *
          n.keep')

sims.array: 3-way array of simulation output, with dimensions n.keep,
          n.chains, and length of combined parameter vector

sims.list: list of simulated parameters:
           for each scalar parameter, a vector of length n.sims
           for each vector parameter, a 2-way array of simulations,
           for each matrix parameter, a 3-way array of simulations,
          etc.

sims.matrix: matrix of simulation output, with 'n.chains * n.keep' rows
          and one column for each element of each saved parameter (for
          convenience, the 'n.keep * n.chains' simulations in
          sims.array and sims.list have been randomly permuted)

 summary: summary statistics and convergence information for each
          element of each saved parameter.

    mean: a list of the estimated parameter means

      sd: a list of the estimated parameter standard deviations

  median: a list of the estimated parameter medians

root.short: names of argument 'parameters.to.save' and "deviance"

long.short: indexes; programming stuff

dimension.short: dimension of 'indexes.short'

indexes.short: indexes of 'root.short'

last.values: list of simulations from the most recent iteration; they
          can be used as starting points if you wish to run WinBUGS for
          further iterations

      pD: 'var(deviance)/2', an estimate of the effective number of
          parameters (the variance is computed as the average of the
          within-chain variances, which gives a more reasonable
          estimate when convergence has not been reached)

     DIC: 'mean(deviance) + pD'

_A_u_t_h_o_r(_s):

     Andrew Gelman, gelman@stat.columbia.edu, <URL:
     http:/www.stat.columbia.edu/~gelman/bugsR/>; modifications and
     packaged by Sibylle Sturtz, sturtz@statistik.uni-dortmund.de, and
     Uwe Ligges.

_R_e_f_e_r_e_n_c_e_s:

     Gelman, A., Carlin, J.B., Stern, H.S., Rubin, D.B. (2003):
     _Bayesian Data Analysis_, 2nd edition, CRC Press.

_S_e_e _A_l_s_o:

     'print.bugs', 'plot.bugs', and the 'coda' package

_E_x_a_m_p_l_e_s:

     # An example model file is given in:
     model.file <- file.path(.path.package("R2WinBUGS"), "model", "schools.txt")
     # Let's take a look:
     file.show(model.file)

     # Some example data (see ?schools for details):
     data(schools)
     schools

     J <- nrow(schools)
     y <- schools$estimate
     sigma.y <- schools$sd
     data <- list ("J", "y", "sigma.y")
     inits <- function(){
         list(theta = rnorm(J, 0, 100), mu.theta = rnorm(1, 0, 100),
             sigma.theta = runif(1, 0, 100))
     }
     parameters <- c("theta", "mu.theta", "sigma.theta")

     ## Not run: 
     ## You may need to edit "bugs.directory",
     ## also you need write access in the working directory:
     schools.sim <- bugs(data, inits, parameters, model.file,
         n.chains = 3, n.iter = 1000,
         bugs.directory = "c:/Program Files/WinBUGS14/",
         working.directory = NULL)
     print(schools.sim)
     plot(schools.sim)
     ## End(Not run)

