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

…qube_code_smell

.github/workflows/update_truth.yml

@@ -0,0 +1,59 @@
+name: Update Truth Data
+
+on:
+  workflow_dispatch:
+    inputs:
+      pull_requests:
+        description: 'Pull request(s) that warranted update, e.g. "#123" or "#123 and dtcenter/MET#123"'
+        required: true
+      change_summary:
+        description: 'Summary of changes to truth data'
+        required: true
+
+jobs:
+  update_truth:
+    name: "Update or create truth reference branch"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if branch is develop or main_vX.Y
+        run: |
+          branch_name=${GITHUB_REF#refs/heads/}
+          echo "branch_name=$branch_name" >> $GITHUB_ENV
+          if [[ $branch_name == "develop" ]] || \
+             [[ $branch_name =~ ^main_v[0-9]+\.[0-9]+$ ]]; then
+            echo Branch is valid - $branch_name
+            exit 0
+          fi
+          echo ERROR: Branch is $branch_name - must be develop or match main_vX.Y
+          exit 1
+      - uses: actions/checkout@v3
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.METPLUS_BOT_TOKEN }}
+      - name: Resolve conflicts between branch and branch-ref
+        run: |
+          branch_name=${{ env.branch_name }}
+          cd ${GITHUB_WORKSPACE}
+          if [[ -z "$(git ls-remote --heads origin ${branch_name}-ref)" ]]; then
+            echo ERROR: ${branch_name}-ref does not exist
+            exit 1
+          fi
+          
+          echo ${branch_name}-ref does exist -- update it
+          git config --global user.name "metplus-bot"
+          git config --global user.email "[email protected]"
+          echo git checkout ${branch_name}
+          git checkout ${branch_name}
+          echo git merge -s ours origin/${branch_name}-ref
+          git merge -s ours origin/${branch_name}-ref
+          echo git push origin ${branch_name}
+          git push origin ${branch_name}
+
+      - name: Create Pull Request
+        run: gh pr create --base $BASE --body "$BODY" --title "$TITLE"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BASE: ${{ env.branch_name }}-ref
+          BODY: ${{ github.event.inputs.change_summary }}<br/>Created by @${{ github.actor}}
+          TITLE: Update ${{ env.branch_name }}-ref after ${{ github.event.inputs.pull_requests }}

.readthedocs.yaml

@@ -9,10 +9,14 @@ version: 2
 #formats: all
 formats: [pdf]
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
 # Optionally set the version of Python and requirements required to build your
 # docs
 python:
-   version: 3.8
    install:
    - requirements: docs/requirements.txt
 

README.md

