TCGen: Basic Use Case

met_tool_wrapper/TCGen/TCGen.conf

Scientific Objective

The TC-Gen tool provides verification of tropical cyclone genesis forecasts in ATCF file format.

Datasets

Track: A Deck or B Deck (Best)
Genesis: Genesis Forecast
Location: All of the input data required for this use case can be found in the met_tool_wrapper sample data tarball. Click here to the METplus releases page and download sample data for the appropriate release: https://github.com/dtcenter/METplus/releases
The 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 utilizes the METplus TCGen wrapper to search for files that match wildcard expressions and generate a command to run the MET tool tc_gen.

METplus Workflow

TCGen is the only tool called in this example. It processes the following run times:

Init: 2016

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 with the -c option, i.e. -c /path/to/TCGen.conf

[config]

# Documentation for this use case can be found at
# https://metplus.readthedocs.io/en/latest/generated/met_tool_wrapper/TCGen/TCGen.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 = TCGen


###
# 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 = INIT

INIT_TIME_FMT = %Y
INIT_BEG = 2016

LEAD_SEQ =

TC_GEN_CUSTOM_LOOP_LIST =


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

TC_GEN_TRACK_INPUT_DIR = {INPUT_BASE}/met_test/tc_data/genesis/atcf
TC_GEN_TRACK_INPUT_TEMPLATE = {init?fmt=%Y}/*.dat

TC_GEN_GENESIS_INPUT_DIR = {INPUT_BASE}/met_test/tc_data/genesis/suite1
TC_GEN_GENESIS_INPUT_TEMPLATE = {init?fmt=%Y}*/genesis*{init?fmt=%Y}*

#TC_GEN_EDECK_INPUT_DIR =
#TC_GEN_EDECK_INPUT_TEMPLATE =

#TC_GEN_SHAPE_INPUT_DIR =
#TC_GEN_SHAPE_INPUT_TEMPLATE =

TC_GEN_OUTPUT_DIR = {OUTPUT_BASE}/met_tool_wrapper/TCGen
TC_GEN_OUTPUT_TEMPLATE = tc_gen_{init?fmt=%Y}


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


###
# TCGen Settings
# https://metplus.readthedocs.io/en/latest/Users_Guide/wrappers.html#tcgen
###

#LOG_TC_GEN_VERBOSITY = 2

TC_GEN_CONFIG_FILE = {PARM_BASE}/met_config/TCGenConfig_wrapped

TC_GEN_INIT_FREQ = 6

TC_GEN_VALID_FREQ = 6

TC_GEN_FCST_HR_WINDOW_BEGIN = 6
TC_GEN_FCST_HR_WINDOW_END = 120

TC_GEN_MIN_DURATION = 12

TC_GEN_FCST_GENESIS_VMAX_THRESH = NA
TC_GEN_FCST_GENESIS_MSLP_THRESH = NA

TC_GEN_BEST_GENESIS_TECHNIQUE = BEST
TC_GEN_BEST_GENESIS_CATEGORY = TD, TS
TC_GEN_BEST_GENESIS_VMAX_THRESH = NA
TC_GEN_BEST_GENESIS_MSLP_THRESH = NA

TC_GEN_OPER_TECHNIQUE = CARQ

# TC_GEN_FILTER_<n> sets filter items in the MET configuration file
# quotation marks within quotation marks must be preceeded with \
TC_GEN_FILTER_1 = desc = "AL_BASIN"; vx_mask = "MET_BASE/tc_data/basin_global_tenth_degree.nc { name=\"basin\"; level=\"(*,*)\"; } ==1";
TC_GEN_FILTER_2 = desc = "AL_DLAND_300"; vx_mask = "MET_BASE/tc_data/basin_global_tenth_degree.nc { name=\"basin\"; level=\"(*,*)\"; } ==1"; dland_thresh = >0&&<300;
TC_GEN_FILTER_3 = desc = "EP_CP_BASIN"; vx_mask = "MET_BASE/tc_data/basin_global_tenth_degree.nc { name=\"basin\"; level=\"(*,*)\";} ==2||==3";
TC_GEN_FILTER_4 = desc = "EP_BASIN"; genesis_window = { beg = -3*24; end = 3*24; }; genesis_radius = 300;
TC_GEN_FILTER_5 = desc = "3DAY_300KM"; genesis_window = { beg = -3*24; end = 3*24; }; genesis_radius = 300;
TC_GEN_FILTER_6 = desc = "3DAY_600KM"; genesis_window = { beg = -3*24; end = 3*24; }; genesis_radius = 600;
TC_GEN_FILTER_7 = desc = "5DAY_300KM"; genesis_window = { beg = -5*24; end = 5*24; }; genesis_radius = 300;
TC_GEN_FILTER_8 = desc = "5DAY_600KM"; genesis_window = { beg = -5*24; end = 5*24; }; genesis_radius = 600;

