Release Notes and Installation Guide (Unix Version)

Transcription

1 Release Notes and Installation Guide (Unix Version) Release 3.1 December 1997

2 - ii - Release Notes and Installation Guide

3 Table of Contents 1 Changes Since Last Release Changes Since Release Changes Since Release Purpose Introduction Requirements Installation Graphical User Interface (GUI) Installation and Setup of the Graphical User Interface Copy the S.A.G.E. CGI Executable Copy the S.A.G.E. CGI Data Files Setup the CGI Temporary File Locations Accessing the CGI Using S.A.G.E FORTRAN Format Statements The "sage31" Script Manual Input/Output Specification Mappings by Program Command Line Options Graphical User Interface iii -

4 - iv - Release Notes and Installation Guide

5 1 Changes Since Last Release 1.1 Changes Since Release 2.2 All of the programs have been enhanced in various ways. Below is a brief list of some of the major changes. This document supersedes the Changes Since Previous Release sections in the various manuals. AGEON - 1. A restriction on the power parameter (p) value was implemented. The value must now be: p = 0 or p$ Output labels and final estimate values for age-of-onset related parameters have been corrected for when the natural log transformation (p = 0) is used. 3. Mean and variance calculations for age-of-onset will not include individuals who have either an unaffected or missing trait code even if the individual has an age-of-onset. DESPAIR - 1. Several bugs have been fixed. In particular, when numbers in the output were too large asterisks were printed; the output field is now increased. 2. We have made it possible to specify a significance level of less than FSP - 1. MEGADATS plotting output is no longer supported. 2. Because the other S.A.G.E. programs no longer require the nuclear family file as input, it has been removed. Note: FSP will count 1-person pedigrees as pedigrees, but these individuals will be moved to the end of the data set as "unrelateds". These pedigrees should not be included as part of the "Number of independent pedigrees" in the analysis programs that read the.seg file. The correct number of independent pedigrees can be obtained from the "FSP FINAL STATISTICS" listing at the end of the FSP information output file, subtracting 1 from that number for each pedigree containing only 1 person. Furthermore, any "pedigree" (set of individual records with the same pedigree number) containing only unrelated people -- see output describing individual pedigrees -- should also be subtracted from that number. LODLINK - 1. Several bugs have been fixed that caused abnormal program termination. 2. The way marker phenotypes are read in has been made more flexible. Previously, the order of the alleles made a difference and the order was not interchangeable. For example, the program would read 1/2 and 2/1 as two different phenotypes unless the user specifically assigned them to the same phenoset in the locus description file. The program will now recognize either order as the same phenotype. 3. You can still use zeros for missing marker phenotype data, provided zero is not defined as an allele or phenotype, but this will produce warning messages that can be ignored. We recommend the use of blanks for missing marker phenotypes, and the warning messages will then be suppressed. Users can also choose to designate a missing value code for the marker phenotype by using the first line of the locus description file to specify it. For example, if you type Missing=M on the first line of the locus description file, the use of M or M/M (or blanks) - 1 -

