Merge remote-tracking branch 'origin/develop' into feature_1581_api_p…

…oint_obs

.github/workflows/main.yml

@@ -0,0 +1,50 @@
+name: MET CI/CD Workflow
+on:
+  push:
+    branches:
+      - develop
+      - develop-ref
+      - feature_*
+      - main_*
+      - bugfix_*
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  documentation:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.6'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade python-dateutil requests sphinx \
+          sphinx-gallery Pillow sphinx_rtd_theme
+      - name: Build docs
+        continue-on-error: true
+        run: |
+          DOCS_DIR=${GITHUB_WORKSPACE}/met/docs
+          cd ${DOCS_DIR}
+          make clean html
+          cd ${GITHUB_WORKSPACE}
+          warning_file=${DOCS_DIR}/_build/warnings.log
+          mkdir -p artifact/documentation
+          cp -r ${DOCS_DIR}/_build/html/* artifact/documentation
+          if [ -s $warning_file ]; then
+            cp -r ${DOCS_DIR}/_build/warnings.log artifact/doc_warnings.log
+            cp artifact/doc_warnings.log artifact/documentation
+          else
+            rm ${warning_file}
+          fi
+      - uses: actions/upload-artifact@v2
+        with:
+          name: documentation
+          path: artifact/documentation
+      - uses: actions/upload-artifact@v2
+        with:
+          name: documentation_warnings.log
+          path: artifact/doc_warnings.log
+          if-no-files-found: ignore

met/data/config/GridStatConfig_default

@@ -43,6 +43,8 @@ regrid = {
 //
 censor_thresh       = [];
 censor_val          = [];
+mpr_column          = [];
+mpr_thresh          = [];
 cat_thresh          = [];
 cnt_thresh          = [ NA ];
 cnt_logic           = UNION;

met/data/config/PointStatConfig_default

@@ -38,6 +38,8 @@ regrid = {
 //
 censor_thresh  = [];
 censor_val     = [];
+mpr_column     = [];
+mpr_thresh     = [];
 cat_thresh     = [ NA ];
 cnt_thresh     = [ NA ];
 cnt_logic      = UNION;

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/Makefile

@@ -21,4 +21,5 @@ clean:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	[ -d $(BUILDDIR) ] || mkdir -p $(BUILDDIR)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -w "$(BUILDDIR)/warnings.log"

met/docs/Users_Guide/config_options.rst

@@ -640,12 +640,12 @@ to be verified. This dictionary may include the following entries:
     metadata of any output files, but the user can set the "desc" entry
     accordingly.
 
-    Examples of user-defined conversion functions include:
+    Examples of user-defined data censoring operations include:
 
     .. code-block:: none
 		    
       censor_thresh = [ >12000 ];
-      censor_val    = [ 12000 ];
+      censor_val    = [  12000 ];
 
   * Several configuration options are provided to override and correct the
     metadata read from the input file. The supported options are listed
@@ -678,6 +678,25 @@ to be verified. This dictionary may include the following entries:
       is_wind_direction    = boolean;
       is_prob              = boolean;
 
+  * The "mpr_column" and "mpr_thresh" entries are arrays of strings and
+    thresholds to specify which matched pairs should be included in the
+    statistics. These options apply to the Point-Stat and Grid-Stat tools.
+    They are parsed seperately for each "obs.field" array entry.
+    The "mpr_column" strings specify MPR column names ("FCST", "OBS",
+    "CLIMO_MEAN", "CLIMO_STDEV", or "CLIMO_CDF"), differences of columns
+    ("FCST-OBS"), or the absolute value of those differences ("ABS(FCST-OBS)").
+    The number of "mpr_thresh" thresholds must match the number of "mpr_column"
+    entries, and the n-th threshold is applied to the n-th column. Any matched
+    pairs which do not meet any of the specified thresholds are excluded from
+    the analysis. For example, the following settings exclude matched pairs
+    where the observation value differs from the forecast or climatological
+    mean values by more than 10:
+
+    .. code-block:: none
+
+      mpr_column = [ "ABS(OBS-FCST)", "ABS(OBS-CLIMO_MEAN)" ];
+      mpr_thresh = [ <=10, <=10 ];
+
   * The "cat_thresh" entry is an array of thresholds to be used when
     computing categorical statistics.
 
@@ -981,6 +1000,8 @@ or
    obs = {
      censor_thresh = [];
      censor_val    = [];
+     mpr_column    = [];
+     mpr_thresh    = [];
      cnt_thresh    = [ NA ];
      cnt_logic     = UNION;
      wind_thresh   = [ NA ];
@@ -3748,17 +3769,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/grid-stat.rst

@@ -221,13 +221,15 @@ __________________________
                      type = [ { method = NEAREST; width = 1; } ]; }
   censor_thresh  = [];
   censor_val     = [];
+  mpr_column     = [];
+  mpr_thresh     = [];
   eclv_points    = 0.05;
   rank_corr_flag = TRUE;
   tmp_dir        = "/tmp";
   output_prefix  = "";
   version        = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
+The configuration options listed above are common to multiple MET tools and are described in :numref:`config_options`.
 
 ___________________________
 

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/point-stat.rst

@@ -334,6 +334,8 @@ ________________________
                      type = [ { method = NEAREST; width = 1; } ]; }
   censor_thresh  = [];
   censor_val     = [];
+  mpr_column     = [];
+  mpr_thresh     = [];
   eclv_points    = 0.05;
   rank_corr_flag = TRUE;
   sid_inc        = [];
@@ -347,7 +349,7 @@ ________________________
   output_prefix  = "";
   version        = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
+The configuration options listed above are common to multiple MET tools and are described in :numref:`config_options`.
 
 _________________________
 

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

@@ -53,8 +53,6 @@
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = ["_themes", ]
 html_js_files = ['pop_ver.js']
-html_theme_options = {'canonical_url': 'https://dtcenter.github.io/MET/latest/'}
-html_theme_options['versions'] = {'latest': '../latest', 'develop': '../develop'}
 html_css_files = ['theme_override.css']
 
 # Add any paths that contain custom static files (such as style sheets) here,