WRAP: Water Rights Analysis Package

Clark Siler, CRWR

 

Table of Contents

 

Introduction

Texas suffered a particularly hard year of drought in 1996. The following year, the Texas legislature passed Senate Bill 1, or the “Water Bill.” This bill changed the way that many aspects of water planning were performed. These changes were facilitated by the implementation of new technological advancements, including use of GIS. One area of change was in the monitoring and record keeping of water rights.[1]

WRAP Origins and Current Use

Dr. Ralph Wurbs of the Texas Water Resources Institute (at Texas A&M University) developed a suite of modeling programs called the Water Rights Analysis Package (WRAP). WRAP is a computer program that digitally manages water rights. This replaces the older method of tracing lines on maps to determine various relationships and properties of water rights.[2]

 

As a computer model, WRAP undergoes improvements and additions to meet the needs of increasing use and technology. In September 2006, the newest version or WRAP was released and implemented by the Texas Commission on Environmental Quality (TCEQ).

 

TCEQ actively uses WRAP with their water availability model system (WAM) to predict water quantities in streams, reservoirs, and watersheds.[3] This information is essential in the allotment and assigning of water rights to meet the need of Texans.

WRAP Research

The author is involved in research for TCEQ, with Dr. David Maidment and Dr. Tim Whiteaker of the Center for Research in Water Resources (CRWR), into problems and solutions related to the changes in the most recent version of WRAP and its output, which affects a WRAP Display tool used by TCEQ. This research is primarily involved in the output of WRAP—the back end of the program package.

This paper provides a brief orientation to the WRAP process, examines the inconsistencies between WRAP output versions, compares WRAP modeled results to real data (through an examination of drought conditions), and discusses methods for storing WRAP output data in database format.

WRAP Process

The Water Rights Analysis Package, or WRAP, is, as its name states, a package for analyzing water rights. This package is a collection or suite of programs that work together with the end goal of producing useful output. The path from initial data to the end result output is followed as each of WRAP’s programs is examined. In this process, please refer to Figure 1 for both orientation and general descriptions.

 

Figure 1. Water Rights Analysis Package Procedure

 

Figure 1 presents a simplified outline or flowchart of the WRAP process. This figure shows the input and output for each of the programs comprising WRAP. Please note that this flowchart is simplified and excludes much of WRAP’s functionality, including capabilities for modeling salinity and options for extended, daily, output.

Input and Output Format

The modular programs of WRAP employ command line interfaces (similar to DOS) that many elementary computer programs use. WRAP utilizes an organizational style that is reliant on ASCII text files. These files are rigidly organized, delimited by spaces, and require that the data be exactly placed—a deviation by a single space wreaks havoc on the programs’ processing capabilities. Nevertheless, despite these files’ rigid requirements, experienced users are able to navigate the tedious waters of input file manipulation. 

WinWRAP

Shown as an overarching yellow banner in Figure 1, WinWRAP is a WRAP wrapper which provides a “soft,” user-friendly graphical user interface. WinWRAP is shown as being over all other programs because it provides access to the three main components of WRAP: WRAP-HYD, WRAP-SIM, and TABLES, with the user not being subjected to these programs’ native command line interface format. While WinWRAP alleviates the need to individually access the other programs, the necessary input files must be organized properly, as they would usually be, before this application can be successfully used.

 

In the path through WRAP’s workings, the user enters WinWRAP either with the input files required for WRAP-HYD or with those for WRAP-SIM. With these files in hand, the user is able to invoke the appropriate programs from a distance through the use of the WRAP wrapper: WinWRAP. The path through WRAP continues as the three pillars of WRAP, WRAP-HYD, WRAP-SIM, and TABLES are discussed.

WRAP-HYD

As described in Figure 1, WRAP-HYD provides an environment for developing necessary input files for WRAP-SIM, namely the file of monthly naturalized flows (FLO) and the file for net evaporation-precipitation depths (EVA). These files are of a hydrological nature, thus the “HYD” in WRAP-HYD.

 

Because WRAP-HYD is solely used to produce the input files for the subsequent program, its use can be skipped entirely if the FLO and EVA files are already available (e.g. TCEQ has naturalized flows for given times for Texas). As shown in Figure 1, the EVA file is both an input and output file for WRAP-HYD; therefore, the unique output is the naturalized flow file. While naturalized flows will be discussed at length in the Naturalized Flows section, it will suffice to say that the FLO file is used as a base case of flow, from which specific anthropogenic effects are added or subtracted therefrom (e.g. diversions, reservoir effects) in the process of modeling available flows for water rights (for more information, see the Naturalized Flows section of this report).

 

In the WRAP path, the user feeds historical flow and evaporation-precipitation data files to WRAP-HYD and obtains the FLO and EVA files as output. These files are then used in WRAP-SIM.