6 - 2 - Release Notes and Installation Guide for missing data will not generate any error messages.[note: There are no spaces on either side of = ]. 4. LODLINK no longer aborts after finding the first inconsistency. However, because the initial inconsistency may lead to further inconsistencies, we strongly recommend that the user correct the first inconsistency found and then rerun the program to see if further inconsistencies are in fact present. When the genotype probability cannot be computed, a -1 is printed in the Optional Genotype Probabilities Output (see LODLINK manual, section 5.3). 5. It is now possible to test the null hypothesis 2 & + 2 % =1. 6. The calculation of the equivalent number of meioses has been changed. It is now no longer calculated when either 2 & or 2 % (but not both) is at 0 or 1. REGC - 1. It is now possible to assume there is dominance or recessivity with respect to the residual population variance F 2, as well as with respect to the mean µ. 2. A printout of the average of each covariate has been added to the output file. REGD - 1. There is now the possibility of including in the model a common sibship component that depends on the proportion of sibs affected. 2. Users are now allowed to specify the symbols for the trait value. REGTL - 1. There is now the possibility of including in model 1 a common sibship effect that depends on the proportion of sibs affected. 2. It is now possible to assume that there is dominance or recessivity with respect to the age coefficient ", as well as with respect to the baseline parameter $, in model Users are now allowed to specify the symbols for the trait value. SIBPAL - 1. Changes have been made to the t-tests to obtain more appropriate p-values for moderate sized samples, but it should be understood that the tests are still only truly valid asymptotically. 2. Covariates are appropriately included in SIBPAL 3.0, but p-values for them have been eliminated because they are not valid. Plots of covariate-adjusted values are not yet available. 3. The way marker phenotypes are read in has been made more flexible. Previously, the order of the alleles made a difference and the order was not interchangeable. For example, the program would read 1/2 and 2/1 as two different phenotypes unless the user specifically assigned them to the same phenoset in the locus description file. The program will now recognize either order as the same phenotype. 4. You can still use zeros for missing marker phenotype data, provided zero is not defined as an allele or phenotype, but this will produce warning messages that can be ignored. We recommend the use of blanks for missing marker phenotypes, and the warning messages will then be suppressed. Users can also choose to designate a missing value code for the marker phenotype by using the first line of the locus description file to specify it. For example, if you type Missing=M on the first line of the locus description file, the use of M or M/M (or blanks) for missing data will not generate any error messages. [Note: There are no spaces on either side of = ]. 5. SIBPAL now prints out an error message when it tries to invert a singular matrix (due to collinearity of the variables), instead of aborting with no explanation. 6. The format of column labels in the output has been made more legible.

7 Release Notes and Installation Guide To help the user know when results may be invalid, we have included warnings in the output. Note: In SIBPAL all tests are based on asymptotic (large sample) theory and a relatively small number of sib pairs (either full or half) can invalidate the results. This problem has usually occurred when there is a small number of half-sibs and a large number of full-sibs. Invalid results can occur because, when full and half sibs are pooled, the weights used depend on the residual variances. However, in calculating the p-values (which are based on large sample theory) it is assumed that the weights are fixed constants and not random variables. For example, if, by chance, there are a few half-sib pairs with a very small variance, they could be given an enormous weight in the pooled result. A warning is printed whenever the variance ratio is > 4 or < 0.25 (a factor of 4 difference). For both binary and continuous traits a! is printed next to any questionable p-values in the pooled output table, as explained at the top of the table. For binary traits, there is a printout of the variance ratio in the optional unpooled output. There is also an option to add a column to the pooled output to print the variance ratios. In addition, whether for binary traits, continuous traits, or traits with variable age of onset, there is an option to run the analysis using either full or half sib data only. 1.2 Changes Since Release 3.0 Many of the programs have been enhanced in various ways. Below is a list of these changes. LODLINK 1. It is no longer required to specify sex codes in the parameter file. The program now accepts M, F, and N (no issue) as valid sex codes as those are assigned by FSP in the segregation analysis data file. SIBPAL 1. The p-value output, for a binary trait, to test whether the proportion of alleles shared differs from 0.5 has been corrected. In 3.0, 1-p was incorrectly output instead of p. 2. The option to use only half sibs for the analysis has been removed. 3. Warning messages are now provided when marker inconsistencies are detected. RELPAL 1. There are better error messages if mistakes are made in the locus descriptor file input. 2. There have been changes made to the numbering of markers and traits. They are now numbered starting with 1 (instead of 0). TDTEX 1. Errors in the chi-square tests have been corrected. 2. The tests performed by default now exclude the Exact Permutation McNemar test. Regressive Model Programs 1. A sixth transmission option has been added. It allows for arbitrary transmission probabilities with homogeneity across generations. All Manuals 1. Hard copies of the manuals will still be included with all new major releases. All online documentation, provided with the Quarterly updates, will be in Adobe Acrobat format only. We provide information about this change and where to obtain an Adobe Acrobat Reader on our New Information web page. (The URL is: new.html). If you need a different format, please contact us directly.

