README.TXT ANNIE A Computer Program for Interactive Hydrologic Data Management Version 4.1 2002/02/25 IMPORTANT NOTE: If you have n-day data sets that were created using the N-day option in version 3.2 of SWSTAT, you will need to run WDMRX to correct a problem with the SEADBG and SEADND attributes. WDMRX is distributed with ANNIE. Instructions for installation, execution, and testing are provided below. After installation, see annie.txt in the doc subdirectory for summary information on ANNIE. For assistance, enhancement requests, or to report bugs, contact the Hydrologic Analysis Software Support Program by sending e-mail to h2osoft@usgs.gov. TABLE OF CONTENTS A. SYSTEM REQUIREMENTS B. DISTRIBUTION FILE C. DOCUMENTATION D. INSTALLING o Installing ANNIE o ANNIE directory structure E. COMPILING (optional) F. RUNNING THE SOFTWARE o Out of environment space error G. GRAPHICAL OUTPUT H. TESTING I. UNINSTALLING J. CONTACTS A. SYSTEM REQUIREMENTS To install and run ANNIE, the following are necessary: - Pentium-class PC - Windows 9x/Me, Windows NT 4.0, Windows 2000, or Windows XP - up to 5.8 megabytes of free disk space - 5.9 megabytes of free memory - on Windows 9x/Me machines, MS-DOS Command Prompt window memory settings as described below A memory protection fault error can occur on Windows 9x/Me machines if the memory settings of MS-DOS Command Prompt windows are not set as follows: After opening an MS-DOS Command Prompt window, click the icon in the upper left corner of the window and select the Properties menu item. Select the Memory tab and modify the fields to set everything to "Auto", but change "Expanded (EMS) memory" to "none" and enter 65535 (the maximum allowed value) in the "MS-DOS protected-mode (DPMI) memory" input field. B. DISTRIBUTION FILE The following distribution file (containing the software, test data sets, and information files) is currently available. annie4_1.exe - Compiled using Lahey Fortran 90, includes source C. DOCUMENTATION Flynn, K.M., Hummel, P.R., Lumb, A.M., and Kittle, J.L., Jr., 1995, User's manual for ANNIE, version 2, a computer program for interactive hydrologic data management: U.S. Geological Survey Water-Resources Investigations Report 95-4085, 211 p. This document is available in electronic format. A Portable Document Format (PDF) version is included in the doc subdirectory of the ANNIE program distribution. This and other formats can also be found at http://water.usgs.gov/software/annie.html. See http://water.usgs.gov/software/ordering_documentation.html for information on ordering printed copies of USGS publications. D. INSTALLING Installing ANNIE ---------------- Follow the steps below to install ANNIE: 1. If a previous version of ANNIE is already installed, remove it. If you previously installed ANNIE 4.0, double-click Add/Remove Programs in the Control Panel, select ANNIE 4.0, and click the Add/Remove button. Any user files in the ANNIE installation directory--such as those created in the test or user subdirectories--will be left behind intact. Move any such user files that need to be retained to another directory and delete the old annie4.0 installation directory. -- OR -- If you previously installed an earlier version of ANNIE, move to another location any data files that you happened to store in the ANNIE installation directory, then: a) Delete the annieX.X directory and its contents, where X.X is the version number of the previously-installed version. b) If you modified the PATH environment variable to make the previous version of ANNIE easily accessible from any directory, remove the annieX.X\bin directory from the PATH environment variable: (1) On Windows 9x machines, edit C:\AUTOEXEC.BAT to remove the annieX.X\bin directory from the "set PATH=" command. Reboot your system after modifying AUTOEXEC.BAT. (2) On Windows Me machines, select Run from the Start menu, enter "msconfig", and click OK. Select the Environment tab, select the PATH variable, and click the Edit button. Remove the annieX.X\bin directory from the value of PATH and click OK. (3) On Windows NT/2000 machines, double-click System in the Control Panel, select the Environment tab, and modify the value for Path to remove the annieX.X\bin directory. Rebooting is not necessary, but any existing MS-DOS Command Prompt windows should be closed and reopened. 2. Double-click annie4_1.exe to execute the installation program. Follow the directions on the screen. By default, the software is installed in the directory C:\Program Files\USGS\annie4.1. This is the recommended installation directory, but you may use other directories or disk drives. Note that program components not installed initially can be installed later, and that any components damaged by, for example, being inadvertently overwritten, can be quickly reinstalled by double-clicking annie4_1.exe--a maintenance version of the installation program will be executed. ANNIE directory structure ------------------------- The following directory structure will be created (the contents of each directory are shown to the right): annie4.1 files NOTICE.TXT, RELEASE.TXT, and this README.TXT `-----bin ANNIE and WDMRX executables `-----bin_data data files required during execution `-----doc documentation files (see file Contents.txt) `-----src Makefile and source code `-----msg files for building message file `-----test files for running verification tests `-----data standard data sets used in verification tests `-----user batch files for running executables Notes: a) The src and msg subdirectories are not installed in the Typical or Compact installations, but can be installed by choosing the Custom installation and selecting the Source Code component. b) The Compact installation will install only the bin, bin_data, and user subdirectories. c) It is recommended that any user files kept in the ANNIE directory structure be placed in the user subdirectory only. d) To compile a new version of the software, you will also need: (1) libraries and other data files from the libanne library distribution (version 4.0 or later, available from http://water.usgs.gov/software/libanne.html), (2) a Fortran compiler (77 or later), and (3) a Graphical Kernel System (GKS) library or the INTERACTER graphics library. E. COMPILING (optional) The source code is provided 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, to compile a new version of the software, you will need: a) a Fortran compiler (77 or later), b) familiarity with the compiler and the operating system under which the compiler runs (i.e., DOS or Windows), c) libraries and other data files from the LIBANNE distribution (version 4.0 or later, available from http://water.usgs.gov/software/libanne.html), and d) a Graphical Kernel System (GKS) library or the INTERACTER library from Interactive Software Services Ltd. (http://www.demon.co.uk/issltd/). As distributed, the DOS version of ANNIE is configured to be compiled with INTERACTER. INTERACTER is not a GKS library, but it is utilized by the DOS version of ANNIE through the use of code that substitutes appropriate INTERACTER subroutine calls for GKS subroutine calls. To compile ANNIE with a GKS library, see the README.TXT documentation distributed with LIBANNE for information on modifying graph.lib. Note that under Windows NT/2000/XP ANNIE must be compiled as a DOS executable (as opposed to a Windows console-mode executable). Subroutines within the LIBANNE util.lib library require the ANSI.SYS device driver, but ANSI.SYS is only supported for DOS applications and not for Windows applications under Windows NT/2000/XP. The Makefile used to compile the executable, using the Lahey Fortran 90 compiler and the Opus make program, is provided as an example. Lahey previously distributed the Opus make program with its compilers, but has since substituted the simpler automake program. The syntax of the Makefiles used with Opus make is very similar to that of UNIX make and can be adapted for use with other make programs. There will likely be further changes needed to compile using a different compiler. F. RUNNING THE SOFTWARE If the option to modify the PATH environment variable was chosen during installation, ANNIE can be run in an MS-DOS Command Prompt window from any directory by typing "annie". If the option to modify the PATH environment variable was not chosen during installation, the full path name of the program must be typed, as in, for example, "c:\program files\usgs\annie4.1\bin\annie" (note that quotation marks must be typed with and enclose any command name with spaces embedded). Alternatively, you can run ANNIE by selecting the ANNIE shortcut from the Start menu. The shortcut is found under Programs, in the Program Folder specified during installation (default: USGS). The shortcut will run ANNIE from the user subdirectory. Therefore, if an input file name is specified with no directory path preceding the name, the input file will be expected to be found in the user subdirectory. Likewise, if an output file name is specified without a directory path preceding the name, the output file will be placed in the user subdirectory. Note that when plots are displayed on the screen, they will be displayed in full-screen mode and will be held on the screen until the Enter key is pressed. If, after pressing the Enter key to clear a plot, the display remains in full-screen mode (which will be the case under Windows NT/2000/XP), press alt+Enter to return from full-screen mode to window mode. Note also that, depending on the video card and monitor of the PC, the quality of the screen display of plots may be improved on Windows 9x/Me machines by removing the "display=10" line from the interact.ini initialization file (see below for details on interact.ini), though this line should not be removed during execution of the verification tests. The "display=10" line is necessary for proper display of plots on Windows NT/2000/XP machines. Out of environment space error ------------------------------ This error can occur when running ANNIE, including when running the verification tests. The error occurs when there is insufficient space to hold a new environment variable definition. You can avoid this error by initiating a new command shell and specifying how much environment space you need. For example, in an MS-DOS Command Prompt window, typing command /e:1024 will initiate a new command shell with 1024 bytes of environment space. Environment space can be between 256 and 32768 bytes. The above command will increase the environment space for only the current Command Prompt window. To permanently increase your environment space, on Windows 9x/Me machines, click the MS-DOS icon in the upper-left corner of the Command Prompt window and select Properties. Select the Memory tab and increase the value in the Initial environment field. On Windows NT/2000/XP machines, add the above command to C:\winnt\system32\config.nt and initiate and use a new MS-DOS Command Prompt window. G. GRAPHICAL OUTPUT Graphical output is generated using version 5.0 of the INTERACTER graphics library from Interactive Software Services Ltd., which is bundled in with the program executable. Graphical output may be displayed on the screen, written to a printer file for subsequent printing on your printer, or written in various output formats for importing into other software packages, such as word-processing and desktop-publishing programs. For a partial listing of which software packages can import the output formats described below, see grexport.txt in the doc subdirectory. The menu choices presented to you for selection of a graphical output device will be: Screen, Laser, Plotter, and Meta. Screen ------ Plots are displayed in full-screen mode and remain on the screen for viewing until the Enter key is pressed. If, after pressing the Enter key to clear a plot, the display remains in full-screen mode (which will be the case under Windows NT/2000/XP), press alt+Enter to return from full-screen mode to window mode. Laser ----- By default, a printer file formatted for your printer type will be produced and will be named interact.plt. Your printer type must be defined in the initialization file interact.ini (see below). To send a printer file to your printer, in an MS-DOS Command Prompt window, change to the directory containing the printer file and type one of the following commands: copy /b interact.plt lpt1 copy /b interact.plt \\\ where is the name of the computer within your local network to which the printer named is attached. Use the first command above if you have a printer attached to your PC, substituting the name of the port to which the printer is connected, if not lpt1. Graphical output is alternatively written in one of the output formats listed below if a file named TERM.DAT is present in the directory in which you are running ANNIE and it includes the "GKSPRT" parameter followed by one of four possible values: Line in TERM.DAT Output format Output file name ---------------- --------------------------- ---------------- GKSPRT 5 Encapsulated PostScript interact.eps GKSPRT 6 PostScript interact.ps GKSPRT 7 PC Paintbrush interact.pcx GKSPRT 8 Windows bitmap (compressed) interact.bmp Note that Encapsulated PostScript and PostScript files are intended for printing on PostScript printers and can be sent to a PostScript printer as described above for printer files. Prior to printing on a PostScript printer, Encapsulated PostScript files can be imported into many word-processing and desktop-publishing packages. Although the imported image will usually not be viewable but will instead only be represented as an empty frame, the image can, in most cases, be repositioned on the page, rotated, and scaled before printing. PC Paintbrush and Windows bitmap files can be imported into many word-processing and desktop-publishing packages. Plotter ------- A Hewlett-Packard Graphics Language file named interact.hpg will be produced which can be imported by some word-processing and desktop-publishing packages or can be sent to a pen plotter. The HP-GL file will be formatted for the plotter type defined in interact.ini. Meta ---- A binary Computer Graphics Metafile (CGM) named interact.cgm will be produced which can be imported by many word-processing and desktop- publishing packages. Modifying the text font ----------------------- The font used for plot titles, axes labels, etc. can be modified for each output device by assigning the values in the table below to the appropriate TERM.DAT parameter. Three parameters control the text font used in plots: GKSCFT specifies the screen and meta file font, GKPRFT specifies the printer font, and GKPLFT specifies the plotter font. In the table below, font 1 is a vector font, where each character is made up of a series of straight lines. The remaining fonts are outline fonts, where each character is drawn as an outline which is then filled as a polygon. Font 1 has a cleaner appearance at low resolutions, and has the cleanest appearance of all the fonts when displayed on the screen. The remaining fonts provide a better-looking result at higher resolutions. TERM.DAT value Font -------------- ------------------------------------------------------------ 1 sans serif (GKSCFT default) 2 sans serif, similar to Helvetica (GKPRFT and GKPLFT default) 3 sans serif, boldface, similar to Helvetica 4 serif, similar to Times Roman 5 serif, boldface, similar to Times Roman 6 monospace, similar to Courier 7 monospace, boldface, similar to Courier To illustrate the use of the above values, you would create a TERM.DAT file in the directory in which you are running ANNIE that contains the following 3 lines in order to use a Helvetica-like font in the screen display and meta file output, a Times-Roman-like font in printer output, and a boldface, Courier-like font in plotter output: GKSCFT 2 GKPRFT 4 GKPLFT 7 Note again that, depending on the video card and monitor of the PC, the quality of the screen display of plots--and especially the display of the plot text--may be improved on Windows 9x/Me machines by removing the "display=10" line from the interact.ini initialization file, though this line should not be removed during execution of the verification tests. The "display=10" line is necessary for proper display of plots on Windows NT/2000/XP machines. Important notes --------------- Note that graphical output written to, for example, interact.pcx, will overwrite any previously-generated PC Paintbrush output written to interact.pcx. To generate multiple graphical output files of the same format in a single program session, it is necessary to rename interact.* to a unique file name after each plot is generated. This can be done in My Computer, Windows Explorer, or in a second, separate MS-DOS Command Prompt window from that in which ANNIE is run. In My Computer or Windows Explorer, highlight the interact.* file you want to rename and select Rename from the File menu. In an MS-DOS window, use the rename command, as in, "rename interact.pcx plot1.pcx". Note also that changes made to the TERM.DAT file must be made prior to initiating a program session in order for those changes to take effect, but that changes can be made to interact.ini during a program session, in between the production of plots. Initialization file interact.ini -------------------------------- The file interact.ini is used to specify the printer and plotter type for which printer files and HP-GL files, respectively, will be formatted. An example interact.ini is included in the bin_data subdirectory and is copied into the current working directory upon execution of ANNIE, unless a file by the same name already exists. Modify the copy of interact.ini in the directory in which you are running ANNIE as described below to assign the appropriate values to the "printer" and "plotter" keywords. The value assigned to the "printer" keyword can be any one of the values below. If your specific printer is not listed below, consult the file printers.txt in the doc subdirectory to see which printer type below would be equivalent to your printer. Note that, in printers.txt, for the printers for which INTERACTER driver 2 is listed, PostScript or Encapsulated PostScript files should be generated; printer files cannot be generated for those printers. 2 - IBM Graphics printer 3 - Panasonic KX-P1081 4 - Amstrad DMP 3000 5 - Epson EX/FX/LX/RX 6 - Epson EX/FX/LX/RX (wide carriage) 7 - Epson MX-80 type II/III 8 - Epson MX-100 9 - Shinwa CP80 10 - HP LaserJet + 11 - HP LaserJet II 12 - IBM Graphics printer (wide carriage) 13 - HP PaintJet 14 - HP DeskJet and DeskJet+ 15 - IBM Proprinter 16 - IBM Proprinter (wide carriage) 17 - Epson LQ/SQ 18 - Epson LQ/SQ (wide carriage) 19 - IBM Proprinter X24 20 - IBM Proprinter X24 (wide carriage) 21 - HP DeskJet 500C or 310/color 22 - HP DeskJet 310/320/500/510/520 (monochrome) 23 - Epson JX/LX color 24 - Epson JX/LX color (wide carriage) 25 - Epson LQ color 26 - Epson LQ color (wide carriage) 28 - HP LaserJet III/4L 29 - HP LaserJet 4/5 30 - HP PaintJet XL 300 31 - HP DeskJet 550C/560C/660C 32 - HP DeskJet 1200C/1600C 33 - HP DeskJet 540/monochrome 34 - HP DeskJet 540/color 35 - HP Color LaserJet 36 - Epson Stylus 37 - Epson Stylus color 38 - HP Color LaserJet 4500/8500 The value assigned to the "plotter" keyword can be any 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 H. 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 tests are run in the test subdirectory. The data subdirectory contains the input data and the expected results for each test. Run the tests by first opening an MS-DOS Command Prompt window and changing to the test subdirectory by typing the following (substitute the drive letter and directory where you installed ANNIE, if you did not install it in the default location): c: cd "program files" cd usgs\annie4.1\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, the only differences that will appear will be in test3.exp and test4.exp in the values for the attributes DATCRE and DATMOD--the dates of data-set creation and last modification, respectively. To clean up after the tests, type the command: clean Note: Some of the tests may require input generated by a previous test, so they should be run in sequential order. Run the tests by following the steps below. Test 1: - Type "annie" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\test1.log". ANNIE will be run using the keystrokes in ..\data\test1.log as if they were typed in. - The files test.wdm and error.fil will be produced. (In addition to possibly containing error messages, error.fil contains a record of some of the program operations executed.) Compare error.fil to ..\data\test1.err by typing: fc ..\data\test1.err error.fil Test 2: - Type "annie" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\test2.log". ANNIE will be run using the keystrokes in ..\data\test2.log as if they were typed in. - The files test2.out and error.fil will be produced. Compare these files to their counterparts in the data subdirectory by typing: fc ..\data\test2.out test2.out fc ..\data\test2.err error.fil Test 3: - Type "annie" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\test3.log". ANNIE will be run using the keystrokes in ..\data\test3.log as if they were typed in. - The files test3.exp and error.fil will be produced. Compare these files to their counterparts in the data subdirectory by typing: fc ..\data\test3.exp test3.exp | more fc ..\data\test3.err error.fil Test 4: - Type "annie" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\test4.log". ANNIE will be run using the keystrokes in ..\data\test4.log as if they were typed in. - The files test4.exp and error.fil will be produced. Compare these files to their counterparts in the data subdirectory by typing: fc ..\data\test4.exp test4.exp fc ..\data\test4.err error.fil Test 5: - Type "annie" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\test5.log". ANNIE will be run using the keystrokes in ..\data\test5.log as if they were typed in. - The files test5.ot1, test5.ot2, and error.fil will be produced. Compare these files to their counterparts in the data subdirectory by typing: fc ..\data\test5.ot1 test5.ot1 fc ..\data\test5.ot2 test5.ot2 fc ..\data\test5.err error.fil Graphics tests 1-6: - Type "annie" to execute the program. - On the opening screen, type "@". In the small panel that appears, type "..\data\graphN.log", where N is the test number, 1-6; e.g., to run graphics test 1, type "..\data\graph1.log". - ANNIE will be run using the keystrokes in ..\data\graphN.log as if they were typed in. When plots are displayed and remain on the screen for viewing, press the Enter key for the program to continue. If, after each test completes, the display remains in full-screen mode (which will be the case under Windows NT/2000/XP), press alt+Enter to return from full-screen mode to window mode. For each of the graphics tests, PC Paintbrush graphical output will be placed in the file "interact.pcx" and the file error.fil will be produced. Compare these files to their graphN.* counterparts in the data subdirectory. For example, following graphics test 1, you would type: fc ..\data\graph1.pcx interact.pcx fc ..\data\graph1.err error.fil The tests are described in the tables below, where 'test' is the test number 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 description of test and files file name & usage ---- --------------------------------- ----------------- 1 Create the wdm file, import two files in the wdm export format (must be run before tests 2-5 and graphics tests 1-6). command file test1.log i data for Cane Branch cane.exp i Illinois basin characteristics il.exp i data management file test.wdm o error file error.fil o 2 Output to a file a table of selected attributes for the Cane Branch and Illinois data (run after test 1). command file test2.log i data management file test.wdm i output table of attributes test2.out o error file error.fil o 3 Use the generate options to (1) compute inches of runoff from cfs and (2) transform 15-minute discharge to 1-hour discharge and then archive the new data sets (run after test 1). command file test3.log i data management file test.wdm i/o archive file of new data sets test3.exp o error file error.fil o 4 Test import and export of a range of data values (run after test 1). command file test4.log i data management file test.wdm i/o archive import file test4.imp i archive export file test4.exp o error file error.fil o 5 List time-series data (1) within a specified range and (2) screen for outliers and magnitude changes. Table time-series data (run after test 1). command file test5.log i data management file test.wdm i/o time series listings test5.ot1 o tabled time series test5.ot2 o error file error.fil o Graphics tests: test description of test and files file name & usage ---- --------------------------------- ----------------- 1 time-series graph of Cane Branch x - time left y - discharge hydrograph right y - evaporation aux - precipitation command file graph1.log i data management file test.wdm i PC Paintbrush file interact.pcx o error file error.fil o 2 time-series graph of Cane Branch x - time left y - discharge aux - precipitation and evap command file graph2.log i data management file test.wdm i PC Paintbrush file interact.pcx o error file error.fil o 3 x-y graph of Cane Branch x - monthly evap left y - monthly precipitation command file graph3.log i data management file test.wdm i PC Paintbrush file interact.pcx o error file error.fil o 4 x-y graph of Cane Branch, check for uneven no. of time series command file graph4.log i data management file test.wdm i PC Paintbrush file interact.pcx o error file error.fil o 5 x-y plot of the Illinois basin characteristics left y - P100 and x - DAREA command file graph5.log i data management file test.wdm i PC Paintbrush file interact.pcx o error file error.fil o 6 x-y plot of the Illinois basin characteristics left y - P100 and right y - p1.25 x - DAREA command file graph6.log i data management file test.wdm i PC Paintbrush file interact.pcx o error file error.fil o I. UNINSTALLING To uninstall ANNIE, double-click Add/Remove Programs in the Control Panel, select ANNIE 4.1, and click the Add/Remove button. Any user files in the ANNIE installation directory--such as those created in the test or user subdirectories--will be left behind intact. J. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Program 437 National Center Reston, VA 20192 e-mail: h2osoft@usgs.gov