Custom Zone Phrasing in Local Where Method - Hazard Services

Focal Point Winter Weather Jobsheets

Custom Zone Phrasing via localWherePhraseConfiguration Method

Purpose:

Specify name substitutions for a zone or group of zones using the localWherePhraseConfiguration method of Hazard Services, and for VTEC criteria

Tasks:

AT-A-GLANCE:

What? Place substitution criteria in the "subList" variable of the localWherePhraseConfiguration method, in an override of LocalVariables.py
Flexible. Use this for anything from single zone naming changes to re-phrasing groups of zones (and also by different VTEC criteria)
All Or Nothing. Substitutions only trigger if ALL zones and ALL VTEC criteria for a given entry are matched.
Order Matters! Zones are ONLY matched to the FIRST good criteria; any subsequent criteria for already-matched zones are ignored. So, order your criteria from the largest zone groupings to the smallest.

Follow the steps below for more detailed guidance.

Task 1: Override two zones (valid for all VTECs)

Task 2: Add a multi-zone name substitution (valid for all VTECs) and proper rule ordering

Task 3: Make a VTEC-specific zone name substitution

Task 1 (of 3) Override one or two zones (valid for all VTECs)

Pick zones whose name you will override (this jobsheet uses VAZ503 and 504 from the LWX domain). You will need the ugc code in subsequent steps
1. Look up the UGC code in your AreaDictionary or by loading the forecast zones map in CAVE if you're unsure.
[OPTIONAL] Create a hazard for your zone(s) to see the initial naming
1. Launch Hazard Services in your desired perspective (e.g. GFE)
2. Use the Select by Area functionality to create a hazard over your desired zone
  1. TIP: To isolate just one forecast zone, click the "Maps" menu and pick the "Forecast Zones" map for your CWA. Then click on the "Maps" Hazard Services toolbar button, pick the "Forecast Zones" item, left click on the map on your desired zone, then right-click to complete the selection.