TC_GEN_DESC = ALL

MODEL =

TC_GEN_STORM_ID =

TC_GEN_STORM_NAME =

TC_GEN_INIT_BEG =
TC_GEN_INIT_END =
TC_GEN_INIT_INC =
TC_GEN_INIT_EXC =

TC_GEN_VALID_BEG =
TC_GEN_VALID_END =

TC_GEN_INIT_HOUR =

TC_GEN_VX_MASK =

TC_GEN_BASIN_MASK =

TC_GEN_DLAND_THRESH = NA

TC_GEN_GENESIS_MATCH_RADIUS = 500

#TC_GEN_GENESIS_MATCH_POINT_TO_TRACK = True

#TC_GEN_GENESIS_MATCH_WINDOW_BEG = 0
#TC_GEN_GENESIS_MATCH_WINDOW_END = 0

#TC_GEN_OPS_HIT_WINDOW_BEG = 0
#TC_GEN_OPS_HIT_WINDOW_END = 48

TC_GEN_DEV_HIT_RADIUS = 500

TC_GEN_DEV_HIT_WINDOW_BEGIN = -24
TC_GEN_DEV_HIT_WINDOW_END = 24

TC_GEN_DISCARD_INIT_POST_GENESIS_FLAG = True

TC_GEN_DEV_METHOD_FLAG = True

TC_GEN_OPS_METHOD_FLAG = True

TC_GEN_CI_ALPHA = 0.05

TC_GEN_OUTPUT_FLAG_FHO = NONE
TC_GEN_OUTPUT_FLAG_CTC = BOTH
TC_GEN_OUTPUT_FLAG_CTS = BOTH
TC_GEN_OUTPUT_FLAG_PCT = NONE
TC_GEN_OUTPUT_FLAG_PSTD = NONE
TC_GEN_OUTPUT_FLAG_PJC = NONE
TC_GEN_OUTPUT_FLAG_PRC = NONE
TC_GEN_OUTPUT_FLAG_GENMPR = NONE


TC_GEN_NC_PAIRS_FLAG_LATLON = TRUE
TC_GEN_NC_PAIRS_FLAG_FCST_GENESIS = TRUE
TC_GEN_NC_PAIRS_FLAG_FCST_TRACKS  = TRUE
TC_GEN_NC_PAIRS_FLAG_FCST_FY_OY   = TRUE
TC_GEN_NC_PAIRS_FLAG_FCST_FY_ON   = TRUE
TC_GEN_NC_PAIRS_FLAG_BEST_GENESIS = TRUE
TC_GEN_NC_PAIRS_FLAG_BEST_TRACKS  = TRUE
TC_GEN_NC_PAIRS_FLAG_BEST_FY_OY   = TRUE
TC_GEN_NC_PAIRS_FLAG_BEST_FN_OY   = TRUE

TC_GEN_VALID_MINUS_GENESIS_DIFF_THRESH = NA

TC_GEN_BEST_UNIQUE_FLAG = TRUE

TC_GEN_DLAND_FILE = MET_BASE/tc_data/dland_global_tenth_degree.nc

TC_GEN_BASIN_FILE = MET_BASE/tc_data/basin_global_tenth_degree.nc

TC_GEN_NC_PAIRS_GRID = G003

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

Note

See the TCGen MET Configuration section of the User’s Guide for more information on the environment variables used in the file below:

////////////////////////////////////////////////////////////////////////////////
//
// TC-Gen configuration file.
//
// For additional information, see the MET_BASE/config/README_TC file.
//
////////////////////////////////////////////////////////////////////////////////

