RdfAnnualizer Help Information


Table of Contents


Overview

The RdfAnnualizer will take a RiverWare Data Format (RDF) file with a timestep of less than a year and will aggregate its data to generate an RDF file with an annual timestep. Methods for aggregating data for the slots in the RDF file are specified via a method control file. The user also specifies the end month for the aggregated year, so calendar years or water years can be generated, for example. The tool can be operated in an interactive mode or in a batch mode as discussed later in this document.

Source RDF File

RDF files are generated from RiverWare and contain data for slots specified by the user. Non-series slots can be written to RDF files, but only data for series slots will be processed by the RdfAnnualizer tool. The exact format of an RDF file is described in the Output and Plotting section of RiverWare Online Help. An RDF file for results from a single run in RiverWare can be created from the Output Manager via a RiverWare Data File device. Slot data for a multiple run in RiverWare can be output to an RDF file by configurations in the Output tab of the MRM Configuration dialog.

The source RDF file should contain series data with a timestep of less than a year.Currently in RiverWare this would include timesteps of  1 hour, 6 hour, 12 hour, daily, weekly, and monthly. If a yearly timestep file is specified as input to the RdfAnnualizer, an error message will be returned that the run is already in an annual timestep.

Method Control File

The method control file specifies the slots to be processed and the annualization method associated with the slots. The file is a text file and the syntax is for each line to contain an entry of the form:
Object.Slot: Method
where Object can be:
where Slot can be:
and where Method can be any of the following:
The behavior of the non-Nan methods is to report NaN for the summary value if any of the input values for the year are NaN. The Nan suffix on a method means that NaN input values are ignored in calculating the summary value.

If the same slot is identified more than once in the method control file through specific declarations or wildcards, the method is set at the first identification and not changed thereafter.

Example Method Control File

An example method control file might contain the following entries:

*.Outflow: Average
*.Pool Elevation: End
Big Reservoir.Evaporation: SumNan
DataObj.*: EndNan

Outflow for all objects in the file will be averaged over the year and if any outflows are NaN, the result for the year will be NaN. Pool Elevation for all abjects in the file will be the last value for the year and if any values over the year are NaN, the result will be NaN. For the object named Big Reservoir, its evaporation slot will be summed over the year, and if any values are NaN, they will be skipped and the remaining values will be used in the sum. For all objects in the file that are data objects, all of their slots will be assigned the last value of the year whether there are any NaNs or not in the data over the year.

End Year Month

The RdfAnnualizer will take a month specification that becomes the end of year for the annualization calculations that generate the result RDF file. The default is December for annualizing to calendar years, but any month can be specified, such as September for water years. Another example would be if you want an RDF file with storage for reservoirs at the end of March, you could annualize with March as the end month and use the End method to get the last value for the year.

Note that if the timesteps in the source RDF file generate partial years at the beginning or end of the time range when annualized into the defined year, the partial years are dropped when the result RDF file is written. The result annual RDF file only contains data for full annualized years.

Result Annual RDF File

The result RDF file contains all of the same descriptive fields as the original source RDF file, such as name, owner, description, etc., and will contain the same number of runs. Note that only slots from the original file that have a method defined in the method control file will be annualized, so the output RDF file could have  fewer slots than the input file (also any non-series slots in the source RDF file will not be annualized). The time_step_unit field is written as year, and the end times for the specific annualized years are listed as the new timesteps for the file.

The same slot header information is listed in the result file for annualized  slots, except a method field is added to show the specific method for how that slot's data was annualized. Also, if the method was Sum or SumNan, the units field for the slot has the phrase "summed over the year" added to it (such as "acre-ft/month summed over the year"). Otherwise, the result annual RDF file looks exactly like an RDF file that was output from a RiverWare model with a yearly timestep.

Interactive Mode

The interactive mode for the tool is started by double-clicking on RdfAnnualizer.exe in Windows Explorer or by entering the program name with no arguments at a Command Prompt. This brings up the following dialog:

RdfAnnualizer Dialog

The Source RDF File, Method Control File, and Result Annual RDF File can be indicated by either using the associated "Select..." button to open a file chooser dialog, or by typing in the path and file name into the file's text field.  In any of these file paths, environment variables of the form $NAME, for example, can be typed in and the NAME environment variable defined on the system would then be substituted into the path when the program is run.

The End of Year Month is a combo box where the month for the end of the annualized year can be selected by the user.

Clicking the "Create RDF File" button will run the program and create the result annual RDF file. If any errors are encountered, they will be displayed in a separate message box. Clicking the "Show Diagnostics" button will bring up a separate dialog where diagnostics and errors from runs are displayed. Clicking the "Help" button will display this help document in a text window. Clicking the "Cancel" button will exit the program.

Batch Mode

The RdfAnnualizer has a batch mode where the program can be executed without invoking the GUI. This can be useful for incorporation into a script that might automatically execute a number of operations in a sequence, including annualizing an RDF file. Batch mode is initiated by entering the program name with one or more arguments at a Command Prompt. The following shows its usage along with valid arguments and their description:

Usage:  RdfAnnualizer <-i file> <-o file> <-c file> <-l file> <-y number> <-h> <-v>
-i: This specifies the input RDF file (required).
-o: This specifies the output annual RDF file (required).
-c: This specifies the method control file (required).
-l: This specifies the log file for messages.
    (will default to the output RDF file name plus a .log file extension)
-y: This integer number specifies the month that you want the year to end with (1 to 12).
    (will default to 12 for December)
-h: This will print help information.
-v: This will print the version number.

Examples

1)  RdfAnnualizer.exe -h
Entering this on the command line will bring up a console window that displays the usage and argument information. The console can be exited by pressing any key.

2)  RdfAnnualizer.exe -v
This prints out the version number of the RdfAnnualizer program to a console window that can then be exited by pressing any key.

3)  RdfAnnualizer -i C:\Temp\Input.rdf -o C:\Temp\Annual.rdf -c C:\Temp\Input.control 
     -l C:\Temp\Annual.log -y 10
This represents a full specification for creating an annual RDF file named Annual.rdf from a source RDF file named Input.rdf using a method control file named Input.control. The input (-i), output (-o) and control file (-c) arguments are all required. Informational messages and any error messages from the run will be written to the Annual.log file specified by the -l argument. The -l argument is optional and if not specified, the log file will default to the output annual RDF file path and name, but with a .log file extension. Note that environment variables of the form $NAME, for example, can be typed in any of the file paths, and the NAME environment variable defined on the system would then be substituted in when the program runs.The -y argument of 10 means the annualized year will end in September, so would be from October 1st through September 30th. The -y argument is optional and will default to 12 for an annualized year of January 1 through December 31st.