Feature #2152 poly_xy (#2154)

met/docs/Users_Guide/masking.rst

@@ -46,7 +46,7 @@ Required arguments for gen_vx_mask
 
 2. The **mask_file** argument defines the masking information, see below.
 
-• For "poly", "box", "circle", and "track" masking, specify an ASCII Lat/Lon file.
+• For "poly", "poly_xy", "box", "circle", and "track" masking, specify an ASCII Lat/Lon file.
 
 • For "grid" and "data" masking, specify a gridded data file.
 
@@ -81,7 +81,7 @@ Optional arguments for gen_vx_mask
 
 • For "lat" and "lon" masking, threshold the latitude and longitude values. 
 
-10. The **-height n** and **-width n** options set the size in grid units for "box"masking.
+10. The **-height n** and **-width n** options set the size in grid units for "box" masking.
 
 11. The **-shapeno n** option is only used for shapefile masking. (See description of shapefile masking below).
 
@@ -97,25 +97,27 @@ Optional arguments for gen_vx_mask
 
 The Gen-Vx-Mask tool supports the following types of masking region definition selected using the **-type** command line option:
 
-1. Polyline (**poly**) masking reads an input ASCII file containing Lat/Lon locations, connects the first and last points, and selects grid points falling inside that polyline. This option is useful when defining geographic subregions of a domain.
+1. Polyline (**poly**) masking reads an input ASCII file containing Lat/Lon locations, connects the first and last points, and selects grid points whose Lat/Lon location falls inside that polyline in Lat/Lon space. This option is useful when defining geographic subregions of a domain.
 
-2. Box (**box**) masking reads an input ASCII file containing Lat/Lon locations and draws a box around each point. The height and width of the box is specified by the **-height** and **-width** command line options in grid units. For a square, only one of **-height** or **-width** needs to be used.
+2. Polyline XY (**poly_xy**) masking reads an input ASCII file containing Lat/Lon locations. It converts the polyline Lat/Lon locations into grid X/Y space and connects the first and last points. It selects grid points whose X/Y location falls inside that polyline in X/Y space. This option is useful when defining geographic subregions of a domain.
 
-3. Circle (**circle**) masking reads an input ASCII file containing Lat/Lon locations and for each grid point, computes the minimum great-circle arc distance in kilometers to those points. If the **-thresh** command line option is not used, the minimum distance value for each grid point will be written to the output. If it is used, only those grid points whose minimum distance meets the threshold criteria will be selected. This option is useful when defining areas within a certain radius of radar locations.
+3. Box (**box**) masking reads an input ASCII file containing Lat/Lon locations and draws a box around each point. The height and width of the box is specified by the **-height** and **-width** command line options in grid units. For a square, only one of **-height** or **-width** needs to be used.
 
-4. Track (**track**) masking reads an input ASCII file containing Lat/Lon locations and for each grid point, computes the minimum great-circle arc distance in kilometers to the track defined by those points. The first and last track points are not connected. As with **circle** masking the output for each grid point depends on the use of the **-thresh** command line option. This option is useful when defining the area within a certain distance of a hurricane track.
+4. Circle (**circle**) masking reads an input ASCII file containing Lat/Lon locations and for each grid point, computes the minimum great-circle arc distance in kilometers to those points. If the **-thresh** command line option is not used, the minimum distance value for each grid point will be written to the output. If it is used, only those grid points whose minimum distance meets the threshold criteria will be selected. This option is useful when defining areas within a certain radius of radar locations.
 
-5. Grid (**grid**) masking reads an input gridded data file, extracts the field specified using its grid definition, and selects grid points falling inside that grid. This option is useful when using a model nest to define the corresponding area of the parent domain.
+5. Track (**track**) masking reads an input ASCII file containing Lat/Lon locations and for each grid point, computes the minimum great-circle arc distance in kilometers to the track defined by those points. The first and last track points are not connected. As with **circle** masking the output for each grid point depends on the use of the **-thresh** command line option. This option is useful when defining the area within a certain distance of a hurricane track.
 
-6. Data (**data**) masking reads an input gridded data file, extracts the field specified using the **-mask_field** command line option, thresholds the data using the **-thresh** command line option, and selects grid points which meet that threshold criteria. The option is useful when thresholding topography to define a mask based on elevation or when threshold land use to extract a particular category.
+6. Grid (**grid**) masking reads an input gridded data file, extracts the field specified using its grid definition, and selects grid points falling inside that grid. This option is useful when using a model nest to define the corresponding area of the parent domain.
 
