Feature #1283 mvmode mods

docs/Users_Guide/config_options.rst

@@ -275,6 +275,7 @@ and, in some cases, elevation for all stations based on stationId.
 This set of stations comes from 2 online sources: the
 `active stations website <https://www.ndbc.noaa.gov/activestations.xml>`_
 and the `complete stations website <https://www.airnow.gov>`_.
+
 As these lists can change as a function of time, a script can be run to pull
 down the contents of both websites and merge any changes with the existing stations
 file content, creating an updated stations file locally.
@@ -301,7 +302,6 @@ can be deleted once the final output file is created.
 
 MET_BASE
 ^^^^^^^^
-
 The MET_BASE variable is defined in the code at compilation time as the path
 to the MET shared data. These are things like the default configuration files,
 common polygons and color scales. MET_BASE may be used in the MET configuration

docs/Users_Guide/mode.rst

@@ -110,9 +110,13 @@ 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.
+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 forecast and observation data *super* objects 
+
+The **multivar_logic** and **multivar_intensity** configuration entries, described in :numref:`MODE-configuration-file`, define the boolean logic for combining objects from multiple fields into *super* objects, and then optionally computing intensities for individual input fields when the input is masked to non-missing only inside the *super* objects. If the **multivar_logic** configuration option iset, there must be the same number of fields defined in an array of dictionaries for fcst and for obs as indicated in the **multivar_logic**. Note that the multi-variate MODE forecast and observation input fields and combination logic do not need to
+match. If a particular  **multivar_intensity** value is TRUE the corresponding pair of fields (fcst and obs) are masked to non-missing inside the fcst and obs super objects, and traditional mode is run on that pair of masked inputs producing uniquely named outputs. If it is FALSE, mode is not run for that pair of inputs.
+
+If all **multivar_intensity** values are FALSE, the forecast and observation *super* objects are written to NetCDF, text, and postscript output files in the standard mode output format, but with no intensity information. 
 
-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
 =====================
@@ -241,6 +245,32 @@ The **multivar_logic** entry is parsed separately from the **fcst** and **obs**
 
 _____________________
 
+.. code-block:: none
+
+   multivar_intensity = [FALSE, TRUE, TRUE];
+
+The **multivar_intensity** entry appears only in the **MODEMultivarConfig_default** file. This option is paired with the **multivar_logic** entry, and can take on a value of TRUE or FALSE for each **field**.  In the multivar case, super objects are created using the **multivar_logic** settings. For each input for which **multivar_intensity** is TRUE, the input is masked to be non-missing only within the super objects, and traditional mode is run on that masked input.  For each input for which **multivar_intensity** is FALSE, the input is skipped over.   If all the multivar_intensity values are FALSE, traditional mode output is created for the super objects, but with no intensity information.
+
+
+_____________________
+
+.. code-block:: none
+
+   multivar_name = "Precip";
+
+The **multivar_name** entry appears only in the **MODEMultivarConfig_default** file. This option is used only when the multivar option is enabled, and only when all **multivar_intensity** flag values are FALSE. It can be thought of as an identifier for the multivariate super object.  It shows up in output files names and content.  If not set the default value is "Super".   It can be set separately for forecasts and observations, or as a common value for both.
+
+
+_____________________
+
+.. code-block:: none
+
+   multivar_level = "LO";
+
+The **multivar_level** entry appears only in the **MODEMultivarConfig_default** file. This option is used only when the multivar option is enabled, and only when all **multivar_intensity** flag values are FALSE. It is the identifier for the multivariate super object as regards level.  It shows up in output files names and content.  If not set the default value is "NA".   It can be set separately for forecasts and observations, or as a common value for both.
+
+_____________________
+
 .. code-block:: none
 
   fcst = {

internal/test_unit/config/MODEConfig_multivar_fake_data

@@ -53,6 +53,11 @@ quilt = FALSE;
 //
 multivar_logic = "#1 && #2 && #3";
 
+//
+// MODE Multivar intensity logic
+//
+multivar_intensity_flag = [FALSE, FALSE, FALSE];
+
 //
 // Forecast and observation fields to be verified
 //
@@ -63,16 +68,19 @@ fcst = {
       {
          name  = "ALPHA";
          level = "(*,*)";
+         merge_flag = NONE;
       }, 
 
       {
          name  = "BETA";
          level = "(*,*)";
+         merge_flag = NONE;
       }, 
 
       {
          name  = "GAMMA";
          level = "(*,*)";
+         merge_flag = NONE;
       }
 
    ];
@@ -84,6 +92,8 @@ fcst = {
    filter_attr_thresh = [];
    merge_thresh       = >=3.5;
    merge_flag         = NONE;
+   multivar_name = "Super";
+   multivar_level = "LO";
 }
 obs = fcst;
 
@@ -97,12 +107,12 @@ mask_missing_flag = NONE;
 //
 // Match objects between the forecast and observation fields
 //
-match_flag = NONE;
+match_flag = MERGE_BOTH;
 
 //
 // Maximum centroid distance for objects to be compared
 //
-max_centroid_dist = 800.0/grid_res;
+max_centroid_dist = 800.0;
 
 ////////////////////////////////////////////////////////////////////////////////
 

internal/test_unit/config/MODEConfig_multivar_fake_data_with_intensities

@@ -0,0 +1,269 @@
+////////////////////////////////////////////////////////////////////////////////
+//
+// 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 = "PRECIP";
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// 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";
+
+//
+// MODE Multivar intensity logic
+//
+multivar_intensity_flag = [TRUE, TRUE, TRUE];
+
+//
+// Forecast and observation fields to be verified
+//
+fcst = {
+
+   field = [
+
+      {
+         name  = "ALPHA";
+         level = "(*,*)";
+         merge_flag = NONE;
+      }, 
+
+      {
+         name  = "BETA";
+         level = "(*,*)";
+         merge_flag = NONE;
+      }, 
+
+      {
+         name  = "GAMMA";
+         level = "(*,*)";
+         merge_flag = NONE;
+      }
+
+   ];
+
+   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;
+   multivar_name = "Super";
+   multivar_level = "LO";
+}
+obs = fcst;
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// Handle missing data
+//
+mask_missing_flag = NONE;
+
+//
+// Match objects between the forecast and observation fields
+//
+match_flag = MERGE_BOTH;
+
+//
+// Maximum centroid distance for objects to be compared
+//
+max_centroid_dist = 800.0;
+
+////////////////////////////////////////////////////////////////////////////////
+
+//
+// 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    = 25.4;
+}
+
+obs_raw_plot = {
+   color_table = "MET_BASE/colortables/met_default.ctable";
+   plot_min    = 0.0;
+   plot_max    = 25.4;
+}
+
+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        = "V11.1.0";
+
+////////////////////////////////////////////////////////////////////////////////