rjags Introduction Parameters: How to determine the parameters of a statistical model

Transcription

1 January 25, 207 File = E:\inet\p548\demo.04-2.rjags.intro.docm John Miyamoto ( jmiyamot@uw.edu) Psych 548: Bayesian Statistics, Modeling & Reasoning Winter 207 Course website: rjags Introduction rjags is an R package; its function create an interface between R and JAGS. This document provides a brief introduction to functions that send information from R to JAGS, thereby defining the statistical model and data that determine the posterior distribution from which JAGS must draw a sample, and functions that transfer the results of this computation back to R. Contents (Cntrl-left click on a link to jump to the corresponding section) Section Topic Basic Steps in Running JAGS with rjags Annotated code for a typical rjags run Functions in the rjags package Parameters: How to determine the parameters of a statistical model The structure of coda.samples output 6 # End of Contents Table Random seeds: Setting random number generators for JAGS. Basic Steps in Running JAGS with rjags TOC The following are typical steps in running JAGS with rjags. There are ways to alter these steps that won't be discussed here. PRELIMINARIES TO THE JAGS RUN: (i) Run R. Load rjags onto the search path by using the library or require function. (ii) Create a model file. This is a text file written in the JAGS language that defines the statistical model that is assumed to generate the data. This step is very important. The model file defines the model(s) that you are intending to study. You must know (keep a record of) the name of the model file, the names of every data object (vector, matrix, list) that you intend to pass from R to JAGS. You must know the names of every parameter in your model. (iii) In R, create a named list whose components are the data objects (vectors, matrices, lists) that you intend to pass to JAGS. These names must be identical to the variable names that reference these objects in the model file. (iv) Create variables that define how the JAGS run should proceed. These variables include things like the number of chains of samples to compute, how many burnin samples to compute, which parameter values should be sent back to R and which can be discarded, etc. rjags FUNCTIONS FOR RUNNING JAGS: jags.model This function tells JAGS what is the model that you are fitting, what are the data, what are the initial values of parameters, how many chains, and how many adaptation steps. update The update function is not part of the rjags package; rather it is part of the standard R installation. The update function has many uses in classical statistical procedures as well as in Bayesian statistical procedures. From the standpoint of running JAGS, the update function is used to run the burnin samples. JAGS computes the samples for the burnin sample but it does not save them. Alternatively, you can create a named list whose components are the names of the data objects that you intend to pass to JAGS. This has the same effect when you run JAGS.

2 January 25, 207 File = E:\inet\p548\demo.04-2.rjags.intro.docm 2 coda.samples jags.samples This function tells JAGS to compute the samples that you want to save and return to R. The samples are returned to R in the form of an MCMC list, which is a special kind of list that is designed for exploring convergence diagnostics. This function serves a similar purpose to the coda.samples function. The primary difference between coda.samples and jags.samples is in the structure of the output of these functions. Both functions draw samples from the posterior distribution, given an appropriate data set and definition of a model. The output from the coda.samples function is designed to serve as inputs to the convergence diagnostic functions in the coda package. As a practical matter, you only need to work with one of these functions since the output from either function can be transformed into the structure of the output from the other function. The remainder of this document will discuss only the coda.samples function. 2. Annotated code for a typical rjags run TOC Table. Variables in R that control the rjags run # R Code # Explanation # Set run parameters (settings that control the run) : model.file = "name of model file" datalist = list(... ) parameters =... n.chains =... # Method for setting initial values inits.lst = list( list(... ),..., list(... ) ) # Method 2 for setting initial values inits.fn = function() { list(... ) } #end def of 'inits.fn =' function # Method for setting initial values inits.fn = NULL n.adapt =... n.burnin =... 2: Include path to file if necessary : Make a named list of data objects that will be passed to JAGS. Alternatively, you can simply make a list of the names of the data objects. 4: Vector of names of variables to be monitored (saved). These names appear in the model file. 5: Set number of chains 6: The initial values can be specified in a list. The list is itself comprised of lists, one component list per chain in the simulation. E.g., if you request chains at Row 5, then you should provide a list with component lists, one for each chain. The component list has named components, the names being identical to the names of parameters in the statistical model. 7: The initial values is set by a function that outputs a list. Each list has named components setting initial values for every sampled parameter in the model file. 8: If you set the initial values to NULL (or if you totally omit any specification of the initial values), then JAGS will choose initial values at random from the permissible values of parameters. This is the easiest way to deal with initial values. 9: Set the number of adaptation steps to tune the sampler. 0: Set number of iterations for burnin. n.iter =... : Set the number of samples to be kept after the burnin samples are discarded. n.thin =... 2: Set the thinning rate. # Start of rjags control of an JAGS run. j.mod = jags.model( file = model.file, data = datalist, inits = inits.lst, n.chains = n.chains, n.adapt = n.adapt ) : 4t0002_007: jags.model is used to create an object representing a Bayesian graphical model, specified with a BUGSlanguage description of the prior distribution, and a set of data. Note that the output (j.mod in this case) is not the samples from the posterior. It is a list whose components define the model. You can omit inits and n.adapt; JAGS will decide for itself how to set these values.