-7. Solar altitude (**solar_alt**) and solar azimuth (**solar_azi**) masking computes the solar altitude and azimuth values at each grid point for the time defined by the **mask_file** setting. **mask_file** may either be set to an explicit time string in YYYYMMDD[_HH[MMSS]] format or to a gridded data file. If set to a gridded data file, the **-mask_field** command line option specifies the field of data whose valid time should be used. If the **-thresh** command line option is not used, the raw solar altitude or azimuth value for each grid point will be written to the output. If it is used, the resulting binary mask field will be written. This option is useful when defining a day/night mask.
+7. Data (**data**) masking reads an input gridded data file, extracts the field specified using the **-mask_field** command line option, thresholds the data using the **-thresh** command line option, and selects grid points which meet that threshold criteria. The option is useful when thresholding topography to define a mask based on elevation or when threshold land use to extract a particular category.
 
-8. Latitude (**lat**) and longitude (**lon**) masking computes the latitude and longitude value at each grid point. This logic only requires the definition of the grid, specified by the **input_file**. Technically, the **mask_file** is not needed, but a value must be specified for the command line to parse correctly. Users are advised to simply repeat the **input_file** setting twice. If the **-thresh** command line option is not used, the raw latitude or longitude values for each grid point will be written to the output. This option is useful when defining latitude or longitude bands over which to compute statistics.
+8. Solar altitude (**solar_alt**) and solar azimuth (**solar_azi**) masking computes the solar altitude and azimuth values at each grid point for the time defined by the **mask_file** setting. **mask_file** may either be set to an explicit time string in YYYYMMDD[_HH[MMSS]] format or to a gridded data file. If set to a gridded data file, the **-mask_field** command line option specifies the field of data whose valid time should be used. If the **-thresh** command line option is not used, the raw solar altitude or azimuth value for each grid point will be written to the output. If it is used, the resulting binary mask field will be written. This option is useful when defining a day/night mask.
 
-9. Shapefile (**shape**) masking uses a closed polygon taken from an ESRI shapefile to define the masking region. Gen-Vx-Mask reads the shapefile with the ".shp" suffix and extracts the latitude and longitudes of the vertices. The other types of shapefiles (index file, suffix ".shx", and dBASE file, suffix ".dbf") are not currently used. The shapefile must consist of closed polygons rather than polylines, points, or any of the other data types that shapefiles support. Shapefiles usually contain more than one polygon, and the **-shape n** command line option enables the user to select one polygon from the shapefile. The integer **n** tells which shape number to use from the shapefile. Note that this value is zero-based, so that the first polygon in the shapefile is polygon number 0, the second polygon in the shapefile is polygon number 1, etc. For the user's convenience, some utilities that perform human-readable screen dumps of shapefile contents are provided. The gis_dump_shp, gis_dump_shx and gis_dump_dbf tools enable the user to examine the contents of her shapefiles. As an example, if the user knows the name of the particular polygon but not the number of the polygon in the shapefile, the user can use the gis_dump_dbf utility to examine the names of the polygons in the shapefile. The information written to the screen will display the corresponding polygon number.
+9. Latitude (**lat**) and longitude (**lon**) masking computes the latitude and longitude value at each grid point. This logic only requires the definition of the grid, specified by the **input_file**. Technically, the **mask_file** is not needed, but a value must be specified for the command line to parse correctly. Users are advised to simply repeat the **input_file** setting twice. If the **-thresh** command line option is not used, the raw latitude or longitude values for each grid point will be written to the output. This option is useful when defining latitude or longitude bands over which to compute statistics.
 
