README September 29, 1997 GLSNET Generalized Least Squares NETwork analysis GLSNET - Version 2.5 1997/09/29 glsnet2.5.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 glsnet2.5.source.tar.gz - Distribution that includes the source code but no compiled software TABLE OF CONTENTS A. DESCRIPTION B. DOCUMENTATION C. EXTRACTING FILES D COMPILING E. INSTALLING F. RUNNING THE PROGRAM G. TESTING H. CONTACTS A. DESCRIPTION The GLSNET procedure uses an analysis of residuals technique to estimate a regional regression equation to predict flow characteristics at ungaged sites. The regression analysis assigns different weights to observed flow characteristics. These weights are based on record length, cross correlation with flow characteristics at other sites, and an assumed model error structure. Stedinger and Tasker (1985, 1986) documented the usefulness of an estimated generalized least squares (EGLS) regression procedure for regional regression of streamflow characteristics. The EGLS procedure assigns different weights to observed flow characteristics based on their record length, cross correlation with flow characteristics at other sites, and the model error variance. Tasker and Stedinger (1989) provide further details on how the elements of the weighting matrix are determined. The problem of identifying the sites from which to collect future streamflow data is formulated as a mathematical program using regional information and is subject to budget constraints. An approximate solution is obtained using a step-backward technique that identifies gaging station sites, either existing or new, to discontinue data collection, or not start data collection, respectively, if the budget is exceeded. The method allows a network manager to design a nearly optimal streamflow data network for collecting regional information. The GLSNET program uses the Watershed Data Management (wdm) file for data management of the station peaks or low flows and the associated descriptive basin characteristics. The IOWDM program may be used to store the required data in a wdm file. The ANNIE program may be used to add additional descriptive attributes to the wdm file and to view the contents of a wdm file. The PEAKFQ and SWSTAT programs may be run to compute required statistics for high-flow and low-flow analysis, respectively. B. DOCUMENTATION Tasker, G.D., and Stedinger, J.R., 1989, An operational GLS model for hydrologic regression: Journal of Hydrology, v. 111, p. 361-375. Stedinger, J.R., and Tasker, G.D., 1985, Regional hydrologic analysis 1: Water Resources Research, v. 21, no. 9, p. 1421-1432. Stedinger, J.R., and Tasker, G.D., 1986, Regional hydrologic analysis 2: Water Resources Research, v. 22, no. 10, p. 1487-1499. C. EXTRACTING FILES Compressed tar files are used to distribute pre-compiled versions of the software and the source code. All of the files needed to install glsnet2.5 are contained in the files glsnet2.5.______.tar.gz (where ______ is a string indicating the file contains either the source code or a pre-compiled version of the program for the indicated operating system). The source version of the tar file contains the source code and all other files needed to compile and install the software on a UNIX-based computer. For either type of distribution, the directory glsnet2.5 will be created (or overwritten) when the files are extracted from the tar tape. If the glsnet2.5 directory already exists, you may want to delete or rename it before extracting the files. The following are the steps to extract the files from a distribution tar file. Steps in extracting files explanation ---------------------------------------- ----------------------------------- mv glsnet2.5.____.tar.gz /usr/opt/wrdapp If the tar file is not already in the directory where you want the distribution installed, move it there. cd /usr/opt/wrdapp If you are not in the directory where the tar file is located, go there. gunzip glsnet2.5.____.tar.gz Uncompress the distribution file. tar -xof glsnet2.5.____.tar Extract the distribution files from the tar file. This creates the following directory structure (the contents of each directory are shown to the right): glsnet2.5 copy of this README file `-----bin compiled executable(s) and shell script to run program `-----bin_data message file required during execution `-----doc documentation files (see file Contents) `-----src Makefile (and, with source tar, the source code) `-----msg (with source tar, script & file to build message file) `-----test scripts to run verification tests `-----data standard data sets used in verification tests Notes: a) The bin and bin_data subdirectories are not included in the glsnet2.5.source.tar.gz distribution; they are created during compilation. b) Source code is included only with the glsnet2.5.source.tar.gz distribution. c) It is recommended that no user files be kept in the glsnet2.5 directory structure. If you plan to put files in the glsnet2.5 directory structure, do so only by creating subdirectories under glsnet2.5. d) The software is configured for installation under the directory /usr/opt/wrdapp. The wrdapp directory may be a separate file system mounted at /usr/opt/wrdapp. If you choose to install the software elsewhere, you will need to retrieve the source version of the tar file and compile the software. e) To compile a new version of the software, you will also need: (1) libraries and other data files from the lib library (version lib3.1.______.tar.gz or later), (2) ANSI-compliant Fortran 77 compiler, (3) a Graphical Kernel System (GKS) library, and (4) the annie program (version annie2.3.______.tar.gz or later) to build the test wdm files. D. COMPILING If you have retrieved a pre-compiled distribution of the software, skip to the Installing section below. If a compiled version of the software is not available for your computer, or if you want to build the executable yourself, follow the instructions in this section. The source code is provided in the glsnet2.5.source.tar.gz distribution so that users can generate the executable themselves. Little or no support can be provided for users generating their own versions of the software. In general, the requirements are ANSI-compliant Fortran 77 and a minimum level of knowledge of the compiler and the UNIX operating system. A Graphical Kernel System (GKS) library is required. Libraries and data files from the lib3.1 distribution are also required. The annie program is needed to build the wdm data files used by the test. As provided, the make file, source code, and text version of the message file are set up for use on Data General AViiON workstations running the DG/UX operating system. To generate a new executable and message file, do the following: 1. The values for the indicated variables in the following glsnet2.5 files may need to be modified (see the file glsnet2.5/doc/versions.doc for more details): may need to be modified ------------------------------- version compiler file name variables flags name library --------------------- --------- ----------- ------- src/Makefile WrdA FFLAGS F77 LGks fglsms.inc FNAME msg/wdimex.sh WrdA test/test.sh WrdA Gks 2. Run the Makefile program in the src directory to compile the source and build the message file. In the directory glsnet2.5/src, run the make: cd glsnet2.5/src make [SIZE=max_no_sites] Where SIZE is the maximum number of sites that can be analyzed. The default is 300 sites. Files for 600 and 700 are provided, the user must provide there own ps___.inc file for other maximums. The glsnet2.5/src/Makefile will: a. Create the directories glsnet2.5/bin and glsnet2.5/bin_data, if they do not already exist. b. Compile the source code and place the glsnet executable in the directory glsnet2.5/bin. The executable will be named gls[max_no_sites].exe, by default this is gls300.exe.. c. Run the wdimex.sh script in glsnet2.5/msg to build the message file (glsmes.wdm); the file is placed in glsnet2.5/bin_data. The tx.wdm and va.wdm files will also be built and placed in the glsnet2.5/data directory. E. INSTALLING To make the glsnet program easy to use, it should be installed in a directory included in the user's search path. The Makefile in glsnet2.5/src contains instructions to optionally place a link in a specified directory to the shell script glsnet contained in glsnet2.5/bin. Use the following commands to do this: cd glsnet2.5/src make install [BINDIR=bin_path] where bin_path is the name of a directory in the user's search path. If BINDIR is specified, a link to the script (glsnet2.5/bin/glsnet) is placed in the specified directory. If BINDIR is not specified, no link is set and the full pathname of the script is required to run the program. For example, if the search path is /usr/bin:/usr/opt/bin:/usr/local/bin, you can use the following command to install the program: make install BINDIR=/usr/local/bin Notes: a) Brackets "[xxx]" are used to indicate optional arguments to commands. b) To create and delete links to the glsnet executable, the installer must have sufficient rights to the BINDIR directory. F. RUNNING THE PROGRAM After the glsnet executable is properly installed (see Installing, above) in a directory that is included in the user's PATH, the program can be executed by typing: glsnet [size] where: size = max no. of stations program will analyze By default, size is 300. Versions of glsnet dimensioned for 600 and 700 stations are also included. G. TESTING Test data sets are provided to verify that the program is correctly installed and running on the system. The tests may also be looked at as examples of how to use the program. The directory glsnet2.5/test contains the script to run the tests. The directory glsnet2.5/data contains the input data and the expected results for each test. Tests are usually run in the glsnet2.5/test directory, but they can be run in any user directory. Type the following commands to test the program installation: [path]/test.sh [start [stop [size]]] where: path = path to the script use "." if running the tests in the glsnet2.5/test directory use full pathname if not running the test in glsnet2.5/test start = the number of the first test to perform, default = 1 stop = the number of the last test to perform, default = 9 size = version of glsnet to be tested, by default this is = 300, versions dimensioned for 600 and 700 stations are also available. For example: command what happens -------------------------------------- -------------------------------- ./test.sh runs all of the tests ./test.sh 1 1 runs the first test ./test.sh 2 runs test 2 /usr/opt/wrdapp/glsnet2.5/test/test.sh runs all of the tests After the tests are completed, the results are compared to the expected results (found in glsnet2.5/data). See the file check.out; if all goes well, the only differences will be due to different processing times. To clean up after the tests, type the command: ./clean.sh Notes: a) Tests 1 and 2 require the tx.wdm and va.wdm files, respectively, exist in the glsnet2.5/data directory. b) The standard data sets were created on a Data General AViiON workstation. You may notice slight numeric differences in the results on other computers. These are generally due to different round-off algorithms and the different architecture of the central processing unit chip. The tests are described in the table below, where 'test' is the test number, 'program' is the program used to run the test, and the 'usage' column indicates how a file is used, with i for input, o for output, and i/o for both input and output. test program description of test and files file name & usage ---- ------- --------------------------------- ----------------- 1 glsnet Generalized least squares analysis of peak-flow data glsnet command file test1.log i Texas peak-flow data, WDM format tx.wdm i regression summary output file test1.out o 2 glsnet Generalized least squares analysis of low-flow partial record data. Includes adding partial record sites. glsnet command file test2.log i Virginia low-flow data, WDM format va.wdm i/o partial record site pr_01632 i partial record site pr_02018 i regression summary output file test2.out o partial record data computation test2.ot1 o partial record data computation test2.ot2 o H. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Team Kathleen M. Flynn e-mail: h2osoft@usgs.gov 437 National Center phone: 703-648-5313 Reston, VA 20192 fax: 703-648-5722 For questions on program content, application, and (or) theory, contact: U.S. Geological Survey Gary D. Tasker e-mail: gdtasker@usgs.gov 432 National Center phone: 703-648-5892 Reston, VA 20192 fax: 703-648-5295