Gen-Vx-Mask Tool: General

Gen-Vx-Mask Functionality

The Gen-Vx-Mask tool is an optional utility that may be run one or more times to define a verification masking region for a domain. The MET tools provide a variety of ways to define spatial verification masking regions over which to accumulate statistics. One such way is to define a polyline consisting of Lat/Lon points which define the region. The Lat/Lon polyline files may be used directly in the other MET tools, however, doing so, for a relatively complex polyline with a few hundred points is inefficient. The Gen-Vx-Mask tool may be used instead to apply a polyline to a domain once and define a bitmap for the mask. Using the output of Gen-Vx-Mask to define verification masking regions in other MET tools is much more efficient.

The Gen-Vx-Mask tool replaces the Gen-Poly-Mask and Gen-Circle-Mask tools from earlier versions and adds support for several ways of defining masking regions, described below. This tool may be run iteratively to combine multiple masks together.

Gen-Vx-Mask Usage

View the usage statement for Gen-Vx-Mask by simply typing the following:

At a minimum, the input_file, the mask_file, and the NetCDF out_file must be passed in on the command line. The input_fileis a gridded data file which defines the domain for which the mask should be defined. The NetCDF out_file is the output NetCDF mask file to be written. The mask_file defines the masking information:

• For "poly", "box", "circle", and "track" masking, specify an ASCII Lat/Lon file.
• For "grid" and "data" masking, specify a gridded data file.
• For "solar_alt" and "solar_azi" masking, specify a gridded data file or a timestring in YYYYMMDD[_HH[MMSS]] format.
• For "lat" and "lon" masking, no "mask_file" needed, simply repeat the path for "input_file".

The Gen-Vx-Mask tool supports the following settings for the -type command line option:

• For -type poly (default), the mask_file is a Lat/Lon polyline file which defines the area to be included in the mask.
• For -type box, the mask_file is a Lat/Lon polyline file which defines individual locations of interest. The -height and -width options define the number of grid points surrounding that location to be included in the mask.
• For -type circle, the mask_file is a Lat/Lon polyline file which defines individual locations of interest. For each grid point, the minimum distance in kilometers to the set of masking points is computed. If the -thresh option is provided, those distances will be thresholded to define a mask. Otherwise, the actual distance values will be written.
• The -type track option is very similar to circle. However, the Lat/Lon points define a connected track rather than individual locations. For each grid point, the minimum distance in kilometers to that track is computed. If the -thresh option is provided, those distances will be thresholded to define a mask. Otherwise, the actual distance values will be written.
• For -type grid, the mask_file is a gridded data file whose grid defines the desired masking region. Any grid points falling inside the masking grid are included in the mask.
• For -type data, the mask_file is a gridded data file which should be on the same grid as in_file. The -mask_field option specifies the field of data which should be extracted from the mask_file. If the -thresh option is provided, those data values will be thresholded to define a mask. Otherwise, the actual data values will be written.
• The -type solar_alt specifies the position of the solar altitude.
• The -type solar_azi specifies the azimuth of the sun.
• The -type lat computes the latitude 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.
• The -type lon computes the 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.
• The -type shape option and value specifies shapefile masking using 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 longitude of the verticies. 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 -shapeno n command line option enables the user to select one polygone from the shapefile. The integer ntells which shape number to use from the shapefile. Note that this value is zero-based, so that the first polygone in the shapefile is polygon number 0, the second is 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 the shapefiles.

The Gen-Vx-Mask tool supports several other useful options:

• The input_file defines the domain of interest, and by default, each grid point is assigned an initial value of 0. The -input_field option may be used to specify a field of data whose values override the default. The input value at each grid point will be written to the output unless its value is updated during the current masking process.
• The -mask_field option is for "data" masking, define the field from "mask_file" to be used.
• The -complement option may be used to apply the opposite (i.e. reverse video) of the current mask. For example, for -type polymasking, all grid points outside the polyline will be selected instead of all points inside.
• The -union, -intersection, and -symdiff options define the logic for combining values from the -input_field with the current mask values.
• By default, 1 is the value written to the output for a grid point inside the mask. The -value option overrides that default value.
• The -name option overrides the default variable name written to the NetCDF output file.
• The -height and -width options are for "box" masking, specify these dimensions in grid units.
• The -thresh defines the threshold to be applied:
  • For "circle" and "track" masking, threshold the distance (km).
  • For "data" masking, threshold the values of "mask_field".
  • For "solar_alt" and "solar_azi" masking, threshold the computed solar values.
  • For "lat" and "lon" masking, threshold the latitude and longitude values.

The variety of options for the Gen-Vx-Mask tool and the ability to run it iteratively enable the user great flexibility in defining the spatial areas for computing statistics.