Session 2: Grid-to-Obs

Session 2: Grid-to-Obs

METplus Practical Session 2

During this practical session, you will run the tools indicated below:

You may navigate through this tutorial by following the links at the bottom of each page or by using the menu navigation.

Since you already set up your runtime enviroment in Session 1, you should be ready to go! To be sure, run through the following instructions to check that your environment is set correctly.

Prerequisites: Verify Environment is Set Correctly

Before running the tutorial instructions, you will need to ensure that you have a few environment variables set up correctly. If they are not set correctly, the tutorial instructions will not work properly.

1: Navigate to your tutorial directory and run the tutorial setup script.
In the following instructions, change "/path/to" to the directory you chose.

EDIT AFTER COPYING and BEFORE HITTING RETURN!

cd /path/to/METplus-4.0.0_Tutorial
source METplus-4.0.0_TutorialSetup.sh

 

2: Check that you have environment variables set correctly. If any of these variables are not set, navigate back to the METplus Setup section of the tutorial.
echo ${METPLUS_TUTORIAL_DIR}
echo ${METPLUS_BUILD_BASE}
echo ${MET_BUILD_BASE}
echo ${METPLUS_DATA}
ls ${METPLUS_TUTORIAL_DIR}
ls ${METPLUS_BUILD_BASE}
ls ${MET_BUILD_BASE}
ls ${METPLUS_DATA}
METPLUS_TUTORIAL_DIR is the location of all of your tutorial work, including configuration files, output data, and any other notes you'd like to keep.
METPLUS_BUILD_BASE is the full path to the METplus installation (/path/to/METplus-X.Y)
MET_BUILD_BASE is the full path to the MET installation (/path/to/met-X.Y)
METPLUS_DATA is the location of the sample test data directory

 

3: Check that the MET applications are in the path:
which point_stat
You should see the usage statement for Point-Stat. The version number listed should correspond to the version listed in MET_BUILD_BASE. If it does not, you will need to either reload the met module, or add ${MET_BUILD_BASE}/bin to your PATH.

 

4: Check that the correct version of run_metplus.py is in your PATH:
which run_metplus.py
If you don't see the full path to script from the shared installation, please set it. It should look the same as the output from this command:
echo ${METPLUS_BUILD_BASE}/ush/run_metplus.py
ls ${METPLUS_BUILD_BASE}/ush/run_metplus.py

 

See the instructions in Session 1 for more information.

You are now ready to move on to the next section.

admin Wed, 06/12/2019 - 16:57

MET Tool: PB2NC

MET Tool: PB2NC cindyhg Tue, 06/25/2019 - 09:25
IMPORTANT NOTE: If you are returning to the tutorial, you must source the tutorial setup script before running the following instructions. If you are unsure if you have done this step, please navigate to the Verify Environment is Set Correctly page.

PB2NC Tool: General

PB2NC Functionality

The PB2NC tool is used to stratify (i.e. subset) the contents of an input PrepBufr point observation file and reformat it into NetCDF format for use by the Point-Stat or Ensemble-Stat tool. In this session, we will run PB2NC on a PrepBufr point observation file prior to running Point-Stat. Observations may be stratified by variable type, PrepBufr message type, station identifier, a masking region, elevation, report type, vertical level category, quality mark threshold, and level of PrepBufr processing. Stratification is controlled by a configuration file and discussed on the next page.

The PB2NC tool may be run on both PrepBufr and Bufr observation files. As of met-6.1, support for Bufr is limited to files containing embedded tables. Support for Bufr files using external tables will be added in a future release.

For more information about the PrepBufr format, visit:

https://emc.ncep.noaa.gov/emc/pages/infrastructure/bufrlib.php

For information on where to download PrepBufr files, visit:

https://dtcenter.org/community-code/model-evaluation-tools-met/input-data

PB2NC Usage

View the usage statement for PB2NC by simply typing the following:
pb2nc
Usage: pb2nc  
  prepbufr_file input prepbufr path/filename
  netcdf_file output netcdf path/filename
  config_file configuration path/filename
  [-pbfile prepbufr_file] additional input files
  [-valid_beg time] Beginning of valid time window [YYYYMMDD_[HH[MMSS]]]
  [-valid_end time] End of valid time window [YYYYMMDD_[HH[MMSS]]]
  [-nmsg n] Number of PrepBufr messages to process
  [-index] List available observation variables by message type (no output file)
  [-dump path] Dump entire contents of PrepBufr file to directory
  [-obs_var var] Sets the variable list to be saved from input BUFR files
  [-log file] Outputs log messages to the specified file
  [-v level] Level of logging
  [-compression level] NetCDF file compression

At a minimum, the input prepbufr_file, the output netcdf_file, and the configuration config_file must be passed in on the command line. Also, you may use the -pbfile command line argument to run PB2NC using multiple input PrepBufr files, likely adjacent in time.

When running PB2NC on a new dataset, users are advised to run with the -index option to list the observation variables that are present in that file.

Configure

Configure cindyhg Tue, 06/25/2019 - 09:26

PB2NC Tool: Configure

Start by making an output directory for PB2NC and changing directories:
mkdir -p ${METPLUS_TUTORIAL_DIR}/output/met_output/pb2nc
cd ${METPLUS_TUTORIAL_DIR}/output/met_output/pb2nc

The behavior of PB2NC is controlled by the contents of the configuration file passed to it on the command line. The default PB2NC configuration may be found in the data/config/PB2NCConfig_default file.

Prior to modifying the configuration file, users are advised to make a copy of the default:
cp ${MET_BUILD_BASE}/share/met/config/PB2NCConfig_default PB2NCConfig_tutorial_run1
Open up the PB2NCConfig_tutorial_run1 file for editing with your preferred text editor.
vi PB2NCConfig_tutorial_run1

The configurable items for PB2NC are used to filter out the PrepBufr observations that should be retained or derived. You may find a complete description of the configurable items in the pb2nc configuration file section of the MET User's Guide or in the Configuration File Overview.

