4. Avnsetup

4. Avnsetup
	Chapter 1. System Administration

avnsetup is a graphical user interface (GUI) which can be used to configure many features of AvnFPS. In most cases, the data displayed and modified in avnsetup are contained in the various files described in Section 2, “Configuring AvnFPS”.

avnsetup main GUI

This section describes tasks that can be accomplished with this program.

	Important
	The AvnFPS severs and, often, AvnWatch GUI are required to be restarted for changes made using the following setup GUIs, except the Trigger Editor, to take affect. The reason for this, is that the underlying files, Section 2, “Configuring AvnFPS”, are read only once into memory on startup of the servers and AvnWatch.

4.1. Editing Monitoring Rules

From the avnsetup main GUI, select the Monitoring Rules button. The Monitoring Criteria Editor will be shown.

Monitoring Criteria Editor

The Monitoring Criteria Editor contains several pages, one for each monitored data source. Pages are selected via “recipe tabs” near the top of the menu. The labels on the tabs refer to the following data sources:

Rules for monitoring METARs (mtrs)
Rules for monitoring lightning observations (ltg)
Rules for monitoring lightning nowcasts (rltg)
Rules for monitoring Colaborative Convective Forecast Product (ccfp)
Rules for monitoring forecast grids (grids)
Rules for monitoring low level wind shear (llws)

Each page has an identical layout: the top part lists currently defined rules, the bottom part contains a list of all available methods and the area where you can view, modify, add or delete a rule.

AvnFPS supports site-specific monitoring rules as well as a set of default rules. When the rule editor is started, the default rules are loaded. This is indicated by XXXX in the Site Id entry field.

To load the default set of rules:

Enter the 'XXXX' into the box labeled Site Id.
Press Enter or select the Load button.

To load the specific rules for a site:

Enter the Station ID into the box labeled Site Id.
Press Enter or select the Load button.

To create a new set of site-specific rules:

Modify the rules using the instructions below.
Enter the applicable Station ID into the box labeled Site Id.
Select the Save button.

To remove site-specific rules:

Enter the Station ID into the box labeled Site Id.
Select the “recipe tab” for the data source for which you want to remove the rules.
Select the Delete button.

The lower half of the Monitoring Criteria Editor allows you to view and modify each of the monitoring rules. The current set of rules is listed by color and message in a selectable list. The Rule Editor at the bottom of the menu shows details of the rule that is currently selected. To the left to the Rule Editor is a list of Available Methods. These methods are software techniques that compare the current forecast to the latest values received from the data source. Each method has its own set of arguments that configure its behavior.

To view the details of an existing rule:

Select the rule from the list.

To modify an existing rule:

Select the rule from the list.
Use the Rule Editor to make the necessary changes. See Appendix B, Monitoring Rules for a description of editor options.
Select Replace.
Select Save to write changes to the configuration file.

To remove a rule:

Select the rule from the list.
Select Remove.
Select Save to write changes to the configuration file.

To add a new rule:

Select a method from the "Available Methods" list. Appendix B, Monitoring Rules provides detailed description of each one. The Rule Editor will update with the appropriate fields. You can see method details by pointing the cursor to the respective button on the list.
Use the Rule Editor to modify arguments as needed. Entering a text message is no longer necessary, if left blank, AvnFPS will generate one for you.
Select Add.
Select Save to write changes to the configuration file.

4.2. Editing TAF Site Information

From the avnsetup main GUI, select the TAF SiteInfo button. The TAF Site Info Editor will be shown.

TAF Site Info Editor

The TAF Site Info Editor is an entry form for data specific for a particular TAF site. Most of the fields can be initialized from data residing in AWIPS files or from built-in values. You must enter data for all sites before creating a product definition (that is, a "collective").

