README October 6, 1997 GLSNET Generalized Least Squares NETwork analysis GLSNET - Version 2.5 1997/09/29 glsnt2_5.exe - self-extracting DOS distribution prepared on an IBM-compatible PC TABLE OF CONTENTS A. SYSTEM REQUIREMENTS B. DESCRIPTION C. DOCUMENTATION D. INSTALLING o Installing GLSNET from self-extracting executable o Installing GLSNET from distribution diskette o GLSNET directory structure o Making GLSNET easily accessible E. RUNNING THE PROGRAM F. TESTING G. GRAPHICAL OUTPUT H. CONTACTS A. SYSTEM REQUIREMENTS For installation of GLSNET, 6.1 megabytes of free disk space is needed. To run GLSNET, the following are necessary: - 386 or greater processor - math coprocessor - 14.6, 39 or 44.1 megabytes of combined free extended memory and free disk space on installation drive (the greater proportion available as memory, the better performance will be); amount needed dependent on whether the 300-, 600-, or 700-station version of GLSNET is executed-- see RUNNING THE PROGRAM below - at least 450K free disk space in current working directory Because of significant memory space requirements, GLSNET initialization may take a few minutes. IMPORTANT NOTE: When the full amount of memory space needed to run GLSNET is not available in physical memory, virtual memory management allows for the portions of the program that will not fit in physical memory to be written to disk. However, when running GLSNET in a Windows 95 MS-DOS window, default settings will not allow virtual memory to be used and, if there is insufficient physical memory available, GLSNET will terminate during initialization with an insufficient memory error. To modify the MS-DOS window settings to be able to use virtual memory, do the following: o Click on the MS-DOS icon in the upper left corner of the MS-DOS window and select the Properties menu item. o Select the Memory tab and enter 65535 (the maximum allowed value) in the "MS-DOS protected-mode (DPMI) memory" input field. The default value of "Auto" does not allow virtual memory to be used. For proper appearance of the GLSNET screens, the ANSI.SYS device driver must be loaded. Without it, the screens will be unreadable. CONFIG.SYS must contain a line such as DEVICE=C:\WINDOWS\COMMAND\ANSI.SYS Determine the location of the ANSI.SYS driver on your system and substitute the pathname of that location if not C:\WINDOWS\COMMAND as shown above. Note that for DOS-only and Windows 3.x systems, the ANSI.SYS driver is normally found in C:\DOS. Reboot your system if you modify CONFIG.SYS. B. 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. C. 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. D. INSTALLING Installing GLSNET from self-extracting executable ------------------------------------------------- To install GLSNET from the self-extracting executable, follow the steps below, replacing with the drive letter where you want to install GLSNET and optionally replacing [directory] with the name of a directory on that drive: 1. If you are not in the directory where the distribution file is located, go there. For example: c: cd \wrdapp 2. Extract the files contained in the distribution file using the command: glsnt2_5 -d :\[directory] Note: be sure to include the -d option and ":\" in the command. Examples are: glsnt2_5 -d c:\ glsnt2_5 -d c:\wrdapp 3. Go to the newly-created glsnet2.5 directory where the files have been extracted. For example: c: cd \wrdapp\glsnet2.5 4. Complete the installation by typing, install :[\directory] using the same drive letter and directory name as for extracting the files; however, if the files are located in the root directory of the installation drive, don't include the backslash. Examples are: install c: install c:\wrdapp The above install command must run successfully in order to create the batch files, glsnet2.5\bin\glsnet.bat and glsnet2.5\test\glsnet.bat which are necessary for successful execution of GLSNET. Be sure that no errors occur when executing the above install command. Installing GLSNET from distribution diskette -------------------------------------------- To install GLSNET from distribution diskette onto your hard drive, type :install : :[\directory] For example, if your floppy drive is a: and you want to install GLSNET directly under the root directory on the c: drive, you would type a:install a: c: This will create the directory c:\glsnet2.5. As an additional example, if you wanted to install GLSNET under a directory named "wrdapp" on the c: drive, you would type a:install a: c:\wrdapp This will create the directory c:\wrdapp\glsnet2.5. GLSNET directory structure -------------------------- The following directory structure will be created (the contents of each directory are shown to the right): glsnet2.5 copy of this README file `-----bin compiled executable(s), batch file to run program `-----bin_data files required during execution `-----doc documentation files `-----test batch files to run verification tests `-----data standard data sets used in verification tests Note: 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. Making GLSNET easily accessible ------------------------------- To make the GLSNET program accessible from any directory, the glsnet2.5\bin directory should be included in the PATH environment variable. Add a line similar to the following to AUTOEXEC.BAT: PATH=%PATH%;C:\glsnet2.5\bin Substitute the appropriate drive letter and pathname if not C:\ as shown above. Reboot your system after modifying AUTOEXEC.BAT. E. RUNNING THE PROGRAM After the glsnet executable is properly installed (see INSTALLING, above), 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. F. 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. Tests are run in the glsnet2.5\test directory. The directory glsnet2.5\data contains the input data and the expected results for each test. After each test is completed, compare the results to the expected results using a file comparison utility such as fc. If all goes well, there should be no differences. To clean up after the tests, type the command: clean Run the tests by following the steps below. Test 1: - Attach to the glsnet2.5\test subdirectory and run test1.bat, which will copy data files into the subdirectory and execute GLSNET. - On the opening screen, type "@". In the small panel that appears, type "..\data\test1.log". - GLSNET will be run using the keystrokes in ..\data\test1.log as if they were typed in. When plots are displayed on the screen, press the Enter (Return) key for the program to continue reading from ..\data\test1.log. - The file test1.out will be produced. Compare this file to the copy found in the glsnet2.5\data subdirectory. For example, if the fc command is available, the files can be compared by typing "fc ..\data\test1.out test1.out". Test 2: - Attach to the glsnet2.5\test subdirectory and run test2.bat, which will copy data files into the subdirectory and execute GLSNET. - On the opening screen, type "@". In the small panel that appears, type "..\data\test2.log". - GLSNET will be run using the keystrokes in ..\data\test2.log as if they were typed in. When plots are displayed on the screen, press the Enter key for the program to continue reading from ..\data\test2.log. - The files listed below will be produced and should be compared with the files by the same name found in the glsnet2.5\data subdirectory. test2.ot1 test2.ot2 test2.out 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 G. GRAPHICAL OUTPUT Graphical output is generated using the INTERACTER graphics library from Interactive Software Services, which is bundled in with the program executable. Graphical output may be displayed on the screen or output to a printer or pen plotter. The file INTERACT.INI is used to identify the specific printer and (or) plotter in use with the PC. An example INTERACT.INI is included in the glsnet2.5\bin_data subdirectory and is copied into the current working directory upon execution of GLSNET unless a file by the same name already exists. Modify the copy of INTERACT.INI in the current working directory as described below to identify the specific printer and (or) plotter in use with your PC. To identify the printer type, include a line in INTERACT.INI containing printer = n where n is one of the following values: 2 - IBM Graphics printer/80 columns 3 - Panasonic KX-P1081 4 - Amstrad DMP 3000 5 - Epson FX type/80 columns 6 - Epson FX type/wide carriage 7 - Epson MX type/80 columns 8 - Epson MX type/wide carriage 9 - Shinwa CP80 10 - HP LaserJet + 11 - HP LaserJet II 12 - IBM Graphics printer/wide carriage 13 - HP PaintJet 14 - HP DeskJet (inc. DeskJet+ and DeskJet 500) 15 - IBM Proprinter/80 columns 16 - IBM Proprinter/wide carriage 17 - Epson LQ type/80 columns 18 - Epson LQ type/wide carriage 19 - IBM Proprinter X24/80 columns 20 - IBM Proprinter X24/wide carriage 21 - HP DeskJet 500C 22 - HP DeskJet 500 23 - Epson JX type/80 columns 24 - Epson JX type/wide carriage 25 - Epson LQ/color 80 columns 26 - Epson LQ/color wide carriage 27 - DEC LN03/LN03+ (ANSI text mode) 28 - HP LaserJet III To identify the plotter type, include a line in INTERACT.INI containing plotter = n where n is one of the following values: 1 - Unspecified HP-GL compatible plotter 2 - Hewlett Packard 7475A using A4 paper 3 - Hewlett Packard 7475A using A3 paper 4 - Epson HI-80 with HP emulation ROM 5 - Facit 4550 A4 6 - Hewlett Packard 7440A A4 (HP Colorpro) 7 - Hewlett Packard 7550A using A4 paper 8 - Hewlett Packard 7550A using A3 paper 9 - Facit 4551 A4 paper 10 - Facit 4551 A3 paper 11 - HP LaserJet III in HP-GL/2 mode (the HPGL output produced will contain escape sequences at the start and end of the file to switch the printer into and out of HP-GL/2 mode) When the printer or plotter is the selected graphical output device, output will appear on the screen simultaneously and there may be some delay as the printer or plotter output is generated. Pressing the Enter key to clear the graphic from the screen is not necessary as when the screen is the selected output device. To output directly to a PostScript printer, no printer identifier need be specified. Instead, create a file named "TERM.DAT" containing the line "GKSPRT 4" in the directory in which you are running the program. Alternatively, raster graphical output will be sent to your printer if a TERM.DAT file does not exist in the directory from which you are running the program or if the TERM.DAT file does not include a line containing "GKSPRT n". Note that the printer is expected to be connected to PRN. If your printer is connected to a different port, produce the INTERACT.PLT file as described below and copy INTERACT.PLT to the port to which your printer is connected. To create a file of raster graphical output that may be copied to a printer at a later time, edit the TERM.DAT file to contain the line "GKSPRT 5". The file INTERACT.PLT will be generated. Copy INTERACT.PLT to your printer using the /B switch to indicate that it is a binary file, e.g., COPY INTERACT.PLT PRN /B. Plotter output, in HP-GL format, cannot be sent directly to your plotter but is placed in INTERACT.PLT, overwriting any previous contents. Copy the INTERACT.PLT file to the port to which the plotter is connected, e.g., COPY INTERACT.PLT COM1. 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