For this tutorial, edit the PB2NCConfig_tutorial_run1 file as follows:

  • Set:
    message_type = [ "ADPUPA", "ADPSFC" ];

    to retain only those 2 message types. Message types are described in:
    http://www.emc.ncep.noaa.gov/mmb/data_processing/prepbufr.doc/table_1.htm

  • Set:
    obs_window = {
       beg = -1800;
       end =  1800;
    }

    so that only observations within 1800 second (30 minutes) of the file time will be retained.

  • Set:
    mask = {
       grid = "G212";
       poly = "";
    }

    to retain only those observations residing within NCEP Grid 212, on which the forecast data resides.

  • Set:
    obs_bufr_var = [ "QOB", "TOB", "UOB", "VOB", "D_WIND", "D_RH" ];

    to retain observations for specific humidity, temperature, the u-component of wind, and the v-component of wind and to derive observation values for wind speed and relative humidity.

    While we are request these observation variable names from the input file, the following corresponding strings will be written to the output file: SPFH, TMP, UGRD, VGRD, WIND, RH. This mapping of input PrepBufr variable names to output variable names is specified by the obs_prepbufr_map config file entry. This enables the new features in the current version of MET to be backward compatible with earlier versions.

Next, save the PB2NCConfig_tutorial_run1 file and exit the text editor.

Run

Run cindyhg Tue, 06/25/2019 - 09:27

PB2NC Tool: Run

Next, run PB2NC on the command line using the following command:
pb2nc \
${METPLUS_DATA}/met_test/data/sample_obs/prepbufr/ndas.t00z.prepbufr.tm12.20070401.nr \
tutorial_pb_run1.nc \
PB2NCConfig_tutorial_run1 \
-v 2
If this run fails due to runtime issues, please download a copy of the output file here and manually save it as tutorial_pb_run1.nc.

PB2NC is now filtering the observations from the PrepBufr file using the configuration settings we specified and writing the output to the NetCDF file name we chose. This should take a few minutes to run. As it runs, you should see several status messages printed to the screen to indicate progress. You may use the -v command line option to turn off (-v 0) or change the amount of log information printed to the screen.

Inspect the PB2NC status messages and note that 69833 PrepBufr messages were filtered down to 8394 messages which produced 52491 actual and derived observations.

If you'd like to filter down the observations further, you may want to narrow the time window or modify other filtering criteria. We will do that after inspecting the resultant NetCDF file.

Output

Output cindyhg Tue, 06/25/2019 - 09:29

PB2NC Tool: Output

When PB2NC is finished, you may view the output NetCDF file it wrote using the ncdump utility.

Run the following command to view the header of the NetCDF output file:
ncdump -h tutorial_pb_run1.nc

In the NetCDF header, you'll see that the file contains nine dimensions and nine variables. The obs_arr variable contains the actual observation values. The obs_qty variable contains the corresponding quality flags. The four header variables (hdr_typ, hdr_sid, hdr_vld, hdr_arr) contain information about the observing locations.

The obs_varobs_unit, and obs_desc variables describe the observation variables contained in the output. The second entry of the obs_arr variable (i.e. var_id) lists the index into these array for each observation. For example, for observations of temperature, you'd see TMP in obs_varKELVIN in obs_unit, and TEMPERATURE OBSERVATION in obs_desc. For observations of temperature in obs_arr, the second entry (var_id) would list the index of that temperature information.

Inspect the output of ncdump before continuing.

Plot-Point-Obs

The plot_point_obs tool plots the location of these NetCDF point observations. Just like plot_data_plane is useful to visualize gridded data, run plot_point_obs to make sure you have point observations where you expect.

Run the following command:
plot_point_obs \
tutorial_pb_run1.nc \
tutorial_pb_run1.ps
Display the output PostScript file by running the following command:
gv tutorial_pb_run1.ps &

Each red dot in the plot represents the location of at least one observation value. The plot_point_obs tool has additional command line options for filtering which observations get plotted and the area to be plotted.

View its usage statement by running the following command:
plot_point_obs

By default, the points are plotted on the full globe.

Next, try rerunning plot_point_obs using the -data_file option to specify the grid over which the points should be plotted:
plot_point_obs \
tutorial_pb_run1.nc \
tutorial_pb_run1_zoom.ps \
-data_file ${METPLUS_DATA}/met_test/data/sample_fcst/2007033000/nam.t00z.awip1236.tm00.20070330.grb

MET extracts the grid information from the first record of that GRIB file and plots the points on that domain.

Display the output PostScript file by running the following command:
gv tutorial_pb_run1_zoom.ps &

The plot_data_plane tool can be run on the NetCDF output of any of the MET point observation pre-processing tools (pb2ncascii2ncmadis2nc, and lidar2nc).

Reconfigure and Rerun

Reconfigure and Rerun cindyhg Tue, 06/25/2019 - 09:31

PB2NC Tool: Reconfigure and Rerun

Now we'll rerun PB2NC, but this time we'll tighten the observation acceptance criteria.

Start by making a copy of the configuration file we just used:
cp PB2NCConfig_tutorial_run1 PB2NCConfig_tutorial_run2
Open up the PB2NCConfig_tutorial_run2 file and edit it as follows:
vi PB2NCConfig_tutorial_run2
  • Set:
    message_type = [];

    to retain all message types.

  • Set:
    obs_window = {
       beg = -25*30;
       end =  25*30;
    }

    so that only observations 25 minutes before and 25 minutes after the top of the hour are retained.

  • Set:
    quality_mark_thresh = 1;

    to retain only the observations marked "Good" by the NCEP quality control system.

