![[logo]](/bugs/images/bugslogo.gif)
Nicky Best 
-
Mary Kathryn Cowles 
-
Karen Vines 
MRC Biostatistics Unit, Institute of Public Health,
Robinson Way, Cambridge CB2 2SR, UK
Tel: 44-1223-330300, Fax: 44-1223-330388
e-mail: bugs@mrc-bsu.cam.ac.uk, ftp: ftp.mrc-bsu.cam.ac.uk
University of Nebraska Medical Center, USA
Now at Department of Epidemiology & Public Health,
Imperial College, London, UK
Now at Department of Statistics, The Open University, UK
This Addendum specifies additional features of CODA 0.4, and details corrected bugs from Version 0.3; it should be read in conjunction with the current manual for CODA 0.3 (Best et al., 1995).
CODA version 0.4 includes some minor modifications to CODA version 0.3. These relate to corrected bugs and changes to the installation procedure and graphics printing options for users running CODA under S-Plus for WINDOWS.
The following functions have been modified from version 0.3:
CODA, inddat and readdat have been modified to allow the user to change the working directory when CODA is run under S-Plus for WINDOWS. One additional function, called set.windows.home, has also been added for this purpose.
The function plot.to.file has been modified to include an option for saving graphics objects as WINDOWS metafiles when running CODA under S-Plus for WINDOWS.
The function geweke.cd in version 0.3 contained an error concerning specification of of the window widths. This has now been corrected from
cd <- (gbara - gbarb)/sqrt((power1/(a/2)) + (power2/(a/5)))to
cd <- (gbara - gbarb)/sqrt((power1/(a*func.defaults$frac1))
+ (power2/(a*func.defaults$frac2)))
To correct for sampling variability in the variance estimates of used to construct their convergence diagnostic, Gelman and Rubin (1992) use the correction factor df/(df-2), where df is the estimated degrees of freedom for a Student-t approximation to the posterior based on the simulations. This factor is incorrect and can lead to problems of infinite or negative estimates for the convergence diagnostic. The correct factor is (df+3)/(df+1) -- see Brooks and Gelman (1998), section 1.3, for further details. The function gpar has been modified accordingly in CODA version 0.4.
CODA runs under S-Plus for UNIX and S-Plus for WINDOWS (version 3.0 and above)
CODA version 0.4 may be obtained from the BUGS web site ( http://www.mrc-bsu.cam.ac.uk or by anonymous ftp from ftp.mrc-bsu.cam.ac.uk (in the directory pub/methodology/bugs). The BUGS software and documentation are also available in this ftp directory or from the web site. Alternatively, CODA may be obtained on a disk by contacting Clare Marshall at MRC Biostatistics Unit. The program is supplied as an ASCII text file called coda04.s.
source("coda04.s")
If you then wish to run CODA from a different directory (e.g. from the directory in which you have stored the output from a particular BUGS analysis), create a .Data sub-directory for this directory. Then invoke S-Plus and use the library() function to load CODA. For example, if you have installed CODA in a library directory with path /usr/fred.bloggs/myspluslib/CODA, then type:
library(CODA, lib.loc="/usr/fred.bloggs/myspluslib")
from within S-Plus. You may also create a .First function containing this command, e.g.
.First <- function() {
library(CODA, lib.loc="/usr/fred.bloggs/myspluslib")
}
This will cause CODA to be loaded automatically every time S-Plus is invoked from that particular directory.
Note: S-plus has a default library directory whose path is $SHOME/library, where $SHOME is the path of the home directory for S-plus on you system. (To identify this path, type library() at the S-plus prompt). You can move your CODA and CODA/.Data directories to $SHOME/library, in which case you can load CODA from within any S-plus session in any directory, by simply typing library(CODA).
attach("C:\\MYSLIB\\CODA\\_DATA")
source("C:\\MYSLIB\\CODA\\coda04.s")
q()
To use CODA on the results of a BUGS run, invoke S-Plus using the WINDOWS icon, and enter the following command:
library(CODA, lib.loc="C:\\MYSLIB")
You may also create a .First function containing this command, e.g.
.First <- function() {
library(CODA, lib.loc="C:\\MYSLIB")
}
This will cause CODA to be loaded automatically every time S-Plus is invoked. (Note the use of a double backslash ( \\ ) separator for directory names within S-Plus for WINDOWS).
Note: S-plus has a default library directory whose path is $SHOME\LIBRARY, where $SHOME is the path of the home directory for S-plus on you system. Usually, this is set the SPLUSWIN. You can move your CODA and CODA\_DATA directories to $SHOME\LIBRARY, in which case you can load CODA from within any S-plus session, by simply typing library(CODA).
If you have made your own modifications to some of the CODA version 0.3 functions, and do not wish to overwrite the whole library when installing CODA version 0.4, you can install the file coda4new.s instead of coda04.s. This file contains only the new functions and those which have been modified since version 0.3. If you run S-Plus from the working directory containing your CODA version 0.3 functions and enter the command source("coda4new.s"), only the new/modified functions will be overwritten.
If you are running S-Plus from within UNIX, create a .Data sub-directory of the directory where the line1.out,... file etc. are located. Invoke S-Plus and load the CODA library as described in §3.2.1.
If you are running S-Plus for WINDOWS, make a note of the directory path containing the the line1.out,... file etc., and then invoke S-Plus using the WINDOWS icon; load the CODA library as described in §3.3.
Having loaded the library in either S-Plus for UNIX or S-Plus for WINDOWS, you can then run CODA by typing
CODA()
You will receive a welcome message on the screen:
_______________________________________________________________ | | | Welcome to CODA! | | Convergence Diagnostics and Output Analysis for BUGS output | |_______________________________________________________________| | | | Authors : Nicky Best, Kate Cowles & Karen Vines. | | | | CODA : Copyright (c) 1995, 1997 MRC Biostatistics Unit. | | All rights reserved | | Version 0.40 | | | |_______________________________________________________________|
You will then be asked the following question:
Are you are running S-Plus under WINDOWS (y or n)?: 1:
If you are, type y after the prompt. The following information will then appear on your screen and you will be given the option to change the S-Plus working directory:
The current working directory is C:\\SPLUSWIN\\HOME By default, CODA will assume all input files (i.e. *.out and *.ind files) are located in this directory, and will write the CODA.LOG file to this directory To change the working directory, enter the new directory name and full path, or leave blank and hit return to continue. (Remember to use a DOUBLE backslash \\ to separate directory names e.g. C:\\SPLUSWIN)
You should enter the name the directory containing the line.out and other output files from your BUGS run. This directory will then become the working directory for your current CODA session; CODA will automatically search this directory for the BUGS output files you want to analyse, and will write the CODA.LOG file to this directory. Once you have specified your working directory, CODA will then display the menu shown below.
If you are a UNIX user, your working directory is automatically set to the directory in which you are currently running S-Plus; hence CODA will not display the above message, but will skip immediately to the menu below:
Do you wish to: 1: Begin a new CODA session using BUGS output files 2: Begin a new CODA session using data saved from a previous CODA session 3: Quit Selection:
The remainder of your CODA version 0.4 session is unchanged from CODA version 0.3.
Once CODA has produced a plot in the graphics window, UNIX users will see the following prompt appear in the text window:
Do you want to save current plots as a postscript file (y/n) ? 1:If you answer y to this question, you will be prompted to enter a name for the file. This causes the contents of the graphics window to be saved as a postscript file. This file may be printed at a later date or included in any text documents (such as Latex) which can import encapsulated postscript objects.
If you are running S-Plus for WINDOWS, you will see the following prompt appear after CODA has finished producing the plots in the graphics window:
Do you want to save current plots to a file (y/n) ? 1: No 2: Yes - as a Placeable Windows Metafile 3: Yes - as a Postscript file Selection:If you answer 2 or 3, you will then be prompted to enter a name for the file. This causes the contents of the graphics window to be saved as either a WINDOWS metafile (option 2) which can be imported into e.g. a Microsoft Word document, or a postscript file (option 3) which can be imported into e.g. a Latex document.
Best, N.G., Cowles, M.K. and Vines, S.K. (1995). CODA: Convergence Diagnosis and Output Analysis Software for Gibbs sampling output, Version 0.3. MRC Biostatistics Unit, Cambridge.
Brooks, S.P. and Gelman, A. (1998). General methods for monitoring convergence of iterative simulations. Journal of Computational and Graphical Statistics, (to appear) -- also available from the MCMC preprint service at Bristol University.
Gelman, A. and Rubin, D.B. (1992). Inference from iterative simulations using multiple sequences. Statistical Science, 7, 457-511.