Keeping good records

No properly managed statistical analysis would use results that were calculated interactively because of the difficulty of reproducing them when you do not have a written record of exactly what was done. For this reason, Stata users usually store their commands in do files.

When running WinBUGS from within Stata we need to create four text files that store the model, data, initial values and batch script. The data and initial values can be written to a file using the –wbslist– command and the script file can be created using –wbsscript-, both of these are described in detail in the book, ‘Bayesian Analysis with Stata’ that is due to be published shortly. Alternatively, the files could be prepared using the commands described in the Stata Journal article http://www.stata-journal.com/article.html?article=st0115. This leaves the model file, which has to be written in WinBUGS syntax, so it is usually created separately using a text editor. Here lies the problem, the do file will not contain a record of the contents of the model file and when you return to the analysis after a long gap, it can be difficult to determine exactly what form the model file had when you last ran the analysis, especially if, like me, you have the bad habit of calling all model files, model.txt.

Ideally we would like the WinBUGS model to be stored as part of the do file, but as it is in WinBUGS syntax it will not run in Stata and so needs to be commented out. For a long time this is what I did. I would create the do file and the model file separately, then copy the model and store it within the do file, commenting it out using  /* …. */.

Recently I developed a slightly different way of achieving the same end. I wrote a program that I called tomodel; this command copies commented out code to a text file. Originally I had no intention of making this command public, but the more I used it, the more I realized that it would be useful to anyone running WinBUGS from within Stata. So I decided to rename the command –wbsmodel– and make it part of the downloadable family of wbs commands. This new command reads the contents of a commented out block of text that is stored in a do file and copies it to a text file. With this command, it is possible to write the model as part of the do file, comment it out and precede it with a call to wbsmodel. When the do file runs the model file is created afresh from the commented out text and thus has exactly the contents that you see in the do file. For instance, a piece of Stata code might read,

….

wbsmodel thisfile.do model.txt

/*

model {

   for( i in 1:10) {

        y[i] ~ dnorm(mu,1)

   }

   mu ~ dnorm(0,0.001)

}

*/

….

The two arguments that follow the command word are the name of the do file that I am working with (thisfile.do) and the name of the text file to which I want the WinBUGS code written (model.txt). The command works by re-reading the do file  until it locates the command line and then it copies the subsequent commented out text to the named file.

The do file runs normally in Stata and I have an exact record of the model file that I used for that analysis. What is more, if I need to edit the model file, all I need to do is to edit the commented out lines within my do file and then re-run it.

All of the commands describd in the forthcoming book ‘Bayesian Analysis with Stata‘ can be net installed from http://stata-press.com/data/bas . At the time of preparing this posting  (19th March 2014) the command is still net installed as tomodel but I have asked for it to be renamed wbsmodel and for it to be added to the wbs family and I expect this to happen soon. Instructions for running the downloadable commands are contained in the help files and you can obtain a pdf of the contents of those help files by downloading my manual.