8 - 4 - Release Notes and Installation Guide

9 2 Purpose The Release Notes and Installation Guide (Unix Version) is designed to provide all the necessary information specific to installing and using the S.A.G.E. software package on a Unix operating system. Information that is program specific is covered in the appropriate manuals. This manual covers, but is not limited to: 1. Hardware and operating system support 2. Installation procedures 3. Input/Output file specifications 4. Program execution We STRONGLY suggest reading the Introduction Manual and the FSP Manual before using any of these programs

10 - 6 - Release Notes and Installation Guide

11 3 Introduction The S.A.G.E. (Statistical Analysis for Genetic Epidemiology) software provides researchers with the tools necessary for various types of statistical genetic analysis of pedigree data. The following programs are included: AGEON ASSOC BCROSS CLUSTR DESPAIR FCOR FSP LODLINK MAPLOC REGC, REGD, REGTL, REGTN RELATE RELPAL SIBPAL TDTEX TOOLKIT For a general description of each of the above programs, please see the Introduction Manual; for a more detailed description see the program specific manual. Installation is handled by a script called "install.sh" which is found on the CD-ROM provided. Once executed, the script will ask several questions necessary to install and configure S.A.G.E The questions include which operating system is running on the target system, the location of the CD- ROM mount point, the destination directory to install S.A.G.E. 3.1, and other relevant information. We recommend installing S.A.G.E. 3.1 in a central location, not in a user s home directory, and therefore installation will usually require assistance from the system administrator. Once installed, make sure file permissions are set correctly. Upon successful completion of the installation script, the S.A.G.E. 3.1 programs, test files, scripts to run S.A.G.E. 3.1, and several forms of online documentation will be installed. A listing of the resulting directory structure, as well as a more detailed description of the installation procedure, can be found in Chapter 5: Installation

12 - 8 - Release Notes and Installation Guide

13 4 Requirements In general, the minimum recommended memory is 32MB. Some programs will require less, but this will vary depending on the operating system and size of each analysis. The following is a list of supported operating systems and corresponding versions. Compatibility with other versions or Unix platforms is not guaranteed. OS Architecture Required Version Recommended Version(s) Digital Unix/OSF1 Alpha C+, 4.0B+ Linux i Kernel 2.0+ with ELF support Solaris Sparc Note: This list will gradually expand to include other Unix operating systems. Please contact us for the most up to date information

14 Release Notes and Installation Guide

15 5 Installation The first step in the installation is to mount the CD-ROM as an ISO 9660 file system with Rockridge Extensions. The exact commands are system specific. Please see your system administrator if you have questions. In the root directory of the installation CD-ROM there is an installation script called install.sh. When executed, the script will query the installer to determine where to install the software, the architecture of the target system and the directory where the CD-ROM is mounted. Example for Digital Unix: mount -r -t cdfs -o rrip /dev/rz6c /mnt cd /mnt./install.sh Example for Linux: mount -r -t iso9660 /dev/cdrom /mnt cd /mnt./install.sh Example for Solaris running vold: cd /cdrom/sage3.1december1997./install.sh The following table shows the directory structure relative to where it is installed. Please note that only one architecture - selected during the installation process - will be installed. sage/v31/ /arch /arch/alpha /linux.386 /solaris /bin /sagegui /doc /etc /test Architecture specific Directories C Binaries for Digital Unix 3.2+ C Binaries for Linux 2.0 (ELF) C Binaries for Solaris 2.4+ Symbolic link to an architecture specific binary directory S.A.G.E. Graphical User Interface Data Files Documentation in Adobe PDF format Location of auxiliary scripts Test files for the S.A.G.E. programs Once the software has been installed successfully, the systems manager should add the S.A.G.E binary directory (sage/v31/bin) to the system path. The alternative is to copy the sage31 script to a location in the system path (i.e., /usr/local/bin)