3 January 25, 207 File = E:\inet\p548\demo.04-2.rjags.intro.docm # R Code # Explanation update( object = j.mod, n.iter = n.burnin ) j.out = coda.samples( model = j.mod, variable.names = parameters, n.iter = n.iter, thin = n.thin ) 5: Compute burnin samples. They will not be saved. 6: coda.samples outputs the chains of samples in MCMC list format. The output is a list of class "mcmc.list". Comment : One can replace the call to coda.samples with a call to jags.samples - the latter function outputs the chains as a list of arrays. For example, if the variable sigma is not indexed, i.e., there is no sigma[], sigma[2],..., then jags.samples will output an array of dimension n.iter n.chains for the sigma variable. If the beta variable has 5 indices, beta[],..., beta[5], then jags.samples will output a list that has a beta component with dimension 5 n.iter n.chains. Comment 2: It may be useful to apply the jags.chains function to the output from coda.samples. The syntax would be: new.chains = jags.chains( sample = j.out, model = j.mod ). Functions in the rjags package TOC Table 2. Functions in the rjags package jags Function Explanation coda.samples This is a wrapper function for jags.samples which sets a trace monitor for all requested nodes, updates the model, and coerces the output to a single mcmc.list object. jags.samples extracts random samples from the posterior distribution of the parameters of a jags model. jags.model jags.samples jags.samples and coda.samples perform the same computations, but they differ in how they structure the output. jags.samples returns the output in the form of a special kind of array in the class mcarray. coda.samples returns the output in the form of a special kind of list in the class mcmc.list. An mcmc.list object is structured to serve as input to functions in the coda package which contains a variety of functions for MCMC convergence diagnostics. jags.model is used to create an object representing a Bayesian graphical model, specified with a BUGS-language description of the prior distribution, and a set of data. Note: Its output is a specification of the model; the output is not the actual samples from the posterior distribution. Use jags.sample, coda.samples and update to compute samples. jags.samples extracts random samples from the posterior distribution of the parameters of a jags model. jags.samples and coda.samples perform the same computations, but they differ in how they structure the output. jags.samples returns the output in the form of a special kind of array in the class mcarray. coda.samples returns the output in the form of a special kind of list in the class mcmc.list. An mcmc.list object is structured to serve as input to functions in the coda package which contains a variety of functions for MCMC convergence diagnostics. read.bugsdata Read data for a JAGS model from a file. read.jagsdata Read data for a JAGS model from a file. update This function is not part of the rjags package (it is part of the stats package, which is installed by default along with the standard R installation). update can be used to sample from a posterior without saving the samples. This is useful when drawing burnin samples. ord

