The BRugs dynamic link library
The brugs library provides an interface to some features of the OpenBUGS software via a C friendly set of procedure. The signatures of these procedures was choosen to make interfacing to the R/Splus statistical packages easy.
The brugs library has the same interface as the Component Pascal module BugsC vis
DEFINITION BugsC (* nonportable (i386) *);
PROCEDURE [ccall] BugsCmd (VAR command: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len: INTEGER);
PROCEDURE [ccall] CLI;
PROCEDURE [ccall] CharArray (VAR procedure: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len: INTEGER; VAR x: POINTER TO ARRAY [untagged] OF SHORTCHAR; VAR lenX, res: INTEGER);
PROCEDURE [ccall] CmdInterpreter (VAR command: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len, res: INTEGER);
PROCEDURE [ccall] Guard (VAR procedure: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len, x, res: INTEGER);
PROCEDURE [ccall] Integer (VAR procedure: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len, x, res: INTEGER);
PROCEDURE [ccall] IntegerArray (VAR procedure: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len: INTEGER; VAR x: ARRAY [untagged] OF INTEGER; VAR lenX, res: INTEGER);
PROCEDURE [ccall] Real (VAR procedure: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len: INTEGER; VAR x, y: REAL; VAR res: INTEGER);
PROCEDURE [ccall] RealArray (VAR procedure: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len: INTEGER; VAR x: ARRAY [untagged] OF REAL; VAR lenX, res: INTEGER);
PROCEDURE [ccall] SetRoot (VAR root: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len: INTEGER);
PROCEDURE [ccall] SetTempDir (VAR tempDir: POINTER TO ARRAY [untagged] OF SHORTCHAR;
VAR len: INTEGER);
PROCEDURE [ccall] UseBufferFile;
PROCEDURE [ccall] UseConsole;
END BugsC.
In the C language this reads
void BugsCmd(char **command, int *len)
void CLI ()
void CharArray (char **procedure, int *len, char **x, int *lenX, int *res)
void CmdInterpreter (char **command, int *len, int *res)
void Guard (char **procedure, int *len, int *x, int *res)
void Integer (char **procedure, int *len, int *x, int *res)
void IntegerArray (char **procedure, int *len, int *x, int *lenX, int *res)
void Real (char **procedure, int *len, double *x, double *y, int *res)
void RealArray (char **procedure, int *len, double *x, int *lenX, int *res)
void SetRoot (char **root, int *len)
void SetTempDir(char **tempDir, int *len)
void UseBufferFile ()
void UseConsole ()
The first two procedures in the library provide an interface to the BUGS scripting language and ClassicBUGS. BugsCmd takes one string argument 'command' and executes this command if it is a valid command in the BUGS scripting language. The CLI procedure sets up the ClassicBUGS command line interface and will terminate when 'quit' is typed at the command prompt. The first time CLI is called, a welcome message should be displayed on the console.
The UseBufferFile and UseConsole procedures can be used to direct output to a buffer file or to the console. The buffer file is always called buffer.txt, but the directory into which it is created can be changed by the procedure SetTempDir. SetRoot sets the root directory that OpenBUGS will search from to find a file. If SetRoot is not called, OpenBUGS uses the current directory of the invoking process.
Procedures CharArray, CmdInterpreter, Guard, Integer, IntegerAray, Real and RealArray provide an interface to Component Pascal procedures in the OpenBUGS software.They allow named procedures in the OpenBUGS software to be called. The string argument 'procedure' is the name of the Component Pascal procedure to be called. 'procedure' is literally the name of the module containing the procedure, a period, and then the name of the procedure. In the above declarations 'res' is the exit status.The 'res' argument is set to a non zero value if it is not possible to call the Component Pascal procedure. This could be because the module or procedure does not exist (res = 1), the procedure was called with the wrong type of argument (res = 2) or the procedure has the wrong signature (res = 3).
CharArray calls a procedure which takes an array of characters as argument. Integer calls a procedure which returns an integer (or boolean). IntegerArray calls a procedure which takes an array of integer as argument. Real calls a procedure which takes an 8 byte real as argument and returns an 8 byte real. RealArray calls a procedure which takes an array of 8 byte reals as argument. In general array arguments to these procedures can either be VAR, IN or OUT parameters and for the case of CharArray a value parameter is also allowed.
The CmdInterpreter, is able to interpret a quite general sequence of semi-colon delimited Component Pascal procedures. These procedure can take literal value parameters, which must be given after the procedure name as string literals within parenthesis (string arguments need to be enclosed in single quotes). The Guard procedure calls a Component Pascal procedure that has a single boolean argument of OUT type. If this procedure sets the boolean to true Guard sets its x argument to one otherwise to zero. The Guard procedure can be used to test for some logical condition before calling further Component Pascal procedure. "Guard" procedures can be embeded in the string of procedure passed to CmdInterpreter to short circuit execution of commands if a logical condition fails.
Where a function has a string or array type argument, the next argument the signature is an integer giving the length of the string or array.
Two examples of using the BRugs library to interface to R/Splus are
"modelCheck" <-
function(fileName)
# Check that OpenBUGS model is syntactically correct
{
path <- dirname(fileName)
path <- if(path == ".") getwd() else path
fileName <- file.path(path, basename(fileName))
if(!file.exists(fileName))
stop("File ", fileName, " does not exist")
if(file.info(fileName)$isdir)
stop(fileName, " is a directory, but a file is required")
command <- paste("BugsEmbed.SetFilePath(", sQuote(fileName),
");BugsEmbed.ParseGuard;BugsEmbed.Parse", sep = "")
if (!is.R()) {
command <- gsub ("\\\\", "/", command)
command <- gsub ("//", "/", command)
}
.C("CmdInterpreter", command, nchar(command), integer(1), PACKAGE = "BRugs")
if(getOption("BRugsVerbose"))
buffer()
}
and
"currentValues" <-
function(nodeLabel)
# Get current value of node
{
nodeLabel <- as.character(nodeLabel)
command <- "BugsRobjects.SetVariable"
len <- nchar(command)
.C("CharArray", command, as.integer(len), nodeLabel, nchar(nodeLabel), integer(1), PACKAGE="BRugs")
command <- "BugsRobjects.GetSize"
nodeSize <- .C("Integer", command, nchar(command), integer(1), integer(1), PACKAGE="BRugs")[[3]]
if(nodeSize == -1)
stop(nodeLabel, " is not a node in BUGS model")
command <- "BugsRobjects.GetValues"
.C("RealArray", command, nchar(command), as.real(rep(NA, nodeSize)),
as.integer(nodeSize), integer(1), NAOK = TRUE, PACKAGE="BRugs")[[3]]
}
Note in the second R function the allocation of the array variable which will contain the current values of the node is done in R.