RVF Forecast Data Duplication Program

This program will duplicate River Forecast Center RVF Forecast Products in the Postgresql hydro database to allow the WFO to edit any RVF river forecast while retaining the original data.

Overview: With the new era of VTEC in hydrology operations comes the necessity for a much more active participation by the WFO in editing the local river forecasts. This is because of the need to finely describe the forecasts within the data in order for RiverPro to correctly format the Watch/Warning/Advisory products and associated VTEC. This means a significant amount of editing of river forecasts will be occurring. Yet there is also a need to have the original RFC forecast available both in real-time for operations and after-the-fact. Having the original forecast available to plot together with the official forecast being edited is a great tool to provide a reference point from which to base the forecaster's edits, as well as having the original forecast available to default back to if needed. In addition, if a WFO wants to do a post-event evaluation, having preserved a copy of the original forecast allows for the comparison of the original and final forecast, the changes between them, and their effect on the applications to be evaluated.

SEW has been running this program successfully for over a year. I would highly recommend this be done at WFOs as they spin up hydro VTEC. It will be difficult to see what went wrong with RiverPro if you can't reproduce the original forecast that may have caused a problem. It would make it that much harder to fix the problems. In addition, it may give the forecaster editing the river forecast data peace of mind knowing the original forecast can always be obtained.

Program: The program script is triggered as each RVF comes in. It duplicates the RVF with a different SHEF type source code and puts it into WHFS. This forms a backup copy of the original forecasts so that they can be edited and both versions can be preserved. The instructions below describe how an AWIPS text database trigger is used on PDXRVFWW and PDXRVFCW to execute the script that does the conversion of the SHEF type source code from the original FZ to FU, and sends the new RVF copy to WHFS.

Description of what the script fz2fu.pl does:
* When invoked by the trigger, the PIL at the end of the trigger line is used as the argument to the script
* sets up a variable for a file and pathname for the temporary file output; uses the same directory that it resides in, but this can be changed (/awips/dev/localapps/hydro/bin/RIVER.TMP)
* sets up a variable for the AWIPS directory to copy the final output to for ingest into WHFS through the SHEF decoder (/data/fxa/ispan/hydro). Set this to another value to test the output
* reads from the text database the particular RVF as given by the PIL in the argument
* looks for a matching string "/???FZ" and changes the SHEF TS code from FZ to FU, where ??? is the SHEF PED; e.g. HGI, QRI, etc.. The match string changes both .E forecast series lines and .A explicit crest forecast lines in the RVF
* writes RVF back out again to a temporary file with the new type source and copies it to the script's output AWIPS directory for ingest into WHFS through the SHEF decoder.

Installation instructions: (assumes OB6 or later). Have the ET staff, AWIPS Focal Point, or ITO assist as needed.

1. Ensure that the SHEF type source FU is in the WHFS database table SHEFTS.

A. The easiest way to do this is to start Snoopyob6 and check the table.
- from the directory where Snoopy is installed: > ./snoopyob6.py
- click on Help/Table info
- select the table shefts and click the 'Full' button
- check for the FU type source

B. If it's there, go to Step 2. Otherwise, continue.

C. If FU is not in SHEFTS, you need to insert it.
- type the following commands in the query box:
> insert into shefts values('FU','Fcst RFC');
- click go
- recheck the table as in A.

or, without Snoopy . . .

