The Model Menu

Contents

   General properties
   Specification...
   Update...
   Save State
   Random number generator...
   Script
   Pretty print
   Latex
   Input / Output options...
   Compile options...
   Updater options...
   Externalize
   Internalize

   
General properties [top]

The commands in this menu either apply to the whole statistical model or open dialog boxes.


Specification... [top]


            


This non-modal dialog box acts on the focus view.

check model : If the focus view contains text, WinBUGS assumes the model is specified in the BUG S language. The check model button parses the BUG S language description of the statistical model. If a syntax error is detected the cursor is placed where the error was found and a description of the error is given on the status line (lower left corner of screen). If a stretch of text is highlighted the parsing starts from the first character highlighted (i.e . highlight the word model) else parsing starts at the top of the window.

If the focus view is a Doodle or contains a selected Doodle (i.e. the Doodle has been selected and is surrounded by a hairy border ), WinBUG S assumes the model has been specified graphically. If a syntax error is detected the node where the error was found is highlighted and a description of the error is given on the status line.

load data: The load dat a button acts on the focus view; it will be greyed out unless the focus view contains text.

Data can be identified in two ways:

1) if the data is in a separate document, the window containing that document needs to be the focus view (the windows title bar will be highlighted) when the load dat a command is used;
2) if the data is specified as part of a document, the first character of the data (either list if in S-Plus format, or the first array name if in rectangular format) must be highlighted and the data will be read from there on.

See Formatting of data for details of how the data should be formatted.

Any syntax errors or data inconsistencies are displayed in the status line. Corrections can be made to the data without returning to th e check mode l stage. When the data have been loaded successfully, 'Data Loaded' should appear in the status line.

The load dat a button becomes active once a model has been successfully checked, and ceases to be active once the model has been successfully compiled.

num of chains: The number of chains to be simulated can be entered into the text entry field next to the caption num of chains . This field can be typed in after the model has been checked and before the model has been compiled. By default, one chain is simulated.

compile: The compil e button builds the data structures needed to carry out MCMC sampling. The model is checked for completeness and consistency with the data.

A node called 'deviance' is automatically created which calculates minus twice the log-likelihood at each iteration, up to a constant. This node can be used like any other node in the graphical model.

This command becomes active once the model has been successfully checked, and when the model has been successfully compiled, 'model compiled' should appear in the status line.

load inits: The load init s button acts on the focus view: it will be greyed out unless the focus view contains text. The initial values will be loaded for the chain indicated in the text entry field to the right of the caption for chai n. The value of this text field can be edited to load initial values for any of the chains.

Initial values are specified in exactly the same way as data files. If some of the elements in an array are known (say because they are constraints in a parameterisation), those elements should be specified as missing (NA) in the initial values file.

This command becomes active once the model has been successfully compiled, and checks that initial values are in the form of an S-Plus object or rectangular array and that they are consistent with the model and any previously loaded data. Any syntax errors or inconsistencies in the initial value are displayed.

If, after loading the initial values, the model is fully initialized this will be reported by displaying the message initial values loaded: model initialize d. Otherwise the status line will show the message initial values loaded but this or another chain contain uninitialized variables . The second message can have several meanings:

a) If only one chain is simulated it means that the chain contains some nodes that have not been initialized yet.
b) If several chains are to be simulated it could mean that no initial values have been loaded for one of the chains.

In either case further initial values can be loaded, or the gen init s button can be pressed to try and generate initial values for al l the uninitialized nodes in al l the simulated chains.

Generally it is recommended to load initial values for all fixed effect nodes (founder nodes with no parents) for all chains, initial values for random effects can be generated using the gen init s button.

The load init s button can still be executed once the MCMC sampling has been started. It will have the effect of starting the sampler out on a new trajectory. A modal warning message will appear if the command is used in this context.
      