4 January 25, 207 File = E:\inet\p548\demo.04-2.rjags.intro.docm 4 jags Function Explanation Below: Technical functions, less important for the novice adapt Run the adaptation iterations for tuning the sampler. This function is not normally called by the user. It is called by the jags.model function when the model object is created. dic.samples Function to extract random samples of the penalized deviance from a jags model. diffdic Compare two models by the difference of two dic objects. list.factories JAGS modules contain factory objects for samplers, monitors, and random number generators for a JAGS model. These functions allow fine-grained control over which factories are active. list.factories returns a data frame with two columns, the first column shows the names of the factory objects in the currently loaded modules, and the second column is a logical vector indicating whether the corresponding factory is active or not. list.modules A JAGS module is a dynamically loaded library that extends the functionality of JAGS. These functions load and unload JAGS modules and show the names of the currently loaded modules. This function lists the currently loaded modules. list.samplers A jags object represents a Bayesian graphical model described using the BUGS language. The output displays the algorithms that have been applied to each model parameter in the computation of the MCMC chain. load.module A JAGS module is a dynamically loaded library that extends the functionality of JAGS. This function loads JAGS modules and shows the names of the currently loaded modules. parallel.seeds On a multi-processor system, you may wish to run parallel chains using multiple jags.model objects, each running a single chain on a separate processor. This function returns a list of values that may be used to initialize the random number generator of each chain. read.data OBSOLETE: This function is provided for compatibility with older versions of the rjags package and will soon be defunct. This function has been replaced with the read.jagsdata function in the current version of JAGS. set.factory JAGS modules contain factory objects for samplers, monitors, and random number generators for a JAGS model. These functions allow fine-grained control over which factories are active. set.factory is called to change the future behaviour of factory objects. If a factory is set to inactive then it will be skipped. unload.module A JAGS module is a dynamically loaded library that extends the functionality of JAGS. This function unloads JAGS modules and show the names of the currently loaded modules. ord 2 4. Parameters: How to determine the parameters of a statistical model TOC Sometimes it is advantageous to set initial values for chains of samples. At each iteration of a chain, the chain contains values for every parameter of the model. The initial values of a chain are the values of the parameters that the user specifies for the parameters of the statistical model; the user may want to examine multiple chains that have many different initial values in order to check whether some initial samples must be discarded in order to avoid undue influence from the initial values. To set initial values for the paramers, however, it is necessary to identify the parameters of the statistical model. How to do this? A researcher should be able to look at a model file and determine what are the parameters of the model. This is especially true if the researcher wrote the model file himself or herself. But sometimes this is difficult. An alternative is to run the jags.model function in rjags. Then apply the list.samplers function to the output of the jags.model function - this will produce a list of the MCMC sampling algorithm that has been applied to each parameter in the model, thereby identifying the model parameters. E.g., first run the jags.model function: jmodel = jags.model(... ) where we fill in appropriate values for the arguments of the jags.model function. Then we run:

5 January 25, 207 File = E:\inet\p548\demo.04-2.rjags.intro.docm 5 list.samplers( jmodel ) The output will show the names of the parameters that need to have initial values set for them. The variable.names function in rjags lists all variables in the model file, including constants, data variables and derived variables that do not have samplers assigned to them. The list.samplers function is more informative with regard to the question, what parameters require initial values?, because it lists only the parameters that are assigned random samplers. 5. The structure of coda.samples output TOC See the document convergence.diag.pdf that is titled, "Convergence Diagnostics: Working with coda.samples Output." 6. Random seeds: Setting random number generators for JAGS TOC See the documentation for jags.model. Random number generators are set through the specification of initial values. You need to set initial values for all model parameters. In addition, initial values are set for two additional components names.rng.name and.rng.seed..rng.name is a string that names a random number generator algorithm. See?set.seed to see the names of random number generators that are available in R. See?jags.model for the names of random number generators that are available in JAGS. RNGkind() shows the default random number generator for R. The following is an example of initial values for chains that set initial values for the JAGS random number generators: inivals = list(.rng.name = "base::mersenne-twister",.rng.seed = 2 ),.RNG.name = "base::mersenne-twister",.rng.seed = 4 ),.RNG.name = "base::mersenne-twister",.rng.seed = 6) ) # You have to set initial values for all of the parameters because if you don't, JAGS will choose initial values at random, and these choices will not be controlled by the.rng.seed that you choose in the initial values. jagsmodel = jags.model( file = "testmod.txt", data = datalist, inits = inivals, n.chains =, n.adapt = adaptsteps )