Note

Go to the end to download the full example code.

PointStat: Compare community observed precipitation to model forecasts

model_applications/precipitation/PointStat_fcstURMA_obsCOCORAHS_ASCIIprecip.conf

Scientific Objective

This use case ingests a CoCoRaHS csv file, a new dataset that utilizes community reporting of precipitation amounts. Numerous studies have shown that a community approach to weather observations not only covers areas that lack traditional verification datasets, but is also remarkably quality controlled. Utilizing Python embedding, this use case taps into a new vital observation dataset and compares it to a 24 hour precipitation accumulation forecast.

Version Added

METplus version 5.0

Datasets

Forecast: 24 UnRestricted Mesoscale Analysis (URMA) 1 hour precipitation accumulation files

Observations: CoCoRaHS, the Community Collaborative Rain, Hail, and Snow Network

Climatology: None

Location: All of the input data required for this use case can be found in a sample data tarball. Each use case category will have one or more sample data tarballs. It is only necessary to download the tarball with the use case’s dataset and not the entire collection of sample data. Click here to access the METplus releases page and download sample data for the appropriate release: https://github.com/dtcenter/METplus/releases This tarball should be unpacked into the directory that you will set the value of INPUT_BASE. See Running METplus section for more information.

METplus Components

This use case calls a Python script in ASCII2NC for the observation dataset. PCPCombine is called for a user-defined summation of the forecast accumulation fields. Finally, PointStat processes the forecast and observation fields, and outputs the requested line types.

METplus Workflow

Beginning time (VALID_BEG): 2022091423

End time (VALID_END): 2022091423

Increment between beginning and end times (VALID_INCREMENT): 1M

Sequence of forecast leads to process (LEAD_SEQ): 24H

1 csv file of multiple valid observation times is passed to ASCII2NC via Python embedding, resulting in a netCDF output. 24 forecast files, each composed of 1 hour precipitation accumulation forecasts, is summarized via PCPCombine. The following boundary times are used for the forecast summation times:

Valid Beg: 2022-09-14 at 00z
Valid End: 2022-09-14 at 23z

The observation data point span the same times as the 24 hour forecast accumulation summation. Finally, PointStat is used to compare the two new fields (point data in netCDF and precipitation accumulation over 24 hours). Because the Valid Time used in configuration file is set to one time (2022-09-14 at 23z) and the precipitation accumulation valid time is set to this same time, the observation window spans across the entire 2022-09-14 24 hour timeframe.

METplus Configuration

METplus first loads all of the configuration files found in parm/metplus_config, then it loads any configuration files passed to METplus via the command line, i.e. parm/use_cases/model_applications/precipitation/PointStat_fcstURMA_obsCOCORAHS_ASCIIprecip.conf

[config]

# Documentation for this use case can be found at
# https://metplus.readthedocs.io/en/latest/generated/met_tool_wrapper/PointStat/PointStat.html

# For additional information, please see the METplus Users Guide.
# https://metplus.readthedocs.io/en/latest/Users_Guide

###
# Processes to run
# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#process-list
###

PROCESS_LIST = ASCII2NC, PCPCombine, PointStat


###
# Time Info
# LOOP_BY options are INIT, VALID, RETRO, and REALTIME
# If set to INIT or RETRO:
#   INIT_TIME_FMT, INIT_BEG, INIT_END, and INIT_INCREMENT must also be set
# If set to VALID or REALTIME:
#   VALID_TIME_FMT, VALID_BEG, VALID_END, and VALID_INCREMENT must also be set
# LEAD_SEQ is the list of forecast leads to process
# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#timing-control
###

LOOP_BY = VALID
VALID_TIME_FMT = %Y%m%d%H
VALID_BEG = 2022091423
VALID_END = 2022091423
VALID_INCREMENT = 1M

LEAD_SEQ = 24H


###
# File I/O
# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#directory-and-filename-template-info
###


ASCII2NC_INPUT_DIR =
ASCII2NC_INPUT_TEMPLATE = "{PARM_BASE}/use_cases/model_applications/precipitation/PointStat_fcstURMA_obsCOCORAHS_ASCIIprecip/read_cocorahs_point.py {INPUT_BASE}/model_applications/precipitation/PointStat_fcstURMA_obsCOCORAHS_ASCIIprecip/CoCoRaHS.{valid?fmt=%Y%m%d}.DailyPrecip.csv"

ASCII2NC_OUTPUT_DIR =
ASCII2NC_OUTPUT_TEMPLATE = {OUTPUT_BASE}/ASCII2NC/precip_{valid?fmt=%Y%m%d}_summary.nc