WRAP-SIM

The “SIM” in WRAP-SIM stands for simulation. This is where the main simulation of WRAP takes place. Water balances for each month of the simulation period are performed, using the FLO and EVA files, along with information for specific reservoir information, channel losses, specified diversions, instream flow requirements (amounts of flow that are required to be in the stream), and hydroelectric power requirements.

 

Three main output files are produced as part of a successful modeling session in WRAP-SIM. These files, as mentioned in Figure 1, are:

  1. MSS – the message file that reports simulation progress and errors in the input data.
  2. YRO – the yield-reliability output file.
  3. OUT – the main output file which is an extremely specifically formatted file which presents a wealth of data in many variables in a somewhat cryptic format.

 

It is the display of the WRAP-SIM output (OUT) file upon which the bulk of the author’s research is based. This file is organized in a condensed data management form, and is relatively inaccessible for the WRAP user. Additional assistance for deciphering this file is provided through the use of TABLES.

 

In the WRAP path, the user provides the WRAP-SIM output files and begins the simulation. As mentioned, a water balance for each time step is performed for each location of interest in the modeling scenario. This process is considerably fast, considering the intricate nature of WRAP’s modeling processes and the large output files produced.

TABLES

The program TABLES is the WRAP users’ greatest ally in the quest for accessible water rights data. As discussed, the WRAP-SIM output format is significantly non-user-friendly. TABLES provides a way for the user to specify the data, format organization, and format type for the WRAP simulation results. Three common format types available from TABLES are:

  1. standard text files of organized and easy to read tables of results,
  2. results in text file format for additional use in Microsoft Excel, and
  3. results in a binary file of HEC-DSSVue (U.S. Army Corps of Engineers’ Hydrologic Engineering Center Data Storage System [4]) format (a format for efficiently storing time series data, similar to NetCDF).

 

In addition to providing useful formats for data, TABLES can perform computations including reliability and frequency relationships.

 

In the WRAP path, the user feeds the WRAP-SIM output file to TABLES and specifies which data is to be displayed, if any further computations are to be done, and the format to which the data is to be written. After the necessary calculations or organizations are performed, the user is able to use the output file at their discretion, according to the output format specified. For example, TABLES provides means for the WRAP user to digest the inaccessible WRAP-SIM output file and display the output in the comfortable data access and manipulation environment the Microsoft Excel provides.

WRAP Wrap-up

Prior to WinWRAP, the user was required to invoke each of WRAP’s programs in series to obtain desired results. The implementation of WinWRAP has provided additional resource to WRAP users and has enhanced the overall WRAP experience. However, despite the advancements in user experience, the ASCII text input files are still required. The modern, novice WRAP user will typically express frustration at the requirement to have spacing be exact, and may bristle at the lack of friendly forms to input data in a more Excel-esque environment. Nevertheless, with training (and patience) the WRAP user can harness the modeling power that WRAP provides.

 

The output from WRAP is used in geographical (GIS) displays. The WRAP Display tool, which is used by TCEQ to display this data, was rendered useless after the most recent version of WRAP was released. This situation is the source for the WRAP research currently underway. In particular, the apparent limitations of the current WRAP Display tool are:

  1. Inconsistent display results
  2. Inability to process large output files
  3. Lack of preprocessing tools
  4. Insufficient display parameter options

 

These limitations are discussed in the following sections.

Inconsistent Display Results

The WRAP output produced with the older version produced reasonable display results when used with the Display tool. The same data, produced by the new version, resulted in invalid results, as illustrated in Figures 2 and 3. These figures show percent of storage in the Cypress watershed (in northeastern Texas) using the two versions.

 

 

Figure 2. Proper WRAP Display From Older Version

 

Figure 3. Inconsistent WRAP Display

 

Examining the WRAP output file, which is used as the main input for the WRAP Display tool, reveals that the problem lies in field spacing. Figure 4 and Figure 5 show WRAP output files from the older (2004) and the new (2006) version, respectively. These figures also show examples of fields that the WRAP Display tool extracts data from. To best see the size differences in these fields, Figure 6 shows both output files overlaid.

 

Figure 4. WRAP 2004 Output File

 

Figure 5. WRAP 2006 Output File

 

Figure 6. Both WRAP Versions' Output Files

The new WRAP 2006 version’s output file has different spacing than past versions for the individual fields. This inconsistency prevents the WRAP Display tool from extracting the information it is designed to process. The current tool is coded to only look for information in the individual fields shown in Figure 4. The change in the output file results in incorrect data being used. Figure 7 shows the WRAP 2006 output with the 2004 spacing. This figure shows the values that the WRAP Display tool extracts for processing. Clearly values obtained in this manner result in inconsistent results.

 