-The polyline, box, circle, and track masking methods all read an ASCII file containing Lat/Lon locations. Those files must contain a string, which defines the name of the masking region, followed by a series of whitespace-separated latitude (degrees north) and longitude (degree east) values.
+10. Shapefile (**shape**) masking uses a closed polygon taken from an ESRI shapefile to define the masking region. Gen-Vx-Mask reads the shapefile with the ".shp" suffix and extracts the latitude and longitudes of the vertices. The other types of shapefiles (index file, suffix ".shx", and dBASE file, suffix ".dbf") are not currently used. The shapefile must consist of closed polygons rather than polylines, points, or any of the other data types that shapefiles support. Shapefiles usually contain more than one polygon, and the **-shape n** command line option enables the user to select one polygon from the shapefile. The integer **n** tells which shape number to use from the shapefile. Note that this value is zero-based, so that the first polygon in the shapefile is polygon number 0, the second polygon in the shapefile is polygon number 1, etc. For the user's convenience, some utilities that perform human-readable screen dumps of shapefile contents are provided. The gis_dump_shp, gis_dump_shx and gis_dump_dbf tools enable the user to examine the contents of her shapefiles. As an example, if the user knows the name of the particular polygon but not the number of the polygon in the shapefile, the user can use the gis_dump_dbf utility to examine the names of the polygons in the shapefile. The information written to the screen will display the corresponding polygon number.
+
+The polyline, polyline XY, box, circle, and track masking methods all read an ASCII file containing Lat/Lon locations. Those files must contain a string, which defines the name of the masking region, followed by a series of whitespace-separated latitude (degrees north) and longitude (degree east) values.
 
 The Gen-Vx-Mask tool performs three main steps, described below.
 

met/src/basic/vx_util/thresh_array.cc

@@ -625,7 +625,10 @@ bool check_prob_thresh(const ThreshArray &ta, bool error_out) {
          mlog << Error << "\ncheck_prob_thresh() -> "
               << "When verifying a probability field, you must "
               << "select at least 3 thresholds beginning with 0.0 "
-              << "and ending with 1.0.\n\n";
+              << "and ending with 1.0 (current setting: "
+              << ta.get_str() << ").\n"
+              << "Consider using the ==p shorthand notation for bins "
+              << "of equal width.\n\n";
          exit(1);
       }
       else {
@@ -641,7 +644,10 @@ bool check_prob_thresh(const ThreshArray &ta, bool error_out) {
             mlog << Error << "\ncheck_prob_thresh() -> "
                  << "When verifying a probability field, all "
                  << "thresholds must be greater than or equal to, "
-                 << "using \"ge\" or \">=\".\n\n";
+                 << "using \"ge\" or \">=\" (current setting: "
+                 << ta.get_str() << ").\n"
+                 << "Consider using the ==p shorthand notation for bins "
+                 << "of equal width.\n\n";
             exit(1);
          }
          else {
@@ -653,8 +659,11 @@ bool check_prob_thresh(const ThreshArray &ta, bool error_out) {
       if(ta[i].get_value() < 0.0 || ta[i].get_value() > 1.0) {
          if(error_out) {
             mlog << Error << "\ncheck_prob_thresh() -> "
-                 << "When verifying a probability field, all "
-                 << "thresholds must be between 0 and 1.\n\n";
+                 << "When verifying a probability field, all thresholds "
+                 << "must be between 0 and 1 (current setting: "
+                 << ta.get_str() << ").\n"
+                 << "Consider using the ==p shorthand notation for bins "
+                 << "of equal width.\n\n";
             exit(1);
          }
          else {

met/src/libcode/vx_nc_util/nc_utils.cc

@@ -25,8 +25,6 @@ using namespace netCDF::exceptions;
 
 ////////////////////////////////////////////////////////////////////////
 
-////////////////////////////////////////////////////////////////////////
-
 void patch_nc_name(string *var_name) {
    size_t offset;
 
@@ -3216,6 +3214,26 @@ NcVar add_var(NcFile *nc, const string &var_name, const NcType ncType,
       mlog << Debug(3) << "    nc_utils.add_var() deflate_level: " << deflate_level << "\n";
       var.setCompression(false, true, deflate_level);
    }
+
+   // Check for lat and lon dimensions
+   ConcatString cs;
+   bool has_lat_dim, has_lon_dim;
+   vector<NcDim>::const_iterator itDim;
+   for (itDim = ncDims.begin(), has_lat_dim = has_lon_dim = false;
+        itDim != ncDims.end(); ++itDim) {
+           if (itDim->getName() == "lat") has_lat_dim = true;
+      else if (itDim->getName() == "lon") has_lon_dim = true;
+      if (itDim != ncDims.begin()) cs << " ";
+      cs << itDim->getName();
+   }
+
+   // Add the coordinates variable attribute for variables
+   // with both lat and lon dimensions
+   if (has_lat_dim && var_name != "lat" &&
+       has_lon_dim && var_name != "lon") {
+      add_att(&var, "coordinates", cs.c_str());
+   }
+
    return var;
 }