Next, run PB2NC again but change the output name using the following command:
pb2nc \
${METPLUS_DATA}/met_test/data/sample_obs/prepbufr/ndas.t00z.prepbufr.tm12.20070401.nr \
tutorial_pb_run2.nc \
PB2NCConfig_tutorial_run2 \
-v 2
If this run fails due to runtime issues, please download a copy of the output file here and manually save it as tutorial_pb_run2.nc.
Inspect the PB2NC status messages and note that 3972 observations were retained rather than 52491 in the previous example.

The majority of the observations were rejected because their valid time no longer fell inside the tighter obs_window setting.

When configuring PB2NC for your own projects, you should err on the side of keeping more data rather than less. As you'll see, the grid-to-point verification tools (Point-Stat and Ensemble-Stat) allow you to further refine which point observations are actually used in the verification. However, keeping a lot of point observations that you'll never actually use will make the data files larger and slightly slow down the verification. For example, if you're using a Global Data Assimilation (GDAS) PREPBUFR file to verify a model over Europe, it would make sense to only keep those point observations that fall within your model domain.

METplus Use Case: PB2NC

METplus Use Case: PB2NC cindyhg Tue, 06/25/2019 - 09:48
IMPORTANT NOTE: If you are returning to the tutorial, you must source the tutorial setup script before running the following instructions. If you are unsure if you have done this step, please navigate to the Verify Environment is Set Correctly page.

METplus Use Case: PB2NC

This use case utilizes the MET PB2NC tool. 

The default statistics created by this use case only dump the partial sums, so we will be also modifying the MET configuration file to add the continuous statistics to the output. 

There is a little more setup in this use case, which will be instructive and demonstrate the basic structure, flexibility and setup of METplus configuration.

Optional: Refer to the MET Users Guide for a description of the MET tools used in this use case.
Optional: Refer to the METplus Config Glossary section of the METplus Users Guide for a reference to METplus variables used in this use case.

 

  1. Review the settings in the PB2NC.conf file:
less ${METPLUS_BUILD_BASE}/parm/use_cases/met_tool_wrapper/PB2NC/PB2NC.conf

Note that the input directory PB2NC_INPUT_DIR is set to a path relative to {INPUT_BASE}, the output directory PB2NC_OUTPUT_DIR is set to a path relative to {OUTPUT_BASE}, and CONFIG_DIR points to a directory of met_config files under {PARM_BASE}:

[dir]
# location of configuration files used by MET applications
CONFIG_DIR = {PARM_BASE}/met_config
 
# directory containing input to PB2NC
PB2NC_INPUT_DIR = {INPUT_BASE}/met_test/data/sample_obs/prepbufr
 
# directory to write output from PB2NC
PB2NC_OUTPUT_DIR = {OUTPUT_BASE}/pb2nc

{PARM_BASE} is set automatically by METplus. The wrapped MET config file for PB2NC is set relative to {CONFIG_DIR} in PB2NC_CONFIG_FILE:

# Location of MET config file to pass to PB2NC
# References CONFIG_DIR from the [dir] section
PB2NC_CONFIG_FILE = {CONFIG_DIR}/PB2NCConfig_wrapped
Let's look at the PB2Nc_CONFIG_FILE

Values for the MET tool PB2NC are passed in from METplus config files, including PB2NC.conf

less ${METPLUS_BUILD_BASE}/parm/met_config/PB2NCConfig_wrapped
////////////////////////////////////////////////////////////////////////////////
//
// PB2NC configuration file.
//
// For additional information, see the MET_BASE/config/README file.
// ////////////////////////////////////////////////////////////////////////////////

//
// PrepBufr message type
//
${PB2NC_MESSAGE_TYPE} ;

//
// Mapping of message type group name to comma-separated list of values
// Derive PRMSL only for SURFACE message types
//
message_type_group_map = [
{ key = "SURFACE"; val = "ADPSFC,SFCSHP,MSONET"; },
{ key = "ANYAIR";  val = "AIRCAR,AIRCFT"; },
{ key = "ANYSFC";  val = "ADPSFC,SFCSHP,ADPUPA,PROFLR,MSONET"; },
{ key = "ONLYSF";  val = "ADPSFC,SFCSHP" }
];
 

No modifications are needed to run the PB2NC METplus tool. 

  1. Run the PB2NC use case:
run_metplus.py \
${METPLUS_BUILD_BASE}/parm/use_cases/met_tool_wrapper/PB2NC/PB2NC.conf \
${METPLUS_TUTORIAL_DIR}/tutorial.conf \
config.OUTPUT_BASE=${METPLUS_TUTORIAL_DIR}/output/PB2NC

 

  1. Review the output files:
ls ${METPLUS_TUTORIAL_DIR}/output/PB2NC/pb2nc

The following is the statistical ouput and files are generated from the command:

  • sample_pb.nc

MET Tool: ASCII2NC

MET Tool: ASCII2NC cindyhg Tue, 06/25/2019 - 09:32
IMPORTANT NOTE: If you are returning to the tutorial, you must source the tutorial setup script before running the following instructions. If you are unsure if you have done this step, please navigate to the Verify Environment is Set Correctly page.

ASCII2NC Tool: General

ASCII2NC Functionality

The ASCII2NC tool reformats ASCII point observations into the intermediate NetCDF format that Point-Stat and Ensemble-Stat read. ASCII2NC simply reformats the data and does much less filtering of the observations than PB2NC does. ASCII2NC supports a simple 11-column format, described below, the Little-R format often used in data assimilation, SURFace RADiation (SURFRAD) data, Western Wind and Solar Integration Studay (WWSIS) data, and AErosol RObotic NEtwork (Aeronet) data versions 2 and 3 format. MET version 9.0 added support for passing observations to ASCII2NC using a Python script.  Future version of MET may be enhanced to support additional commonly used ASCII point observation formats based on community input.

MET Point Observation Format