Figure 7. WRAP 2006 Output with 2004’s Spacing

 

The WRAP Display tool’s code is adjusted to extract the data shown in Figure 5, and the resulting GIS display is shown in Figure 8. Note that this display perfectly matches the original display using the older (2004) WRAP output file, shown in Figure 2.

 

Figure 8. Adjusted WRAP Display

Inability to Process Large Output Files

The WRAP output files can be very large. These files contain information for each water right and reservoir in the study area for each month in every year of the study period. The Colorado watershed, for example, produces an output file that cannot currently be processed by the WRAP Display tool. Attempts to use these large files result in the termination of the WRAP Display tool and ArcGIS.

 

The problem lies in the behind-the-scenes processing that takes place when files are loaded. Variables are used to contain the output file data that are subsequently used in calculations. Large files require many variables, or large arrays of variables. These large arrays demand significant amounts of computer memory, and the current Visual Basic platform on which the WRAP Display toolbar is built cannot handle this draw on memory.

 

Visual Basic 2005 (which employs .NET technology) provides means to handle these large files, including using virtual memory. Therefore, to overcome the limitations associated with large files, the WRAP Display tool will be redeveloped in this .NET environment. This change should not only rectify the size problem, but will provide avenues for further GUI development.

Lack of Preprocessing Tools

Control points are used by the models (WRAP and WAM models) to relate data in the output files with geographic data. TCEQ supplied files for this research that already had control points in place. However, to assign control point IDs to water rights features in the GIS (i.e. to preprocess), TCEQ currently uses a tedious manual method to extract the control point IDs from the output of a program called 1SRT. The ideal solution would be to read the control point IDs directly from the WRAP output file.

 

At this point, it seems that a tool can be built to read the output from the 1SRT program to populate the control point IDs. This tool would eliminate some of the manual preprocessing. However, after learning more about the 1SRT program and how it produces its output file, investigation will determine if this information can be directly extracted from the WRAP output file (thus eliminating the need for the 1SRT output in the process). This will provide a valuable preprocessing tool which may save time and reduce the tediousness of preparing data for processing.

Insufficient Display Parameter Options

Overcoming the changes in the output file format provided increased understanding of the file’s content. Thus, the display of additional variables should not present major obstacles. This process will likely involve further (deeper) parsing of the output file to harvest the desired display information. Therefore, clarification and guidance on which parameters are to be handled (and possibly where they are in the output file) is needed. These additional parameters may include options related to elevation-area-capacity curves for small reservoirs.

 

Comparing WRAP Results to Observed Data

The Neches River Basin (in eastern Texas, see Figure 9) was used for the comparison of WRAP modeled results to observed data. Reservoir storage data obtained from USGS’ National Water Information System (NWIS) [5] is shown in the following figures along with WRAP modeled results. Three of the reservoirs had ample storage data available (accessed by USGS reservoir gage data): Sam Rayburn Reservoir, B A Steinhagen Lake, and Lake Palestine. Interestingly, these are the largest of the reservoirs in the Neches Basin (larger reservoirs may be more likely to have USGS storage data).

 

Figure 9. Neches Watershed 

Data for the largest reservoir, Sam Rayburn Reservoir, is shown in Figure 10. At least two interesting facts are noticeable from this graph. While the WRAP simulation begins in 1940, the observed data is unavailable before 1965. In addition, the WRAP data begins with the reservoir full whereas the observed is near empty. The reasons for these two items are to wit: the reservoir’s construction was not completed until 1965, and WRAP simulations are based on the assumption that all reservoirs begin full. Clearly that is not the case here, but there are quantifiable reasons for the departure. Turning attention to the sets of data, the observed and WRAP modeled data seem fairly close; there are differences, but the overall feeling is one of accordance.

 

Figure 10. Observed and Modeled Data for Sam Rayburn Reservoir
 

Figure 11 shows the data for B A Steinhagen Lake. This data also exhibits the difference as that of Rayburn; this lake was completed in 1951. As far as accuracy, the observed and modeled WRAP results, while within an acceptable distance of each other, are not as close as Rayburn. Nevertheless, the general feeling is of congruity.

 

Figure 11. Observed and Modeled Data for B A Steinhagen Lake

In an entirely different spirit, Figure 12 shows the two sets of data for Lake Palestine. Interestingly, the listed date of completion is 1971, when the reservoir begins filling (perhaps prior data is related only to streamflow, incorrectly attributed to reservoir storage). The comparison of observed to modeled behavior are markedly different. Where the WRAP modeled storage seems to reflect an actual reservoir, perhaps overly dramatically, though, the observed data has the appearance of isolation from precipitation data. It is possible that there is an additional source of reservoir water in this system that is not modeled accurately in WRAP. Nevertheless, the data is irreconcilable. 

 

