**BOX_Wx_Tool**

*Matthew H. Belk*

*National Weather Service*

*Taunton, MA*

**Introduction**

The advent of GFE has shifted the NWS focus from producing forecast
text, to that of forecast data. As such, the consistency of the forecast
data is paramount. The Wx field in GFE is far and away the most complex,
and most dependent field in the database. Wx depends upon so many other
fields within the database (T, Sky, QPF and PoP to name a few); it is
very difficult to manually edit these fields as a consistent
meteorological whole. The answer to this problem, for us, is the
BOX_Wx_tool. This SmartTool allows the forecaster to assign just about
any Wx type while keeping the database internally consistent.

I chose to use the thickness technique developed by Kermit Keeter (SOO,
WFO RAH) as displayed in BUFKIT (Ed Mahoney et. al, WDTB) to determine
mixed precipitation types. A more detailed explanation of the TREND
technique can be found at this [Internet
address](http://www.meas.ncsu.edu/nws/www/trends/). Although there are
many other techniques for determining precipitation types, the TREND
technique was chosen because:

1\) Ease of forecaster manipulation

The primary dependence on thickness allows forecasters to make
adjustment to

precipitation type by editing two thickness fields. The temperature
field would be

the only other field that could influence the precipitation types.

2\) Ease of interpolation.

> In order to catch type transitions during an event, you need a finer
> temporal resolution. Thickness interpolates significantly better as a
> scalar field than the

weather "ugly strings". How does one interpolate from "Chc R-" to "Lkly
R-S-

Chc IP-" over a 6 hour period?

**Assumptions**

The most recent version accompanying this document is dated April 21,
2006. This date may be verified at the top of the tool code comments.
This version of the tool is considered to be version 1.3. It is further
assumed that IFPS 17 or higher is being used. The tool will work with
any duration of PoP grids, but the transitions will not be as smooth.

Several fields must be added to the Fcst, Official and various model
databases. The reason for adding these fields is found in Appendix A.
The files provided with the SmartTool, and this document, contain the
calculations. A detailed methodology of the SmartTool can be found in
Appendix B. It is assumed the user knows how to correctly configure GFE
to use the new fields and install the SmartTool. More advanced
customizations can be found in Appendix C.

**Usage**

There are three fields that must be completed before this SmartTool can
be used. They are: PoP, Sky, and T. If the QPF field is completed as
well, precipitation intensity other than light ('-') may be assigned. I
recommend running this SmartTool in chunks, rather than for seven days
at a time. This is very easy to do with the 'Run' option, which will
leave the dialog displayed with the latest settings. This means you only
need to tweak the settings as the weather scenario changes from day to
day, which can save time if many settings were changed with the first
execution of the SmartTool.

The following figure shows the user input screen as it appears by
default. The significance of each option will then be discussed.

-   **General Weather
    Options**![](media/image1.png){width="4.894444444444445in"
    height="7.165277777777778in"}

```{=html}
<!-- -->
```
-   The first three options control basic facets of the tool's behavior.

```{=html}
<!-- -->
```
-   The **Probability Term** option uses ***Uncertainty*** terminology
    (ex. Chc, Lkly, Def) or areal ***Coverage*** terminology (ex. Sct,
    Num, Wide) as specified.

```{=html}
<!-- -->
```
-   The **Character** option determines whether to assign
    ***Stratiform*** (ex. R) or ***Showery*** (ex. RW) precipitation
    types as specified.

```{=html}
<!-- -->
```
-   The **Trace Precip** option determines whether to assign trace
    precipitation types or not. Trace precipitation types will be
    assigned at points where the PoP is \>= the user specified amount
    (15% default) and \< 25%.

> If 'Slight Chance' terminology is used, trace precipitation is
> assigned where PoP is \>=
>
> user specified amount (14% default) and \< 15%. The *Default Parameter
> Thresholds*
>
> section of Appendix C will tell you how to change this default value
> to a more
>
> appropriate value. In addition, *The\_\_init\_\_ Method* section of
> Appendix C will tell
>
> you how to disable the use of 'Slight Chance' if desired.
>
> Stratiform trace precipitation types are: L, ZL and SW\--. Showery
> trace precipitation
>
> types are: RW\--, ZL and SW\--.

-   **Mixed Precipitation Options**

```{=html}
<!-- -->
```
-   The next four options are only used with mixed precipitation.