The MET point observation format consists of one observation value per line. Each input observation line should consist of the following 11 columns of data:

  1. Message_Type
  2. Station_ID
  3. Valid_Time in YYYYMMDD_HHMMSS format
  4. Lat in degrees North
  5. Lon in degrees East
  6. Elevation in meters above sea level
  7. Variable_Name for this observation (or GRIB_Code for backward compatibility)
  8. Level as the pressure level in hPa or accumulation interval in hours
  9. Height in meters above sea level or above ground level
  10. QC_String quality control string
  11. Observation_Value

It is the user's responsibility to get their ASCII point observations into this format.

ASCII2NC Usage

View the usage statement for ASCII2NC by simply typing the following:
ascii2nc
Usage: ascii2nc  
  ascii_file1 [...] One or more input ASCII path/filename
  netcdf_file Output NetCDF path/filename
  [-format ASCII_format] Set to met_pointlittle_rsurfradwwsis, aeronet, aeronetv2, aeronetv3, or python
  [-config file] Configuration file to specify how observation data should be summarized
  [-mask_grid string] Named grid or a gridded data file for filtering point observations spatially
  [-mask_poly file] Polyline masking file for filtering point observations spatially
  [-mask_sid file|list] Specific station ID's to be used in an ASCII file or comma-separted list
  [-log file] Outputs log messages to the specified file
  [-v level] Level of logging
  [-compress level] NetCDF compression level

At a minimum, the input ascii_file and the output netcdf_file must be passed on the command line. ASCII2NC interrogates the data to determine it's format, but the user may explicitly set it using the -format command line option. The -mask_grid-mask_poly, and -mask_sid options can be used to filter observations spatially.

Run

Run cindyhg Tue, 06/25/2019 - 09:33

ASCII2NC Tool: Run

Start by making an output directory for ASCII2NC and changing directories:
mkdir -p ${METPLUS_TUTORIAL_DIR}/output/met_output/ascii2nc
cd ${METPLUS_TUTORIAL_DIR}/output/met_output/ascii2nc

Since ASCII2NC performs a simple reformatting step, typically no configuration file is needed. However, when processing high-frequency (1 or 3-minute) SURFRAD data, a configuration file may be used to define a time window and summary metric for each station. For example, you might compute the average observation value +/- 15 minutes at the top of each hour for each station. In this example, we will not use a configuration file.

The sample ASCII observations in the MET tarball are still identified by GRIB code rather than the newer variable name option.

Dump that file and notice that the GRIB codes in the seventh column could be replaced by corresponding variable names.

For example, 52 corresponds to RH:

cat ${METPLUS_DATA}/met_test/data/sample_obs/ascii/sample_ascii_obs.txt
Run ASCII2NC on the command line using the following command:
ascii2nc \
${METPLUS_DATA}/met_test/data/sample_obs/ascii/sample_ascii_obs.txt \
tutorial_ascii.nc \
-v 2

ASCII2NC should perform this reformatting step very quickly since the sample file only contains data for 5 stations.

Output

Output cindyhg Tue, 06/25/2019 - 09:37

ASCII2NC Tool: Output

When ASCII2NC is finished, you may view the output NetCDF file it wrote using the ncdump utility.

Run the following command to view the header of the NetCDF output file:
ncdump -h tutorial_ascii.nc

The NetCDF header should look nearly identical to the output of the NetCDF output of PB2NC. You can see the list of stations for which we have data by inspecting the hdr_sid_table variable:

ncdump -v hdr_sid_table tutorial_ascii.nc
Feel free to inspect the contents of the other variables as well.

This ASCII data only contains observations at a few locations.

Use the plot_point_obs to plot the locations, increasing the level of verbosity to 3 to see more detail:
plot_point_obs \
tutorial_ascii.nc \
tutorial_ascii.ps \
-data_file ${METPLUS_DATA}/met_test/data/sample_fcst/2007033000/nam.t00z.awip1236.tm00.20070330.grb \
-v 3
gv tutorial_ascii.ps &

Next, we'll use the NetCDF output of PB2NC and ASCII2NC to perform Grid-to-Point verification using the Point-Stat tool.

MET Tool: Point-Stat

MET Tool: Point-Stat cindyhg Tue, 06/25/2019 - 09:38
IMPORTANT NOTE: If you are returning to the tutorial, you must source the tutorial setup script before running the following instructions. If you are unsure if you have done this step, please navigate to the Verify Environment is Set Correctly page.

Point-Stat Tool: General

Point-Stat Functionality

The Point-Stat tool provides verification statistics for comparing gridded forecasts to observation points, as opposed to gridded analyses like Grid-Stat. The Point-Stat tool matches gridded forecasts to point observation locations using one or more configurable interpolation methods. The tool then computes a configurable set of verification statistics for these matched pairs. Continuous statistics are computed over the raw matched pair values. Categorical statistics are generally calculated by applying a threshold to the forecast and observation values. Confidence intervals, which represent a measure of uncertainty, are computed for all of the verification statistics.

Point-Stat Usage

View the usage statement for Point-Stat by simply typing the following:
point_stat
Usage: point_stat  
  fcst_file Input gridded file path/name
  obs_file Input NetCDF observation file path/name
  config_file Configuration file
  [-point_obs file] Additional NetCDF observation files to be used (optional)
  [-obs_valid_beg time] Sets the beginning of the matching time window in YYYYMMDD[_HH[MMSS]] format (optional)
  [-obs_valid_end time] Sets the end of the matching time window in YYYYMMDD[_HH[MMSS]] format (optional)
  [-outdir path] Overrides the default output directory (optional)
  [-log file] Outputs log messages to the specified file (optional)
  [-v level] Level of logging (optional)

At a minimum, the input gridded fcst_file, the input NetCDF obs_file (output of PB2NC, ASCII2NC, MADIS2NC, and LIDAR2NC, last two not covered in these exercises), and the configuration config_file must be passed in on the command line. You may use the -point_obs command line argument to specify additional NetCDF observation files to be used.

Configure

Configure cindyhg Tue, 06/25/2019 - 09:40

Point-Stat Tool: Configure

