Add a new basin_map configuration option for TC-Pairs.

Describe the New Feature

This feature request came from Michelle Harrold running tc_pairs on ATCF data for a DTC testing and evaluation project. Her forecast track data specified basins named SI and SP while the BEST track dataset used a basin named SH. Rather than having to pre-process her track data to rename SI/SP to SH, enhance tc_pairs to do it.

Add a new basin_map config file entry similar to the message_type_map found in the ascii2nc config file.

Based on feedback from Jonathan Vigh, define the default map as follows:

basin_map = [
   { name = "SI"; val = "SH"; },
   { name = "SP"; val = "SH"; },
   { name = "AU"; val = "SH"; },
   { name = "AB"; val = "IO"; },
   { name = "BB"; val = "IO"; }
]

Be sure to update the data/config/README file with a description of the purpose of this map. See below for details from an email from Jonathan about this situation...

I'd say that the model centers are providing their outputs properly, but JTWC, who is the source of the best track data that most U.S.-based modeling groups use for verification, mashes these together into a 'SH' region for convenience. Here is documentation of how JTWC maps the basin identifiers all into SH (see Appendix 2): https://www.metoc.navy.mil/jtwc/products/best-tracks/tc-bt-report.html

Note the 1-letter DOD codes, the 2-letter ATCF basin/region codes, and all the other names used for the basins.

And if this wasn't confusing enough, the ATCF also supports sub-region codes, which partly comport with the DOD 1-letter codes.

To add confusion, NCEP is likely also providing their model output in CXML, which is another format used by other groups, namely Australia. CXML uses 3-letter basin identifiers. Here is some code that illustrates the mapping from CXML -> 2-letter ATCF:

# if ($cxml_basin eq "ATL") {
# $atcf_basin = "AL";
# } elsif ($cxml_basin eq "NEP") {
# $atcf_basin = "EP";
# } elsif ($cxml_basin eq "NWP") {
# $atcf_basin = "WP";
# } elsif ($cxml_basin eq "NIO") {
# $atcf_basin = "BB";
# } elsif ($cxml_basin eq "SWI") {
# $atcf_basin = "SI";
# } elsif ($cxml_basin eq "SEI") {
# $atcf_basin = "AU";
# } elsif ($cxml_basin eq "SWP") {
# $atcf_basin = "SP";
# } elsif ($cxml_basin eq "GLO") {
# $atcf_basin = "TG";

Note, I think the modelers may use TG in the case of a Mediterranean TC, but I'm not sure about this.

Even this is confusing, because I don't typically see AU or BB used in practice (but then again, I'm not looking at Australian- or Indian-sourced data, so who knows). Also, I think BB gets mapped to IO anyway. Finally, I believe there is a South Atlantic basin 'SL' that can get used on the rare occasion of a South Atlantic TC.

But this is just to let you know that there are a variety of basins or sub-basins that could theoretically appear depending on what schema a modeling group is using. But to do verification, some sort of replacement must be done either in the data, or by MET to get things to work. So in summary, I think the following mapping should work: SI/SP/AU -> SH AB/BB -> IO

This discussion applies to ATCF, which is largely a U.S.-based schema. If a user wanted to use the RSMC-provided best tracks (which is different from JTWC), they could pull this out of iBTrACS. But as I've mentioned before, there be dragons there (different operational practices, different wind-averaging periods, etc.).

Acceptance Testing

Update tc_pairs and have Michelle test with her track data to confirm that tc_pairs creates matches.

Time Estimate

1 day

Sub-Issues

Consider breaking the new feature down into sub-issues.

[X] Add a checkbox for each sub-issue here. No sub-issues required.

Relevant Deadlines

None

Funding Source

None

Define the Metadata

Assignee

[X] Select engineer(s) or no engineer required: John Halley Gotway
[X] Select scientist(s) or no scientist required: Michelle Harrold for testing and Jonathan Vigh for perspective on global TC's.

Labels

[X] Select component(s)
[X] Select priority
[X] Select requestor(s)

Projects and Milestone

