Update develop-ref after #2088 and #2093

.github/workflows/testing.yml

@@ -148,7 +148,7 @@ jobs:
       matrix:
         tests:
           - 'ascii2nc_indy pb2nc_indy tc_dland tc_pairs tc_stat plot_tc tc_rmw rmw_analysis tc_gen'
-          - 'met_test_scripts mode_graphics mtd regrid airnow gsi_tools netcdf modis series_analysis gen_ens_prod wwmca_regrid gen_vx_mask grid_weight interp_shape grid_diag grib_tables lidar2nc shift_data_plane trmm2nc aeronet wwmca_plot ioda2nc gaussian'
+          - 'met_test_scripts mode_multivar mode_graphics mtd regrid airnow gsi_tools netcdf modis series_analysis gen_ens_prod wwmca_regrid gen_vx_mask grid_weight interp_shape grid_diag grib_tables lidar2nc shift_data_plane trmm2nc aeronet wwmca_plot ioda2nc gaussian'
       fail-fast: false
     steps:
       - uses: actions/checkout@v2

met/Make-include

@@ -34,6 +34,7 @@ MET_CPPFLAGS = -I${top_builddir}/src/basic/vx_cal \
 	     -I${top_builddir}/src/libcode/vx_solar \
 	     -I${top_builddir}/src/libcode/vx_statistics \
 	     -I${top_builddir}/src/libcode/vx_stat_out \
+	     -I${top_builddir}/src/libcode/vx_bool_calc \
 	     -I${top_builddir}/src/libcode/vx_summary \
 	     -I${top_builddir}/src/libcode/vx_time_series \
 	     -I${top_builddir}/src/libcode/vx_series_data \
@@ -73,6 +74,7 @@ MET_LDFLAGS = -L${top_builddir}/src/basic/vx_cal \
 	     -L${top_builddir}/src/libcode/vx_pxm \
 	     -L${top_builddir}/src/libcode/vx_render \
 	     -L${top_builddir}/src/libcode/vx_regrid \
+	     -L${top_builddir}/src/libcode/vx_bool_calc \
 	     -L${top_builddir}/src/libcode/vx_shapedata \
 	     -L${top_builddir}/src/libcode/vx_solar \
 	     -L${top_builddir}/src/libcode/vx_statistics \

met/configure.ac

