BUGS Developer Manual
Version 2.1.1, June 2005
Andrew Thomas 1
1 Dept of Mathematics & Statistics,
University of Helsinki
Helsinki
Finland
e-mail: ant@rni.helsinki.fi
Contents
Introduction
Compiling the Source Code
Executable versions
Initializing OpenBUGS
Distributing OpenBUGS
Writing BUGS Extensions
Random Number Generators
Sampling Algorithms
OpenBUGS Source Code
The Bugs subsystem
The Compare subsystem
The Correl subsystem
The Deviance subsystem
The Doodle subsystem
The Graph subsystem
The Html subsystem
The Lin subsystem
The Maps subsystem
The Math subsystem
The Monitors subsystem
The Plots subsystem
The Ranks subsystem
The Samples subsystem
The Spatial subsystem
The Summary subsystem
The Updater subsystem
Miscellaneous
The C Source Code for LinBUGS
Introduction [top]
The OpenBUGS software is writen in the language Component Pascal (CP) a slight refinement of Oberon2 which is an object orientated developement of Modula2. Like Modula2 CP is a modular programming language, each module having a well defined interface. CP is a type safe garbage collected language with features in common with Java. CP software consists of a number of modules that are loaded and linked as needed at run time. The tools to develope CP software are available (free of charge) from Oberonmicrosystems at www.oberon.ch. They are called "BlackBox". The OpenBUGS software has been developed with version 1.5 Beta of the BlackBox tools. The BlackBox distribution contains a component framework of precompiled CP modules, a complete description of the CP language plus an extensive tutorial on the use of the BlackBox tools. OpenBUGS and in particular its graphical user interface WinBUGS makes heavy use of the the BlackBox component framework. The BlackBox tools are unique to Windows but CP source code can be compiled to Java Byte Code or .Net assemblies using alternative tools from GardensPoint at www.citi.qut.edu.au/research/plas/projects/cp_files/index.jsp .
The OpenBUGS software consists of a (large) number of files organised in a set of subsystems. The current OpenBUGS software contains the following subsystems: Bugs, Compare, Correl, Deviance, Doodle, Graph, Html, Lin, Maps, Math, Monitors, Plots, Ranks, Samples, Spatial, Summary, Updater. Each subsystem usually contains five subdirectories /Mod, /Rsrc, /Code, /Sym and /Docu. The "source" code of OpenBUGS consists of two type of file: the CP source code in subdirectories /Mod and the resources in subdirectories /Rsrc. The resource directories contain such things as dialog boxes, menu systems, error messages and configuration files. The run time code of BUGS consists of compiled binary code files in subdirectories /Code and the same resources in subdirectories /Rsrc. The /Code subdirectory contains the compiled binary code in a form akin to dynamic link libraries called ocf files (Oberon code files) but also includes extensive meta information. The /Sym subdirectories contain the interfaces for the CP modules in machine readable form called osf (Oberon symbol files). Both the ocf and osf files are produced by the compiler from the CP source code.The interface of a module is specified in the source code using a simple mark up language. If a CP module imports another module the symbol file of the imported module is needed by the compiler. The symbol files are not needed to run the BUGS software and conversely the ocf are not needed to compile the CP source code but are needed to run the BUGS software. The /Docu of a subsystem contain software documentation. Some of the subdirectories in the OpenBUGS distribution only contain /Code and /Rsrc subdirectories. These are the libraries provided by Oberonmicrosystem. The symbol files and documentation for these libraries are included with the BlackBox tools. Oberonmicrosystems has made BlackBox available under the Lazy Cat open source license.
The source code and documentation for the OpenBUGS software is in odc files (oberon document files), the native document format of BlackBox. This document format can be translated automatically into HTML or ascii. The OpenBUGS software source will be made available on the web as HTLM documents under the GNU GPL licence. OpenBUGS is able to import these HTML documents (either drag the html file icon into OpenBUGS or use the File Open menu with the file type set to html) these imported files can then be saved as odc files.
BlackBox uses the subsystem name as a prefix to the module name and uses this prefix to determine the physical location of the module in the file system. For example the module SamplesIndex has CP source code in file Index.odc in subdirectory Samples/Mod and when compiled will produce the code file Index.ocf in subdirectory Samples/Code and and the interface file Index.osf in subdirectory Samples/Sym. The documentation for the module SamplesIndex should be called Index.odc and placed in subdirectory Samples/Docu. The BlackBox developement tools use this prefix naming convention to locate relevent information.
OpenBUGS contains two types of subsystems: one type implements class hierarchies and the other procedural libraries. In general each procedural type subsystem has four levels of interface: a GUI level interface in the Cmds module, a scripting level interface in the Embed module, an interface that outputs to an abstract formatter class in the Formatter module and a Component Pascal interface in the Interface module.
Compiling the Source Code [top]
The BlackBox tools can be downloaded as a self extracting Windows exe file from www.oberon.ch . This unpacks into a directory called BlackBox in Program Files. The zipped distribution of the OpenBUGS source code can be uncompressed and copied into the BlackBox directory directory by directory. To compile the complete Component Pascal source code open the make file and use the mouse to click into the round blob containing an ! mark. If the compiler detects an error in a module the compilation will stop at that module which will be opened in a window with the error marked and described. If the directory into which the compiler wishes to place a code or symbol file does not exist the user will be prompted to create the directory. Note that if you change the interface to a module your new module will not be able to work with other developers versions of OpenBUGS. The Component Pascal module loader checks the "finger prints" (crytographic check sums) of each module it loads against the "finger prints" the importing module expects and flags an error if these are inconsistant.
OpenBUGS can be run from inside the BlackBox developement enviroment. Indeed this has the advantage of making the full BlackBox debugger (DevDebug) available for diagnosing run time traps. The exact point in the source code where the problem occurs is usually detected!
There also a few other modules in the OpenBUGS source code. These files need to the compiled when the executable version are linked (see below)
Executable versions [top]
The OpenBUGS software family is unusual in consisting of a large number of unlinked modules. These modules are linked at run time as required by the module link loader StdLoader. This loader is packed together with a few other service modules and possibly a special module Init into a small .exe or .dll / so file. These .exe and .dll / so files know nothing about the OpenBUGS software and are quite generic. The StdLoader module caues the body of a module called Init to be executed. If the module Init is not linked into the .exe file or the .dll / so StdLoader will load and link it. Various implementations of Init are possible giving rise to software with different functionality.
There are various ways of running the OpenBUGS software on computers with the Microsoft Windows operating system. winbugs.exe and bugs.exe are small Microsoft Windows program which loads code files (ocf) as needed. The bugs.exe program is run from the shortcut ClassicBUGS and has a similar interface to the old "ClassicBUGS" software. This shortcut sets the properties of the dos window used by the dos.exe program. A second shortcut BackBUGS runs winbugs with the file name specified on the command line, after the key word /SCRIPT, used as a source of commands in a BUGS script. This allows another program to call BUGS to do MCMC. The BackBUGS shortcut has been set up so that no window opens while BUGS runs. This can be changed by editing the shortcut so that "/HEADLESS" is removed from the command line.
brugs.dll is a small dynamic link library that can load ocf files as needed. The brugs dynamic link library was designed for use from within R and only loads ocf files that do not depend on Microsoft Windows. It is also possible to use the brugs dynamic link library from within a general C program. The pro cedures exported by the brugs library are specified in the module Bugs C.
In general the ocf files are not operating system dependent. In the make file those modules in black should be usable from Linux. We have produced a Linux ELF shared object file, bugs.so, equivalent of the bugs.exe file for running the BUGS software on the Linux platform. This bugs.so needs loading using dlopen from within a small C program. A second ELF shared object file brugs.so provides the R interface on Linux.
The R functions for interfacing to the brugs dynamic link library are in the BRugs package on CRAN. The names of these R functions are the same as in the OpenBUGS scripting language and have the same function. Both the scripting language and the R functions use metaprogramming to communicate with OpenBUGS, see the module BugsStdInterpreter for details.
To make the executable versions of the OpenBUGS software a linker tool is used to pack several code (ocf) files into one exe or dynamic link library (shared object file on Linux). The linker is given a list of module names (in the form subsystem prefix followed by a file name). The linker searches for the ocf file in the code subdirectory of the subsystem with the appropiate file name. Note that this ocf might correspond to a module with a name different to the name given to the linker (for example the code file found the linker finds for LinConsole --Lin/Code/Console.ocf-- corresponds to a module Console and not LinConsole)
ClassicBUGS uses the Console module for input and output. There are two version of the the module Console one for the Windows platform and the other for the Linux platform. On Windows the Console module makes calls to the Windows API while on Linux it makes calls to the C runtime library. There are several versions of the Init module. The winbugs.exe program links at runtime with the version of the Init module found in the Code subdirectory if it exists otherwise it links with the version in System/Code subdirectory. For winbugs.exe to function correctly it must link with the latter Init module, that is the file Code/Init.ocf must not exist (the Code/Init.ocf file sets up the Windows interface for WinBUGS and also for BlackBox). The bugs.exe and bugs.so files link a version of the Init module that sets up the command line interpreter. This versions of the Init module is in Bugs/Mod/Init.odc. The source code file Init.odc in the root directory contains an empty implementation of the Init module. This empty implementation is linked into the brugs.dll and brugs.so libraries to prevent them loading the Windows interface.
To create the winbugs.exe file click in the round .blob containing an ! mark with the mouse
DevCompiler.CompileThis BugsConsole BugsConfig
DevLinker.Link
winbugs.exe := Kernel$ + Files HostFiles StdLoader Console
1 Bugslogo.ico 2 Doclogo.ico 3 SFLogo.ico 4 CFLogo.ico 5 DtyLogo.ico
6 folderimg.ico 7 openimg.ico 8 leafimg.ico
1 Move.cur 2 Copy.cur 3 Link.cur 4 Pick.cur 5 Stop.cur 6 Hand.cur 7 Table.cur
To create the classic version bugs.exe file c lick on the round blobs below containing an ! mark.
DevCompiler.CompileThis BugsConsole BugsInit
DevLinker.Link
dos bugs.exe := Kernel$+ Files HostFiles StdLoader Console Init 1 Bugslogo.ico
Finally delete the Init code file created: Code/Init.ocf.
THIS IS VERY IMPORTANT BLACKBOX / WINBUGS WILL NOT START UP IF THIS FILE EXISTS!!!
To create the brugs.dll file click in the round blob below containing a ! mark with the mouse.
DevCompiler.CompileThis BugsConsole
next open the file Init.odc in the root directory and compile it (Ctl key + k key) and then click in the round blob below containing a ! mark with the mouse.
DevLinker.LinkDynDll
brugs.dll := Kernel$+ Meta Files HostFiles StdLoader Init Console BugsInterpreter BugsC#
Finally delete the Init code file created: Code/Init.ocf.
THIS IS VERY IMPORTANT BLACKBOX / WINBUGS WILL NOT START UP IF THIS FILE EXISTS!!!
(*
Please note I am the only person who has the ELF linker at present.
*)
To create the classic version of bugs as a so file c lick on the round blobs below containing an ! mark.
DevCompiler.CompileThis LinConsole BugsInit
DevElfLinker.LinkDynDll
bugs.so := LinKernel$+ Files LinHostFiles StdLoader Console Init
Finally delete the Init code file created: Code/Init.ocf.
THIS IS VERY IMPORTANT BLACKBOX / WINBUGS WILL NOT START UP IF THIS FILE EXISTS!!!
The small C program to load the bugs.so on Linux is here CBugs
To create an ELF version of brugs.so for Intel Linux click in the round blobs containg an ! mark with the mouse.
DevCompiler.CompileThis LinLibc LinConsole
next open the file Init.odc in the root directory and compile it (Ctl key + k key) and then click in the round blob below containing a ! mark with the mouse.
DevElfLinker.LinkDynDll
brugs.so := LinKernel$+ Files LinHostFiles StdLoader Meta Init Console BugsInterpreter BugsC#
Finally delete the Init code file created: Code/Init.ocf.
THIS IS VERY IMPORTANT BLACKBOX / WINBUGS WILL NOT START UP IF THIS FILE EXISTS!!!
Initializing OpenBUGS [top]
Before the OpenBUGS software runs it needs to be initialized. The winbugs.exe version of the software is initialized in module BugsConfig. The bugs.exe and bugs.so versions of the software are initialized in BugsCLI. The the brugs.dll and brugs.so versions of the OpenBUGS software export a procedure Initialize which take two string arguments to inform OpenBUGS in which directory the OpenBUGS software is installed and into which directory OpenBUGS should write files.
Distributing OpenBUGS [top]
OpenBUGS consists of many seperate files in a complex directory structure. Some tools have been developed to copy the files needed for the run time, source and web version of OpenBUGS to seperate directories. These tools also translate OpenBUGS documentation from the odc format into html if appropiate and source code files into plain text files with the extension cp. These tools are in the module DevDistribute and the dialog boxes are in directory Dev/Rsrc (just use the file dialog to open the dialog box and click on the button. The OpenBUGS software uses several shortcuts / scripts, the directory paths in these files depend on where the OpenBUGS software is installed and might need editing.