```{=html}
<!-- -->
```
-   The **All Liquid** option offers a means to bypass the code which
    determines mixed precipitation types. This can speed up the tool's
    execution when only liquid precipitation is expected. The only two
    types of precipitation that can be assigned if this option is set to
    'No' are rain (R) and freezing rain (ZR) based upon the surface
    temperature, T.

```{=html}
<!-- -->
```
-   The next two options, **Mix Prob 2** and **Mix Prob 3**, allow the
    forecaster some control over the probability terminology associated
    with second and third precipitation types. There are basically four
    categories of mixed precipitation: slight chance, chance, likely and
    categorical. The dominant precipitation form is always assigned the
    appropriate category based upon the PoP field. Additional
    precipitation types will be assigned with a probability that is
    either the ***Same***, ***1 Cat less***, ***2 Cat less*** or ***3
    Cat less***. All measurable mixed precipitation types cannot be
    assigned with a category less than slight chance (SChc or Iso). The
    order of the types is determined by the nomogram.

> Assume we have a categorical PoP, **Mix Prob 2** is '1 Cat less',
> **Mix Prob 3** is '2 Cat
>
> less' and we need to assign a mix of R-, S- and IP- in that order. The
> results would be:
>
> Def R- Lkly S- Chc IP- for **Uncertainty** PoP terminology or
>
> Wide R- Lkly S- Sct IP- for the **Coverage** PoP terminology

-   **Conjunction and Categorical Duration Options**

```{=html}
<!-- -->
```
-   Allows the forecaster to connect multiple precipitation types using
    'AND' or 'OR'

-   Allows forecaster to select modifiers to categorical precipitation
    other than ***Def***inite or ***Wide***spread
    (***Oc***casio***n***a***l***, ***Fr***e***q***uent,
    ***Br***ie***f***, ***P***erio***ds*** or ***Inter***mittent)

```{=html}
<!-- -->
```
-   **Convective Precipitation Options**

```{=html}
<!-- -->
```
-   The next four options are only used with convective precipitation.

```{=html}
<!-- -->
```
-   The **Thunder** option allows the forecaster to decide if convection
    should be forecast or not. This can speed up the tool's execution
    when no convection is anticipated. If this option is set to 'No',
    thunderstorms will NOT be assigned no matter how many indices you
    have chosen.