Site Id	TAF site ID
TAF WMO	WMO header used to transmit forecast
TAF AFOS	PIL used during transmission
TAF Duration	Length, in hours, of the regularly issued TAF.
Visibility	A comma separated list of visibilities (miles) defining categories used by the monitoring modules. Given the list 0 < V₁ < V₂ < ... < V_n, the category k consists of visibilities V such that V_k-1 <= V < V_k, k = 1,..., n+1 and V₀ = 0, V_n+1 = ∞.
Ceiling	A comma separated list of ceilings (feet) defining categories used by the monitoring modules. The categories are defined the same manner as above.
Radar Cutoff	A comma separated list of heights in meters defining lowest height to be used in computing LLWS using this radar. The length of the cutoff list must be equal to the number of radars listed in the 'Radar' text field below.
Profiler Cutoff	A comma separated list of heights in meters defining lowest height to be used in computing LLWS using this profiler. The length of list must be equal to the number of profilers listed in the 'Profiler' text field below.
Latitude	Site latitude, in degrees north
Longitude	Site longitude. (west longitudes are negative)
Elevation	Site elevation, in meters
Runway(s)	A comma separated list of runway directions in degrees. Used to calculate cross-, head- and tail-wind components.
METAR	METAR site id associated with the TAF, most likely the same as TAF.
NAM	The closest site id found in NAM BUFR message associated with the TAF.
GFSMOS	The closest site id found in GFS MOS message associated with the TAF.
NAMMOS	The closest site id found in NAM MOS message associated with the TAF.
GFS LAMP	The closest site id found in GFS LAMP message associated with the TAF, usually the same as GFS MOS identifier.
Radars	A comma separated list of radars associated with the TAF. Can be empty.
Profilers	A comma separated list of profilers associated with the TAF. Can be empty.
Impact	When selected Impact Check will be performed when QC button is pushed
Climate	When selected Climate Check will be performed when QC button is pushed
Current Wx	When selected Current Weather Check will be performed when QC button is pushed

Note

Airport runway directions, as entered in this editor, are based on true north, not magnetic north. For purposes of computing crosswinds, only one runway heading is required as it does not matter from the pilot's perspective trying to land his/her aircraft whether the crosswind goes from left-to-right or right-to-left. It's the magnitude of the crosswind that's important.

If head- or tail-winds are important for monitoring, then the airport runway heading must be carefully chosen. One should consult Appendix-B LLMetar rule's description for guidance.

To create data for a new TAF site:

Enter the Station ID into the box labeled Site Id.
Select the Update button. Many of the fields will be filled in. The headers are read from AWIPS file afos2awips.txt. Latitude, longitude and elevation (in meters) come from metarStationInfo.txt. Other values are built-in defaults.
Modify displayed entries as needed. The METAR text field must be filled in, all others fields in the 'Alternate ids' are optional. A simple validation test is performed when you type. The program will not allow you to enter obviously incorrect values, incomplete entries are indicated by a pink background.
Select the Save button.
Create templates as described in the next section.

To modify TAF site data:

Enter the Station ID into the box labeled Site Id.
Press the Load button.
Modify displayed entries as needed.
Select the Save button.

4.3. Editing TAF Site Templates

The bottom part of TAF Site Editor provides tools to create and edit template files that can be used to initialize forecasts. There is a separate template for each forecast issue time. This allows to enter issue specific phrases such as AMD NOT SKED AFT ....

To create TAF templates:

Enter the Station ID into the box labeled Site Id.
Select the Make button. This will create all four templates containing Station ID, issue and valid times. For example, a 06Z template for KPIT and a 30-h TAF location is:
KPIT D10520Z D106/D212 =

To modify TAF template:

Enter the Station ID into the box labeled Site Id.
Select issue time from Issue menu and press the Edit to invoke a text editor. Do not press the Make button, as this will overwrite your current templates.

	Note
	With the introduction of 30-h long TAFs, macros `D1` and `D2` make references to the starting and ending day and can be used within the body of the TAF such as `AMD NOT SKED AFT D10300` for example.

4.4. Editing TAF Product Definition

From the avnsetup main GUI, select TAF Products button. TAF Product Configuration Editor will be shown.

TAF Product Configuration Editor

The existing products will be displayed in the alphabetical order, with the default (if defined) on the top of the list. The Idents window displays list of all TAF sites in the product.

To add a product:

