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.