ASCII2NC_SKIP_IF_OUTPUT_EXISTS = False

ASCII2NC_FILE_WINDOW_BEGIN = 0
ASCII2NC_FILE_WINDOW_END = 0


FCST_PCP_COMBINE_RUN = True

FCST_PCP_COMBINE_INPUT_DIR = {INPUT_BASE}/model_applications/precipitation/PointStat_fcstURMA_obsCOCORAHS_ASCIIprecip
FCST_PCP_COMBINE_INPUT_TEMPLATE = {lead?fmt=%HH}

FCST_PCP_COMBINE_OUTPUT_DIR = {OUTPUT_BASE}/PCPCombine
FCST_PCP_COMBINE_OUTPUT_TEMPLATE = fcst_24hr_precip.nc


FCST_POINT_STAT_INPUT_DIR = {FCST_PCP_COMBINE_OUTPUT_DIR}
FCST_POINT_STAT_INPUT_TEMPLATE = {FCST_PCP_COMBINE_OUTPUT_TEMPLATE}

OBS_POINT_STAT_INPUT_DIR = {OUTPUT_BASE}/ASCII2NC
OBS_POINT_STAT_INPUT_TEMPLATE = precip_{valid?fmt=%Y%m%d}_summary.nc

POINT_STAT_OUTPUT_DIR = {OUTPUT_BASE}/PointStat

POINT_STAT_CLIMO_MEAN_INPUT_DIR =
POINT_STAT_CLIMO_MEAN_INPUT_TEMPLATE =

POINT_STAT_CLIMO_STDEV_INPUT_DIR =
POINT_STAT_CLIMO_STDEV_INPUT_TEMPLATE =

###
# ASCII2NC Settings
# https://metplus.readthedocs.io/en/latest/Users_Guide/wrappers.html#ascii2nc
###

#LOG_ASCII2NC_VERBOSITY = 1
#ASCII2NC_CONFIG_FILE =

ASCII2NC_WINDOW_BEGIN = 0
ASCII2NC_WINDOW_END = 0

ASCII2NC_INPUT_FORMAT = python

ASCII2NC_MASK_GRID =
ASCII2NC_MASK_POLY =
ASCII2NC_MASK_SID =

ASCII2NC_TIME_SUMMARY_FLAG = False
ASCII2NC_TIME_SUMMARY_RAW_DATA = False
ASCII2NC_TIME_SUMMARY_BEG = 000000
ASCII2NC_TIME_SUMMARY_END = 235959
ASCII2NC_TIME_SUMMARY_STEP = 300
ASCII2NC_TIME_SUMMARY_WIDTH = 600
ASCII2NC_TIME_SUMMARY_GRIB_CODES = 
ASCII2NC_TIME_SUMMARY_VAR_NAMES = APCP
ASCII2NC_TIME_SUMMARY_TYPES = min, max, range, mean, stdev, median, p80
ASCII2NC_TIME_SUMMARY_VALID_FREQ = 0
ASCII2NC_TIME_SUMMARY_VALID_THRESH = 0.0

###
# PCPCombine Settings
# https://metplus.readthedocs.io/en/latest/Users_Guide/wrappers.html#pcpcombine
###

FCST_PCP_COMBINE_METHOD = USER_DEFINED

FCST_PCP_COMBINE_COMMAND = -sum 00000000_000000 1 20220914_230000 24 {FCST_PCP_COMBINE_OUTPUT_DIR}/{FCST_PCP_COMBINE_OUTPUT_TEMPLATE} -pcpdir {FCST_PCP_COMBINE_INPUT_DIR}

#LOG_PCP_COMBINE_VERBOSITY = 2

FCST_IS_PROB = false

FCST_PCP_COMBINE_INPUT_DATATYPE = GRIB

FCST_PCP_COMBINE_INPUT_ACCUMS = 1H
FCST_PCP_COMBINE_INPUT_NAMES = APCP
FCST_PCP_COMBINE_INPUT_LEVELS = L0

FCST_PCP_COMBINE_OUTPUT_ACCUM = 24

###
# Field Info
# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#field-info
###

POINT_STAT_ONCE_PER_FIELD = False

#POINT_STAT_FCST_FILE_TYPE =
#POINT_STAT_OBS_FILE_TYPE =