Start by making an output directory for Point-Stat and changing directories:
mkdir -p ${METPLUS_TUTORIAL_DIR}/output/met_output/point_stat
cd ${METPLUS_TUTORIAL_DIR}/output/met_output/point_stat

The behavior of Point-Stat is controlled by the contents of the configuration file passed to it on the command line. The default Point-Stat configuration file may be found in the data/config/PointStatConfig_default file.

The configurable items for Point-Stat are used to specify how the verification is to be performed. The configurable items include specifications for the following:

  • The forecast fields to be verified at the specified vertical levels.
  • The type of point observations to be matched to the forecasts.
  • The threshold values to be applied.
  • The areas over which to aggregate statistics - as predefined grids, lat/lon polylines, or individual stations.
  • The confidence interval methods to be used.
  • The interpolation methods to be used.
  • The types of verification methods to be used.
Let's customize the configuration file. First, make a copy of the default:
cp ${MET_BUILD_BASE}/share/met/config/PointStatConfig_default PointStatConfig_tutorial_run1
Next, open up the PointStatConfig_tutorial_run1 file for editing and modify it as follows:
vi PointStatConfig_tutorial_run1
  • Set:
    fcst = {
      message_type = [ "ADPUPA" ];
      field = [
        {
          name     = "TMP";
          level      = [ "P850-1050", "P500-850" ];
          cat_thresh = [ <=273, >273 ];
        }
      ];
    }
    obs = fcst;

    to verify temperature over two different pressure ranges against ADPUPA observations using the thresholds specified.

  • Set:
    ci_alpha = [ 0.05, 0.10 ];

    to compute confidence intervals using both a 5% and a 10% level of certainty.

  • Set:
    output_flag = {
       fho    = BOTH;
       ctc    = BOTH;
       cts    = STAT;
       mctc   = NONE;
       mcts   = NONE;
       cnt    = BOTH;
       sl1l2  = STAT;
       sal1l2 = NONE;
       vl1l2  = NONE;
       val1l2 = NONE;
       pct    = NONE;
       pstd   = NONE;
       pjc    = NONE;
       prc    = NONE;
       ecnt   = NONE;
       eclv   = BOTH;
       mpr    = BOTH;
    }

    to indicate that the forecast-hit-observation (FHO) counts, contingency table counts (CTC), contingency table statistics (CTS), continuous statistics (CNT), partial sums (SL1L2), economic cost/loss value (ECLV), and the matched pair data (MPR) line types should be output. Setting SL1L2 and CTS to STAT causes those lines to only be written to the output .stat file, while setting others to BOTH causes them to be written to both the .stat file and the optional LINE_TYPE.txt file.

  • Set:
    output_prefix = "run1";

    to customize the output file names for this run.

Note that in the mask dictionary, the grid entry is set to FULL. This instructs Point-Stat to compute statistics over the entire input model domain. Setting grid to FULL has this special meaning.

Next, save the PointStatConfig_tutorial_run1 file and exit the text editor.

Run

Run cindyhg Tue, 06/25/2019 - 09:41

Point-Stat Tool: Run

Next, run Point-Stat to compare a GRIB forecast to the NetCDF point observation output of the ASCII2NC tool.

Run the following command line:
point_stat \
${METPLUS_DATA}/met_test/data/sample_fcst/2007033000/nam.t00z.awip1236.tm00.20070330.grb \
../ascii2nc/tutorial_ascii.nc \
PointStatConfig_tutorial_run1 \
-outdir . \
-v 2

Point-Stat is now performing the verification tasks we requested in the configuration file. It should take less than a minute to run. You should see several status messages printed to the screen to indicate progress.

If you receive a syntax error such as the one listed below, review PointStatConfig_tutorial_run1 for an extra comma after the "}" on line number 59

        cat_thresh = [ >273.0 ];
        }, <---Remove the comma

DEBUG 1: Default Config File: /usr/local/met-9.0/share/met/config/PointStatConfig_default
DEBUG 1: User Config File: PointStatConfig_tutorial_run1
ERROR  :
ERROR  : yyerror() -> syntax error in file "/tmp/met_config_26760_0"
ERROR  :
ERROR  :    line   = 59
ERROR  :
ERROR  :    column = 0
ERROR  :
ERROR  :    text   = "]"
ERROR  :
ERROR  :
ERROR  :    ];
ERROR  : _____
ERROR  :

Now try rerunning the command listed above, but increase the verbosity level to 3 (-v 3).

Notice the more detailed information about which observations were used for each verification task. If you run Point-Stat and get fewer matched pairs than you expected, try using the -v 3 option to see why the observations were rejected.

Users often write MET-Help to ask why they got zero matched pairs from Point-Stat. The first step is always rerunning Point-Stat using verbosity level 3 or higher to list the counts of reasons for why observations were not used!

Output

Output cindyhg Tue, 06/25/2019 - 09:42

Point-Stat Tool: Output

The output of Point-Stat is one or more ASCII files containing statistics summarizing the verification performed. Since we wrote output to the current directory, it should now contain 6 ASCII files that begin with the point_stat_ prefix, one each for the FHO, CTC, CNT, ECLV, and MPR types, and a sixth for the STAT file. The STAT file contains all of the output statistics while the other ASCII files contain the exact same data organized by line type.

Since the lines of data in these ASCII files are so long, we strongly recommend configuring your text editor to NOT use dynamic word wrapping. The files will be much easier to read that way:

  • In the kwrite editor, select Settings->Configure Editor, de-select Dynamic Word Wrap and click OK.
  • In the vi editor, type the command :set nowrap. To set this as the default behavior, run the following command:
    echo "set nowrap" >> ~/.exrc