16 Release Notes and Installation Guide

17 6 Graphical User Interface (GUI) 6.1 Installation and Setup of the Graphical User Interface The Graphical User Interface used for creating S.A.G.E. parameter files is included on the distribution CD-ROM. It is not always necessary to install the GUI on your local system since the most up to date version is always online at the S.A.G.E Web site. The only reason to install the GUI locally is if the delay is large between your local network and S.A.G.E. or if there is no Internet access from your site. If it is decided that the GUI will be run on a local server, the following instructions detail the process of installation and configuration. Due to the great variety of Web Server software available the steps may be slightly different for each installation. The following instructions are intended for experienced Web or Systems Administrators and will require detailed system specific knowledge. If such experience is not available, then we suggest using the GUI on the S.A.G.E. Web site Copy the S.A.G.E. CGI Executable Copy the CDROM/arch/ARCH/sagecgi program to the CGI binary directory for the Web Server on your system and ARCH is your correct architecture. Make sure the file permissions are set such that the program is executable by the HTTP server. ex. cp /mnt/cdrom/arch/alpha/sagecgi /usr/local/httpd/cgi-bin chmod a+x /usr/local/httpd/cgi-bin/sagecgi Copy the S.A.G.E. CGI Data Files CGI data and HTML files then need to be copied from the CDROM. Copy the CDROM/sagegui directory and all its contents to a location accessible as a document path from your HTTP server. The default location is directly under the "DOCUMENT_ROOT", which is defined by the HTTP server. It is also possible to install the CGI Data files in an alternate location such as user CGI directories or other locations accessible to the HTTP server. See below for more information. Verify that the permissions are such that the data files can be read by CGI programs run from the HTTP server. Usually, this requires setting file ownership to the same user id as the HTTP server or CGI user id. ex. For a default installation where DOCUMENT_ROOT is /usr/local/httpd/htdocs cp -r /mnt/cdrom/sagegui /usr/local/httpd/htdocs chown -R <HTTPD/CGI user id> /usr/local/httpd/htdocs/sagegui chmod -R a+r /usr/local/httpd/htdocs/sagegui ex. For a non-default installation to a user public HTML directory: /home/jacobs/public_html/sagegui. cp -r /mnt/cdrom/sagegui /home/jacobs/public_html/sagegui chgrp -R <HTTPD/CGI user id> /usr/local/httpd/htdocs/sagegui Additional configuration steps are required for this type of installation. See below

18 Release Notes and Installation Guide Setup the CGI If any of the following are true, then additional steps are necessary to configure the GUI: The S.A.G.E. CGI is installed anywhere other than The S.A.G.E. CGI data files are installed anywhere other than If the S.A.G.E. CGI temporary files are to be created in a location other than /tmp The modifications must be made to the 'runcgi.html' file in the CGI data file directory. A script file called config.sh that will be able to configure the CGI for the majority of systems can be found in the CGI data directory. Detailed instructions are included in the file runcgi.html if the script cannot correctly configure the CGI for your system Temporary File Locations While the GUI is running, it creates many temporary files containing information about parameter files being created. By default, these are placed in the standard operating system specific location. This is typically /tmp for most Unix systems. If another location is preferred, the CGI can be instructed to use another path by making a simple modification to the runcgi.html file installed in the CGI Data Files directory. This modification can be made by the config.sh script on most systems and detailed information is also included in runcgi.html. It is very important to know that the S.A.G.E. CGI does not delete any of these temporary files when it is done with them. It is up to the system administrator or user who owns the temporary file directory to periodically clear it out. This is done by adding a task to the Unix periodic scheduler daemon, 'cron'. ex. To delete all S.A.G.E. temporary files from /tmp that have not been accessed in more than two days at 4am each day a line must be added to the crontab file for the user that owns the temporary files. This is usually the same user id that the HTTP server runs as or the root account. [To edit the crontab file] crontab -e [add the following line] 0 4 * * * find /tmp -name "*.sage" -type f -atime +1 -exec rm -f {} \; Accessing the CGI To access the CGI load the URL that corresponds to the CGI data directory. This will bring up the Main Menu. Test the "Create New Parameter File" option to verify that installation was successful and all options were specified correctly.