@@ -9,3 +9,5 @@ Model Evaluation Tools (MET) Repository
 This repository contains the source code for the Model Evaluation Tools package.
 
 Please see the [MET website](https://dtcenter.org/community-code/model-evaluation-tools-met) and the [MET User's Guide](https://met.readthedocs.io/en/latest) for more information. Support for the METplus components is provided through the [METplus Discussions](https://github.com/dtcenter/METplus/discussions) forum. Users are welcome and encouraged to answer or address each other's questions there! For more information, please read "[Welcome to the METplus Components Discussions](https://github.com/dtcenter/METplus/discussions/939)".
+
+For information about the support provided for releases, see our [Release Support Policy](https://metplus.readthedocs.io/en/develop/Release_Guide/index.html#release-support-policy).

configure

@@ -6051,6 +6051,9 @@ fi
 
 CPPFLAGS=$CPPFLAGS' -DMET_BASE="\"$(pkgdatadir)\""'
 
+# Add -std=c++11 to CXXFLAGS
+CXXFLAGS=$CXXFLAGS' -std=c++11'
+
 # Define other variables for the makefiles
 
 FC_LIBS=-lgfortran

configure.ac

@@ -1086,6 +1086,9 @@ AM_CONDITIONAL([ENABLE_DEVELOPMENT], [test -n "$MET_DEVELOPMENT"])
 
 CPPFLAGS=$CPPFLAGS' -DMET_BASE="\"$(pkgdatadir)\""'
 
+# Add -std=c++11 to CXXFLAGS                                                                                                                                                 
+CXXFLAGS=$CXXFLAGS' -std=c++11'
+
 # Define other variables for the makefiles
 
 AC_SUBST(FC_LIBS, [-lgfortran])

docs/Users_Guide/appendixB.rst

@@ -25,6 +25,8 @@ The following map projections are currently supported in MET:
 
 * Semi Lat/Lon
 
+.. _App_B-grid_specification_strings:
+
 Grid Specification Strings
 ==========================
 

docs/Users_Guide/appendixC.rst

@@ -248,25 +248,16 @@ Heidke Skill Score (HSS)
 
 Called "HSS" in CTS output :numref:`table_PS_format_info_CTS` and "HSS" in MCTS output :numref:`table_PS_format_info_MCTS`
 
-HSS is a skill score based on Accuracy, where the Accuracy is corrected by the number of correct forecasts that would be expected by chance. In particular, 
+HSS is a skill score based on Accuracy, where the Accuracy is compared to the number of correct forecasts that would be expected by chance. In particular, 
 
 .. math:: \text{HSS } = \frac{n_{11} + n_{00} - C_2}{T - C_2},
 
 where
 
 .. math:: C_2 = \frac{(n_{11} + n_{10}) (n_{11} + n_{01}) + (n_{01} + n_{00}) (n_{10} + n_{00})}{T}.
 
-A more general format that uses percentages is provided by Ou (:ref:`Ou, 2016 <Ou-2016>`),
-
-.. only:: latex
-
-  .. math:: \text{HSS(\%) } = 100 \ast \frac{(H - E)}{(T - E)}
-
-.. only:: html
-
-  .. math:: \text{HSS(%) } = 100 \ast \frac{(H - E)}{(T - E)}
-
-where H is the number of forecasts in the correct category and E is the expected number of forecasts by chance.
+Note that the C_2 value is calculated based on the data fields supplied by the user. Therefore, for C2 to appropriately represent a random forecast, 
+a sufficiently large sized dataset of forecasts and observations would be needed.
 
 HSS can range from minus infinity to 1. A perfect forecast would have HSS = 1.
 
@@ -275,11 +266,13 @@ Heidke Skill Score - Expected Correct (HSS_EC)
 
 Called "HSS_EC" in CTS output :numref:`table_PS_format_info_CTS` and MCTS output :numref:`table_PS_format_info_MCTS`
 
-HSS_EC is a skill score based on Accuracy, where the Accuracy is corrected by the number of correct forecasts that would be expected by chance. In particular,
+HSS_EC calculates the HSS as described above, but with a C2 value based on a set expected chance (EC) value. 
+Instead of C2 being calculated by the user’s dataset, 
 
-.. math:: \text{HSS } = \frac{n_{11} + n_{00} - C_2}{T - C_2},
+.. math:: \text{HSS } = \text{T*EC },
 
-The C_2 value is user-configurable with a default value of T divided by the number of contingency table categories.
+where EC is allowed to be prescribed by the user ranging from 0 to 1. By default the EC is set to 1 divided by the number of contingency table categories, 
+e.g. EC is set to 0.33333 for a 3 category (tercile) forecast and 0.5 for a two category (binary) forecast. 
 
 HSS_EC can range from minus infinity to 1. A perfect forecast would have HSS_EC = 1.
 

docs/Users_Guide/config_options.rst

@@ -1541,6 +1541,8 @@ Point-Stat and Ensemble-Stat, the reference time is the forecast valid time.
      end =  5400;
   }
 
+.. _config_options-mask:
+
 mask
 ^^^^
 
@@ -1562,14 +1564,26 @@ in the following ways:
 
 * The "poly" entry contains a comma-separated list of files that define
   verification masking regions. These masking regions may be specified in
-  two ways: as a lat/lon polygon or using a gridded data file such as the
-  NetCDF output of the Gen-Vx-Mask tool.
+  two ways: in an ASCII file containing lat/lon points defining the mask polygon,
+  or using a gridded data file such as the NetCDF output of the Gen-Vx-Mask tool.
+  Some details for each of these options are described below:
+
+  * If providing an ASCII file containing the lat/lon points defining the mask
+    polygon, the file must contain a name for the region followed by the latitude
+    (degrees north) and longitude (degrees east) for each vertex of the polygon.
+    The values are separated by whitespace (e.g. spaces or newlines), and the
+    first and last polygon points are connected.
+    The general form is "poly_name lat1 lon1 lat2 lon2... latn lonn".
+    Here is an example of a rectangle consisting of 4 points:
+
+    .. code-block:: none
+       :caption: ASCII Rectangle Polygon Mask
 
-  * An ASCII file containing a lat/lon polygon.
-    Latitude in degrees north and longitude in degrees east.
-    The first and last polygon points are connected.
-    For example, "MET_BASE/poly/EAST.poly" which consists of n points:
-    "poly_name lat1 lon1 lat2 lon2... latn lonn"
+       RECTANGLE
+       25  -120
+       55  -120
+       55   -70
+       25   -70
 
     Several masking polygons used by NCEP are predefined in the
     installed *share/met/poly* directory. Creating a new polygon is as
@@ -1582,7 +1596,8 @@ in the following ways:
     observation point falls within the polygon defined is done in x/y
     grid space.
 
-  * The NetCDF output of the gen_vx_mask tool.
+  * The NetCDF output of the gen_vx_mask tool. Please see :numref:`masking`
+    for more details.
 
   * Any gridded data file that MET can read may be used to define a
     verification masking region. Users must specify a description of the
@@ -1591,7 +1606,7 @@ in the following ways:
     applied, any grid point where the resulting field is 0, the mask is
     turned off. Any grid point where it is non-zero, the mask is turned
     on.
-    For example,  "sample.grib {name = \"TMP\"; level = \"Z2\";} >273"
+    For example, "sample.grib {name = \"TMP\"; level = \"Z2\";} >273"
 
 * The "sid" entry is an array of strings which define groups of
   observation station ID's over which to compute statistics. Each entry
@@ -2391,7 +2406,7 @@ are empty. Note: grib_code 11 is equivalent to obs_var "TMP".
 Settings specific to individual tools
 -------------------------------------
 
-EnsembleStatConfig_default
+GenEnsProdConfig_default
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ens
@@ -2486,6 +2501,64 @@ combination of the categorical threshold (cat_thresh), neighborhood width
      ];
   }
 