Type the product name in the text window under the Products label and press Enter. An error message will be displayed that the product cannot be loaded. This is to be expected, as it's being created for the first time.
Enter Site ID in the window under the Idents label. Hit Enter after each site.
Enter PIL for work TAF in the window under the Work PIL label. TAFs associated with this product will be saved under this PIL in the text database.
The Collective PIL is optional, used by OCONUS sites to send all TAFs listed in the Idents text window field under a single text product identifier.
When finished, press Save. A new product definition file will be created.
The Verify button checks whether the AFOS and WMO ID of each TAFs are correct and ready to be transmitted by the handleOUP.pl.

To modify an existing product:

Select the product on the Products list.
To add a new TAF site, type the ID in the window under the Idents label and hit Enter.
To delete a site, select it on the Idents list and press the Delete button.
Press Save to update product definition file.
The Verify button checks whether the AFOS and WMO ID of the new TAF(s) is correct and ready to be transmitted by the handleOUP.pl.

To delete a product:

Select the product on the Products list.
Press Delete. A confirmation dialog will be displayed. Press OK, this will delete product definition file. TAF site files (info.cfg and any template files) will not be removed.

To mark a product as the default:

Select the product on the Products list,
Press the Default. This will designate the selected product as default product when starting the Monitoring GUI.

4.5. Creating Triggers

AvnFPS obtains TAFs, collaborative convective forecast products (CCFPs), and METARs from AWIPS Text Database (fxatext). As new versions of these products arrive, the metarDecoder can "trigger" another application--usually a script--to run. AvnFPS uses this triggering feature to retrieve TAF, CCFP, and METAR products for monitoring as soon as they arrive in the database. The Trigger Editor manages the configuration of the textdb triggers needed to support AvnFPS. The current version creates trigger template, to be processed by AWIPS localization script and simultaneously updates the table watchwarn in fxatext database holding Postgres trigger scripts. So you do not have to run localization after creating the template file. However the file is still necessary, as the localization process drops the watchwarn table and recreates it from templates.

To start the Trigger Editor, select Triggers button. The Trigger Editor will be displayed.

Trigger Editor

On startup, the Trigger Editor searches AvnFPS configuration files for all TAF and METAR sites routes that have been configured by your office. (These are files stored in the directories etc/tafs and etc/mtrs). The two columns: TAF and METAR list those sites. If there is a template file, etc/triggerTemplate, its entries are used to fill the corresponding PIL boxes. If the trigger template does not have an entry for an id, the relevant box will remain blank, with a pink background.

	Note
	The CCFP product issued from Aviation Weather Center is a national product and not site-specific. This product, consisting of 3 text files, are in the `watchwarn` table, by default.

To create AvnFPS triggers:

Press the Update button. The program will try to determine missing PILs for the TAFs from the file afos2awips.txt. METAR PILs are created by from corresponding TAF PILs by replacing TAF by MTR. The existing values will not be overwriten.
Correct the entries and fill in empty fields.
Press Make when finished. Empty (pink) entries will be skipped, if you have an invalid entry, an error message will be shown. If there are no errors, the editor will save the contents of the editor to a file and update the watchwarn table in the fxatext database.

4.6. Climate Data File Tool

From the Avnsetup main GUI, selecting the Climate Data button will cause the Climate Data Tool Dialog to appear.

Climate Data Tool Dialog

4.6.1. Introduction

Since AvnFPS 3.0 with the introduction of its climatology tools, an up-to-date archive of METAR observations was needed for each TAF. Given the current count of more than 620 TAFs, it became time consuming to refresh these archives each year at MDL. A better solution was to encapsulate the software that generates the HDF5 climate files into a user-friendly interface and provide that as part of the AvnFPS suite of configuration tools. The Climate Data Tool allows the user to update the AvnFPS climate files as often as they wish, limited only by the availability of latest QC'd observations at the National Climatic Data Center (NCDC).

The Climate Data Tool will allow users to create brand-new HDF5 climate files as well as update the ones you already have. For either task, the steps to perform are nearly the same. Creating brand-new files requires an additional preliminary step. The bulk of the procedure to update or create the HDF5 climate file have been broken down into a series of steps implemented as buttons which are laid out from top to bottom on the right-hand side of the GUI.