gen inits: The gen init s button attempts to generate initial values by sampling either from the prior or from an approximation to the prior. In the case of discrete variables a check is made that a configuration of zero probability is not generated. This command will generate extreme values if any of the priors are very vague. If the command is successful the message 'initial values generated: model initialized' is displayed otherwise the message 'could not generate initial values' is displayed .

The gen init s button becomes active once the model has been successfully compiled, and will cease to be active once the model has been initialized.


Update... . [top]

         

This menu will become active once the model has been compiled and initialized, and has fields:

updates : update s * thi n MCMC updates will be carried out.

refresh : the number of updates divided by thi n between redrawing the screen.

thin : the samples from every k ^th iteration will be used for inference, where k is the value of thi n. Setting k > 1 can help to reduce the autocorrelation in the sample, but there is no real advantage in thinning except to reduce storage requirements.

update : Click to start updating the model. Clicking on updat e during sampling will pause the simulation after the current block of iterations, as defined by refres h, has been completed; the number of updates required can then be changed if needed. Clicking on update again will restart the simulation. This button becomes active when the model has been successfully compiled and given initial values.

iteration : the total number of iterations carried out divided by thin.

over relax : click on this box (a tick will then appear) to select an over-relaxed form of MCMC (Neal, 1998) which will be executed where possible. This generates multiple samples at each iteration and then selects one that is negatively correlated with the current value. The time per iteration will be increased, but the within-chain correlations should be reduced and hence fewer iterations may be necessary. However, this method is not always effective and should be used with caution. The auto-correlation function may be used to check whether the mixing of the chain is improved.

adapting : This box will be ticked while the Metropolis or slice-sampling MCMC algorithm is in its initial tuning phase where some optimization parameters are tuned. The Metropolis and slice-sampling algorithms have adaptive phases of 4000 and 500 iterations respectively which will be discarded from all statistics. For details of how to change these default settings please see


Save State [top]

Opens windows showing the current state of all the stochastic variables in the model, displayed in S-Plus format for each chain. These could then be used as an initial value file for future runs.


Random number generator... . [top]

         

Opens a non-modal dialog box containing:

seed: a text entry field where the new seed of the random number generator can be typed.

state : the random number gererator can have an internal state described by multiple integer values. This variable tells the generator which internal state integer is to be replaced by seed.

coverage: the pseudo-random number generator used by OpenBUGS generates a finite (albeit very long) sequence of distinct numbers, which would eventually be repeated if the sampler were run for a sufficiently long time. The coverage field shows the percentage of this sequence covered during the current OpenBUGS session.

set: sets the currently selected internal state variable of the random number generator to the value entered into the seed field. The seed must be set after the model is checked (via 'check model' - see Specification... ) in order for the new value to apply to the current analysis.


Script [top]

The Script command is used to run "model scripts" in batch-mode: if the focus-view contains a series of OpenBUGS batch-mode commands then selecting this command from the Model menu will cause the script to be executed. Please see Batch-mode: Scripts for full details.


Pretty print [top]

Opens a new window containing the BUGS language code describing the currently checked model. This model can have either been specified in the BUGS language or as a Doodle . Any comments in the origonal BUGS language description will be lost. The BUGS langguage code will be formatted in a standardized form.

For example if the model described by this Doodle is checked the pretty print option will open a windows containing the BUGS language code below


                  


Latex [top]

Opens a new window containing the Latex code describing the currently checked model. This model can have either been specified in the BUGS language or as a Doodle . Any comments in the origonal BUGS language description will be lost.

For example if this model is checked then the latext option will produce the below latex

                model {
                   for (i in 1:K) {
                      for (j in 1:n) {
                         Y[i, j] ~ dnorm(eta[i, j], tau.C)
                         eta[i, j] <- phi[i, 1] / (1 + phi[i, 2] * exp(phi[i, 3] * x[j]))
                      }
                      phi[i, 1] <- exp(theta[i, 1])
                      phi[i, 2] <- exp(theta[i, 2]) - 1
                      phi[i, 3] <- -exp(theta[i, 3])
                      for (k in 1:3) {
                         theta[i, k] ~ dnorm(mu[k], tau[k])
                      }
                   }
                   tau.C ~ dgamma(1.0E-3, 1.0E-3)
                   sigma.C <- 1 / sqrt(tau.C)
                   varC <- 1 / tau.C
                   for (k in 1:3) {
                      mu[k] ~ dnorm(0, 1.0E-4)
                      tau[k] ~ dgamma(1.0E-3, 1.0E-3)
                      sigma[k] <- 1 / sqrt(tau[k])
                   }
                }

            
            