```{=html}
<!-- -->
```
-   The next option, **T Prob**, behaves like the **Mix Prob 2** and
    **Mix Prob 3** options. It allows the forecaster to lower the
    probability of thunder from that of the dominant precipitation type.
    Thunderstorms can have the following probability terminology:
    ***Def***inite/***Wide***spread,
    ***L***i***k***e***ly***/***Num***erous,
    ***Ch***an***c***e/***Sc***a***t***tered, ***S***light
    ***Ch***an***c***e or ***Iso***lated.

```{=html}
<!-- -->
```
-   The **Area** option provides a list of convective indices which may
    be selected in any combination. These indices will be used to define
    the area where Thunderstorms should be added to the weather "ugly
    string". A query is made for each index selected using the threshold
    defined later, assuming that index field is available. If more than
    one index is used, thunderstorms will be included where favored by
    **all** the available indices chosen. If there is at least one field
    available, thunderstorms will be assigned.

> For an example I will use the default setting. The two indices chosen
> by default are
>
> CAPE and CIN. The default threshold for CAPE is 1000 J/kg and the
> threshold is 50
>
> J/kg for CIN. CIN is positive in this case because that is how the
> models display it.
>
> This means thunderstorms would be inserted, assuming Sky and PoP
> support Wx as
>
> well, where:
>
> CAPE \>= 1000 J/kg and CIN \<= 50 J/kg
>
> If the K index, K, is added to the above with its default threshold,
> the condition
>
> would become, where all three fields are available:
>
> CAPE \>= 1000 J/kg, CIN \<= 50 J/kg and K \>= 30
>
> The following indices are available to define the area of
> thunderstorms:

CAPE Convective Available Potential Energy

CIN Convective Inhibition Energy

DCI Deep Convective Index

K K Index

Sfc LI Lifted Index (can be BL LI for NAM12 and RUC80)

TQ TQ Index (low-level convection)

TT Total Totals Index

-   The **T Intensity** option provides another list of convective
    indices which are used in an attempt to delineate areas where
    thunderstorms may be severe. Areas so defined by these elements
    would have 'T+' added to the "ugly string" instead of a simple 'T'.
    The methodology for these indices is identical to that of the
    **Area** indices:

> The following indices are available to define the area for severe
> thunderstorms:

BRN Bulk Richardson Number

BRN Shear Bulk Richardson Number Shear

CAPE Convective Available Potential Energy

EHI Energy Helicity Index

SWEAT Severe Weather Threat Index

-   The **T Attributes** allows certain attributes to be included along
    with the thunderstorm weather type under the following conditions:

    1.  Tornadoes, large hail or damaging winds will only be assigned
        with a forecast of severe thunderstorms (T+).

    2.  Small hail or gusty winds will be assigned only if their
        stronger counterparts are not selected as well.

    3.  Frequent lightning will be included if it is selected.

```{=html}
<!-- -->
```
-   **Parameter Thresholds**

```{=html}
<!-- -->
```
-   The remaining questions allow the forecaster to override the default
    threshold settings, and hence the behavior of the SmartTool. The
    significance of some of these questions is explained below. See
    Appendix C for details on changing the default display limits of any
    of these thresholds.

```{=html}
<!-- -->
```
-   Enter sky cover needed to begin Wx (%):

> This value can range from 50-100% by default. Wx will only be assigned
> where the Sky cover is greater than or equal to this value. See
> Appendix C for the steps to lower the 50% limit if desired.

-   Enter minimum PoP for trace precip:

> This value can range from 5-14%. It defines the area where trace
> precipitation types
>
> will be assigned, only if **Trace Precip** is set to 'Yes'.

-   Enter maximum temperature for S/IP (deg F):

> This is the maximum temperature where snow and/or sleet will be
> retained in the
>
> "ugly string". Once this temperature is exceeded, all frozen
> precipitation is changed
>
> to rain.

-   \*\*\*\*\* T Area Indices \*\*\*\*\*

> This section is where the forecaster can modify the default thresholds
> for any of the
>
> thunderstorm 'Area' indices.

-   \*\*\*\*\* T Intensity Indices \*\*\*\*\*

> This section is where the forecaster can modify the default thresholds
> for any of the
>
> thunderstorm 'Intensity' indices.

**APPENDIX A: INITIALIZATION FILES FOR NCEP MODELS**

WFO Taunton, MA creates hourly forecast grids for most fields in the
forecast database. We have found this to provide the most realistic
evolution of weather systems. However, this also increases the workload
upon the forecaster. Through the use of the SmartInit feature of GFE, we
have been able to ease this burden to an extent. By creating additional
fields for our internal use with the SmartInit process, we can
manipulate these fields however we wish. This in turn, allows for
SmartTools to use this information and create smooth and realistic
transitions through time and space. Forecast consistency is improved as
we depend less on hand-editing of the Wx grids, and let SmartTools do
most of the work with the first cut. These additional parameters are
treated like all the others: start with the current database and make
changes if necessary.

The SmartInitialization files included with this SmartTool and document
(MyGFS40.py, MyNAM12.py, MyNGM80.py, MyRUC80.py, and MyLAPS.py) are
sanitized versions of the ones used operationally at WFO Taunton and
should work right out of the box. All entries which do not pertain to
the BOX_WX_Tool were removed to avoid confusion about what needs to be
copied. If you already have an existing version of any of these files,
it is strongly recommended you cut and paste the necessary lines into
your existing files. **Be certain to include the '*self.\_useTopo*'
definition in the \_\_init\_\_ method, or the thickness calculations
will fail.** It should be noted these updated files have more efficient
calculations for the fields than the previous version.

Due to the variability of available model data, some fields are not
calculated in the exact same fashion between models. For example the
Deep Convective Index (DCI) field uses the lifted index as input. For
the NAM12 and RUC80 the lifted index field is calculated using a
boundary layer parcel. Meanwhile the GFS40 and NGM80 use surface based
parcels. This variability also means that certain fields, like CAPE and
CIN, cannot be computed for all models namely the NGM80. Please examine
these files to see how the various fields are being calculated, and if
they suit your needs. These files would go into the
/awips/GFESuite/primary/etc/SITE directory on px1.

Also attached is a sanitized version of the operational localConfig.py
file from WFO Taunton, MA. This file may be used as an example of how to
add these fields to the various model, Fcst and Official databases. You
should be able to cut and paste most of its contents into your own
localConfig.py. This file also goes into the
/awips/GFESuite/primary/etc/SITE directory.

**APPENDIX B: TOOL METHODOLOGY**

There are many steps and checks taken by the SmartTool in determining
the contents of each Wx grid. These steps and checks are:

1.  Delineate the area where PoP \>= 15%.

2.  If trace precipitation is desired, delineate the area where PoP
    supports these precipitation

types.

3.  Determine the intersection of areas outlined in steps 1 and 2, with
    the area where the sky cover supports precipitation as well. Wx will
    only be assigned in the area remaining after this step. Currently no
    error is indicated to the forecaster if PoP supports Wx, but there
    is insufficient sky cover. It is assumed the forecaster has already
    ensured consistency between Sky and PoP. This can be accomplished by
    lowering the PoP assuming the Sky field is correct, or increasing
    the Sky assuming the PoP field is correct.

4.  If mixed precipitation is desired and the 1000-850 mb and 850-700 mb
    thicknesses are available, determine the base precipitation type(s)
    from the thickness nomogram. Otherwise assume liquid precipitation
    by default.

5.  Check precipitation type(s) from step 4 against the surface
    temperature at the time of the Wx grid. If a type is not supported
    by the surface temperature, it will be changed to a more appropriate
    type. The critical temperatures for each phase follows:

> [Type]{.underline} [Changes To]{.underline} [Occurs when]{.underline}
>
> R or RW ZR T \< 31.8 deg F
>
> RW-- ZL T \< 31.8 deg F
>
> ZR R or RW T \> 32.2 deg F
>
> ZL L T \> 32.2 deg F
>
> S or IP R T \> chosen temperature
>
> SW RW T \> chosen temperature
>
> SW- RW- T \> chosen temperature
>
> SW-- RW-- T \> chosen temperature

The reason for the different thresholds around freezing is so it is
possible to have rain

and/or freezing rain at the same location.

6.  If thunderstorms are desired and at least one of the 'Area' index
    fields is available, find the spatial overlap of all the available
    'Area' indices chosen. The location of this overlap is where
    thunderstorms will be supported. Where this overlap also intersects
    the area from the end of step 3, thunderstorms will be included.

7.  If at least one of the thunderstorm 'Intensity' indices is chosen
    and available, delineate the locations where severe thunderstorms
    are supported. Include severe thunderstorms, if any locations were
    defined where they are supported. These locations must be contained
    within the area defined at the end of step 6.

**APPENDIX C: ADVANCED CUSTOMIZATIONS**

The BOX_Wx_Tool was designed to be flexible. With a little bit of time
and knowledge, it is possible to customize this tool more completely for
your site.

-   **Default Parameter Thresholds**

The customization with the most impact will be the default thresholds.
These limits are located in the following section of code near the top.
Although I tried to choose commonly accepted limits, I do not expect
these limits to be ideal for each office. The items in **bold** can be
changed to whatever values serve your office the best.

\# Set up variables to be solicited from the user

VariableList = \[

(\'Probability Term\' , **\'Uncertainty\'**, \'radio\',
\[\'Uncertainty\', \'Coverage\'\]),

(\'Character\' , **\'Showery\'**, \'radio\', \[\'Stratiform\',
\'Showery\'\]),

(\'Trace Precip\' , **\'No\'**, \'radio\', \[\'No\', \'Yes\'\]),

(\"\" , \"\", \"label\"),

(\'All Liquid\' , **\'No\'**, \'radio\', \[\'Yes\', \'No\'\]),

(\'Mix Prob 2\' , **\'Same\'**, \'radio\', \[\'Same\', \'1 Cat less\',
\'2 Cat less\',

\'3 Cat less\', \'None\'\]),

(\'Mix Prob 3\' , **\'Same\'**, \'radio\', \[\'Same\', \'1 Cat less\',
\'2 Cat less\',

\'3 Cat less\', \'None\'\]),

('Conjunction', **'And'**, 'radio', \['And', 'Or'\]),

('Duration', **'Def'**, 'radio', \['Def', 'Ocnl', 'Frq', 'Brf', 'Pds',

'Inter'\]),

(\"\" , \"\", \"label\"),

(\'Thunder\' , **\'No\'**, \'radio\', \[\'No\', \'Yes\'\]),

(\'T Prob\' , **\'Same\'**, \'radio\', \[\'Same\', \'1 Cat less\', \'2
Cat less\',

\'3 Cat less\', \'4 Cat less\'\]),

(\'Area\' , **\[\'CAPE\', \'CIN\'\]**, \'check\',

\[\'CAPE\', \'CIN\', \'DCI\', \'K\', \'Sfc LI\', \'TQ\', \'TT\'\]),

(\'T Intensity\' , **\[\'\'\]**, \'check\',

\[\'BRN\', \'BRN Shear\', \'CAPE\', \'EHI\', \'SWEAT\'\]),

(\'T Attributes\' , **\[\'\'\]**, \'check\',

\[\'Tornadoes\', \'Small Hail\', \'Large Hail\',

\'Damaging Winds\', \'Gusty Winds\', \'Frequent Lightning\'\]),

(\'Enter sky cover needed to begin Wx (%):\', 30.0, \'numeric\'),

(\'Enter minimum PoP for trace precip:\', **10.0**, \'numeric\'),

(\" \*\*\*\*\* Non Liquid Precip \*\*\*\*\* \" , \"\", \"label\"),

(\'Enter maximum temperature for S/IP (deg F):\', **38.0**,
\'numeric\'),

(\" \*\*\*\*\* T Area Indices \*\*\*\*\* \" , \"\", \"label\"),

(\'Enter minimum CAPE for T:\', **1000.0**, \'numeric\'),

(\'Enter maximum CIN for T:\', **50.0**, \'numeric\'),

(\'Enter minimum DCI for T:\', **30.0**, \'numeric\'),

(\'Enter minimum K Index for T:\', **30.0**, \'numeric\'),

(\'Enter maximum Sfc LI for T:\', **0.0**, \'numeric\'),

(\'Enter minimum TQ Index for T:\', **17.0**, \'numeric\'),

(\'Enter minimum TT Index for T:\', **50.0**, \'numeric\'),

(\" \*\*\*\*\* T Intensity Indices \*\*\*\*\* \" , \"\", \"label\"),

(\'Enter maximum BRN for T+:\', **45.0**, \'numeric\'),

(\'Enter minimum BRN Shear for T+:\', **300.0**, \'numeric\'),

(\'Enter minimum CAPE for T+:\', **1500.0**, \'numeric\'),

(\'Enter minimum EHI for T+:\', **2.0**, \'numeric\'),

(\'Enter minimum SWEAT for T+:\', **300.0**, \'numeric\')

\]

-   **The \_\_init\_\_ Method**

The \_\_init\_\_ method is called first upon execution of a SmartTool.
Inside the \_\_init\_\_

method of this tool, it is possible to control when weather intensities
are used, the

minimum Sky value that will be accepted from a forecaster and if the
tool should assign measurable precipitation types for the 'Slight
Chance' category (15-24% PoP).

The values that could be changed are highlighted in **bold** text.

def \_\_init\_\_(self, dbss):

SmartScript.SmartScript.\_\_init\_\_(self, dbss)

\# In order to assign precipitation intensity from QPF, the \'hourly\'

\# thresholds for moderate and heavy rain must be defined.

\# Precipitaion intensity is determined by equally distributing the

\# QPF amounts of a specific time period, between the hours of that

\# time period where measurable precipitation is forecast to occur.

\#

\# The resulting QPF average is then used in conjunction with the

\# thresholds defined below to assign intensity. This is an attempt

\# to account for variability in precip intensity.

\#

\# When the Wx grid duration is \> 6 hrs, the corresponding QPF is

\# scaled to a \"6 hr\" QPF.

\#

\# By default, all Wx is light (-).

\# Define \'hourly\' threshold amounts for moderate rain for each hour

\# of Wx duration

self.\_modRthresh = {1:0.11, \# 0.11 total/6 hr QPF

2:0.11, \# 0.22 total/6 hr QPF

3:0.10, \# 0.30 total/6 hr QPF

4:0.10, \# 0.40 total/6 hr QPF

5:0.09, \# 0.45 total/6 hr QPF

6:0.08 \# 0.48 total/6 hr QPF

}

\# Define \'hourly\' threshold amounts for heavy rain for each hour

\# of Wx duration

self.\_hvyRthresh = {1:0.30, \# 0.30 total/6 hr QPF

2:0.26, \# 0.52 total/6 hr QPF

3:0.24, \# 0.72 total/6 hr QPF

4:0.18, \# 0.72 total/6 hr QPF

5:0.15, \# 0.75 total/6 hr QPF

6:0.13 \# 0.78 total/6 hr QPF

}

\# Define percentage to reduce threshold for RWm and RW+

\# The lower this percentage, the easier it is to get

\# moderate and heavy precipitation when the type is

\# \'Showery\' only.

self.\_modifyThresh = 0.70

\# Define minimum sky cover allowed to be input by forecaster

self.\_minSky = 20.0

\# Indicate if you wish to use \'Slight Chance\' terminology

self.\_slightChance = \'Yes\' \# answer \'Yes\' or \'No\'