Add gridded output fields from tc_gen in NetCDF format

[DanielAdriaansen]

Describe the Enhancement

TC genesis can be summarized in various ways, including the computation of the seasonal-to-sub-seasonal (S2S) metrics Track Density Function (TDF) and Genesis Density Function (GDF). To compute these metrics, it would be useful to have the following information from tc_gen written to a gridded (see NOTE1) NetCDF output file:

1. Total count of observed genesis events
2. Total count of unique forecast genesis events (see NOTE2)
3. Total count of genesis hits
4. Total count of genesis misses
5. Total count of genesis false alarms
6. Total count of forecast track points (see NOTE3)
7. Total count of observed track points (see NOTE3)

NOTE1: It would be preferable to have a user configurable global grid to produce output on.

NOTE2: In order to not "double count" forecast genesis events (i.e. only include unique forecast genesis events), care will need to be taken to consider whether there are multiple forecasts of genesis at the same location (grid cell). For example, a model run a 00, 06, 12, and 18 UTC each day could produce 4 forecasts valid at 12 UTC two days in advance. The lead times from these forecasts would be 60, 54, 48, and 42. If all of those forecasts produced a genesis event at the same location (grid cell) and same valid time then these should only be counted as one genesis forecast and not 4.

NOTE3: It would be useful to include a user configurable boolean flag/option in the tc_gen config file to include track points before or after the genesis point in both the forecast and observed tracks. Something like INCLUDE_TRACK_BEFORE_GENESIS, with the default set to FALSE.

Time Estimate

Estimate the amount of work required here.
Approximately 1-2 days.

Sub-Issues

Consider breaking the enhancement down into sub-issues.

• Add support for user configurable global grid
• Add support for writing NetCDF output file
• Add support for keeping track of requested output fields
• Add support for duplicate forecast genesis event ID and removal
• Add user configuration to include track points before genesis or only after genesis

Relevant Deadlines

NONE

Funding Source

Split: 7790971, 2785051

Define the Metadata

Assignee

• Select engineer(s) or no engineer required: John Halley-Gotway
• Select scientist(s) or no scientist required: Dan Adriaansen

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Review projects and select relevant Repository and Organization ones
• Select milestone

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, MET, METdb, METviewer, METexpress, METcalcpy, METplotpy

Enhancement Checklist

See the METplus Workflow for details.

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

[JohnHalleyGotway]

Dan, here's some proposed additions to the TC-Gen config file:

//
// NetCDF genesis and track density output
//
nc_pairs_grid = "G001";
nc_pairs_flag = {
   latlon    = TRUE;
   best_gen  = TRUE;
   best_pts  = TRUE;
   fcst_gen  = TRUE;
   fcst_pts  = TRUE;
   gen_fy_oy = TRUE;
   gen_fy_on = TRUE;
   gen_fn_oy = TRUE;
}

These will control the contents of the NetCDF output file. best_gen/fcst_gen would only include the genesis event locations, while best_pts/fcst_pts would include ALL track points. I'm unsure about NOTE3. Would that impact which points are included in best_pts/fcst_pts? So the user could control which tracks points are included? Reasonable examples might include all points, genesis and all prior points, or genesis +/- 12 hours. So perhaps add:

// genesis time +/- 12 hours
genesis_track_points_window = { beg = -12;  end = 12;  };
// 10 days prior to genesis
genesis_track_points_window = { beg = -120; end = 0;   }; 
// 10 days after genesis
genesis_track_points_window = { beg = 0;    end = 120; }; 
// genesis +/- 10 days (DEFAULT)
genesis_track_points_window = { beg = -120; end = 120; };

Is that what you're looking for? Or something else?

[DanielAdriaansen]

What will the "latlon" item include?

Perhaps also genesis and all post-genesis points as well? Otherwise your filtering options make sense to me and give the user the flexibility to retain track points in pretty much any manner they choose.

Is there a sample netCDF file I can look at once you create it?

[JohnHalleyGotway]

Don't worry about "latlon". It just says whether or not to write a field of lat and lon values for the grid to the NetCDF file. It's sometimes convenient to have them for plotting. But sometimes users turn them off to save space.

So best_gen and fcst_gen options are intended to write only the genesis event locations.
And best_pts and fcst_pts options write out track points... while genesis_track_points_window defines WHICH track points to include, relative to the genesis event.

I went down a bit of a rabbit hole today. I'll share an example NetCDF file when I have one ready.

[JohnHalleyGotway]

Project meeting on 1/6/2020:

Note: I added comments here since I'll actually make these changes on the 1430 development branch, not 1448.

Dan H has been testing feature_1448_tc_gen using 2019 Atlantic storms.
All the hits and false alarms are what he expects.
Will continue testing but for now the hits vs false alarm classifications are done as we'd expect.
Some questions...

(1) Add config option for:

//
// Discard genesis forecasts 
//
discard_init_post_genesis = TRUE;  // default: TRUE

(2) Update default value for:

genesis_radius = 300; to 500

(3) Update the name of the config option:

//
// Lead times in hours to be searched for genesis events.
(change to 'Forecast hours to be searched for genesis events.')
//
lead_window = { (rename to fcst_hr_window)
   beg = 24; (from 24 to 6)
   end = 120;
}

(4) Update the false alarm and hit log messages to include the forecast hour (e.g. 20191017_120000 forecast genesis FOR 24 HOUR FORECAST at).

(5) Compute the genesis time offset as FCST-BEST instead of BEST-FCST.

(6) Remove existing genesis_radius and add genesis_match_radius and genesis_hit_radius:

//
// Genesis matching search radius in km
//
genesis_radius = 500;

genesis_match_radius // might set this more strict (e.g. smaller)
genesis_hit_radius // might set this more generously (e.g. larger)

(7) Support a list of model initializations to be excluded from the analysis.
Add a new GitHub issue for init_inc and init_exc similar to the sid_inc and sid_exc from Point-Stat.

(8) Replace genesis_track_points_window with a threshold option instead.
Compute the difference between the genesis time and track point valid time.
e.g. replace genesis_track_points_window with a threshold option instead.

After updating the config options, build on kiowa for Kathryn to test and update the docs.

[JohnHalleyGotway]

Got the code working well and producing the desired NetCDF genesis pairs output. Updated the user's guide.

Still need to...

• Enhance the unit test to exercise more of these options.
• Support lists of model initializations to be included/excluded from the analysis (need a new GitHub issue for init_inc and init_exc).
• Add the MPR output line type per MET Enhance tc_gen to write a matched pair output line type. #1597.