The following table briefly describes the purpose and actions of these buttons.

Button	Description/Purpose
Assess Data	Examines existing AvnFPS climate file(s), if present, with NCDC's ISH files to determine what years are needed from NCDC to bring the local file(s) up-to-date.
Generate Scripts	Create and view scripts for downloading NCDC data files for either Linux or Windows computers.
Process Data	Analyze and incorporate NCDC files into HDF5 climate file(s)
Validate	Temporarily move new HDF5 climate file(s) into place for viewing by AvnFPS climate tools for verification
Commit	Move new HDF5 climate file into the AvnFPS database permanently. Perform cleanup actions by removing NCDC files and old HDF5 climate file.
Reject	Restore previous HDF5 climate file.
Save Log	Record session activity to disk.

Note

It is important to recognize that while the steps--briefly outlined in the table above--are few and relatively uncomplicated, this procedure does requires the use of an open Internet facing computer, either a Linux or Windows machine, to access the NCDC site and its archives. The process of transferring scripts and data files to and from AWIPS and the 'outside world' is left as an exercise for the reader.

4.6.2. Adding New Site

If the TAF site in question is not listed in the "Idents" scrolled window, you will need to add it.

With the Create radio button in the Climate Tool Dialog selected, fill in the Site ID and METAR AFOS ID text fields and then select the Write Site Data button to add it to the Idents list.

Adding new site

Proceed with the steps in the next section to create the new climate file.

4.6.3. Analyzing Climate Files

With the TAF site selected in the Idents window, information about the site(s) selected will appear in the text window. The information displayed includes the site's USAF and WBAN identifiers, and the NCDC data available for these identifer(s). In this case, KHXD is a new location with no local climate file, so NCDC has observations spanning from 2004 to 2008, and the 'Local' column has no information to display, which is denoted by a string of dashes, '---'. For existing climate files in the AvnFPS database, a span of years would be displayed, indicating the file's current contents.

Assessing the HDF5 climate file

After clicking on the Assess Data button, the NCDC's ISH files and local HDF5 climate file (in this case, none for KHXD) are examined to determine what is needed to bring the local climate file up-to-date. After the analysis, you will be prompted for the next step.

Climate File Assessment

Note

When creating the climate file(s) the software will determine what NCDC files are needed only within the last 30 years. The reasons for this are initial difficulties with memory allocation and length of time to process very long climatic histories. This time restriction may be removed in a later version of this tool and, in any case, does not prevent users from appending later years to existing files.

4.6.4. Downloading NCDC Climate Files

Clicking on the Generate Script button will open a dialog allowing you to create either a Windows or Linux FTP script to download NCDC files needed to bring your local climate files up-to-date.

By clicking on the Linux FTP script, a script with suitable commands for a Linux platform appears in the text window.

Linux script for downloading NCDC files

By clicking on the Windows FTP script, a batch file with suitable commands for a DOS platform appears in the text window.

Windows script for downloading NCDC files

Now move the download file to the appropriate machine with Internet access. Once there, run the script to get the needed data files from NCDC.

What follows is an example of a Linux download session to gather NCDC data for site KHXD.

[tyr:...tmp] > ./getNCDCData-KHXD.sh
--17:05:22--  ftp://ftp.ncdc.noaa.gov/pub/data/noaa/2004/720120-99999-2004.gz
           => `720120-99999-2004.gz'
Resolving ftp.ncdc.noaa.gov... 205.167.25.101
Connecting to ftp.ncdc.noaa.gov|205.167.25.101|:21... connected.
Logging in as anonymous ... Logged in!
==> SYST ... done.    ==> PWD ... done.
==> TYPE I ... done.  ==> CWD /pub/data/noaa/2004 ... done.
==> PASV ... done.    ==> RETR 720120-99999-2004.gz ... done.
Length: 48,108 (47K) (unauthoritative)

100%[========================================================================================>] 48,108        337.35K/s
17:05:23 (335.49 KB/s) - `720120-99999-2004.gz' saved [48108]