+ensemble_flag
+"""""""""""""
+
+The "ensemble_flag" entry is a dictionary of boolean value indicating
+which ensemble products should be generated:
+
+* "latlon" for a grid of the Latitude and Longitude fields
+
+* "mean" for the simple ensemble mean
+
+* "stdev" for the ensemble standard deviation
+
+* "minus" for the mean minus one standard deviation
+
+* "plus" for the mean plus one standard deviation
+
+* "min" for the ensemble minimum
+
+* "max" for the ensemble maximum
+
+* "range" for the range of ensemble values
+
+* "vld_count" for the number of valid ensemble members
+
+* "frequency" for the ensemble relative frequency meeting a threshold
+
+* "nep" for the neighborhood ensemble probability
+
+* "nmep" for the neighborhood maximum ensemble probability
+
+* "rank" to write the rank for the gridded observation field to separate
+  NetCDF output file.
+
+* "weight" to write the grid weights specified in grid_weight_flag to the
+  rank NetCDF output file.
+
+.. code-block:: none
+		
+  ensemble_flag = {
+    latlon     = TRUE;
+     mean      = TRUE;
+     stdev     = TRUE;
+     minus     = TRUE;
+     plus      = TRUE;
+     min       = TRUE;
+     max       = TRUE;
+     range     = TRUE;
+     vld_count = TRUE;
+     frequency = TRUE;
+     nep       = FALSE;
+     nmep      = FALSE;
+     rank      = TRUE;
+     weight    = FALSE;
+  }
+  
+EnsembleStatConfig_default
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 fcst, obs
 """""""""
 
@@ -2628,58 +2701,6 @@ levels, and range of values.
      max              = NA;
   }
 
-ensemble_flag
-"""""""""""""
-
-The "ensemble_flag" entry is a dictionary of boolean value indicating
-which ensemble products should be generated:
-
-* "mean" for the simple ensemble mean
-
-* "stdev" for the ensemble standard deviation
-
-* "minus" for the mean minus one standard deviation
-
-* "plus" for the mean plus one standard deviation
-
-* "min" for the ensemble minimum
-
-* "max" for the ensemble maximum
-
-* "range" for the range of ensemble values
-
-* "vld_count" for the number of valid ensemble members
-
-* "frequency" for the ensemble relative frequency meeting a threshold
-
-* "nep" for the neighborhood ensemble probability
-
-* "nmep" for the neighborhood maximum ensemble probability
-
-* "rank" to write the rank for the gridded observation field to separate
-  NetCDF output file.
-
-* "weight" to write the grid weights specified in grid_weight_flag to the
-  rank NetCDF output file.
-
-.. code-block:: none
-		
-  ensemble_flag = {
-     mean      = TRUE;
-     stdev     = TRUE;
-     minus     = TRUE;
-     plus      = TRUE;
-     min       = TRUE;
-     max       = TRUE;
-     range     = TRUE;
-     vld_count = TRUE;
-     frequency = TRUE;
-     nep       = FALSE;
-     nmep      = FALSE;
-     rank      = TRUE;
-     weight    = FALSE;
-  }
-
 rng
 """
 

docs/Users_Guide/installation.rst

@@ -21,6 +21,8 @@ Programming Languages
 
 The MET package, including MET-TC, is written primarily in C/C++ in order to be compatible with an extensive verification code base in C/C++ already in existence. In addition, the object-based MODE and MODE-TD verification tools rely heavily on the object-oriented aspects of C++. Knowledge of C/C++ is not necessary to use the MET package. The MET package has been designed to be highly configurable through the use of ASCII configuration files, enabling a great deal of flexibility without the need for source code modifications.
 
+With the release of MET-11.1.0, C++11 is now the minimum required version of the C++ programming language standard.
+
 NCEP's BUFRLIB is written entirely in Fortran. The portion of MET that handles the interface to the BUFRLIB for reading PrepBUFR point observation files is also written in Fortran.
 
 The MET package is intended to be a tool for the modeling community to use and adapt. As users make upgrades and improvements to the tools, they are encouraged to offer those upgrades to the broader community by offering feedback to the developers.