July, 2003 Jerry Halpern Jerry.Halpern@stanford.edu (650)723-5705 retrovar The program retrovar finds the estimates for the parameters associated with the covariates and the covariance matrix of these estimates for the "marginal covariate model" as described in the "THEOREM" in the section titled "ASYMPTOTIC DISTRIBUTION OF \hat{\beta} FOR MARGINAL COVARIATE MODELS" in Genetic Epidemiology (2003); "Logistic Regression of Family Data From Retrospective Study designs"; Alice S. Whittemore and Jerry Halpern. I. INSTALLATION: retrovar is written in C. retrovarzip.exe can be downloaded from the link for StatisticalSoftware given in the page found with http://www.stanford.edu/dept/HRP/epidemiology. retrovarzip.exe is a "zip" archive. In usual conventions this would be named "retrovar.zip". However, I have named it "retrovarzip.exe" because, although it is not actually an executable file, a browser that tries to download it will assume it is and will just download it without making any changes to it (A browser often makes an educated guess based on a file's name about the kind of file being downloaded. Then the browser may take some action based on its guess. This can result in the downloaded file being seriously different from the original file). After retrovarzip.exe is downloaded to your own computer change its name to "retrovar.zip". ======================================================================== NOTE:NOTE:NOTE: ======================================================================== If you are using a WINDOWS(NT, 2000, XP) machine, open a "command window". You can do this by finding the program "cmd.exe" and clicking on its icon. The instructions below for copying and moving files, and running programs assume that you are initiating these actions by giving the appropriate commands at the prompt in a "command window". The mouse can sometimes be used, but if in doubt try again by giving commands at the prompt rather than by using the mouse. ======================================================================== 1)retrovarzip.exe Includes: a)retrovar.c This is the source C code that has the main subroutine and other code specific to the this work. b)2aux.c This contains the source for a number of routines from the "Numerical Recipes in C" library such as "svdcmp" for finding the singular value decomposition of matrices which are commonly useful to me as well as a few other utility routines that I have written such as "inversse". c)2include.h This is a header that causes the compiler to assume the older K&R form for the source code, and also other header code appropriate for the NRinC routines. It also changes all references for "float" to "double". d)makefile This is a makefile that the "make" command in unix environments can use to compile the retrovar executable from 2include.h, retrovar.c and 2aux.c . e)retrovarsol This is an executable compiled with the gcc compiler on a SUN SPARC Sun-Blade-2000 machine under SunOS 2.8. f)retrovarwindw.exe This is an executable compiled with the gcc compiler under cygwin 1.3.12-4 on a WINDOWS machine running WINDOWS-2000 Professional. g)cygwin1.dll This is a basic library for running programs compiled for WINDOWS using gcc in the cygwin 1.3.12-4 version of unixForWindows. h)retrovar.ctl This is a sample control file for easy use of retrovar. i)retrovar.dta This is a sample data set. j)JHREADMEvar This is a copy of these instructions. 2) Actually Setting Up the Programs. a)Download the retrovarzip.exe file from http://www.stanford.edu/dept/epidemiology Web Page. Put retrovarzip.exe into a convenient directory on your computer. b)make a directory named "retrovar.dir" and copy or move retrovarzip.exe to it. c)Change the name of retrovarzip.exe to retrovar.zip. d) Unzip retrovar.zip. If you are using WINDOWS, download and use the "unzip.exe" program from http://www.stanford.edu/dept/epidemiology. The command in WINDOWS is "unzip retrovar.zip". NOTE: unzip.exe executes under windows; it will not work under UNIX. NOTE: This unzip.exe is a very old version of unzip. It will only handle names in the form allowed by (old) DOS. DO NOT replace any "unzip.exe" you may already have on your machine with this one. If you are using unix, "unzip" will most likely be already installed on your computer. In unix the command would be "unzip retrovar.zip". If you have a full implementation of java installed on your computer, you can unzip the retrovar.zip with the command "jar -tf retrovar.zip". Unzipping retrovar.zip will make available all of the files described in 1) above. e)NOTE:This instruction, e), is only for users operating on a WINDOWS machine: Be sure that cygwyn1.dll is put into a directory that is listed in the "PATH" environment variable. i)You could just copy cygwyn1.dll to C:\WINNT\system32. (WINNT is for an NT or 2000 system, for XP copy cygwin1.dll to C:\WINDOWS\SYSTEM32). If you do this and then later install a complete version of cygwyn on your machine, remember to delete the copy that you have now put into C:\WINNT\system32. ii)If you know how, you could make a new directory, say, "c:\cygwin\bin", copy cygwyn1.dll to that directory, and then change the PATH environment variable to include c:\cygwin\bin. f)After going through this process, if you are operating under a version of UNIX, before retrovarsol will execute, you may neet to change the permissions using "chmod 700 retrovarsol to make it executable. II) DESCRIPTION OF THE DATA THAT THE PROGRAM REQUIRES: R is the number of covariates. H is the number of strata. For this program it must be >= 1. The external file holding the data may have any name allowed by the operating system and shell that you are using, except it may not contain blanks, tabs, or a new_line character. R, H, and the name of the external file holding the data for each individual are prompted for when the retrovar is run. The external file holding the data is expected to have one line per individual. Each line having the format: 1: Pedigree_number. 2: iy the outcome = 1--event happened or 0--event did not happen. 3: R numbers, one for each element of the covariate vector. 4: The integer in [1,...,H] giving the strata of that individual. III) RUNNING THE PROGRAM: 1) Be in the directory in which you unzipped retrovar.zip. 2) Create an ordinary ASCII text file containing the data for each individual, as described above. 3) Execute the appropriate executable version of retrovar and respond to the prompts for R, H, and the name of the data file (Just give the name simply, do not surround it with quotes or other punctuation). You may find it convenient to use a control file. If, for example, R is 5, H is 3, and the name of the datafile is "mydata". you could create a control file, called, say, "mycontrol" which would have 3 lines: 5 3 mydata You could then give the command, "retrovar < mycontrol", and then retrovar would take the responses to its prompts from mycontrol without any need for manual responses from the user. You can also save the output from a run of retrovar by running retrovar with the command, "retrovar < mycontrol > myoutput".