pbugs: Run 'WinBUGS' or 'OpenBUGS' Models in Parallel

In fisabio/pbugs: Run 'WinBUGS' or 'OpenBUGS' Models in Parallel

Run WinBUGS or OpenBUGS Models in Parallel

Description

Run WinBUGS or OpenBUGS models from your R session running parallel instances of these programs, one per chain. In this manner several cores (one per chain) are used to run the MCMC simulation of the corresponding model. Results are returned in an object of bugs and pbugs classes.

Usage

pbugs(data, inits, parameters.to.save, model.file,debug = FALSE, program =
  c("winbugs", "openbugs"),bugs.directory = "default", cluster = NULL, pbugs.directory
  = "default",slice = FALSE, OpenBUGS.pgm = "default", cluster_export = NULL, ...)

Arguments

data	List or character. Either a named list (names corresponding to variable names in the model.file) of the data for the WinBUGS model, or (which is not recommended and unsafe) a vector or list of the names of the data objects used by the model. If data is a one element character vector (such as "data.txt"), it is assumed that data have already been written to the working directory into that file, e.g. by the function bugs.data. This argument is also required, with the same format, by the R2WinBUGS::bugs function.
inits	Function or list (length == n.chains). 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 (if possible). If inits is a character vector with n.chains elements, it is assumed that inits have already been written to the working directory into those files, e.g. by the function bugs.inits. This argument is also required, with the same format, by the R2WinBUGS::bugs function.
parameters.to.save	Character vector of the names of the parameters to save which should be monitored. This argument is also required, with the same format, by the R2WinBUGS::bugs function.
model.file	Function or character (length 1). File containing the model written in WinBUGS code. The extension can be either '.bug' or '.txt'. If the extension is '.bug' and program == "WinBUGS", a copy of the file with extension '.txt' will be created in the pbugs() call and removed afterwards. Note that similarly named '.txt' files will be overwritten. Alternatively, model.file can be an R function that contains a BUGS model that is written to a temporary model file (see tempfile) using write.model. This argument is also required, with the same format, by the R2WinBUGS::bugs function.
debug	Logical, default: FALSE. Open WinBUGS in debug mode. It does not work for OpenBUGS in Unix OS's (only through Wine: useWINE == TRUE).
program	Character (length 1), default argument: "winbugs". The program to use for the MCMC inference, either WinBUGS or OpenBUGS.
bugs.directory	Character (length 1), default: system dependent (Unix-Windows). The default argument calls to the corresponding default argument of the R2WinBUGS::bugs function. Directory where WinBUGS is installed. Several copies (as many as chains to be run) of this directory are created at the pbugs.directory folder, if they are not still created.
cluster	Integer (length 1), default: NULL. Number of computer cores to use for running the model. If not provided, the function sets it to the minimum of the number of available cores minus one the number of chains run.
pbugs.directory	Character (length 1). Path to the pbugs directory were different copies (one per chain) of either WinBUGS or OpenBUGS are stored. Default value is "/home/user/.wine/drive_c/pbugs/winbugs" for WinBUGS and "/home/user/.wine/drive_c/pbugs/openbugs" for OpenBUGS on UNIX OS's and "c:/pbugs/winbugs" and "c:/pbugs/openbugs" on Windows OS.
slice	Logical, default: FALSE. Should WinBUGS' adaptive rejection sampler (DFreeARS) for log-concave distributions be replaced by a Slice sampler? This is useful to sort out some Traps as described in the "Changing MCMC defaults" section of the WinBUGS help. This argument does not work with OpenBUGS.
OpenBUGS.pgm	Character (length 1), default: system dependent (Unix-Windows). The default argument calls to the corresponding default argument of the R2WinBUGS::bugs function. Directory where OpenBUGS is installed. Several copies (as many as chains to be run) of this directory are created at the pbugs.directory folder, if they are not still created.
cluster_export	Character, default: NULL. Additional objects to export to computer cores.
...	Additional arguments to be passed to R2WinBUGS::bugs function.

Details

This function basically executes parallel calls (one per chain) to R2WinBUGS::bugs, so it is possible to use almost all the arguments associated to that function. The summary.only argument of bugs can be only set equal to FALSE in pbugs.

The idea of the pbugs implementation is to minimize code adaptation from regular bugs instances. Suitable code for the bugs function should run in principle in parallel by simply calling to the pbugs function with the same arguments as the original bugs call.

Aditionally, this function has some enhanced functionality as compared to bugs such as replacing WinBUGS' adaptive rejection sampler (DFreeARS) by a Slice sampler, to sort out some classical 'Traps', from R. This option does not work with OpenBUGS.

Note that when DIC == TRUE in pbugs, DICs and their components are calculated as the mean of the different DICs returned per each of the chains run. If convergence is appropriately achieved this should not be hardly different to the DIC calcuted for all the chains simulated.

Value

The arguments in the returned pbugs object are the same than for any R2WinBUGS::bugs object, plus the following:

exec_time	Execution time taken by the function
seed	Seed used, for reproducible simulations
n_cores	Number of computer cores used

See Also

R2WinBUGS::bugs

Examples

## Not run: 
  library(pbugs)
  data(sample_df)
  bugs_model <- function() {
    for (i in 1:N) {
      y[i] ~ dbern(pi[i])
      logit(pi[i]) <- beta[1] + beta[2] * x1[i] + beta[3] * x2[i] + beta[4] * x3[i]
    }
    for (j in 1:4) {
      beta[j] ~ dflat()
    }
  }
  bugs_data <- with(sample_df, list(y = y, x1 = x1, x2 = x2, x3 = x3, N = length(y)))
  bugs_init <- function() list(beta = rnorm(4, sd = .5))
  bugs_pars <- c("beta", "pi")
  result    <- pbugs(data = bugs_data, inits = bugs_init, parameters.to.save = bugs_pars,
                     model.file = bugs_model, n.thin = 1, n.chains = 4)

## End(Not run)

fisabio/pbugs documentation built on Jan. 28, 2024, 5:13 a.m.