19 7 Using S.A.G.E. 7.1 FORTRAN Format Statements For our FORTRAN format statement tutorial, and for a list of other online tutorials we have available, please see our website at: The "sage31" Script The simplest way to run S.A.G.E. is to use the "sage31" script. The first menu will provide a listing of all included S.A.G.E. programs and prompt the user to select one. After selection, the script will request the names of the various input files and output files and then start the analysis. For running analyses that involve running one or more S.A.G.E. programs repeatedly please see the next section on batch execution. We have added a new option to the sage31 script that will provide a list of the command line options available for a specific program by typing help and the name of the program. Please see section 7.5 of this manual titled Command Line Options for more information. 7.3 Manual Input/Output Specification All of the S.A.G.E. analysis programs can be run non-interactively at the command line or from batch execution scripts. The major task of these scripts is to specify the input and output file names for the analysis programs to use without going through the high level sage31" script. In addition, batch scripts are often used to run complex batch analyses involving several S.A.G.E. programs, run simulations and summarize the results over many analyses, or otherwise automate the process of running S.A.G.E. (see section 5.4 Command Line Options for additional details). Under S.A.G.E. 3.1, input and output files are specified as logical files (or logical units, as Fortran calls them). To assign a logical unit to a filename, an environment variable of the form FORTn must be set, where n is the logical unit number. If the environment variable is not set for a logical unit a default filename of the form fort.n is then assumed. The following tables provides examples: Environment Variable Default Filename 1 FORT1 fort.1 11 FORT11 fort FORT21 fort

20 Release Notes and Installation Guide Setting the environment variables is somewhat system specific, but should follow one of the following formats: Bourne/Posix Shell (sh, bash, ksh): i.e., <VARIABLE>=<VALUE>; export <VARIABLE> FORT1=sibpal.par; export FORT1 C Shell (csh, tcsh): i.e., setenv <VARIABLE> <VALUE> setenv FORT1 sibpal.par Here are two examples of a batch scripts for SIBPAL. sh Shell Example: #/bin/sh # A simple job control script to run SIBPAL FORT1=sibpal.par FORT11=sibpal.loc FORT12=sibpal.dat FORT13=sibpal.lnk FORT21=sibpal.out FORT22=sibpal.sum FORT23=sibpal.opt export FORT1 FORT11 FORT12 FORT13 FORT21 FORT22 FORT23 #Note: a full path to SIBPAL may be needed depending on your configuration. sibpal csh Shell Example: #/bin/csh #Another simple job control script to run SIBPAL setenv FORT1 sibpal.par setenv FORT11 sibpal.loc setenv FORT12 sibpal.dat setenv FORT13 sibpal.lnk setenv FORT21 sibpal.out setenv FORT22 sibpal.sum setenv FORT23 sibpal.opt #Note: a full path to SIBPAL may be needed depending on your configuration. sibpal

21 7.4 Mappings by Program Release Notes and Installation Guide The following is a list of environment variables and the description of the files they map to by program (see section 5.2 Manual Input/Output Specification for usage information). AGEON 11 Family Data File 12 FSP Pointer Table File 21 Detailed Output 22 Output File From MAXFUN ASSOC 11 Segregation Analysis Data File 21 Standard Output 22 Optional Detailed Output BCROSS 11 Data File 21 Detailed Output 22 Summary Output 23 Output File From MAXFUN CLUSTR 11 Data File 21 Output File From MAXFUN 22 Summary Output

