[bugsicon]    The R Model Functions

Contents

    General properties
    Model Specification
    Model Updating
   
Random Number Generator
    Options
   


General properties [top]

The R functions in this group apply to the whole statistical model. All the functions in this group have names starting with model . If an attempt is made to execute one of these model functions in an inappropiate context the generic error message 'command is not allowed (greyed out)' is displayed. If a function with a file argument displays this error message check that the file exists.

Model Specification [top]

model.check: The model.check(fileName) function parses the BUGS language description of the statistical model contained in the file of name fileName . If a syntax error is detected the position of the error and a description of the error is printed., otherwise the 'model is syntaxicaly correct' message is displayed.

model.data: The model.data(fileName) function loads data contained in the file of name fileName into the statsistical model.

   
See here for details of data formats

If any syntax errors or data inconsistencies are detected an error message is displayed. Corrections can be made to the data without returning to the
check model stage. When the data have been loaded successfully the , 'data loaded' message should appear.

The
load.data function can be executed once a model has been successfully checked, it can no longer be executed once the model has been successfully compiled.

model.compile: The model.compile(numChains = 1) function builds the data structures needed to carry out MCMC sampling. The model is checked for completeness and consistency with the data. Simulation is carried out for numChains chains. By default numChains is one.

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' mesage should be printed.

model.num.chains: The model.num.chains() function returns the number of chains being simulated

model.inits: The model.inits(fileName, chainNum) function loads initial values for the MCMC simulation contained in the file of name fileName . The initial values will be loaded for the chain number chainNum . By default chainNum is one the first time model.inits is executed and increamented by one after each call modula the number of chains numChains being simulated.

This function can be executed 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 any previously loaded data. Any syntax errors or inconsistencies in the initial value are displayed. 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.

If, after loading the initial values, the model is fully initialized this will be reported by displaying the message
'initial values loaded: model initialized' . Otherwise the message 'initial values loaded: model contains uninitialized nodes' will be displayed. 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
model.gen.inits function can be executed to try and generate initial values for all the uninitialized nodes in all 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
model.gen.inits function.

This
load.inits button can still be executed once MCMC sampling has been started. It will have the effect of starting the sampler out on a new trajectory.

model.gen.inits: The model.gen.inits function 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 function will generate extreme values if any of the priors are very vague. If the function is successful the message 'initial values generated: model initialized' is displayed otherwise the message 'could not generate initial values' is displayed.

The
model.gen.inits function can be executed once the model has been successfully compiled, and can no longer be executed once the model has been initialized.

Model Updating [top]

These functions can be executed once the model has been compiled and initialized.

model.update: The model.update(numUpdates, thin = 1, overRelax = FALSE) function updates the model by carrying out thin * numUpdates MCMC iterations for each chain. The samples from every k th iteration will be used for inference, where k is the value of thin . Setting thin > 1 can help to reduce the autocorrelation in the sample, but there is no real advantage in thinning except to reduce storage requirements. If overRelax is true 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.

model.iteration: The model.iteration() function returns the total number of iterations carried out divided by thin.

model.updates: The model.updates() function returns the number of MCMC iterations the last update function has carried out divided by thin.

model.adapting: The model.adapting() function returns true while the Metropolis or slice-sampling MCMC algorithm is in its initial tuning phase where some optimization parameters are tuned. All statistics for the model will ignore information from this adapting phase. 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 Update options...

model.adaptivePhase: The model.adaptivePhase() returns the length of the adaptive phase of the simulation. This is only known after the simulation has finished adapting. If this function is called while the simulation is still adapting MAX(INTEGER) is returned. If the simulation does not have an adaptive phase then zero is returned.

Random Number Generator [top]

model.set.seed: The model.set.seed(seed) function sets the seed of the random number generator to seed (seed must be a posative, non zero integer).

model.get.seed: The model.get.seed(seed) function returns the seed of the random number generator.

Options [top]

model.precision: The model.precision(prec) sets the precision to which results are displayed to prec figures. It does not affect the precision of any calculations.

Once a model has been compiled, the various updating algorithms required in order to perform the MCMC simulation may be 'tuned' somewhat via these three functions. The first argument of each function is a string defining which particular MCMC updating algorithm is to be tuned. Technically this string is the type name of the factory object used to create the updater, for example 'UpdaterMetnormal.Factory' for the random walk metropolis sampler. The second argument of the functions is an integer giving the new value of some internal parameter.

model.setAP: The model.setAP(factoryName, adaptivePhase) function changes the length of the updaters adaptive phase to adaptivePhase if appropiate.

model.setIts: The model.setIts(factoryName, iterations) function changes the number of times an iterative algorithm is run before a failure is reported to iterations if appropiate.

model.setOR: The model.setOR(factoryName, overRelaxation) function sets the amount of over relaxation the updater uses to overRelaxation if appropiate.