FCST_POINT_STAT_VAR1_NAME = APCP_24
FCST_POINT_STAT_VAR1_LEVELS = L0
#FCST_VAR1_THRESH = <=273, >273
OBS_POINT_STAT_VAR1_NAME = TotalPrecipAmt
OBS_POINT_STAT_VAR1_LEVELS = L0
#OBS_VAR1_THRESH = <=273, >273
BOTH_POINT_STAT_VAR1_THRESH = <=6.35, <=12.7, <=25.4

###
# PointStat Settings
# https://metplus.readthedocs.io/en/latest/Users_Guide/wrappers.html#pointstat
###

#LOG_POINT_STAT_VERBOSITY = 2

POINT_STAT_CONFIG_FILE ={PARM_BASE}/met_config/PointStatConfig_wrapped

#POINT_STAT_OBS_QUALITY_INC = 1, 2, 3
#POINT_STAT_OBS_QUALITY_EXC =

#POINT_STAT_CLIMO_MEAN_TIME_INTERP_METHOD = NEAREST
#POINT_STAT_CLIMO_STDEV_TIME_INTERP_METHOD =

#POINT_STAT_INTERP_VLD_THRESH =
#POINT_STAT_INTERP_SHAPE =
#POINT_STAT_INTERP_TYPE_METHOD = BILIN
#POINT_STAT_INTERP_TYPE_WIDTH = 2

#POINT_STAT_OUTPUT_FLAG_FHO =
POINT_STAT_OUTPUT_FLAG_CTC = BOTH
POINT_STAT_OUTPUT_FLAG_CTS = BOTH
#POINT_STAT_OUTPUT_FLAG_MCTC =
POINT_STAT_OUTPUT_FLAG_MCTS = BOTH
POINT_STAT_OUTPUT_FLAG_CNT = BOTH
#POINT_STAT_OUTPUT_FLAG_SL1L2 = STAT
#POINT_STAT_OUTPUT_FLAG_SAL1L2 =
#POINT_STAT_OUTPUT_FLAG_VL1L2 = STAT
#POINT_STAT_OUTPUT_FLAG_VAL1L2 =
#POINT_STAT_OUTPUT_FLAG_VCNT =
#POINT_STAT_OUTPUT_FLAG_PCT =
#POINT_STAT_OUTPUT_FLAG_PSTD =
#POINT_STAT_OUTPUT_FLAG_PJC =
#POINT_STAT_OUTPUT_FLAG_PRC =
#POINT_STAT_OUTPUT_FLAG_ECNT =
#POINT_STAT_OUTPUT_FLAG_RPS =
#POINT_STAT_OUTPUT_FLAG_ECLV =
#POINT_STAT_OUTPUT_FLAG_MPR =
#POINT_STAT_OUTPUT_FLAG_ORANK =

#POINT_STAT_CLIMO_CDF_BINS = 1
#POINT_STAT_CLIMO_CDF_CENTER_BINS = False
#POINT_STAT_CLIMO_CDF_WRITE_BINS = True
#POINT_STAT_CLIMO_CDF_DIRECT_PROB =

#POINT_STAT_HSS_EC_VALUE =

OBS_POINT_STAT_WINDOW_BEGIN = -82800
OBS_POINT_STAT_WINDOW_END = 3600

POINT_STAT_OFFSETS = 0

MODEL = URMA

POINT_STAT_DESC = CoCoRaHS
OBTYPE =

POINT_STAT_REGRID_TO_GRID = NONE
POINT_STAT_REGRID_METHOD = BILIN
POINT_STAT_REGRID_WIDTH = 2

POINT_STAT_OUTPUT_PREFIX =

#POINT_STAT_OBS_VALID_BEG = {valid?fmt=%Y%m%d_%H}
#POINT_STAT_OBS_VALID_END = {valid?fmt=%Y%m%d_%H}

POINT_STAT_MASK_GRID = FULL
POINT_STAT_MASK_POLY = 
POINT_STAT_MASK_SID =
#POINT_STAT_MASK_LLPNT =

POINT_STAT_MESSAGE_TYPE = ADPSFC

#POINT_STAT_HIRA_FLAG =
#POINT_STAT_HIRA_WIDTH =
#POINT_STAT_HIRA_VLD_THRESH =
#POINT_STAT_HIRA_COV_THRESH =
#POINT_STAT_HIRA_SHAPE =
#POINT_STAT_HIRA_PROB_CAT_THRESH =

#POINT_STAT_MESSAGE_TYPE_GROUP_MAP =

MET Configuration

METplus sets environment variables based on user settings in the METplus configuration file. See How METplus controls MET config file settings for more details.

YOU SHOULD NOT SET ANY OF THESE ENVIRONMENT VARIABLES YOURSELF! THEY WILL BE OVERWRITTEN BY METPLUS WHEN IT CALLS THE MET TOOLS!