Open up the point_stat_run1_360000L_20070331_120000V_ctc.txt CTC file using the text editor of your choice and note the following:
vi point_stat_run1_360000L_20070331_120000V_ctc.txt
  • This is a simple ASCII file consisting of several rows of data.
  • Each row contains data for a single verification task.
  • The FCST_LEAD, FCST_VALID_BEG, and FCST_VALID_END columns indicate the timing information of the forecast field.
  • The OBS_LEAD, OBS_VALID_BEG, and OBS_VALID_END columns indicate the timing information of the observation field.
  • The FCST_VAR, FCST_UNITS, FCST_LEV, OBS_VAR, OBS_UNITS, and OBS_LEV columns indicate the two parts of the forecast and observation fields set in the configure file.
  • The OBTYPE column indicates the PrepBufr message type used for this verification task.
  • The VX_MASK column indicates the masking region over which the statistics were accumulated.
  • The INTERP_MTHD and INTERP_PNTS columns indicate the method used to interpolate the forecast data to the observation location.
  • The FCST_THRESH and OBS_THRESH columns indicate the thresholds applied to FCST_VAR and OBS_VAR.
  • The COV_THRESH column is not applicable here and will always have NA when using point_stat.
  • The ALPHA column indicates the alpha used for confidence intervals.
  • The LINE_TYPE column indicates that these are CTC contingency table count lines.
  • The TOTAL column indicates the total number of matched pairs.
  • The remaining columns contain the counts for the contingency table computed by applying the threshold to the forecast/observation matched pairs. The FY_OY (forecast: yes, observation: yes), FY_ON (forecast: yes, observation: no), FN_OY (forecast: no, observation: yes), and FN_ON (forecast: no, observation: no) columns indicate those counts.
Next, answer the following questions about this contingency table output:
  1. What do you notice about the structure of the contingency table counts with respect to the two thresholds used? Does this make sense?
  2. Does the model appear to resolve relatively cold surface temperatures?
  3. Based on these observations, are temperatures >273 relatively rare or common in the P850-500 range? How can this affect the ability to get a good score using contingency table statistics? What about temperatures <=273 at the surface?
Close that file, open up the point_stat_run1_360000L_20070331_120000V_cnt.txt CNT file, and note the following:
vi point_stat_run1_360000L_20070331_120000V_cnt.txt
  • The columns prior to LINE_TYPE contain the same data as the previous file we viewed.
  • The LINE_TYPE column indicates that these are CNT continuous lines.
  • The remaining columns contain continuous statistics derived from the raw forecast/observation pairs. See the CNT OUTPUT FORMAT section in the Point-Stat section of the MET User's Guide for a thorough description of the output.
  • Again, confidence intervals are given for each of these statistics as described above.
Next, answer the following questions about these continuous statistics:
  1. What conclusions can you draw about the model's performance at each level using continuous statistics? Justify your answer. Did you use a single metric in your evaluation? Why or why not?
  2. Comparing the first line with an alpha value of 0.05 to the second line with an alpha value of 0.10, how does the level of confidence change the upper and lower bounds of the confidence intervals (CIs)?
  3. Similarly, comparing the first line with few numbers of matched pairs in the TOTAL column to the third line with more, how does the sample size affect how you interpret your results?
Close that file, open up the point_stat_run1_360000L_20070331_120000V_fho.txt FHO file, and note the following:
vi point_stat_run1_360000L_20070331_120000V_fho.txt
  • The columns prior to LINE_TYPE contain the same data as the previous file we viewed.
  • The LINE_TYPE column indicates that these are FHO forecast-hit-observation rate lines.
  • The remaining columns are similar to the contingency table output and contain the total number of matched pairs, the forecast rate, the hit rate, and observation rate.
  • The forecast, hit, and observation rates should back up your answer to the third question about the contingency table output.
Close that file, open up the point_stat_run1_360000L_20070331_120000V_mpr.txt MPR file, and note the following:
vi point_stat_run1_360000L_20070331_120000V_mpr.txt
  • The columns prior to LINE_TYPE contain the same data as the previous file we viewed.
  • The LINE_TYPE column indicates that these are MPR matched pair lines.
  • The remaining columns are similar to the contingency table output and contain the total number of matched pairs, the matched pair index, the latitude, longitude, and elevation of the observation, the forecasted value, the observed value, and the climatological value (if applicable).
  • There is a lot of data here and it is recommended that the MPR line_type is used only to verify the tool is working properly.

Reconfigure

Reconfigure cindyhg Tue, 06/25/2019 - 09:44

Point-Stat Tool: Reconfigure

Now we'll reconfigure and rerun Point-Stat.

Start by making a copy of the configuration file we just used:
cp PointStatConfig_tutorial_run1 PointStatConfig_tutorial_run2

This time, we'll use two dictionary entries to specify the forecast field in order to set different thresholds for each vertical level. Point-Stat may be configured to verify as many or as few model variables and vertical levels as you desire.