@@ -1240,6 +1240,7 @@ AC_CONFIG_FILES([Makefile
                  src/libcode/vx_summary/Makefile
                  src/libcode/vx_python3_utils/Makefile
                  src/libcode/vx_data2d_python/Makefile
+                 src/libcode/vx_bool_calc/Makefile
                  src/libcode/vx_pointdata_python/Makefile
                  src/tools/Makefile
                  src/tools/core/Makefile

met/data/config/MODEConfig_default

@@ -25,7 +25,6 @@ obtype = "ANALYS";
 
 //
 // Verification grid
-// May be set separately in each "field" entry
 //
 regrid = {
    to_grid    = NONE;

met/data/config/MODEMultivarConfig_default

@@ -0,0 +1,259 @@
+////////////////////////////////////////////////////////////////////////////////
+//
+// MODE configuration file.
+//
+// For additional information, please see the MET User's Guide.
+//
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Output model name to be written
+//
+model = "WRF";
+
+//
+// Output description to be written
+//
+desc = "NA";
+
+//
+// Output observation type to be written
+//
+obtype = "ANALYS";
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Verification grid
+//
+regrid = {
+   to_grid    = NONE;
+   method     = NEAREST;
+   width      = 1;
+   vld_thresh = 0.5;
+   shape      = SQUARE;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Approximate grid resolution (km)
+//
+grid_res = 20;
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Run all permutations of radius and threshold
+//
+quilt = FALSE;
+
+//
+// MODE Multivar boolean combination logic
+//
+multivar_logic = "#1 && #2 && #3";
+
+//
+// Forecast and observation fields to be verified
+//
+fcst = {
+
+   field = [
+
+      {
+         name  = "ALPHA";
+         level = "(*,*)";
+      }, 
+
+      {
+         name  = "BETA";
+         level = "(*,*)";
+      }, 
+
+      {
+         name  = "GAMMA";
+         level = "(*,*)";
+      }
+
+   ];
+
+   conv_radius        = 2; // in grid squares
+   conv_thresh        = >=5.0;
+   vld_thresh         = 0.5;
+   filter_attr_name   = [];
+   filter_attr_thresh = [];
+   merge_thresh       = >=3.5;
+   merge_flag         = NONE;
+}
+obs = fcst;
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Handle missing data
+//
+mask_missing_flag = NONE;
+
+//
+// Match objects between the forecast and observation fields
+//
+match_flag = NONE;
+
+//
+// Maximum centroid distance for objects to be compared
+//
+max_centroid_dist = 800.0/grid_res;
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Verification masking regions
+//
+mask = {
+   grid      = "";
+   grid_flag = NONE; // Apply to NONE, FCST, OBS, or BOTH
+   poly      = "";
+   poly_flag = NONE; // Apply to NONE, FCST, OBS, or BOTH
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Fuzzy engine weights
+//
+weight = {
+   centroid_dist    = 2.0;
+   boundary_dist    = 4.0;
+   convex_hull_dist = 0.0;
+   angle_diff       = 1.0;
+   aspect_diff      = 0.0;
+   area_ratio       = 1.0;
+   int_area_ratio   = 2.0;
+   curvature_ratio  = 0.0;
+   complexity_ratio = 0.0;
+   inten_perc_ratio = 0.0;
+   inten_perc_value = 50;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Fuzzy engine interest functions
+//
+interest_function = {
+
+   centroid_dist = (
+      (            0.0, 1.0 )
+      (  60.0/grid_res, 1.0 )
+      ( 600.0/grid_res, 0.0 )
+   );
+
+   boundary_dist = (
+      (            0.0, 1.0 )
+      ( 400.0/grid_res, 0.0 )
+   );
+
+   convex_hull_dist = (
+      (            0.0, 1.0 )
+      ( 400.0/grid_res, 0.0 )
+   );
+
+   angle_diff = (
+      (  0.0, 1.0 )
+      ( 30.0, 1.0 )
+      ( 90.0, 0.0 )
+   );
+
+   aspect_diff = (
+      (  0.00, 1.0 )
+      (  0.10, 1.0 )
+      (  0.75, 0.0 )
+   );
+
+   corner   = 0.8;
+   ratio_if = (
+      (    0.0, 0.0 )
+      ( corner, 1.0 )
+      (    1.0, 1.0 )
+   );
+
+   area_ratio = ratio_if;
+
+   int_area_ratio = (
+      ( 0.00, 0.00 )
+      ( 0.10, 0.50 )
+      ( 0.25, 1.00 )
+      ( 1.00, 1.00 )
+   );
+
+   curvature_ratio = ratio_if;
+
+   complexity_ratio = ratio_if;
+
+   inten_perc_ratio = ratio_if;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Total interest threshold for determining matches
+//
+total_interest_thresh = 0.7;
+
+//
+// Interest threshold for printing output pair information
+//
+print_interest_thresh = 0.0;
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Plotting information
+//
+met_data_dir = "MET_BASE";
+
+fcst_raw_plot = {
+   color_table = "MET_BASE/colortables/met_default.ctable";
+   plot_min    = 0.0;
+   plot_max    = 0.0;
+}
+
+obs_raw_plot = {
+   color_table = "MET_BASE/colortables/met_default.ctable";
+   plot_min    = 0.0;
+   plot_max    = 0.0;
+}
+
+object_plot = {
+   color_table = "MET_BASE/colortables/mode_obj.ctable";
+}
+
+//
+// Boolean for plotting on the region of valid data within the domain
+//
+plot_valid_flag = FALSE;
+
+//
+// Plot polyline edges using great circle arcs instead of straight lines
+//
+plot_gcarc_flag = FALSE;
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// NetCDF matched pairs, PostScript, and contingency table output files
+//
+ps_plot_flag    = TRUE;
+nc_pairs_flag   = TRUE;
+ct_stats_flag   = TRUE;
+
+////////////////////////////////////////////////////////////////////////////////
+
+shift_right = 0;   //  grid squares
+
+////////////////////////////////////////////////////////////////////////////////
+
+output_prefix  = "";
+version        = "V10.1.0";
+
+////////////////////////////////////////////////////////////////////////////////

met/data/config/Makefile.am

@@ -30,6 +30,7 @@ config_DATA = \
 	Madis2NcConfig_default \
 	MODEAnalysisConfig_default \
 	MODEConfig_default \
+	MODEMultivarConfig_default \
 	MTDConfig_default \
 	PB2NCConfig_default \
 	PointStatConfig_default \

met/docs/Users_Guide/mode.rst

@@ -103,10 +103,21 @@ Summary statistics
 
 Once MODE has been run, summary statistics are written to an output file. These files contain information about all single and cluster objects and their attributes. Total interest for object pairs is also output, as are percentiles of intensity inside the objects. The output file is in a simple flat ASCII tabular format (with one header line) and thus should be easily readable by just about any programming language, scripting language, or statistics package. Refer to :numref:`MODE-output` for lists of the statistics included in the MODE output files. Example scripts will be posted on the MET website in the future.
 
+.. _MODE-multivar:
+
+Multi-Variate MODE
+------------------
+
+Traditionally, MODE defines objects by smoothing and thresholding data from a single input field. MET version 10.1.0 extends MODE by adding the option to define objects using multiple input fields.
+
+As described in :numref:`MODE-configuration-file`, the **field** entry in the forecast and observation dictionaries define the input data to be processed. If **field** is defined as a dictionary, the traditional method for running MODE is invoked, where objects are defined using a single input field. If **field** is defined as an array of dictionaries, each specifying a different input field, then the multi-variate MODE logic is invoked and requires the **multivar_logic** configuration entry to be set. Traditional MODE is run once for each input field to define objects for that field. Note that the object definition criteria can be defined separately for each field array entry. The objects from each input field are combined into a *super* object for both the forecast and observation data.
+
+The **multivar_logic** configuration entry, described in :numref:`MODE-configuration-file`, defines the boolean logic for combining objects from multiple fields into a *super* object. If this configuration option is set, there must be an equal or greater number of fields defined in an array of dictionaries for it define a *super* object of more than one field. Note that the multi-variate MODE forecast and observation input fields and combination logic do not need to match. The resulting forecast and observation *super* objects are written to NetCDF output files. Users can then configure and run traditional MODE to compare the forecast super object to the observed super object.
+
 Practical information
 =====================
 
-This section contains a description of how MODE can be configured and run. The MODE tool is used to perform a features-based verification of gridded model data using gridded observations. The input gridded model and observation datasets must be in one of the MET supported gridded file formats. The requirement of having all gridded fields using the same grid specification has been removed with METv5.1. The Grid-Stat tool performs no interpolation when the input model, observation, and climatology datasets must be on a common grid. MET will interpolate these files to a common grid if one is specified. There is a regrid option in the configuration file that allows the user to define the grid upon which the scores will be computed. The gridded analysis data may be based on observations, such as Stage II or Stage IV data for verifying accumulated precipitation, or a model analysis field may be used. However, users are cautioned that it is generally unwise to verify model output using an analysis field produced by the same model.
+This section contains a description of how MODE can be configured and run. The MODE tool is used to perform a features-based verification of gridded model data using gridded observations. The input gridded model and observation datasets must be in one of the MET supported gridded file formats. If the input datasets are not already on a common grid, MODE can interpolate them to a common grid. The regrid option in the configuration file enables the user to specify the grid upon which the scores will be computed. The gridded analysis data may be based on observations, such as Stage II or Stage IV data for verifying accumulated precipitation, or a model analysis field may be used. However, users are cautioned that it is generally unwise to verify model output using an analysis field produced by the same model.
 
 MODE provides the capability to select a single model variable/level from which to derive objects to be analyzed. MODE was developed and tested using accumulated precipitation. However, the code has been generalized to allow the use of any gridded model and observation field. Based on the options specified in the configuration file, MODE will define a set of simple objects in the model and observation fields. It will then compute an interest value for each pair of objects across the fields using a fuzzy engine approach. Those interest values are thresholded, and any pairs of objects above the threshold will be matched/merged. Through the configuration file, MODE offers a wide range of flexibility in how the objects are defined, processed, matched, and merged.
 
@@ -198,7 +209,6 @@ _____________________
 
 The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
 
-
 _____________________
 
 .. code-block:: none
@@ -221,6 +231,16 @@ The **quilt** entry indicates whether all permutations of convolution radii and
 
 _____________________
 
+.. code-block:: none
+
+   multivar_logic = "#1 && #2 && #3";
+
+The **multivar_logic** entry appears only in the **MODEMultivarConfig_default** file. This option applies to running multi-variate MODE by setting **field** to an array of dictionaries to define multiple input fields. Objects are defined separately for each input field based on the configuration settings specified for each field array entry. The **multivar_logic** entry is a string which defines how objects for each field are combined into a final *super* object. The objects for each field are referred to as '#N' where N is the N-th field array entry. The '&&' and '||' strings define intersection and union logic, respectively. For example, "#1 && #2" is the intersection of the objects from the first and second fields. "(#1 && #2) || #3" is the union of that intersection with the objects from the third field.
+
+The **multivar_logic** entry is parsed separately from the **fcst** and **obs** dictionaries and can be defined differently in each.
+
+_____________________
+
 .. code-block:: none
 
   fcst = {
@@ -242,6 +262,8 @@ _____________________
 
 The **field** entries in the forecast and observation dictionaries specify the model and observation variables and level to be compared. See a more complete description of them in :numref:`config_options`. In the above example, the forecast settings are copied into the observation dictionary using **obs = fcst;.**
 
+When **field** is set to an array of dictionaries rather than a single one, the multi-variate MODE logic is invoked. Please see :numref:`MODE-multivar` for a description of that logic.
+
 The **censor_thresh** and **censor_val** entries are used to censor the raw data as described in :numref:`config_options`. Their functionality replaces the **raw_thresh** entry, which is deprecated in met-6.1. Prior to defining objects, it is recommended that the raw fields should be made to look similar to each other. For example, if the model only predicts values for a variable above some threshold, the observations should be thresholded at that same level. The censor thresholds can be specified using symbols. By default, no censor thresholding is applied.
 
 The **conv_radius** entry defines the radius of the circular convolution applied to smooth the raw fields. The radii are specified in terms of grid units. The default convolution radii are defined in terms of the previously defined **grid_res** entry. Multiple convolution radii may be specified as an array (e.g. **conv_radius = [ 5, 10, 15 ];**).