If there is a setting in the MET configuration file that is currently not supported by METplus you’d like to control, please refer to: Overriding Unsupported MET config file settings

Ascii2NcConfig_wrapped
////////////////////////////////////////////////////////////////////////////////
//
// Default ascii2nc configuration file
//
////////////////////////////////////////////////////////////////////////////////

//
// The parameters listed below are used to summarize the ASCII data read in
//

//
// Time periods for the summarization
// obs_var (string array) is added and works like grib_code (int array)
// when the obs name is given instead of grib_code
//
${METPLUS_TIME_SUMMARY_DICT}

//
// Mapping of input little_r report types to output message types
//
message_type_map = [
   { key = "FM-12 SYNOP";  val = "ADPSFC"; },
   { key = "FM-13 SHIP";   val = "SFCSHP"; },
   { key = "FM-15 METAR";  val = "ADPSFC"; },
   { key = "FM-18 BUOY";   val = "SFCSHP"; },
   { key = "FM-281 QSCAT"; val = "ASCATW"; },
   { key = "FM-32 PILOT";  val = "ADPUPA"; },
   { key = "FM-35 TEMP";   val = "ADPUPA"; },
   { key = "FM-88 SATOB";  val = "SATWND"; },
   { key = "FM-97 ACARS";  val = "AIRCFT"; }
];

//
// Indicate a version number for the contents of this configuration file.
// The value should generally not be modified.
//
//version = "V10.0";

tmp_dir = "${MET_TMP_DIR}";

${METPLUS_MET_CONFIG_OVERRIDES}
PointStatConfig_wrapped
////////////////////////////////////////////////////////////////////////////////
//
// Point-Stat configuration file.
//
// For additional information, see the MET_BASE/config/README file.
//
////////////////////////////////////////////////////////////////////////////////

//
// Output model name to be written
//
// model =
${METPLUS_MODEL}

//
// Output description to be written
// May be set separately in each "obs.field" entry
//
// desc =
${METPLUS_DESC}

////////////////////////////////////////////////////////////////////////////////

//
// Verification grid
//
// regrid = {
${METPLUS_REGRID_DICT}

////////////////////////////////////////////////////////////////////////////////

//
// May be set separately in each "field" entry
//
censor_thresh = [];
censor_val    = [];
cat_thresh    = [ NA ];
cnt_thresh    = [ NA ];
cnt_logic     = UNION;
wind_thresh   = [ NA ];
wind_logic    = UNION;
eclv_points   = 0.05;
//hss_ec_value =
${METPLUS_HSS_EC_VALUE}
rank_corr_flag = FALSE;

//
// Forecast and observation fields to be verified
//
fcst = {
  ${METPLUS_FCST_FILE_TYPE}
  //field = [
  ${METPLUS_FCST_FIELD}
  ${METPLUS_FCST_CLIMO_MEAN_DICT}
  ${METPLUS_FCST_CLIMO_STDEV_DICT}
}

obs = {
  ${METPLUS_OBS_FILE_TYPE}
  //field = [
  ${METPLUS_OBS_FIELD}
  ${METPLUS_OBS_CLIMO_MEAN_DICT}
  ${METPLUS_OBS_CLIMO_STDEV_DICT}
}
////////////////////////////////////////////////////////////////////////////////

//
// Point observation filtering options
// May be set separately in each "obs.field" entry
//
// message_type =
${METPLUS_MESSAGE_TYPE}
sid_exc        = [];

//obs_quality_inc =
${METPLUS_OBS_QUALITY_INC}

//obs_quality_exc =
${METPLUS_OBS_QUALITY_EXC}

//duplicate_flag =
${METPLUS_DUPLICATE_FLAG}

//obs_summary =
${METPLUS_OBS_SUMMARY}

//obs_perc_value =
${METPLUS_OBS_PERC_VALUE}

//
// Mapping of message type group name to comma-separated list of values.
//
//message_type_group_map =
${METPLUS_MESSAGE_TYPE_GROUP_MAP}

//obtype_as_group_val_flag =
${METPLUS_OBTYPE_AS_GROUP_VAL_FLAG}

////////////////////////////////////////////////////////////////////////////////

//
// Climatology data
//
//climo_mean = {
${METPLUS_CLIMO_MEAN_DICT}


//climo_stdev = {
${METPLUS_CLIMO_STDEV_DICT}

//
// May be set separately in each "obs.field" entry
//
//climo_cdf = {
${METPLUS_CLIMO_CDF_DICT}