[X] Review projects and select relevant Repository and Organization ones
[X] Select milestone

Define Related Issue(s)

Consider the impact to the other METplus components.

[X] METplus, MET, METdb, METviewer, METexpress, METcalcpy, METplotpy No impacts.

New Feature Checklist

See the METplus Workflow for details.

[X] Complete the issue definition above.
[x] Fork this repository or create a branch of develop. Branch name: feature_<Issue Number>_<Description>
[x] Complete the development and test your changes.
[x] Add/update unit tests.
[x] Add/update documentation.
[x] Push local changes to GitHub.
[x] Submit a pull request to merge into develop. Pull request: feature <Issue Number> <Description>
[x] Iterate until the reviewer(s) accept and merge your changes.
[x] Delete your fork or branch.
[x] Close this issue.

Installed the feature_1390_basin_map branch on hera for Michelle to test: /scratch1/BMC/dtc/John.H.Gotway/MET/MET-feature_1390_basin_map/met

I implemented the handling of the basin_map in the ATCFLineBase::read_line() function. Prior to reading data into an ATCFLineBase (or derived type) object, the application code (tc_pairs) calls set_basin_map() to point to the basin_map defined in the config file. For consistency, I moved the logic for determining BEST and operational tracks, as well as appending model suffix names, to the base class as well. That way, these modifications to and interpretations of input ATCF lines are all handled in one spot.

Here is a snippet that can be inserted into the TCpairs config file describing the basin_map functionality.

// // Specify mapping of basin identifiers for matching. // // Many global modeling centers use ATCF basin identifiers based on region (e.g., 'SP' for South Pacific Ocean, etc.), // however the best track data provided by the Joint Typhoon Warning Center (JTWC) use just one basin identifier 'SH' // for all of the Southern Hemisphere basins. Additionally, some modeling centers may report basin identifiers separately // for the Bay of Bengal (BB) and Arabian Sea (AB) whereas JTWC uses 'IO'. // // The basin mapping allows MET to map the basin identifiers to the expected values without having to modify your data.
// For example, the first entry in the list below indicates that any data entries for 'SI' will be matched as if they were 'SH'. // In this manner, all verification results for the Southern Hemisphere basins will be reported together as one basin. // // An empty list indicates that no basin mapping should be used. Use this if you are not using JTWC best tracks and you // would like to match explicitly by basin or sub-basin. Note that if your model data and best track do not use the same // basin identifier conventions, using an empty list for this parameter will result in missed matches. // basin_map = [ { name = "SI"; val = "SH"; }, { name = "SP"; val = "SH"; }, { name = "AU"; val = "SH"; }, { name = "AB"; val = "IO"; }, { name = "BB"; val = "IO"; } ]

Jonathan,

Great, thanks! I dropped this description into the README_TC file here:

https://github.com/NCAR/MET/blob/2bbbc8a5244a88728f7a7d29f38ccedec9583831/met/data/config/README_TC#L241

And in the tc _pairs chapter: https://github.com/NCAR/MET/blob/develop/met/docs/Users_Guide/tc-pairs.rst

Thanks John

On Thu, Jul 9, 2020 at 10:58 AM Jonathan Vigh notifications@github.com wrote:

Here is a snippet that can be inserted into the TCpairs config file describing the basin_map functionality.

// // Specify mapping of basin identifiers for matching. // // Many global modeling centers use ATCF basin identifiers based on region (e.g., 'SP' for South Pacific Ocean, etc.), // however the best track data provided by the Joint Typhoon Warning Center (JTWC) use just one basin identifier 'SH' // for all of the Southern Hemisphere basins. Additionally, some modeling centers may report basin identifiers separately // for the Bay of Bengal (BB) and Arabian Sea (AB) whereas JTWC uses 'IO'. // // The basin mapping allows MET to map the basin identifiers to the expected values without having to modify your data. // For example, the first entry in the list below indicates that any data entries for 'SI' will be matched as if they were 'SH'. // In this manner, all verification results for the Southern Hemisphere basins will be reported together as one basin. // // An empty list indicates that no basin mapping should be used. Use this if you are not using JTWC best tracks and you // would like to match explicitly by basin or sub-basin. Note that if your model data and best track do not use the same // basin identifier conventions, using an empty list for this parameter will result in missed matches. // basin_map = [ { name = "SI"; val = "SH"; }, { name = "SP"; val = "SH"; }, { name = "AU"; val = "SH"; }, { name = "AB"; val = "IO"; }, { name = "BB"; val = "IO"; } ]

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/NCAR/MET/issues/1390#issuecomment-656178712, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFA4HKFLBWZTGVBAZML66ATR2XLJ5ANCNFSM4OIYJRVA .

