Update develop-ref after #1734 and #1738

.github/pull_request_template.md

@@ -4,7 +4,9 @@
 
 - [ ] Recommend testing for the reviewer(s) to perform, including the location of input datasets, and any additional instructions:</br>
 
-- [ ] Do these changes include sufficient documentation and testing updates? **[Yes or No]**
+- [ ] Do these changes include sufficient documentation updates, ensuring that no errors or warnings exist in the build of the documentation? **[Yes or No]**
+
+- [ ] Do these changes include sufficient testing updates? **[Yes or No]**
 
 - [ ] Will this PR result in changes to the test suite? **[Yes or No]**</br>
 If **yes**, describe the new output and/or changes to the existing output:</br>

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required 
+version: 2
+
+# Build all formats (htmlzip, pdf, epub)
+#formats: all
+formats: []
+
+# Optionally set the version of Python and requirements required to build your
+# docs
+python:
+   version: 3.7
+   install:
+   - requirements: met/docs/requirements.txt
+
+# Configuration for Sphinx documentation (this is the default documentation
+# type)
+sphinx:
+  builder: html
+  configuration: met/docs/conf.py

met/data/config/TCStatConfig_default

@@ -111,6 +111,12 @@ column_thresh_val  = [];
 column_str_name = [];
 column_str_val  = [];
 
+//
+// Stratify by excluding strings in non-numeric data columns.
+//
+column_str_exc_name = [];
+column_str_exc_val  = [];
+
 //
 // Similar to the column_thresh options above
 //
@@ -123,6 +129,12 @@ init_thresh_val  = [];
 init_str_name = [];
 init_str_val  = [];
 
+//
+// Similar to the column_str_exc options above
+//
+init_str_exc_name = [];
+init_str_exc_val  = [];
+
 //
 // Stratify by the ADECK and BDECK distances to land.
 //

met/docs/Users_Guide/appendixF.rst

@@ -65,7 +65,9 @@ The data must be loaded into a 2D NumPy array named **met_data**. In addition th
      'long_name': 'FooBar',
      'level':     'Surface',
      'units':     'None',
-
+
+     # Define 'grid' as a string or a dictionary
+
      'grid': {
         'type': 'Lambert Conformal',
         'hemisphere': 'N',
@@ -83,12 +85,32 @@ The data must be loaded into a 2D NumPy array named **met_data**. In addition th
         'ny': 129,
       }
 
-     }
+  }
+
+
+In the dictionary, valid time, initialization time, lead time and accumulation time (if any) must be indicated by strings. Valid and initialization times must be given in YYYYMMDD[_HH[MMSS]] format, and lead and accumulation times must be given in HH[MMSS] format, where the square brackets indicate optional elements. The dictionary must also include strings for the name, long_name, level, and units to describe the data. The rest of the **attrs** dictionary gives the grid size and projection information in the same format that is used in the netCDF files written out by the MET tools. Those entries are also listed below. Note that the **grid** entry in the **attrs** dictionary can either be defined as a string or as a dictionary itself.
+
+If specified as a string, **grid** can be defined as follows:
+
+• As a named grid:
+
+.. code-block:: none
 
+  'grid': 'G212'
+
+• As a grid specification string, as described in :ref:`appendixB`:
+
+.. code-block:: none
+
+  'grid': 'lambert 185 129 12.19 -133.459 -95 40.635 6371.2 25 25 N'
+
+• As the path to an existing gridded data file:
+
+.. code-block:: none
 
-In the dictionary, valid time, initialization time, lead time and accumulation time (if any) must be indicated by strings. Valid and initialization times must be given in YYYYMMDD[_HH[MMSS]] format, and lead and accumulation times must be given in HH[MMSS] format, where the square brackets indicate optional elements. The dictionary must also include strings for the name, long_name, level, and units to describe the data. The rest of the **attrs** dictionary gives the grid size and projection information in the same format that is used in the netCDF files written out by the MET tools. Those entries are also listed below. Note that the **grid** entry in the **attrs** dictionary is itself a dictionary.
+  'grid': '/path/to/sample_data.grib'
 