Edit the PointStatConfig_tutorial_run2 file as follows:
vi PointStatConfig_tutorial_run2
  • Set:
    fcst = {
       field = [
        {
          name       = "TMP";
          level      = [ "Z2" ];
          cat_thresh = [ >273, >278, >283, >288 ];
        },
        {
          name       = "TMP";
          level      = [ "P750-850" ];
          cat_thresh = [ >278 ];
        }
      ];
    }
    obs = fcst;

    to verify 2-meter temperature and temperature fields between 750hPa and 850hPa, using the thresholds specified.

  • Set:
     message_type = ["ADPUPA","ADPSFC"]
     sid_inc = [];
     sid_exc = [];
     obs_quality = [];
     duplicate_flag = NONE;
     obs_summary = NONE;
     obs_perc_value = 50;

    to include the Upper Air (UPA) and Surface (SFC) observations in the evaluation

  • Set:
    mask = {
       grid  = [ "G212" ];
       poly  = [ "MET_BASE/poly/EAST.poly",
                 "MET_BASE/poly/WEST.poly" ];
       sid   = [];
       llpnt = [];
    }

    to compute statistics over the NCEP Grid 212 region and over the Eastern and Western United States, as defined by the polylines specified.

  • Set:
    interp = {
       vld_thresh = 1.0;
       shape       = SQUARE;
       type = [
          {
             method = NEAREST;
             width  = 1;
          },
          {
             method = DW_MEAN;
             width  = 5;
          }
       ];
    }

    to indicate that the forecast values should be interpolated to the observation locations using the nearest neighbor method and by computing a distance-weighted average of the forecast values over the 5 by 5 box surrounding the observation location.

  • Set:
    output_flag = {
       fho    = BOTH;
       ctc    = BOTH;
       cts    = BOTH;
       mctc   = NONE;
       mcts   = NONE;
       cnt    = BOTH;
       sl1l2  = BOTH;
       sal1l2 = NONE;
       vl1l2  = NONE;
       val1l2 = NONE;
       pct    = NONE;
       pstd   = NONE;
       pjc    = NONE;
       prc    = NONE;
       ecnt   = NONE;
       eclv   = BOTH;
       mpr    = BOTH;
    }

    to switch the SL1L2 and CTS output to BOTH and generate the optional ASCII output files for them.

  • Set:
    output_prefix = "run2";

    to customize the output file names for this run.

Let's look at our configuration selections and figure out the number of verification tasks Point-Stat will perform:
  • 2 fields: TMP/Z2 and TMP/P750-850
  • 2 observing message types: ADPUPA and ADPSFC
  • 3 masking regions: G212, EAST.poly, and WEST.poly
  • 2 interpolations: UW_MEAN width 1 (nearest-neighbor) and DW_MEAN width 5

Multiplying 2 * 2 * 3 * 2 = 24. So in this example, Point-Stat will accumulate matched forecast/observation pairs into 24 groups. However, some of these groups will result in 0 matched pairs being found. To each non-zero group, the specified threshold(s) will be applied to compute contingency tables.

Can you diagnose why some of these verification tasks resulted in zero matched pairs? (Hint: Reread the tip two pages back!)

Rerun

Rerun cindyhg Tue, 06/25/2019 - 09:45

Point-Stat Tool: Rerun

Next, run Point-Stat to compare a GRIB forecast to the NetCDF point observation output of the PB2NC tool, as opposed to the much smaller ASCII2NC output we used in the first run.
 

Run the following command line:
point_stat \
${METPLUS_DATA}/met_test/data/sample_fcst/2007033000/nam.t00z.awip1236.tm00.20070330.grb \
../pb2nc/tutorial_pb_run1.nc \
PointStatConfig_tutorial_run2 \
-outdir . \
-v 2

Point-Stat is now performing the verification tasks we requested in the configuration file. It should take a minute or two to run. You should see several status messages printed to the screen to indicate progress. Note the number of matched pairs found for each verification task, some of which are 0.

Plot-Data-Plane Tool

In this step, we have verified 2-meter temperature. The Plot-Data-Plane tool within MET provides a way to visualize the gridded data fields that MET can read.

Run this utility to plot the 2-meter temperature field:
plot_data_plane \
${METPLUS_DATA}/met_test/data/sample_fcst/2007033000/nam.t00z.awip1236.tm00.20070330.grb \
nam.t00z.awip1236.tm00.20070330_TMPZ2.ps \
'name="TMP"; level="Z2";'

Plot-Data-Plane requires an input gridded data file, an output postscript image file name, and a configuration string defining which 2-D field is to be plotted.

View the output by running:
display nam.t00z.awip1236.tm00.20070330_TMPZ2.ps &
View the usage for Plot-Data-Plane by running it with no arguments or using the --help option:
plot_data_plane --help
Now rerun this Plot-Data-Plane command but...
  1. Set the title to 2-m Temperature.
  2. Set the plotting range as 250 to 305.
  3. Use the color table named ${MET_BUILD_BASE}/share/met/colortables/NCL_colortables/wgne15.ctable

Next, we'll take a look at the Point-Stat output we just generated.

See the usage statement for all MET tools using the --help command line option or with no options at all.

Output

Output cindyhg Tue, 06/25/2019 - 09:46

Point-Stat Tool: Output

The format for the CTC, CTS, and CNT line types are the same. However, the numbers will be different as we used a different set of observations for the verification.

Open up the point_stat_run2_360000L_20070331_120000V_cts.txt CTS file, and note the following:
vi point_stat_run2_360000L_20070331_120000V_cts.txt
  • The columns prior to LINE_TYPE contain header information.
  • The LINE_TYPE column indicates that these are CTS lines.
  • The remaining columns contain statistics derived from the threshold contingency table counts. See the point_stat output section of the MET User's Guide for a thorough description of the output.
  • Confidence intervals are given for each of these statistics, computed using either one or two methods. The columns ending in _NCL(normal confidence lower) and _NCU (normal confidence upper) give lower and upper confidence limits computed using assumptions of normality. The columns ending in _BCL (bootstrap confidence lower) and _BCU (bootstrap confidence upper) give lower and upper confidence limits computed using bootstrapping.
Close that file, open up the point_stat_run2_360000L_20070331_120000V_sl1l2.txt SL1L2 partial sums file, and note the following:
vi point_stat_run2_360000L_20070331_120000V_sl1l2.txt
  • The columns prior to LINE_TYPE contain header information.
  • The LINE_TYPE column indicates these are SL1L2 partial sums lines.

Lastly, the point_stat_run2_360000L_20070331_120000V.stat file contains all of the same data we just viewed but in a single file. The Stat-Analysis tool, which we'll use later in this tutorial, searches for the .stat output files by default but can also read the .txt output files.

vi point_stat_run2_360000L_20070331_120000V.stat

METplus Use Case: PointStat

METplus Use Case: PointStat cindyhg Tue, 06/25/2019 - 09:53
IMPORTANT NOTE: If you are returning to the tutorial, you must source the tutorial setup script before running the following instructions. If you are unsure if you have done this step, please navigate to the Verify Environment is Set Correctly page.