22 Release Notes and Installation Guide DESPAIR 21 Output File FCOR 11 Family Data File 12 FSP Pointer Table File 21 Pair Frequencies Report 22 Correlations Report 23 Error File FSP 11 Family Data File 21 Information File 22 FSP Pointer Table File 24 Segregation Analysis Data File LODLINK 11 Marker Locus Description File 12 Segregation Analysis Data File 13 Penetrance File 21 Detailed Output 22 Summary Output 23 Optional Genotype Probabilities Output 24 Output File From MAXFUN

23 MAPLOC 12 Data File Release Notes and Installation Guide A List of Test Locations and Associated Lod Sums 22 A Graph of Lod Sums Versus Test Locations REGC 11 Segregation Analysis Data File 21 Standard Output 22 Optional Detailed Output 23 Optional Penetrance Function File 24 Optional Conditional Type Probability Output REGD 11 Segregation Analysis Data File 21 Standard Output 22 Optional Detailed Output 23 Optional Penetrance Function File 24 Optional Conditional Type Probability Output REGTL 11 Segregation Analysis Data File 21 Standard Output 22 Optional Detailed Output 23 Optional Penetrance Function File 24 Optional Conditional Type Probability Output

24 Release Notes and Installation Guide REGTN 11 Segregation Analysis Data File 21 Standard Output 22 Optional Detailed Output 23 Optional Penetrance Function File 24 Optional Conditional Type Probability Output RELATE 11 Family Data File 12 FSP Pointer Table File 21 Pair Frequencies Report 22 Information File 23 New Pedigree Data File 24 Code Totals File RELPAL 11 Marker Locus Description File 12 Family Data File 13 ˆB Input File 21 Detailed Output File 22 Summary Output File 23 ˆB Output File

25 SIBPAL 11 Marker Locus Description File 12 Family Data File 13 FSP Pointer Table File 21 Detailed Output 22 Summary Output 23 Optional Output Release Notes and Installation Guide TDTEX 11 Marker Locus Description File 12 Family Data File 21 Output File TOOLKIT PROGRAMS DBSORT 11 Family Data File 21 Sorted Family Data File 22 Information File PEDCHK 11 Segregation Analysis Data File 21 Output File

26 Release Notes and Installation Guide RENUM 11 Family Data File 21 New Family Data File 22 Information File SPLIT 11 Family Data File 21 New Data File 22 Cut Data File 23 Information File 7.5 Command Line Options To run the programs from the command line, first make sure all input and output files have been specified (see section 5.2 Manual Input/Output Specification for additional details). Then use the program name and any arguments to change default values. Common to all programs are the command line parameters "-h" and "-v". The "-h" argument provides the following information: the name of the program, the version, a sample usage, general options, modifiable parameters and where to go for more information. The "-v" option will provide the same information as "-h", but will also run the analysis. For example, the command "regc -h" would be typed at a command line, yielding: $> regc -h S.A.G.E. RELEASE REGC DECEMBER 1997 Usage: regc [-v] [-h] [-i MAXIND] [-s MAXS] [-p NP] [-n NPV] General Options: -v Provide verbose information on parameters. -h Show this helpful information. Modifiable parameters (maximum values): -i MAXIND = 5000 Number of Individuals. -s MAXS = 10 Number of matings per individual. -p NP = 45 Number of parameters to maximize. -n NPV = 45 Number of non-fixed/dependent parameters to maximize. Please refer to the manual for more information. The parameter names in the usage options, such as MAXIND, are to be replaced with the value for that variable. To change the maximum number of individuals from 5000 to 8000 would require the command "regc -i 8000".

27 Release Notes and Installation Guide Graphical User Interface Parameter files for S.A.G.E. programs may be created manually according to the specifications in the S.A.G.E. manuals or using the graphical user interface (GUI). The GUI is available on the distribution CD-ROM (See section 6 for installation instructions) or on our website. The address is: The newest version of the GUI will be maintained there, along with all information on enhancements, capabilities and execution. It is recommended that the GUI be accessed there.