--17:05:23--  ftp://ftp.ncdc.noaa.gov/pub/data/noaa/2005/720120-99999-2005.gz
           => `720120-99999-2005.gz'
Resolving ftp.ncdc.noaa.gov... 205.167.25.101
Connecting to ftp.ncdc.noaa.gov|205.167.25.101|:21... connected.
Logging in as anonymous ... Logged in!
==> SYST ... done.    ==> PWD ... done.
==> TYPE I ... done.  ==> CWD /pub/data/noaa/2005 ... done.
==> PASV ... done.    ==> RETR 720120-99999-2005.gz ... done.
Length: 147,613 (144K) (unauthoritative)

100%[========================================================================================>] 147,613      644.33K/s
17:05:23 (642.52 KB/s) - `720120-99999-2005.gz' saved [147613]

--17:05:23--  ftp://ftp.ncdc.noaa.gov/pub/data/noaa/2006/720120-99999-2006.gz
           => `720120-99999-2006.gz'
Resolving ftp.ncdc.noaa.gov... 205.167.25.101
Connecting to ftp.ncdc.noaa.gov|205.167.25.101|:21... connected.
Logging in as anonymous ... Logged in!
==> SYST ... done.    ==> PWD ... done.
==> TYPE I ... done.  ==> CWD /pub/data/noaa/2006 ... done.
==> PASV ... done.    ==> RETR 720120-99999-2006.gz ... done.
Length: 139,125 (136K) (unauthoritative)

100%[========================================================================================>] 139,125      610.03K/s
17:05:24 (608.62 KB/s) - `720120-99999-2006.gz' saved [139125]

--17:05:24--  ftp://ftp.ncdc.noaa.gov/pub/data/noaa/2007/720120-99999-2007.gz
           => `720120-99999-2007.gz'
Resolving ftp.ncdc.noaa.gov... 205.167.25.101
Connecting to ftp.ncdc.noaa.gov|205.167.25.101|:21... connected.
Logging in as anonymous ... Logged in!
==> SYST ... done.    ==> PWD ... done.
==> TYPE I ... done.  ==> CWD /pub/data/noaa/2007 ... done.
==> PASV ... done.    ==> RETR 720120-99999-2007.gz ... done.
Length: 134,053 (131K) (unauthoritative)

100%[========================================================================================>] 134,053      716.04K/s
17:05:25 (713.94 KB/s) - `720120-99999-2007.gz' saved [134053]

--17:05:25--  ftp://ftp.ncdc.noaa.gov/pub/data/noaa/2008/720120-99999-2008.gz
           => `720120-99999-2008.gz'
Resolving ftp.ncdc.noaa.gov... 205.167.25.101
Connecting to ftp.ncdc.noaa.gov|205.167.25.101|:21... connected.
Logging in as anonymous ... Logged in!
==> SYST ... done.    ==> PWD ... done.
==> TYPE I ... done.  ==> CWD /pub/data/noaa/2008 ... done.
==> PASV ... done.    ==> RETR 720120-99999-2008.gz ... done.
Length: 122,064 (119K) (unauthoritative)

100%[========================================================================================>] 122,064      700.17K/s
17:05:26 (699.58 KB/s) - `720120-99999-2008.gz' saved [122064]

==================================================
Please move these just-downloaded NCDC files to an
AWIPS machine into the /awips/adapt/avnfps/OB9.2/tmp
directory. When finished, press the Process Data
button on the Climate Data Update GUI to resume
further processing of the data into a HDF5 climate
file.
==================================================

A Windows session after double-clicking on the batch file icon:

Windows Downloading Session

As the download scripts suggest, copy the downloaded files back into the AWIPS system, to the /awips/adapt/avnfps/OB9.2/tmp/ directory for continued processing.

4.6.5. Processing NCDC data files

Once the NCDC files have been transferred to the AWIPS machine, clicking on the Process Data button will start the actual climate data file update (or creation in this case).

Processing NCDC Data

Once processing is underway, the GUI will provide constant feedback to the user about when the processing started, how many lines are being written, estimated time to complete, how much progress has been made at any moment, and when the processing is complete.

