BUGS Developer Manual
Version 2.10, April 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
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 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 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, 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 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). 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 only allows the /Code and /Rsrc subdirectories of these libraries can to be distributed!
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 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.
Also included with OpenBUGS is an interface to the R programming language and a simple C program that implements a command line interface (similar to the unix ClassicBUGS software).
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. To compile the complete Component Pascal source code use the mouse to highlight the below list of modules
BugsMappers ... StdCmds1
and then pick the Compile Module List option from the BlakBox Dev menu. 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.
The modules in red form the Windows interface for OpenBUGS. OpenBUGS can be run from inside the BlackBox developement enviroment. Indeed this has the advantage of making the BlackBox debugger available for diagnosing run time traps. The HtmlPacker module contains a script for copying the OpenBUGS run time into a seperate directory.
The modules in blue are experimental. They should ease the developement of new types of node in OpenBUGS models.
BugsMappers BugsStrings BugsMeta BugsFiles
BugsC BugsMessages BugsRegistry
MathSort MathMatrix MathSparsematrix MathFunc MathRandnum MathODE MathFunctional MathRungeKutta MathRungeKutta45 MathBulirschStoer MathAESolver MathIntegrate
MathLincon
MathTT800
GraphRules GraphNodes GraphLogical GraphStochastic GraphScalar GraphVector GraphUnivariate GraphMultivariate GraphConjugateMV GraphChain GraphConstant GraphStack GraphMixture GraphFlat GraphBlock GraphFunction GraphMetFunction GraphVecFunction
UpdaterUpdaters UpdaterActions UpdaterMethods UpdaterUnivariate UpdaterMultivariate UpdaterContinuous UpdaterMetmonitor
MonitorsSamples MonitorsSummary MonitorsDeviance
BugsVersion BugsGrammar BugsScript BugsNames BugsIndex BugsVariables BugsParser BugsEvaluate BugsOptimize BugsNodes BugsCodegen BugsData BugsDeviance BugsCoder BugsRobjects BugsInterface BugsInfo BugsEmbed BugsRectData BugsSplusData
SamplesMonitors SamplesIndex SamplesInterface SamplesFormatted SamplesEmbed
SummaryMonitors SummaryIndex SummaryInterface SummaryFormatted SummaryEmbed
RanksMonitors RanksIndex RanksInterface RanksFormatted RanksEmbed
DevianceMonitors DevianceIndex DeviancePlugin DevianceInterface DevianceFormatted DevianceEmbed
CorrelInterface
CorrelFormatted CorrelEmbed
GraphCloglog GraphCut GraphEigenvals GraphGammap GraphInprod GraphInverse GraphKepler GraphLog GraphLogdet GraphLogit GraphProbit GraphProduct GraphRanks GraphPValue GraphSumation GraphTable GraphFunctional GraphODEmath GraphODElang
GraphPredictive GraphBern GraphBinomial GraphCat GraphFounder GraphGeometric GraphHypergeometric GraphMendelian GraphNegbin GraphPoisson GraphRecessive GraphMultinom GraphBeta GraphChisqr GraphDbexp GraphExp GraphF GraphGamma GraphGengamma GraphLogistic GraphLognorm GraphNormal GraphPareto GraphPolygene GraphT GraphTrapezium GraphUniform GraphWeibull GraphWeibullShifted GraphDirichlet GraphMVNormal GraphMVT GraphRENormal GraphStochtrend GraphWishart
UpdaterAM UpdaterHybrid UpdaterHybrid1D
UpdaterAMblock UpdaterBeta UpdaterCatagorical UpdaterDirichlet UpdaterDirichletprior UpdaterDFreeARS UpdaterForward UpdaterGamma UpdaterGriddy UpdaterMetover UpdaterDFreeHybrid1D UpdaterHybridgamma UpdaterDFreeHybrid UpdaterHybridnormal UpdaterHybridglm UpdaterMetbinomial UpdaterMetnormal UpdaterMultinomial UpdaterMVNormal UpdaterMVNLinear UpdaterNormal UpdaterPareto UpdaterPoisson UpdaterRejection UpdaterSCAM UpdaterGLM UpdaterSlice UpdaterWishart
SpatialBound SpatialPWDPrior SpatialCARl1 SpatialCARNormal SpatialCARProper SpatialStrucMVN SpatialDiscKrig SpatialExpKrig SpatialMaternKrig SpatialMVCAR SpatialPoissconv
GraphScalarT GraphVectorT GraphUnivariateT GraphScalartemp1 GraphVectortemp1
GraphUnivariatetemp1
BugsTexts BugsDialog
UpdaterSettings
BugsCmds
PlotsAxis PlotsViews PlotsDialog PlotsNomaxis PlotsStdaxis PlotsEmptyaxis
SamplesViews SamplesPlots SamplesCmds SamplesCorrelat SamplesDensity SamplesDiagnostics SamplesHistory SamplesQuantiles SamplesTrace
SummaryCmds
RanksDensity
RanksCmds
DevianceCmds
CompareViews CompareBoxplot CompareCaterpillar CompareModelFit CompareScatter CompareCmds
CorrelBivariate CorrelMatrix CorrelPlots CorrelCmds
DoodleNodes DoodlePlates DoodleModels DoodleMenus DoodleDialog DoodleViews DoodleParser DoodleCmds
UpdaterMetplots
MapsMap MapsImporter MapsIndex MapsAdjacency MapsViews MapsViews1 MapsCmds MapsArcinfo MapsEpimap MapsSplus
HtmlEntitySets
HtmlExporter HtmlImporter HtmlPacker HtmlPDF
Config StdCmds1
Executable versions
[top]
There are various ways of running the OpenBUGS software. winbugs.exe is a small Microsoft Windows program which loads code files (ocf) as needed. 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 C program, so writing a command line version of BUGS is straight forward (see the CBugs document).
In general the ocf files are not operating system dependent. The 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 stand alone Linux program using this shared object file is already working but is still fragile. The source code for this program is in CBugs.odc and needs saving as a .c file before compiling with gcc.
The R functions for interfacing to the brugs dynamic link library are in RCode.odc and need saving as a .R file and then sourcing into R. 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 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 brugs.dll file highlight the red
"
MODULE Init; END Init
."
and pick
"Compile Selection" from the "Dev" menu. Next
click in the round blob containing a ! mark (just before DevLinker) with the mouse. Finally delete the Init code file created: Code/Init.ocf.
THIS IS VERY IMPORTANT BLACKBOX / WINBUGS WILL NOT START UP IF THIS FILE EXISTS!!!
DevLinker.LinkDynDll
brugs.dll := Kernel$+ Init Meta Files HostFiles StdLoader Math Strings
BugsMappers BugsStrings BugsMeta BugsC#
To create an ELF version of brugs.so for Intel Linux click in the first round blob containg an ! mark with the mouse.
To link a self contained version of the brugs.so, one which does not need to load modules at run-time,
click in the second round blob with the mouse.
(*
Please note I am the only person who has the ELF linker at present.
*)
DevElfLinker.LinkDynDll
brugs.so := LinKernel$+ LinInit Meta Files LinHostFiles StdLoader Math Strings
BugsMappers BugsStrings BugsMeta BugsC#
DevElfLinker.LinkDynDll
bigbrugs.so := LinKernel$+ LinInit Meta Files LinHostFiles StdLoader Math Strings
BugsMappers BugsStrings BugsMeta BugsC#
BUgsFiles BugsMessages BugsRegistry
Services
MathSort MathMatrix MathSparsematrix MathFunc MathRandnum MathODE MathFunctional MathRungeKutta MathRungeKutta45 MathBulirschStoer MathAESolver MathIntegrate
GraphRules GraphNodes GraphLogical GraphStochastic GraphScalar GraphVector GraphUnivariate GraphMultivariate GraphConjugateMV GraphChain GraphConstant GraphStack GraphMixture GraphFlat GraphBlock GraphFunction GraphMetFunction GraphVecFunction
UpdaterUpdaters UpdaterActions UpdaterMethods UpdaterUnivariate UpdaterMultivariate UpdaterContinuous UpdaterConjugate UpdaterBlock UpdaterConjugateMV UpdaterMetmonitor
MonitorsSamples MonitorsSummary MonitorsDeviance
BugsVersion BugsGrammar BugsScript BugsNames BugsIndex BugsVariables BugsParser BugsEvaluate BugsOptimize BugsNodes BugsCodegen BugsData BugsDeviance BugsCoder BugsInterface BugsInfo BugsEmbed BugsRectData BugsSplusData BugsRobjects
SamplesMonitors SamplesIndex SamplesInterface SamplesFormatted SamplesEmbed
SummaryMonitors SummaryIndex SummaryInterface SummaryFormatted SummaryEmbed
RanksMonitors RanksIndex RanksInterface RanksFormatted RanksEmbed
DevianceMonitors DevianceIndex DeviancePlugin DevianceInterface DevianceFormatted DevianceEmbed
CorrelInterface
CorrelFormatted CorrelEmbed
GraphCloglog GraphCut GraphGammap GraphInprod GraphInverse GraphKepler GraphLog GraphLogdet GraphLogit GraphProbit GraphProduct GraphRanks GraphPValue GraphSumation GraphTable GraphFunctional GraphODEmath GraphODElang
GraphPredictive GraphBern GraphBinomial GraphCat GraphFounder GraphGeometric GraphHypergeometric GraphMendelian GraphNegbin GraphPoisson GraphRecessive GraphMultinom GraphBeta GraphChisqr GraphDbexp GraphExp GraphF GraphGamma GraphGengamma GraphLogistic GraphLognorm GraphNormal GraphPareto GraphPolygene GraphT GraphTrapezium GraphUniform GraphWeibull GraphWeibullShifted GraphDirichlet GraphMVNormal GraphMVT GraphRENormal GraphStochtrend GraphWishart
UpdaterBeta UpdaterCatagorical UpdaterDirichlet UpdaterDirichletprior UpdaterDFreeARS UpdaterForward UpdaterGamma UpdaterGriddy UpdaterMetover UpdaterHybrid1D UpdaterDFreeHybrid1D UpdaterHybridgamma UpdaterHybrid UpdaterDFreeHybrid UpdaterHybridnormal UpdaterHybridglm UpdaterMetbinomial UpdaterMetnormal UpdaterMultinomial UpdaterMVNormal UpdaterMVNLinear UpdaterNormal UpdaterPareto UpdaterPoisson UpdaterRejection UpdaterGLM UpdaterSlice UpdaterWishart
SpatialBound SpatialPWDPrior SpatialCARl1 SpatialCARNormal SpatialCARProper SpatialStrucMVN SpatialDiscKrig SpatialExpKrig SpatialMaternKrig SpatialMVCAR SpatialPoissconv