-The supported grid **type** strings are described below:
+When specified as a dictionary, the contents of the **grid** dictionary vary based on the grid **type** string. The entries for the supported grid types are described below:
 
 • **Lambert Conformal** grid dictionary entries:
 

met/docs/Users_Guide/config_options.rst

@@ -81,7 +81,7 @@ The configuration file language supports the following data types:
   * The following percentile threshold types are supported:
 
     * "SFP" for a percentile of the sample forecast values.
-      e.g. ">SFP50" means greater than the 50-th forecast percentile.
+      e.g. ">SFP33.3" means greater than the 33.3-rd forecast percentile.
 
     * "SOP" for a percentile of the sample observation values.
       e.g. ">SOP75" means greater than the 75-th observation percentile.
@@ -3748,17 +3748,19 @@ Where "job_name" is set to one of the following:
   Job command FILTERING options that may be used only when -line_type
   has been listed once. These options take two arguments: the name of the
   data column to be used and the min, max, or exact value for that column.
-  If multiple column eq/min/max/str options are listed, the job will be
+  If multiple column eq/min/max/str/exc options are listed, the job will be
   performed on their intersection:
 
   .. code-block:: none
 
-    "-column_min    col_name value"     e.g. -column_min BASER 0.02
-    "-column_max    col_name value"
-    "-column_eq     col_name value"
-    "-column_thresh col_name threshold" e.g. -column_thresh FCST '>273'
-    "-column_str    col_name string" separate multiple filtering strings
-                                     with commas
+    "-column_min     col_name value"     e.g. -column_min BASER 0.02
+    "-column_max     col_name value"
+    "-column_eq      col_name value"
+    "-column_thresh  col_name threshold" e.g. -column_thresh FCST '>273'
+    "-column_str     col_name string" separate multiple filtering strings
+                                      with commas
+    "-column_str_exc col_name string" separate multiple filtering strings
+                                      with commas
 
 
   Job command options to DEFINE the analysis job. Unless otherwise noted,

met/docs/Users_Guide/config_options_tc.rst

@@ -517,8 +517,8 @@ For example:
 
 Stratify by performing string matching on non-numeric data columns.
 Specify a comma-separated list of columns names and values
-to be checked.  May add using the "-column_str name string" job command
-options.
+to be included in the analysis.
+May add using the "-column_str name string" job command options.
 
 For example:
 
@@ -531,6 +531,23 @@ For example:
   column_str_name = [];
   column_str_val  = [];
 
+**column_str_exc_name, column_str_exc_val**
+
+Stratify by performing string matching on non-numeric data columns.
+Specify a comma-separated list of columns names and values
+to be excluded from the analysis.
+May add using the "-column_str_exc name string" job command options.
+
+For example:
+
+| column_str_exc_name = [ "LEVEL" ];
+| column_str_exc_val  = [ "TD"    ];
+|
+
+.. code-block:: none
+
+  column_str_exc_name = [];
+  column_str_exc_val  = [];
 
 **init_thresh_name, init_thresh_val**
 
@@ -567,6 +584,23 @@ For example:
   init_str_name = [];
   init_str_val  = [];
 
+**init_str_exc_name, init_str_exc_val**
+
+Just like the column_str_exc options above, but apply the string matching only
+when lead = 0.  If lead = 0 string does match, discard the entire track.
+May add using the "-init_str_exc name thresh" job command options.
+
+For example:
+
+| init_str_exc_name = [ "LEVEL" ];
+| init_str_exc_val  = [ "HU"    ];
+|
+
+.. code-block:: none
+
+  init_str_exc_name = [];
+  init_str_exc_val  = [];
+
 **water_only**
 
 Stratify by the ADECK and BDECK distances to land.  Once either the ADECK or
@@ -747,8 +781,10 @@ Where "job_name" is set to one of the following:
     "-track_watch_warn   name"
     "-column_thresh      name thresh"
     "-column_str         name string"
+    "-column_str_exc     name string"
     "-init_thresh        name thresh"
     "-init_str           name string"
+    "-init_str_exc       name string"
 
   Additional filtering options that may be used only when -line_type
   has been listed only once. These options take two arguments: the name
