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 Dos 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 ClassicBUGS
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 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, Dos, 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 an open source license.
The source code and documentation for the OpenBUGS software is in odc files, the native document format of BlackBox. This document format can be translated automatically into HTML. 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) which 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. Note that both BlackBox and OpenBUGS contain a directory called Docu. It is best to rename the BlackBox Docu directory to say BBDocu before copying over the OpenBUGS source code. 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]
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 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 /NOAPPWIN 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. The signitures of brugs exported pro cedures in C syntax are given in BRugs
In general the ocf files are not operating system dependent. In the list above those modules in black should be usable from Linux. We have produced a Linux ELF shared object file, brugs.so, equivalent of the brugs.dll for running the BUGS software on the Linux platform. A second ELF shared object file bugs.so implements a "ClassicBUGS" interface on Linux. This bugs.so needs loading using dlopen from within a small C program.
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 BugsMeta 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 file need not be the code file for module name subsystem plus file name.
To create the winbugs.exe file click in the round .blob containing an ! mark with the mouse
DevLinker.Link
winbugs.exe := Kernel$ + Files HostFiles StdLoader
1 Bugslogo.ico 2 Doclogo.ico 3 SFLogo.ico 4 CFLogo.ico 5 DtyLogo.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 DosConsole DosInit
DevLinker.Link
dos bugs.exe := Kernel$ + Files HostFiles StdLoader Math Strings 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 blobs containing a ! mark with the mouse.
DevCompiler.CompileThis LinInit
DevLinker.LinkDynDll
brugs.dll := Kernel$+ Meta Files HostFiles StdLoader Init 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!!!
To create an ELF version of brugs.so for Intel Linux click in the round blobs containg an ! mark with the mouse.
(*
Please note I am the only person who has the ELF linker at present.
*)
DevCompiler.CompileThis LinInit
DevElfLinker.LinkDynDll
brugs.so := LinKernel$+ Meta Files LinHostFiles Init StdLoader BugsInterpreter BugsC#
To create the ELF bugs.so shared object file click in the below round blobs containg an ! mark with the mouse. This so has no exported procedures but its initialization code sets up the event loop so loading this so using dlopen should be equivalent to the bugs.exe program under Windows. This so needs to be loaded by a small C program bugs.c
(*
Please note I am the only person who has the ELF linker at present.
*)
DevCompiler.CompileThis LinLibc LinConsole DosInit
DevElfLinker.LinkDynDll
bugs.so := LinKernel$+ Files LinHostFiles StdLoader Math Strings 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!!!
Initializing OpenBUGS [top]
The OpenBUGS software needs initializing when it is loaded into the computer memory. The Component Pascal procedures following the "INIT()" string in the text file /Bugs/Rsrc/Script.txt are executed when OpenBUGS is loaded. The procedures have the following purposes
BugsGrammar.LoadGrammar('Spatial/Rsrc/Grammar.txt') load an additional grammar file
MathLincon.Install Installs the linear congurance arndom number generator
The OpenBUGS software writes files to a tempory directory. The "SET_TEMP_DIR()"
script command executes the following Component Pascal procedure
BugsFiles.SetTempDir('C:/TEMP') and sets the temp direcory where files will be wriiten .
The "VERSION()" script command executes the following Component Pascal procedure
BugsFiles.ShowMsg('Weclome to OpenBUGS 2.1.1') and sets the software version number.
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. These tools are under the "Distribution" menu. 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. Also the directory for temp files (see the previous section) might need editing.