//
// ATCF file format reference:
//   http://www.nrlmry.navy.mil/atcf_web/docs/database/new/abrdeck.html
//

////////////////////////////////////////////////////////////////////////////////
//
// Genesis event definition criteria.
//
////////////////////////////////////////////////////////////////////////////////

//
// Model initialization frequency in hours, starting at 0.
//
// init_freq =
${METPLUS_INIT_FREQ}

//
// Valid hour frequency to be analyzed in hours, starting at 0
//
// valid_freq =
${METPLUS_VALID_FREQ}

//
// Forecast hours to be searched for genesis events
//
// fcst_hr_window =
${METPLUS_FCST_HR_WINDOW_DICT}

//
// Minimum track duration for genesis event in hours.
//
// min_duration =
${METPLUS_MIN_DURATION}

//
// Forecast genesis event criteria.  Defined as tracks reaching the specified
// intensity category, maximum wind speed threshold, and minimum sea-level
// pressure threshold.  The forecast genesis time is the valid time of the first
// track point where all of these criteria are met.
//
// fcst_genesis =
${METPLUS_FCST_GENESIS_DICT}

//
// BEST track genesis event criteria.  Defined as tracks reaching the specified
// intensity category, maximum wind speed threshold, and minimum sea-level
// pressure threshold.  The BEST track genesis time is the valid time of the
// first track point where all of these criteria are met.
//
// best_genesis =
${METPLUS_BEST_GENESIS_DICT}

//
// Operational track technique name
//
// oper_technique =
${METPLUS_OPER_TECHNIQUE}

////////////////////////////////////////////////////////////////////////////////
//
// Track filtering options
// May be specified separately in each filter array entry.
//
////////////////////////////////////////////////////////////////////////////////

//
// Array of dictionaries containing the track filtering options
// If empty, a single filter is defined using the top-level settings.
//
// filter =
${METPLUS_FILTER}

//
// Description written to output DESC column
//
// desc =
${METPLUS_DESC}

//
// Forecast ATCF ID's
// If empty, all ATCF ID's found will be processed.
// Statistics will be generated separately for each ATCF ID.
//
// model =
${METPLUS_MODEL}

//
// BEST and operational track storm identifiers
//
// storm_id =
${METPLUS_STORM_ID}

//
// BEST and operational track storm names
//
// storm_name =
${METPLUS_STORM_NAME}

//
// Forecast and operational initialization times to include or exclude
//
// init_beg =
${METPLUS_INIT_BEG}

// init_end =
${METPLUS_INIT_END}

// init_inc =
${METPLUS_INIT_INC}

// init_exc =
${METPLUS_INIT_EXC}

//
// Forecast, BEST, and operational valid time window
//
// valid_beg =
${METPLUS_VALID_BEG}

// valid_end =
${METPLUS_VALID_END}

//
// Forecast and operational initialization hours
//
// init_hour =
${METPLUS_INIT_HOUR}

//
// Forecast and operational lead times in hours
//
// lead =
${METPLUS_LEAD}

//
// Spatial masking region (path to gridded data file or polyline file)
//
// vx_mask =
${METPLUS_VX_MASK}

//
// Spatial masking of hurricane basin names from the basin_file
//
// basin_mask =
${METPLUS_BASIN_MASK}

//
// Distance to land threshold
//
//dland_thresh =
${METPLUS_DLAND_THRESH}

////////////////////////////////////////////////////////////////////////////////
//
// Matching and scoring options
// May be specified separately in each filter array entry.
//
////////////////////////////////////////////////////////////////////////////////

//
// Genesis matching logic. Compare the forecast genesis point to all points in
// the Best track (TRUE) or the single Best track genesis point (FALSE).
//
//genesis_match_point_to_track =
${METPLUS_GENESIS_MATCH_POINT_TO_TRACK}

//
// Radius in km to search for a matching genesis event
//
// genesis_match_radius =
${METPLUS_GENESIS_MATCH_RADIUS}

//
// Time window in hours, relative to the model genesis time, to search for a
// matching Best track point
//
//genesis_match_window = {
${METPLUS_GENESIS_MATCH_WINDOW_DICT}