@@ -758,11 +794,13 @@ Where "job_name" is set to one of the following:
 
   .. code-block:: none
 
-    "-column_min col_name value" For example: -column_min TK_ERR 100.00
-    "-column_max col_name value"
-    "-column_eq  col_name value"
-    "-column_str col_name string" separate multiple filtering strings
-                                  with commas
+    "-column_min     col_name value" For example: -column_min TK_ERR 100.00
+    "-column_max     col_name value"
+    "-column_eq      col_name value"
+    "-column_str     col_name string" separate multiple filtering strings
+                                      with commas
+    "-column_str_exc col_name string" separate multiple filtering strings
+                                      with commas
 
   Required Args: -dump_row
 

met/docs/Users_Guide/gsi-tools.rst

@@ -230,7 +230,7 @@ The GSID2MPR tool writes the same set of MPR output columns for the conventional
     - PRS_MAX_WGT
     - Pressure of the maximum weighing function
 
-The gsid2mpr output may be passed to the Stat-Analysis tool to derive additional statistics. In particular, users should consider running the **aggregate_stat** job type to read MPR lines and compute partial sums (SL1L2), continuous statistics (CNT), contingency table counts (CTC), or contingency table statistics (CTS). Stat-Analysis has been enhanced to parse any extra columns found at the end of the input lines. Users can filter the values in those extra columns using the **-column_thresh** and **-column_str** job command options.
+The gsid2mpr output may be passed to the Stat-Analysis tool to derive additional statistics. In particular, users should consider running the **aggregate_stat** job type to read MPR lines and compute partial sums (SL1L2), continuous statistics (CNT), contingency table counts (CTC), or contingency table statistics (CTS). Stat-Analysis has been enhanced to parse any extra columns found at the end of the input lines. Users can filter the values in those extra columns using the **-column_thresh**, **-column_str**, and **-column_str_exc** job command options.
 
 An example of the Stat-Analysis calling sequence is shown below:
 
@@ -425,7 +425,7 @@ The GSID2MPR tool writes the same set of ORANK output columns for the convention
     - TZFND
     - d(Tz)/d(Tr)
 
-The gsidens2orank output may be passed to the Stat-Analysis tool to derive additional statistics. In particular, users should consider running the **aggregate_stat** job type to read ORANK lines and ranked histograms (RHIST), probability integral transform histograms (PHIST), and spread-skill variance output (SSVAR). Stat-Analysis has been enhanced to parse any extra columns found at the end of the input lines. Users can filter the values in those extra columns using the **-column_thresh** and **-column_str** job command options.
+The gsidens2orank output may be passed to the Stat-Analysis tool to derive additional statistics. In particular, users should consider running the **aggregate_stat** job type to read ORANK lines and ranked histograms (RHIST), probability integral transform histograms (PHIST), and spread-skill variance output (SSVAR). Stat-Analysis has been enhanced to parse any extra columns found at the end of the input lines. Users can filter the values in those extra columns using the **-column_thresh**, **-column_str**, and **-column_str_exc** job command options.
 
 An example of the Stat-Analysis calling sequence is shown below:
 

met/docs/Users_Guide/stat-analysis.rst

@@ -522,13 +522,14 @@ This job command option is extremely useful. It can be used multiple times to sp
 
 .. code-block:: none
 
-  -column_min    col_name value
-  -column_max    col_name value
-  -column_eq     col_name value
-  -column_thresh col_name thresh
-  -column_str    col_name string
-
-The column filtering options may be used when the **-line_type** has been set to a single value. These options take two arguments, the name of the data column to be used followed by a value, string, or threshold to be applied. If multiple column_min/max/eq/thresh/str options are listed, the job will be performed on their intersection. Each input line is only retained if its value meets the numeric filtering criteria defined or matches one of the strings defined by the **-column_str** option. Multiple filtering strings may be listed using commas. Defining thresholds in MET is described in :numref:`config_options`.
+  -column_min     col_name value
+  -column_max     col_name value
+  -column_eq      col_name value
+  -column_thresh  col_name thresh
+  -column_str     col_name string
+  -column_str_exc col_name string
+
+The column filtering options may be used when the **-line_type** has been set to a single value. These options take two arguments, the name of the data column to be used followed by a value, string, or threshold to be applied. If multiple column_min/max/eq/thresh/str options are listed, the job will be performed on their intersection. Each input line is only retained if its value meets the numeric filtering criteria defined, matches one of the strings defined by the **-column_str** option, or does not match any of the string defined by the **-column_str_exc** option. Multiple filtering strings may be listed using commas. Defining thresholds in MET is described in :numref:`config_options`.
 
 .. code-block:: none
 