Figure 12. Observed and Modeled Data for Lake Palestine

Data Management

The limitations mentioned in the WRAP Output Inconsistencies section discussed changing programming environments for the WRAP Display tool to Visual Basic 2005 (which uses .NET technology). This change discards a fairly crude independent graphing utility that has no direct connection to ArcGIS and will embrace ArcGIS' graphing capabilities. This change will allow convenient user-interface solutions including having graphically connected displays, data, and graphs. However, this change required a change in data management. This is so because the older tool was able to graph data from memory whereas ArcGIS requires that data be stored and organized in tables. This requirement introduces considerable options into the WRAP research, including determining the best means for transferring and storing the data from the WRAP output ASCII file into an ArcGIS recognizable format.

Data Transfer

The process of taking ASCII data from a simple text file and placing it into a geodatabase can require considerable time depending on the method employed. For example, initial transfers required upwards of one hour for the entire process to complete. This was using fairly crude methods which were later discarded due to the incredible time commitment required for each transfer. This was particularly unacceptable considering the modeling nature of WRAP and the potential for needing to display multiple scenarios, each taking over an hour.

In order to reduce the time required for data transfer, batch writing methods are used where multiple lines of data are written to the destination at one time, as opposed to writing line by line. This difference can be compared to a trip to the grocery store. Upon arriving home, one typically does not carry each item into the house one by one but rather uses bags or boxes to bunch the items together and improve the efficiency of the whole process. Batch writing is similar in that multiple lines of data can be transferred (written to the destination) simultaneously, thus saving time over having each item written one at a time.

In addition to changing the method of writing, the organization of data was also changed. The initial trials were performed using a data structure similar to MyDB that uses one line for a single variable at a single location at a given time. The original structure of the WRAP output file (seen in Figures 4-7) is tabular where multiple variables are stored for a given time and location. When a similar structure is used in the transfer process, the total number of lines transferred can be reduced on the order of ten. This results in approximately one-tenth the processing time. In fact, the results of using this data organization structure (which may be called Arc Hydro II) will help in determining new methods of dealing with the wealth of data that is available in the world of hydrological science and research.

Combining the batch writing and data organization together results in overall data transfer times that are considerably less than initial trials. Applying these changes reduces the time from over an hour to a minutes.

Data Storage

Using ArcGIS ArcMap 9.2 provides many options for storage of data. The future of data storage seems to lie in database structures, particularly geodatabases for GIS purposes. Two options for geodatabase structures are available in version 9.2: personal geodatabase, and file geodatabase. The personal geodatabase is the traditional GIS database type [6].

  • Personal Geodatabase is based on a Microsoft Access data file and has a 2 GB size limit (This size limit is too small for many WRAP applications).
  • File geodatabase is the newer version that is not Access compliant, is not as limited (its size limit is 1 TB), and it has shown to be faster in write times than its counterpart.

The advantages and nature of the file geodatabase are well suited for the purposes of WRAP data storage. Not only can it store the large amount of data that WRAP produces, but it is faster than the other options. Using file geodatabases should provide both speed and the advantages of using cutting-edge data storage technology, both of which will contribute positively to furthering research into WRAP and its connectivity to ArcGIS.

Primary Contact:

Clark Siler
Center for Research in Water Resources
University of Texas at Austin

email: clarksiler@mail.utexas.edu

References

[1] Texas Environmental Profiles, “Senate Bill 1”: http://www.texasep.org/html/wqn/wqn_2pln_sb1.html Accessed 28 Sep 2006.

[2] Texas Water Resources Institute, New Waves, “Computerized Waters: Model changes management of Texas surface waters,” Feb 2006. http://twri.tamu.edu/news/2006-02-08/ Accessed 16 Oct 2006.

[3] Texas Commission on Environmental Quality, Water Availability Models. http://www.tceq.state.tx.us/permitting/water_supply/water_rights/wam.html Accessed 05 Dec 2006.

[4] US Army Corp of Engineers, HEC-DSS Introduction. http://www.hec.usace.army.mil/software/hec-dss/hecdss-dss.html Accessed 02 May 2007.

[5] United States Geological Survey National Water Information System, http://waterdata.usgs.gov/nwis

[6] ESRI ArcGIS 9.2 Desktop Help, Types of Geodatabases. http://webhelp.esri.com/arcgisdesktop/9.2/index.cfm?TopicName=Types_of_geodatabases Accessed 11 Jun 2007.

These materials may be used for study, research, and education, but please credit the authors and the Center for Research in Water Resources, The University of Texas at Austin. All commercial rights reserved. Copyright 2007 Center for Research in Water Resources.