3. Select a category (e.g. Winter) and hazard (e.g. BZ.W), then click "Preview" to generate a product
4. Look at the "Where:" text field to see the current naming being pulled for your affected zone(s).
Switch to the Localization Perspective by clicking on the "Open Perspective" icon at the top-right of your CAVE window, and choosing "Localization"
In the Localization Perspective, navigate to the Utilities sub-directory under the Hazard Services folder.
Double click on LocalVariables.py to show the available versions
Create a user override version if none exists (user override is best practice for testing changes):
1. If there is only a BASE version: right click on BASE and select Create Override File, then select User
2. If there is another version (e.g. SITE) you wish to use: right click on that file and select Copy To, then select User (this lets you work on an updated SITE version to replace the original when you're finished)
Double click on the USER version of LocalVariables.py to open it for editing
Open a reference copy of the existing LocalVariables.py file, which will be used for comparison and copying existing code to overrides.
1. It's typically best to open the BASE version because most methods have not already been overridden in a higher-level override
In the reference file you opened, scroll or search to find the "localWherePhraseConfiguration" method (whose first line appears as "def localWherePhraseConfiguration(self):" in LocalVariables.py)
Once found, select the entire localWherePhraseConfiguration method by clicking and dragging from (and including) the "def localWherePhraseConfiguration(self):" line which begins the function, all the way to (and including) the last line of the function which has the "return subList" statement.
Copy the selected contents by right-clicking and selecting "Copy" from the pop-up menu, or by hitting CTRL-C on your keyboard
Switch back to the USER override you were working on
Paste the localWherePhrase method into your USER override on a blank line after the "class..." and "pass" lines (or after any pre-existing override methods in the file), by right-clicking and selecting "Paste" from the pop-up menu, or by hitting CTRL-V on your keyboard
In the user override, locate the uncommented line below in the localWherePhraseConfiguration method :
```
subList = []
```
Add a dictionary { } like the following inside the subList variable (bold shows the new code). Substitute your ugcCode(s) for VAZ503/4 in the example below, as well as a new name to use for these UGCs in the quoted text after that.
```
subList = [
    {
       "vtecCriteria": [], # No VTEC criteria
       "zoneGroupCriteria": [
            (["VAZ503", "VAZ504"], "Highland"),
       ]
   },
]
```
Be extremely attentive to the proper brackets, quotes, commas, and indentation - avoiding typos now will save you headaches later!
1. WHAT IT MEANS: This dictionary { } entry in subList has two parts: a vtecCriteria field (empty here so that it applies to all VTECs), and a zoneGroupCriteria which is a list [ ] of tuples ( ) corresponding to zone groups to test for (two in our simple case) and their substitution phrase if matched. Multiple tuples may be included in zoneGroupCriteira to handle multiple substitutions, but zones can only be matched to one substitution before they are exhausted!
When finished, save the file by hitting Ctrl+S, or selecting Save from the File menu
1. If a "File Version Conflict" is encountered, click OK to accept merge
2. In the two-panel "Merge" tab that opens, make no changes, once again save the file by hitting Ctrl+s, then close the "Merge" tab
3. When a "File Changed" message appears, click Yes.
4. This behavior will only be encountered each time a new override file that did not exist before is created and saved
[OPTIONAL, HIGHLY RECOMMENDED] Test your name substitution by returning to your previous perspective (e.g. GFE) and issuing a hazard for your zone
1. No need to fully issue - just generate a hazard overlapping your zone, and check the "Where" text field to verify that your new name is used for the appropriate zone
Finished!

Task 2 (of 3) Add a multi-zone name substitution (valid for all VTECs) and consider ordering

Identify two or more zones which you intend to express with a single phrase substitution in the Where bullet (e.g. zones in a known geographic descriptor). You will need the UGC codes for each zone in subsequent steps
[OPTIONAL] Create a hazard and preview a product for your zones to see the initial naming
1. Notice the "Where:" text and how the current names are being independently pulled for each of your zones.
Open a USER override of LocalVariables.py file (STEPS 3-7 in TASK 1 above) and find the "subList" variable in the localWherePhraseConfiguration method override (if you don't already have this method override, do steps 8-15 in TASK 1 above)
If one doesn't already exist, create a criteria group in subList with no "vtecCriteria" like the following (changes in bold):
```
subList = [
    {
        "vtecCriteria": [], # No VTEC criteria
        "zoneGroupCriteria":  [], # It's OK if you have pre-existing entries in here, leave them
    }
]
```
1. If you did TASK 1, you should not need to do this. You will already have one dictionary in subList with an empty value [ ] for "vtecCriteria" (and some entries in zoneGroupCriteria). We will be adding additional zone substitutions to this entry in the next steps.
2. Be careful with syntax if you are typing this for the first time (review opening and closing brackets, quotes, commas, and indentation... avoid typos now to save time later!)
Now populate the zoneGroupCriteria field as follows
1. Add a multi-zone substitution in zoneGroupCriteria for your two or more zones to substitute with a single phrase (changes in bold). Replace the example ugc codes and phrasing used below with your own:
```
 subList = [
            {"VtecCriteria":[],
             "zoneGroupCiteria":[(["MDZ501", "MDZ502", "VAZ503", "VAZ504", "WVZ501", "WVZ502", "WVZ503", "WVZ504", "WVZ505",
                                   "WVZ506"],"the Allegheny Front"),
       ],
    }
]
```
2. If you have other pre-existing entries in zoneGroupCriteria, we'll touch on how to handle those next
3. WHAT THIS DOES: You've added two (or more) ugcs which will be expressed in the Where bullet by the phrase to their right, ONLY IF:
  1. BOTH ugcs are in the hazard,
  2. The VTEC criteria (in this case empty, so applies to all VTECs) are matched, AND...
  3. NO other match for any of those ugcs has already been triggered
Handling more than one entry... If you have (or want to add) another substitution rule for one of these zones, you must consider the ordering of these rules as you enter them. These sub-steps show the effect of ordering.
1. [BEST PRACTICE] Place your most elaborate/difficult-to-match criteria FIRST. In our example, suppose in addition to our multi-zone substitution we also have other substitutions for VAZ503 and 504 (e.g. from TASK 1). Then your subList should look as follows:
```
subList = [
            {"VtecCriteria":[],
             "zoneGroupCiteria":[(["MDZ501", "MDZ502", "VAZ503", "VAZ504", "WVZ501", "WVZ502", "WVZ503", "WVZ504", "WVZ505",
                                   "WVZ506"],"the Allegheny Front"), # HARDER MATCH...GOES FIRST
                                 (["DCZ001", "MDZ508", "MDZ011", "MDZ506", "MDZ014", "MDZ504", "MDZ013", "MDZ016", "MDZ017",
                                   "MDZ018", "VAZ052", "VAZ053","VAZ054", "VAZ055","VAZ056", "VAZ057"], "the I-95 Corridor"),
                                 (["VAZ503", "VAZ504"], "Highland"), # EASIER MATCH...GOES LAST
                                 ]
            },
        ]
```
  WHY GOOD? In order of appearance, the group substitution for the Allegheny Front will be matched first in a hazard with those UGCs, after which both zones are ignored for any additional substitutions. The Highland substitution is then only considered if the hazard does not also contain the other UGCs.
2. [BAD EXAMPLE] For an example of a bad practice, see below where more easily matched criteria are placed first. This is an easy way to accidentally prevent more complex criteria from ever being triggered:
```
subList = [
    {
        "vtecCriteria": [], # No VTEC criteria
        "zoneGroupCriteria":  [  # BAD EXAMPLE OF ORDERING, AVOID!
            (["VAZ503", "VAZ504"], "Highland"),
            (["MDZ501", "MDZ502", "VAZ503", "VAZ504", "WVZ501", "WVZ502", "WVZ503", "WVZ504", "WVZ505",  
              "WVZ506"],"the Allegheny Front"),                                
            (["DCZ001", "MDZ508", "MDZ011", "MDZ506", "MDZ014", "MDZ504", "MDZ013", "MDZ016", "MDZ017",  
              "MDZ018", "VAZ052", "VAZ053","VAZ054", "VAZ055","VAZ056", "VAZ057"], "the I-95 Corridor"),
        ],
    }
]
```
  WHY BAD? UGCs are ONLY MATCHED TO ONE SUBSTITUTION. In order of appearance, the VAZ503/4 UGC substitution will always match a hazard before the subsequent Allegheny Front criteria even has a chance. Since VAZ503/4 are immediately removed from consideration for any other substitution by the first match, you'll never get to see your larger phrasing.
3. [MORE INFO] As you add additional zones within "zoneGroupCriteria", AND additional criteria groups dictionaries { } within "subList", consider the top-down ordering of your substitutions and ensure that an easier-to-match substitution doesn't preclude a harder-to-match substitution later.
When finished, save the file by hitting Ctrl+S, or selecting Save from the File menu
1. If a "File Version Conflict" is encountered, click OK to accept merge
2. In the two-panel "Merge" tab that opens, make no changes, once again save the file by hitting Ctrl+s, then close the "Merge" tab
3. When a "File Changed" message appears, click Yes.
4. This behavior will only be encountered each time a new override file that did not exist before is created and saved
[OPTIONAL, HIGHLY RECOMMENDED] Test your name substitution by returning to your previous perspective (e.g. GFE) and issuing a hazard for your zone
1. No need to fully issue - just generate a hazard overlapping your zone, and check the "Where" text field to verify that your new name is used for the appropriate zone
[BONUS] Try out different orderings of multiple zoneGroupCriteria or criteria groups within subList to see for yourself how the ordering impacts the substitutions chosen. Make sure you're seeing the substitutions you expect!
1. In the end, stick to the best practice of harder-to-match criteria BEFORE easier-to-match criteria
Finished!

Task 3 (of 3) Make a VTEC-specific zone name substitution

Create a zone name substitution following either TASK 1 or TASK 2 above which you will subsequently add a VTEC constraint to. For simplicity, the example below shows a single zone substitution:

subList = [
    {
        "vtecCriteria": [], # No VTEC criteria
        "zoneGroupCriteria": [
            (["COZ036"],"Jefferson between 6000 and 9000ft"),
        ]
    },
]

Now edit the "vtecCriteria" line following the examples below, substituting the phensig value(s) you'd like as a prerequisite for triggering the naming substitutions (change in bold):
```
subList = [
    {
        "vtecCriteria": ['BZ.W'],
        "zoneGroupCriteria": [
            (["COZ036"],"Jefferson between 6000 and 9000ft"),
        ]
    },
]
```
1. Multiple phensigs: Multiple phensigs can be added to this criteria, each in quotes and comma-separated, to re-use the same substitutions for multiple hazard types. HOWEVER, if you have a product segment with multiple phensigs, ALL phensigs in the segment must match an item in the same vtecCriteria list or that particular substitution will NOT trigger.
Handling more than one entry... just like multiple zoneGroupCriteria, having a vtec-specific criteria group requires consideration of the rule order to behave as expected.
1. [BEST PRACTICE] Place your most elaborate/difficult-to-match criteria FIRST. In terms of VTEC criteria, of course a VTEC-agnostic rule (like "vtecCritera": [ ]) is easiest to match and should NOT be placed before a VTEC-specific rule for a given zone.
[OPTIONAL, HIGHLY RECOMMENDED] Test your VTEC-specific substitution by returning to your previous perspective (e.g. GFE) and issuing a hazard for your zone
1. No need to fully issue - just generate a hazard which matches your VTEC criteria and overlaps your zone, and check the "Where" text field to verify that your new name is used for the appropriate zone
Finished!

Previous: Populate Predefined Edit Areas Drop Down in Zorro Tool	Focal Point Winter Weather Table of Contents	Next: Change (or Remove) Zone Type Text in Where Bullet