//
// Radius in km for a development scoring method hit
//
// dev_hit_radius =
${METPLUS_DEV_HIT_RADIUS}

//
// Time window in hours for a development scoring method hit
//
// dev_hit_window =
${METPLUS_DEV_HIT_WINDOW_DICT}

// Time window in hours for the Best track genesis minus model initialization
// time difference for an operational scoring method hit
//
//ops_hit_window = {
${METPLUS_OPS_HIT_WINDOW_DICT}

//
// Discard genesis forecasts for initializations at or after the matching
// BEST track genesis time
//
// discard_init_post_genesis_flag =
${METPLUS_DISCARD_INIT_POST_GENESIS_FLAG}

//
// Scoring methods to be applied
//
//dev_method_flag =
${METPLUS_DEV_METHOD_FLAG}

// ops_method_flag =
${METPLUS_OPS_METHOD_FLAG}

////////////////////////////////////////////////////////////////////////////////
//
// Output options
// May be specified separately in each filter array entry.
//
////////////////////////////////////////////////////////////////////////////////

//
// Confidence interval alpha value
//
// ci_alpha =
${METPLUS_CI_ALPHA}

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

//
// NetCDF genesis pair counts
//
// nc_pairs_flag =
${METPLUS_NC_PAIRS_FLAG_DICT}

//
// Specify which track points should be counted by thresholding the track point
// valid time minus genesis time difference.
//
// valid_minus_genesis_diff_thresh =
${METPLUS_VALID_MINUS_GENESIS_DIFF_THRESH}

//
// Count unique BEST track genesis event locations (TRUE) versus counting the
// location for all pairs (FALSE).
//
// best_unique_flag =
${METPLUS_BEST_UNIQUE_FLAG}

////////////////////////////////////////////////////////////////////////////////
//
// Global settings
// May only be specified once.
//
////////////////////////////////////////////////////////////////////////////////

//
// Specify the NetCDF output of the gen_dland tool containing a gridded
// representation of the minimum distance to land.
//
// dland_file =
${METPLUS_DLAND_FILE}

//
// Specify the NetCDF file containing a gridded representation of the
// global basins.
//
// basin_file =
${METPLUS_BASIN_FILE}

//
// NetCDF genesis pairs grid
//
// nc_pairs_grid =
${METPLUS_NC_PAIRS_GRID}

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

tmp_dir = "${MET_TMP_DIR}";

${METPLUS_MET_CONFIG_OVERRIDES}

Running METplus

This use case can be run two ways: 1) Passing in TCGen.conf then a user-specific system configuration file:

run_metplus.py -c /path/to/METplus/parm/use_cases/met_tool_wrapper/TCGen/TCGen.conf -c /path/to/user_system.conf
  1. Modifying the configurations in parm/metplus_config, then passing in TCGen.conf:

    run_metplus.py -c /path/to/METplus/parm/use_cases/met_tool_wrapper/TCGen/TCGen.conf
    

The former method is recommended. Whether you add them to a user-specific configuration file or modify the metplus_config files, the following METplus configuration variables must be set correctly to run this example.:

  • INPUT_BASE - Path to directory where sample data tarballs are unpacked (See Datasets section to obtain tarballs).

  • OUTPUT_BASE - Path where METplus output will be written. This must be in a location where you have write permissions

  • MET_INSTALL_DIR - Path to location where MET is installed locally

Example User Configuration File:

[dir]
INPUT_BASE = /path/to/sample/input/data
OUTPUT_BASE = /path/to/output/dir
MET_INSTALL_DIR = /path/to/met-X.Y

NOTE: All of these items must be found under the [dir] section.

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 this use case will be found in met_tool_wrapper/TCGen and will contain the following files:

  • tc_gen_2016_ctc.txt

  • tc_gen_2016_cts.txt

  • tc_gen_2016.stat

Keywords

Note

  • TCGenToolUseCase

  • DTCOrgUseCase

  • TropicalCycloneUseCase

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

sphinx_gallery_thumbnail_path = ‘_static/met_tool_wrapper-TCGen.png’

Total running time of the script: (0 minutes 0.000 seconds)

Gallery generated by Sphinx-Gallery