Processing the latex code gives

         
         
Input / Output options... [top]

         
         
The model specification tool can either take input from the focus window when Input options is set to window or from files when Input option is set to file.

OpenBUGS will either produce output in windows if Output option is set to window or produce output in the log window if Output option is set to log.

The precision to which OpenBUGS displays output is controlled by the output precision field.


Compile options... [top]

         
         
compile logicals : OpenBUGS tries to write and compile new Component Pascal classes to represent logical nodes in the statistical model. This option is only valid with WinBUGS as it relies on run time linking.

updater by method : OpenBUGS chooses update algorithms for the model in a by method order if this box is checked otherwise updaters are choosen by order of node name.

use chain graph : OpenBUGS tries to rewrite random effects in terms of a chain graph.

seperate generators : OpenBUGS uses independent random number generators for each chain simulated. This should give the same chains as running one chain on each of multiple processors provided the processor index field has been set appropiately. The random number generator for each chain is initialized to a state labeled by the chain index.

trap on error : Causes OpenBUGS to trap when an error occurs. Useful option for finding difficult errors.

processor index : OpenBUGS initializes the chain of random numbers used in the simulation to a well defined state labelled by this integer provided that the seperate generator box is not checked.


Updater options [top]

Tabbed dialog box for controlling how OpenBUGS updates the model.

The first tab is used to influence which updater algorithms are used while the second tab is used to adjust the default parameters of the choosen algorithms.

The updater (sampler) algorithms that OpenBUGS has available are displayed in the list box underneath "sampler". The radio button can be used to enable / disable the selected sampler. These radio buttons are only active when a model has not been compiled. They control which algorithms OpenBUGS will consider using when the model is compile. Once the model has been compiled it is possible to change the algoithm used for a node (or block of nodes) by typing the node in question in the text entry box underneath "change updater for", selecting a new updater algorithm from the list and clicking ok.

         
         
         
The second tab of the dialog displays the actual updater algorithms used in sampling the compiled mode in a list. To change the default parameters of one of these updaters select it from the list and then edit the appropiate fields and click set. The new parameter values will be used until the end of the current OpenBUGS session. Clicking save will make changes to the default parameters of the algorithm persistent across OpenBUGS sessions.

         



Externalize [top]

This option writes out all the internal data structures that OpenBUGS has created for a running model to a file called restart.bug. It provides a way of "saving" the model for future use.


Internalize [top]

This option reads in all the internal data structures that OpenBUGS needs to set up a running model from a file called restart.bug. It provides a way of "restarting" the model for further use. This option will open a window containing a BUGS language description of the resarted model and all the tool dialogs will be restored to the state they had when the model was last running.

As an example of the Externalize / Internalize options a running version of the Rats model has been saved in the restart.bug file in this distribution of OpenBUGS. Selecting the Internalize option open a new window displaying

         

While opening the Update Tool will show that the model has been updated for 2000 iteration

         
         
Similarly opening the Samples Tool will show that the variables alpha0 and sigma have been monitored

         
      
Statistics for alpha0 and sigma can be calculated the model can be updated for more iterations etc.

The internal data structures used by OpenBUGS can be quite large, especially if many variables are monitored for many interations of the sampler. For this reason the restart.bug file can be large. To encourage users not to save many large files the restart.bug file is always overwritten. If you want to keep this file just rename it once it has been created and then change the name back to restart.bug when you want to restart the model.