////////////////////////////////////////////////////////////////////////////////

//
// Land/Sea mask
// For LANDSF message types, only use forecast grid points where land = TRUE.
// For WATERSF message types, only use forecast grid points where land = FALSE.
// land_mask.flag may be set separately in each "obs.field" entry.
//
//land_mask = {
${METPLUS_LAND_MASK_DICT}

//
// Topography
// For SURFACE message types, only use observations where the topo - station
// elevation difference meets the use_obs_thresh threshold.
// For the observations kept, when interpolating forecast data to the
// observation location, only use forecast grid points where the topo - station
// difference meets the interp_fcst_thresh threshold.
// topo_mask.flag may be set separately in each "obs.field" entry.
//
//topo_mask = {
${METPLUS_TOPO_MASK_DICT}

////////////////////////////////////////////////////////////////////////////////

//
// Point observation time window
//
// obs_window = {
${METPLUS_OBS_WINDOW_DICT}

////////////////////////////////////////////////////////////////////////////////

//
// Verification masking regions
//
//mask = {
${METPLUS_MASK_DICT}

////////////////////////////////////////////////////////////////////////////////

//
// Confidence interval settings
//
ci_alpha  = [ 0.05 ];

boot = {
   interval = PCTILE;
   rep_prop = 1.0;
   n_rep    = 0;
   rng      = "mt19937";
   seed     = "";
}

////////////////////////////////////////////////////////////////////////////////

//
// Interpolation methods
//
//interp = {
${METPLUS_INTERP_DICT}

////////////////////////////////////////////////////////////////////////////////

//
// HiRA verification method
//
//hira = {
${METPLUS_HIRA_DICT}

////////////////////////////////////////////////////////////////////////////////
// Threshold for SEEPS p1 (Probability of being dry)

//seeps_p1_thresh =
${METPLUS_SEEPS_P1_THRESH}

////////////////////////////////////////////////////////////////////////////////

//
// Statistical output types
//
//output_flag = {
${METPLUS_OUTPUT_FLAG_DICT}

////////////////////////////////////////////////////////////////////////////////

//ugrid_dataset =
${METPLUS_UGRID_DATASET}

//ugrid_max_distance_km =
${METPLUS_UGRID_MAX_DISTANCE_KM}

//ugrid_coordinates_file =
${METPLUS_UGRID_COORDINATES_FILE}

////////////////////////////////////////////////////////////////////////////////

//point_weight_flag =
${METPLUS_POINT_WEIGHT_FLAG}

tmp_dir = "${MET_TMP_DIR}";

// output_prefix =
${METPLUS_OUTPUT_PREFIX}
//version        = "V10.0.0";

////////////////////////////////////////////////////////////////////////////////

${METPLUS_MET_CONFIG_OVERRIDES}

Python Embedding

This use case does not use Python embedding.

User Scripting

User Scripting is not used in this use case.

Running METplus

Pass the use case configuration file to the run_metplus.py script along with any user-specific system configuration files if desired:

run_metplus.py /path/to/METplus/parm/use_cases/model_applications/precipitation/PointStat_fcstURMA_obsCOCORAHS_ASCIIprecip.conf /path/to/user_system.conf

See Running METplus for more information.

Expected Output

A successful run will output the following both to the screen and to the logfile:

INFO: METplus has successfully finished running.

Refer to the value set for OUTPUT_BASE to find where the output data was generated. Output for the use case will be found in 3 folders(relative to OUTPUT_BASE). Those folders are:

  • ASCII2NC

  • PCPCombine

  • PointStat

The ASCII2NC folder will contain one file from the ASCII2NC tool call:

  • precip_20220914_summary.nc

The PCPCombine folder will also contain one file, from the PCPCombine call:

  • fcst_24hr_precip.nc

The final folder, PointStat, contains all of the following output from the PointStat call:

  • point_stat_000000L_20220914_230000V_cnt.txt

  • point_stat_000000L_20220914_230000V_ctc.txt

  • point_stat_000000L_20220914_230000V_cts.txt

  • point_stat_000000L_20220914_230000V_mcts.txt

  • point_stat_000000L_20220914_230000V.stat

Keywords

Note

  • PointStatToolUseCase

  • ASCII2NCToolUseCase

  • PCPCombineToolUseCase

  • PythonEmbeddingFileUseCase

  • PrecipitationAppUseCase

  • NETCDFFileUseCase

Navigate to the METplus Quick Search for Use Cases page to discover other similar use cases.

Gallery generated by Sphinx-Gallery