met/docs/Users_Guide/tc-stat.rst

@@ -251,7 +251,16 @@ _________________________
   column_str_name = [];
   column_str_val  = [];
 
-The **column_str_name** and **column_str_val** fields stratify by performing string matching on non-numeric data columns. Specify a comma-separated list of columns names and values to be checked. The length of the **column_str_val** should match that of the **column_str_name**. Using the **-column_str name val** option within the job command lines may further refine these selections.
+The **column_str_name** and **column_str_val** fields stratify by performing string matching on non-numeric data columns. Specify a comma-separated list of columns names and values to be **included** in the analysis. The length of the **column_str_val** should match that of the **column_str_name**. Using the **-column_str name val** option within the job command lines may further refine these selections.
+
+_________________________
+
+.. code-block:: none
+
+  column_str_exc_name = [];
+  column_str_exc_val  = [];
+
+The **column_str_exc_name** and **column_str_exc_val** fields stratify by performing string matching on non-numeric data columns. Specify a comma-separated list of columns names and values to be **excluded** from the analysis. The length of the **column_str_exc_val** should match that of the **column_str_exc_name**. Using the **-column_str_exc name val** option within the job command lines may further refine these selections.
 
 _________________________
 
@@ -260,7 +269,7 @@ _________________________
   init_thresh_name = [];
   init_thresh_val  = [];
 
-The **init_thresh_name** and **init_thresh_val** fields stratify by applying thresholds to numeric data columns only when lead = 0. If lead =0, but the value does not meet the threshold, discard the entire track. The length of the **init_thresh_val** should match that of the **init_thresh_name**. Using the **-init_thresh name val** option within the job command lines may further refine these selections.
+The **init_thresh_name** and **init_thresh_val** fields stratify by applying thresholds to numeric data columns only when lead = 0. If lead = 0, but the value does not meet the threshold, discard the entire track. The length of the **init_thresh_val** should match that of the **init_thresh_name**. Using the **-init_thresh name val** option within the job command lines may further refine these selections.
 
 _________________________
 
@@ -269,7 +278,16 @@ _________________________
   init_str_name = [];
   init_str_val  = [];
 
-The **init_str_name** and **init_str_val** fields stratify by performing string matching on non-numeric data columns only when lead = 0. If lead =0, but the string does not match, discard the entire track. The length of the **init_str_val** should match that of the **init_str_name**. Using the **-init_str name val** option within the job command lines may further refine these selections.
+The **init_str_name** and **init_str_val** fields stratify by performing string matching on non-numeric data columns only when lead = 0. If lead = 0, but the string **does not** match, discard the entire track. The length of the **init_str_val** should match that of the **init_str_name**. Using the **-init_str name val** option within the job command lines may further refine these selections.
+
+_________________________
+
+.. code-block:: none
+
+  init_str_exc_name = [];
+  init_str_exc_val  = [];
+
+The **init_str_exc_name** and **init_str_exc_val** fields stratify by performing string matching on non-numeric data columns only when lead = 0. If lead = 0, and the string **does** match, discard the entire track. The length of the **init_str_exc_val** should match that of the **init_str_exc_name**. Using the **-init_str_exc name val** option within the job command lines may further refine these selections.
 
 _________________________
 

met/docs/conf.py

@@ -24,7 +24,7 @@
 verinfo = version
 release = f'{version}'
 release_year = '2021'
-release_date = f'{release_year}0302'
+release_date = f'{release_year}-03-31'
 copyright = f'{release_year}, {author}'
 
 # -- General configuration ---------------------------------------------------