Once processing of the NCDC files is completed, the Validate button will become active.

	Note
	On rare occasions, NCDC archive files can be corrupted. This problem will show up in the text window as decompression errors as processing proceeds. To correct, the user can simply remove the offending file, located in the `/awips/adapt/avnfps/OB9.2/tmp` directory, or try downloading the yearly observation file from the NCDC archives again at a later time.

4.6.6. Examining new HDF5 climate file

Once processing is completed, clicking on the Validate button will temporarily move the new climate in place so that AvnFPS climate tools can examine the new file. The climate tools can be accessed from the Tools pull-down menu.

Validating New Climate File

Using the Climate Tool METAR Viewer to examine the new records.

Validating New Climate File with METAR Viewer

Using the Climate Tool Wind Rose to examine the new records.

Validating New Climate File with Wind Rose Tool

After examining the new climate file using the climate tools and it's found satisfactory, pressing the Commit button will keep the new file in place and remove the old one and the downloaded NCDC files.

If the new climate file is not satisfactory (or corrupted), pressing the Reject button will restore the previous version of the file back to the AvnFPS database. The downloaded NCDC files remain should you wish to attempt to update the HDF5 climate file again.

The Save Log button saves the status text window's content to disk. The log file is stored in the /awips/adapt/avnfps/OB9.2/tmp directory.

4.6.7. Miscellaneous

In the Climate Data Tool menu bar, selecting Commands->Data Details button will open the Data Details dialog.

Climate Data Details

The Data Details dialog presents a bar graph representation indicating the number of observations per year in the NCDC archive files for the selected station.

Climate Data Station Details

In the Climate History GUI, there are a few items to note. The Idents list lists all the stations you have selected in the main GUI. Click on one of these stations for histogram(s) representing the number of observations by year available at that station. For each station, one or more tab(s) will appear above the graph. If a station has had multiple USAF-WBAN IDs, then a tab with a separate graph for each USAF-WBAN ID combination will appear.

In the image above, there is just one tab/pane. The visible graph tells us that METAR data for KHXD started in 2004 and continues to 2008.

Selecting Commands->Update Helper Files opens the Helper File Info dialog.

Climate Data Helper File Info Dialog

These two data files are crucial to the proper operation of the Climate Data Tool:

ish-history contains detailed historical information about each station
ish-inventory contains details about the inventory of archived observations available for all stations

These files are regularly updated and made available by NCDC. They should be refreshed at least yearly so as to include the current year when assessing the climate files for updates. The Generate Script buttons invoke the dialog which allows the user to generate download script for these files, similar to the data archives.

	Note
	These 'ish-' files are kept in the `/awips/adapt/avnfps/OB9.2/etc` directory.

In the Climate Data Tool menu bar, selecting the Tools pull-down menu reveals the list of the AvnFPS climate tools. This is provided as a convenience for validating new and updated climate files.

Climate Data Helper Tools Pulldown Menu

4.7. Using Text Editor

To edit the configuration files that do not have a GUI interface: forecasters, logging.cfg, server.cfg, gui.cfg, ids.cfg, flt_cat.cfg, grp_taf.cfg, use the AvnFPS text editor. It is invoked by pressing Text Edit button. Here's a snapshot of the editor with the contents of the etc/forecasters file.

Setup Editor Dialog

Press Open, you will get a file selection dialog listing content of directory etc. In this dialog, select a file to edit, then press Open.

File Selection Dialog

Press Save button when finished. If you want to create a new file, simply type its contents in the text window, and then use Save As button to save to disk.

You can also use the text editor to edit X resource configuration file. However, we suggest that you only modify the system-wide file which is used as a initial selection when a forecaster modifies his own resources through the graphical editor available in AvnWatch. Proceed as above, and in the file selection dialog, select the app-resources folder, then the file X. You may edit files for individual forecasters (those with names X.N), however any comments you put there will be stripped by the graphical editor every time the forecaster modifies the resources from AvnWatch.

	Tip
	Font and color names may be cryptic. You may want to use the graphical editor in AvnWatch first to display color codes and available fonts.


3. Starting and Stopping AvnFPS		5. Configuring IFPS to send gridded data to AvnFPS