Feature 1870 realtime (#1893)

* Per #1870. add TCPairs config entries for valid_inc, valid_exc, and write_valid.

* Per #1870, removing 2 files I accidentally added.

* Per #1870, add code to parse the new tc_pairs config options.

* Per #1870, unrelated... just fixing spacing.

* Per #1870, update TrackPairInfo/Array classes and tc_pairs application code to use the write_valid option to subset the tracks by requested valid time before writing them.

* Per #1870, update the User's Guide with the new config options. Document valid_inc/valid_exc in the common TC config section and add write_valid to the TC-Pairs chapter.

* Per #1870, move the subset_write_valid() functionality to the library code and support it for both track and probability arrays.

* Per #1870, update unit_tc_pairs.xml with 2 new calls to exercise the new write_valid functionality for both tracks and probabilities.

* Per #1870, correct some typos in the docs... PROBRI and probri should be PROBRIRW and probrirw, resp.

* Per #1870, switching match_points from TRUE back to FALSE after I acciedentally committed that change.

* Per #1870, just fixing indent.

Co-authored-by: John Halley Gotway <[email protected]>

met/data/config/TCPairsConfig_default

@@ -50,10 +50,17 @@ init_inc = [];
 init_exc = [];
 
 //
-// Valid model time window
+// Valid model time windows to include or exclude
 //
 valid_beg = "";
 valid_end = "";
+valid_inc = [];
+valid_exc = [];
+
+//
+// Valid times for which output should be written
+//
+write_valid = [];
 
 //
 // Model initialization hours

met/docs/Users_Guide/config_options_tc.rst

@@ -92,6 +92,8 @@ or exclude (exc). Tracks whose initial time meets the specified
 criteria will be used. An empty string indicates that all times
 should be used.
 
+In TC-Stat, the **-init_beg**, **-init_end**, **init_inc** and **-int_exc** job command options can be used to further refine these selections.
+
 For example:
 
 | init_beg = "20100101";
@@ -107,26 +109,34 @@ For example:
   init_inc = [];
   init_exc = [];
 
+.. _valid_beg end inc exc_1:
 
-.. _valid_beg, valid_end_1:
-
-:ref:`valid_beg, valid_end <valid_beg, valid_end_1>`
-
-Specify a model valid time window in YYYYMMDD[_HH[MMSS]] format.
-Tracks for which all valid times fall within the time window will be used.
-An empty string indicates that all times should be used.
+ ref:`valid_beg, valid_end, valid_inc, valid_exc <valid_beg end inc exc_1>`
+
+Specify a model valid time window YYYYMMDD[_HH[MMSS]] format or provide a
+list of specific valid times to include (inc) or exclude (exc). If a time
+window is specified, only tracks for which all points are contained within
+the window will be used. If valid times to include or exclude are specified,
+tracks will be subset down to the points which meet that criteria. Empty
+begin/end time strings and empty include/exclude lists indicate that all
+valid times should be used.
 
+In TC-Stat, the **-valid_beg**, **-valid_end**, **valid_inc** and **-valid_exc** job command options can be used to further refine these selections.
 
 For example:
-		
+
 | valid_beg = "20100101";
-| valid_end = "20101231";
-| 
+| valid_end = "20101231_12";
+| valid_inc = [ "20101231_06" ];
+| valid_exc = [ "20101231_00" ];
+|
 
 .. code-block:: none
-		
+
   valid_beg = "";
   valid_end = "";
+  valid_inc = [];
+  valid_exc = [];
 
 .. _init_hour_1:
 
@@ -422,7 +432,6 @@ 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.
 
-
 .. code-block:: none
 
   basin_map = [
@@ -481,9 +490,9 @@ For example:
   valid_inc = [];
   valid_exc = [];
 
-.. _ini valid_hour lead req:
+.. _init valid_hour lead req:
 
-:ref:`ini_hour, valid_hour, lead, lead_req <ini valid_hour lead req>`
+:ref:`init_hour, valid_hour, lead, lead_req <init valid_hour lead req>`
 
 Stratify by the initialization and valid hours and lead time.
 Specify a comma-separated list of initialization hours,

met/docs/Users_Guide/tc-pairs.rst

@@ -99,6 +99,8 @@ ____________________
   init_exc     = [];
   valid_beg    = "";
   valid_end    = "";
+  valid_inc    = [];
+  valid_exc    = [];
   init_hour    = [];
   init_mask    = [];
   lead_req     = [];
@@ -118,6 +120,14 @@ The **model** variable contains a list of comma-separated models to be used. Eac
 
 ____________________
 
+.. code-block:: none
+
+  write_valid = [ "20101231_06" ];
+
+The **write_valid** entry specifies a comma-separated list of valid time strings in YYYYMMDD[_HH[MMSS]] format for which output should be written. An empty list indicates that data for all valid times should be written. This option may be useful when verifying track forecasts in realtime. If evaluating performance for a single valid time, this option can limit the output to that time and skip output for earlier track points.
+
+____________________
+
 .. code-block:: none
 
   check_dup = FALSE;
@@ -315,7 +325,7 @@ TC-Pairs produces output in TCST format. The default output file name can be ove
     - Valid time masking grid applied
   * - 13
     - LINE_TYPE
-    - Output line type (TCMPR or PROBRI)
+    - Output line type (TCMPR or PROBRIRW)
 
 .. _TCMPR Line Type:
 
@@ -462,9 +472,9 @@ TC-Pairs produces output in TCST format. The default output file name can be ove
     - A/BDEPTH
     - system depth, D-deep, M-medium, S-shallow, X-unknown
 
-.. _PROBRI Line Type:
+.. _PROBRIRW Line Type:
 
-.. list-table:: Format information for PROBRIRW (Probability of Rapid Intensification) output line type.
+.. list-table:: Format information for PROBRIRW (Probability of Rapid Intensification/Weakening) output line type.
   :widths: auto
   :header-rows: 2
 
@@ -475,8 +485,8 @@ TC-Pairs produces output in TCST format. The default output file name can be ove
     - Header Column Name
     - Description
   * - 13
-    - PROBRI
-    - Probability of Rapid Intensification line type
+    - PROBRIRW
+    - Probability of Rapid Intensification/Weakening line type
   * - 14
     - ALAT
     - Latitude position of edeck model

met/docs/Users_Guide/tc-stat.rst

@@ -139,6 +139,8 @@ _________________________
   init_exc     = [];
   valid_beg    = "";
   valid_end    = "";
+  valid_inc    = [];
+  valid_exc    = [];
   init_hour    = [];
   lead_req     = [];
   init_mask    = [];
@@ -161,15 +163,6 @@ The **amodel** and **bmodel** fields stratify by the amodel and bmodel columns b
 
 _________________________
 
-.. code-block:: none
-
-  valid_inc = [];
-  valid_exc = [];
-
-The **valid_inc** and **valid_exc** fields stratify by valid times, based on a comma-separated list of specific valid times to include (inc) or exclude (exc). Time strings are defined by YYYYMMDD[_HH[MMSS]]. Using the **-valid_inc** and **-valid_exc** options within the job command lines may further refine these selections.
-
-_________________________
-
 .. code-block:: none
 
   valid_hour = [];
@@ -372,7 +365,7 @@ _________________________
         -job summary -line_type TCMPR  -column TK_ERR -dump_row ./tc_summary_job.tcst
         -job rirw    -line_type TCMPR  -rirw_time 24 -rirw_exact false -rirw_thresh ge20
         -job probrirw -line_type PROBRIRW -column_thresh RI_WINDOW ==24 \
-                      -probri_thresh 30 -probri_prob_thresh ==0.25
+                      -probrirw_thresh 30 -probrirw_prob_thresh ==0.25
 
 .. _tc_stat-output:
 
@@ -466,12 +459,12 @@ The PROBRIRW job produces probabilistic contingency table counts and statistics
 
 • The **-prob_exact bool** option is a boolean defining whether the exact or maximum BEST track intensity change over the time window should be used. If true, the values in the **BDELTA** column are used. If false, the values in the **BDELTA_MAX** column are used. The default is true.
 
-• The **-probri_bdelta_thresh** threshold option defines the BEST track intensity change event threshold. This should typically be set consistent with the probability threshold (**-prob_thresh**) chosen above. The default is greater than or equal to 30 kts.
+• The **-probrirw_bdelta_thresh** threshold option defines the BEST track intensity change event threshold. This should typically be set consistent with the probability threshold (**-prob_thresh**) chosen above. The default is greater than or equal to 30 kts.
 
-• The **-probri_prob_thresh threshold_list** option defines the probability thresholds used to create the output Nx2 contingency table. The default is probability bins of width 0.1. These probabilities may be specified as a list (>0.00,>0.25,>0.50,>0.75,>1.00) or using shorthand notation (==0.25) for bins of equal width.
+• The **-probrirw_prob_thresh threshold_list** option defines the probability thresholds used to create the output Nx2 contingency table. The default is probability bins of width 0.1. These probabilities may be specified as a list (>0.00,>0.25,>0.50,>0.75,>1.00) or using shorthand notation (==0.25) for bins of equal width.
 
 • The **-out_line_type** option defines the output data that should be written. This job can write PCT, PSTD, PJC, and PRC output line types. The default is PCT and PSTD.  Please see :numref:`table_PS_format_info_PCT` through :numref:`table_PS_format_info_PRC` for more details.
 
 Users may also specify the **-out_alpha** option to define the alpha value for the confidence intervals in the PSTD output line type. Multiple values in the **RI_WINDOW** column cannot be combined in a single PROBRIRW job since the BEST track intensity threshold should change for each. Using the **-by RI_WINDOW** option or **-column_thresh RI_WINDOW ==24** option provide convenient ways avoiding this problem.
 
-Users should note that for the PROBRIRW line type, **PROBRI_PROB** is a derived column name. The -probri_thresh option defines the probabilities of interest (e.g. **-probri_thresh 30**) and the **PROBRI_PROB** column name refers to those probability values, regardless of their column number. For example, the job command options **-probri_thresh 30 -column_thresh PROBRI_PROB >0** select 30 kt probabilities and match probability values greater than 0.
+Users should note that for the PROBRIRW line type, **PROBRI_PROB** is a derived column name. The -probrirw_thresh option defines the probabilities of interest (e.g. **-probrirw_thresh 30**) and the **PROBRI_PROB** column name refers to those probability values, regardless of their column number. For example, the job command options **-probrirw_thresh 30 -column_thresh PROBRI_PROB >0** select 30 kt probabilities and match probability values greater than 0.

met/src/basic/vx_config/config_constants.h

@@ -1012,6 +1012,7 @@ static const char conf_key_valid_end[]                = "valid_end";
 static const char conf_key_valid_inc[]                = "valid_inc";
 static const char conf_key_valid_exc[]                = "valid_exc";
 static const char conf_key_valid_hour[]               = "valid_hour";
+static const char conf_key_write_valid[]              = "write_valid";
 static const char conf_key_lead[]                     = "lead";
 static const char conf_key_lead_req[]                 = "lead_req";
 static const char conf_key_init_mask[]                = "init_mask";

met/src/libcode/vx_tc_util/prob_rirw_pair_info.cc

@@ -453,3 +453,20 @@ bool ProbRIRWPairInfoArray::add(const ProbRIRWInfo &p, const TrackInfo &t) {
 
 ////////////////////////////////////////////////////////////////////////
 
+void ProbRIRWPairInfoArray::subset_write_valid(const TimeArray &ta) {
+
+   // Check for no work to do
+   if(ta.n() == 0) return;
+
+   ProbRIRWPairInfoArray new_pairs;
+   for(int i=0; i<Pairs.size(); i++) {
+      if(ta.has(Pairs[i].prob_rirw().valid())) new_pairs.add(Pairs[i]);
+   }
+
+   // Save the subset
+   *this = new_pairs;
+
+   return;
+}
+
+////////////////////////////////////////////////////////////////////////

met/src/libcode/vx_tc_util/prob_rirw_pair_info.h

@@ -178,6 +178,7 @@ class ProbRIRWPairInfoArray {
 
       void add(const ProbRIRWPairInfo &);
       bool add(const ProbRIRWInfo &, const TrackInfo &);
+      void subset_write_valid(const TimeArray &);
 };
 
 ////////////////////////////////////////////////////////////////////////

met/src/libcode/vx_tc_util/tc_columns.cc

@@ -160,7 +160,7 @@ void write_tc_mpr_row(TcHdrColumns &hdr, const TrackPairInfo &p,
 
       // Set the description
       if(p.n_lines() > i) {
-	hdr.set_desc((string)p.line(i)->get_item("DESC", false));
+         hdr.set_desc((string)p.line(i)->get_item("DESC", false));
       }
 
       // Write the header columns
@@ -191,7 +191,7 @@ void write_prob_rirw_row(TcHdrColumns &hdr, const ProbRIRWPairInfo &p,
 
    // Pass the description from the input line to the output
    if(p.line().n_items() > 0) {
-     hdr.set_desc((string)p.line().get_item("DESC", false));
+      hdr.set_desc((string)p.line().get_item("DESC", false));
    }
 
    // Write one line for all the probabilities

met/src/libcode/vx_tc_util/track_pair_info.cc

@@ -309,6 +309,14 @@ void TrackPairInfo::initialize(const TCStatLine &l) {
 
 void TrackPairInfo::set_keep(int i, int val) {
 
+   // Check range
+   if(i < 0 || i >= NPoints) {
+      mlog << Error
+           << "\nTrackPairInfo::set_keep(int, int) -> "
+           << "range check error for index value " << i << "\n\n";
+      exit(1);
+   }
+
    Keep.set(i, val);
 
    return;
@@ -780,13 +788,23 @@ TrackPairInfo TrackPairInfo::keep_subset() const {
    TrackPairInfo tpi;
 
    // Loop over the points
-   for(i=0; i<NLines; i++) {
+   for(i=0; i<NPoints; i++) {
 
       // Check the retention status
       if(Keep[i] == 0) continue;
 
-      // Add the current track pair point
-      tpi.add(Line[i]);
+      // Add from TC-Stat line data
+      if(NLines == NPoints) {
+         tpi.add(Line[i]);
+      }
+      // Otherwise, add from TC-Pairs track pair
+      else {
+         if(tpi.n_points() == 0) tpi.initialize(ADeck, BDeck);
+         tpi.add(ADeck[i], BDeck[i],
+                 ADeckDLand[i], BDeckDLand[i],
+                 TrackErr[i], XErr[i], YErr[i],
+                 AlongTrackErr[i], CrossTrackErr[i]);
+      }
    }
 
    return(tpi);
@@ -1008,4 +1026,26 @@ void TrackPairInfoArray::add_watch_warn(const ConcatString &ww_sid,
    return;
 }
 
+////////////////////////////////////////////////////////////////////////
+
+void TrackPairInfoArray::subset_write_valid(const TimeArray &ta) {
+
+   // Check for no work to do
+   if(ta.n() == 0) return;
+
+   // Check each point for requested valid times
+   int i, j, keep;
+   for(i=0; i<NPairs; i++) {
+      for(j=0; j<Pair[i].n_points(); j++) {
+         keep = (ta.has(Pair[i].valid(j)) ? 1 : 0);
+         Pair[i].set_keep(j, keep);
+      }
+
+      // Subset the track
+      Pair[i] = Pair[i].keep_subset();
+   }
+
+   return;
+}
+
 ///////////////////////////////////////////////////////////////////////

met/src/libcode/vx_tc_util/track_pair_info.h

@@ -215,6 +215,7 @@ class TrackPairInfoArray {
 
       void add(const TrackPairInfo &);
       void add_watch_warn(const ConcatString &, WatchWarnType, unixtime);
+      void subset_write_valid(const TimeArray &);
 };
 
 ////////////////////////////////////////////////////////////////////////