METplus Use Case: PointStat

This use case utilizes the MET Point-Stat tool. 

Optional: Refer to the MET Users Guide for a description of the MET tools used in this use case.
Optional: Refer to the METplus Config Glossary section of the METplus Users Guide for a reference to METplus variables used in this use case.

  1. View Configuration File
Change to the ${METPLUS_TUTORIAL_DIR} directory:
cd ${METPLUS_TUTORIAL_DIR}
Define a unique directory under output that you will use for this use case. Create a configuration file to override OUTPUT_BASE to that directory.
vi ${METPLUS_BUILD_BASE}/parm/use_cases/met_tool_wrapper/PointStat/PointStat.conf

In the [dir] section the forecast and observations directories are specified in relation to INPUT_BASE (${METPLUS_DATA}), while the output directory is given in relation to {OUTPUT_BASE} (${METPLUS_TUTORIAL_DIR}/output).

FCST_POINT_STAT_INPUT_DIR = {INPUT_BASE}/met_test/data/sample_fcst
OBS_POINT_STAT_INPUT_DIR = {INPUT_BASE}/met_test/out/pb2nc
...
POINT_STAT_OUTPUT_DIR = {OUTPUT_BASE}/point_stat

Using the PointStat configuration file, you should be able to run the use case using the sample input data set without any other changes.

  1. Run the PointStat use case:
run_metplus.py \
${METPLUS_BUILD_BASE}/parm/use_cases/met_tool_wrapper/PointStat/PointStat.conf \
${METPLUS_TUTORIAL_DIR}/tutorial.conf \
config.OUTPUT_BASE=${METPLUS_TUTORIAL_DIR}/output/PointStat
  1. Review the output files:
ls ${METPLUS_TUTORIAL_DIR}/output/PointStat/point_stat

The following is the statistical output and files are generated from the command:

  • point_stat_360000L_20070331_120000V.stat
  1. Update configuration file and re-run
Copy the configuration file to the user_config directory and open for editing:
cp ${METPLUS_BUILD_BASE}/parm/use_cases/met_tool_wrapper/PointStat/PointStat.conf ${METPLUS_TUTORIAL_DIR}/user_config/PointStat_tutorial.conf
vi ${METPLUS_TUTORIAL_DIR}/user_config/PointStat_tutorial.conf
Update the POINT_STAT_OUTPUT_PREFIX and consolidate the FCST_VAR and OBS_VAR settings into BOTH_VAR being they are identical.
POINT_STAT_OUTPUT_PREFIX = run2

BOTH_VAR1_NAME = TMP
BOTH_VAR1_LEVELS = P750-900
BOTH_VAR1_THRESH = <=273, >273
 
BOTH_VAR2_NAME = UGRD
BOTH_VAR2_LEVELS = Z10
BOTH_VAR2_THRESH = >=5
 
BOTH_VAR3_NAME = VGRD
BOTH_VAR3_LEVELS = Z10
BOTH_VAR3_THRESH = >=5

  1. Rerun the use-case and compare the output
run_metplus.py \
${METPLUS_TUTORIAL_DIR}/user_config/PointStat_tutorial.conf \
${METPLUS_TUTORIAL_DIR}/tutorial.conf \
config.OUTPUT_BASE=${METPLUS_TUTORIAL_DIR}/output/PointStat
Diff the original output file with run2. They should be identical.
diff \
${METPLUS_TUTORIAL_DIR}/output/PointStat/point_stat/point_stat_360000L_20070331_120000V.stat \
${METPLUS_TUTORIAL_DIR}/output/PointStat/point_stat/point_stat_run2_360000L_20070331_120000V.stat

Additional Exercises

Additional Exercises

End of Practical Session 2

Congratulations! You have completed Session 2!

If you have extra time, you may want to try this additional METplus exercise.

The default statistics created by this use case only dump the partial sums, so we will be also modifying the MET configuration file to add the continuous statistics to the output. There is a little more setup in this use case, which will be instructive and demonstrate the basic structure, flexibility and setup of METplus configuration.

Instructions: Copy and modify the METplus configuration file for Upper Air to write Continuous statistics (cnt) and the Vector Continuous Statistics (vcnt) line types to both the stat file and its own file.
Copy the PointStat.conf file to the user_config directory.
cp ${METPLUS_BUILD_BASE}/parm/use_cases/met_tool_wrapper/PointStat/PointStat.conf \
${METPLUS_TUTORIAL_DIR}/user_config/PointStat_add_linetype.conf
Edit the file to remove the # character from the beginning of the variables (this uncomments the line) and set the values to BOTH.
Change this line (around line 68):
#POINT_STAT_OUTPUT_FLAG_CNT =

to

POINT_STAT_OUTPUT_FLAG_CNT = BOTH
and change this line (around line 73):
#POINT_STAT_OUTPUT_FLAG_VCNT =

to

POINT_STAT_OUTPUT_FLAG_VCNT = BOTH
vi ${METPLUS_TUTORIAL_DIR}/user_config/PointStat_add_linetype.conf
Rerun METplus and use config.OUTPUT_BASE to change the output directory from the command line:
run_metplus.py \
${METPLUS_TUTORIAL_DIR}/user_config/PointStat_add_linetype.conf \
${METPLUS_TUTORIAL_DIR}/tutorial.conf \
config.OUTPUT_BASE=${METPLUS_TUTORIAL_DIR}/output/PointStatAddLinetype
Review the additional output files generated under ${METPLUS_TUTORIAL_DIR}/output/PointStatAddLinetype/point_stat
point_stat_360000L_20070331_120000V.stat
point_stat_360000L_20070331_120000V_cnt.txt
point_stat_360000L_20070331_120000V_vcnt.txt
Open the stat file and notice there are two more linetypes, cnt and vcnt.
cindyhg Tue, 06/25/2019 - 09:55