Hi John, Great -- I like your edits. Jonathan

Jonathan Vigh
Project Scientist I, Joint Numerical Testbed
Research Applications Laboratory (RAL) National Center for Atmospheric Research (NCAR) P.O. Box 3000 tel: +1 (303) 497-8205 Boulder, CO 80307-3000 fax: +1 (303) 497-8171Jonathan's Staff Web Page http://www.ral.ucar.edu/staff/jvigh/ (CV, publications, etc.)Tropical Cyclone Guidance Project http://hurricanes.ral.ucar.edu/ (real-time hurricane data)

Tropical Cyclone Data Project https://verif.rap.ucar.edu/tcdata/ (FLIGHT+, VDM+, TC-OBS datasets)

Hurricane Risk Calculator https://wxrisk.ucar.edu (personalizing hurricane risk assessments for evacuation decision support)

During COVID-19, my working day is definitely not the same as your working day. Please do not feel obliged to reply to this email outside of your normal working hours.

On Thu, Jul 9, 2020 at 9:46 AM johnhg notifications@github.com wrote:

Jonathan,

Great, thanks! I dropped this description into the README_TC file here:

https://github.com/NCAR/MET/blob/2bbbc8a5244a88728f7a7d29f38ccedec9583831/met/data/config/README_TC#L241

And in the tc _pairs chapter: https://github.com/NCAR/MET/blob/develop/met/docs/Users_Guide/tc-pairs.rst

Thanks John

On Thu, Jul 9, 2020 at 10:58 AM Jonathan Vigh notifications@github.com wrote:

Here is a snippet that can be inserted into the TCpairs config file describing the basin_map functionality.

// // Specify mapping of basin identifiers for matching. // // Many global modeling centers use ATCF basin identifiers based on region (e.g., 'SP' for South Pacific Ocean, etc.), // however the best track data provided by the Joint Typhoon Warning Center (JTWC) use just one basin identifier 'SH' // for all of the Southern Hemisphere basins. Additionally, some modeling centers may report basin identifiers separately // for the Bay of Bengal (BB) and Arabian Sea (AB) whereas JTWC uses 'IO'. // // The basin mapping allows MET to map the basin identifiers to the expected values without having to modify your data. // For example, the first entry in the list below indicates that any data entries for 'SI' will be matched as if they were 'SH'. // In this manner, all verification results for the Southern Hemisphere basins will be reported together as one basin. // // An empty list indicates that no basin mapping should be used. Use this if you are not using JTWC best tracks and you // would like to match explicitly by basin or sub-basin. Note that if your model data and best track do not use the same // basin identifier conventions, using an empty list for this parameter will result in missed matches. // basin_map = [ { name = "SI"; val = "SH"; }, { name = "SP"; val = "SH"; }, { name = "AU"; val = "SH"; }, { name = "AB"; val = "IO"; }, { name = "BB"; val = "IO"; } ]

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/NCAR/MET/issues/1390#issuecomment-656178712, or unsubscribe < https://github.com/notifications/unsubscribe-auth/AFA4HKFLBWZTGVBAZML66ATR2XLJ5ANCNFSM4OIYJRVA

.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/NCAR/MET/issues/1390#issuecomment-656204080, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEWD6VU2MNMKXHHAGLBDZCTR2XQ4ZANCNFSM4OIYJRVA .

dtcenter / MET