A. Use line commands to access postgresql to check the table SHEFTS.
- open a terminal window and type the following commands:
> setenv PGUSER pguser
- ( if this doesn't work, try > export PGUSER=pguser). This may not be critical; things seem to work without it.
> /usr/local/pgsql/bin/psql hd_ob6xxx
where xxx is your WFO ID
> select * from shefts order by 1;
- this will list the shef type source codes recognized by WHFS; look for FU

B. If its there, quit and go to Step 2. Otherwise, continue with F.
- to quit postgresql, type the following command: > \q

C. If FU is not in SHEFTS, you need to insert it.
- type the following command:
> insert into shefts values('FU','Fcst NWRFC');
- recheck the shefts table with the 'select' SQL in D above
- when you have it inserted, quit: > \q

2. Install duplication script fz2fu.pl.

A. Install the script.
- create a directory for the script, such as /awips/dev/localapps/hydro/bin.
> mkdir /awips/dev/localapps/hydro/bin
- copy the file fz2fu.pl to /awips/dev/localapps/hydro/bin
> cp fz2fu.pl /awips/dev/localapps/hydro/bin/fz2fu.pl
- make the owner fxa:fxalpha
- make it executable: > chmod a+x fz2fu.pl

B. Change Type Source if necessary.
The script assumes that the RVF type source for the river forecasts is FZ. If your RFC uses something else, like FF, then you need to change this in the script.
- open the script in an editor using an editor like NEDIT, GEDIT, or VI
- go to the line near the bottom of the script that says 'my $match = "FZ"; # the string to find' .
Change the FZ to FF or whatever type source your RVFs use. The type source to replace it with could also be changed to any other appropriate one as long as it is in your SHEFTS table and not used by anything else. Simply change the subsequent line in the script in a similar manner.
- save and exit the editor.

3. (Optional but recommended) Test the script by command line
- go to the directory where you placed the fz2fu.pl script or change directory to it if not there: > cd /awips/dev/localapps/hydro/bin
- from the prompt, execute the script with the RVF PIL as the argument:
> ./fz2fu.pl PDXRVFWW
- This should put the latest version of the RVF into your temporary file RIVER.TMP and send it to WHFS via the SHEF decoder

4. Set up AWIPS Text Database Triggers to run the script automatically when ever a RVF comes in.

A. login as user fxa

B. Go to the AWIPS trigger directory: > cd /data/fxa/siteConfig/textApps

C. Make a backup copy of your site trigger file:
> cp siteTrigger.template siteTrigger.template.mmddyyyy
where 'mmddyyy' is the numeric current date

D. Edit your site trigger file to add the RVF triggers: > nedit &
- go to the trigger directory and open the siteTrigger.template file
- you will see a list of AWIPS product identifiers and the associated action to be triggered by each product. Add a similar line for each RVF product you receive for your HSA, and point to the full path and filename of where you installed fz2fu.pl.

PDXRVFWW /awips/dev/localapps/hydro/bin/fz2fu.pl PDXRVFWW
PDXRVFCW /awips/dev/localapps/hydro/bin/fz2fu.pl PDXRVFCW

- when you are done adding all the triggers, save and exit the editor

E. Re-localize for these new triggers.
- as user fxa, shell into DX1: > ssh dx1
- change directories to get to the localization scripts:
> cd /awips/fxa/data/localization/scripts
- run the localization script ONLY FOR TRIGGERS!!!
> ./mainScript.csh -trigger XXX
where 'XXX' is your WFO ID.

For more information on triggers, see http://fxa.noaa.gov/doc/triggers.html.

Now, when a RVF comes in, it should trigger the script and create a copy of the forecast in the hydro database using the FU type source. You may then view it in TimeSeries or save it to a file. You can monitor the whole process in several ways to look for any problems.

Monitoring the Process: When a text product comes in that sets off the AWIPS text database trigger, a copy of the incoming product will show up under its PIL at: dx1:/data/fxa/trigger. This can be used to monitor the triggering system.

A copy of the temporary output file from the fz2fu.pl script is at following location, or whatever file directory you set up: /awips/dev/localapps/hydro/bin/RIVER.TMP. This is the file sent to WHFS with the SHEF type source FU. This can be used to monitor how the script is working.

The SHEF decoder log files are at /awips/hydroapps/shefdecode/logs/decoder directory in a file called 'shef_decode_log_mmdd' , where mm is the month and dd is the day. This can be used to monitor how the file is getting decoded.

Product Usage: Use the hydro Time Series program to see that you now have forecast data under two Type/Source codes:

FZ - This should now be the forecast that is edited for inclusion in your River Pro product
FU - This is the original RFC forecast hydrograph that should never be edited.

Contact Information:
Brent Bower, SSH WFO Seattle
206-526-6095 x228