Note

Click here to download the full example code

5.1.19.1. 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

#
#  CONFIGURATION
#
[config]

# Looping by times: steps through each 'task' in the PROCESS_LIST for each
# defined time, and repeats until all times have been evaluated.
LOOP_ORDER = processes

# 'Tasks' to be run
PROCESS_LIST = TCGen

LOOP_BY = INIT

# The init time begin and end times, increment, and last init hour.
INIT_TIME_FMT = %Y
INIT_BEG = 2016
INIT_END = 2016

# This is the step-size. Increment in seconds from the begin time to the end time
# set to 6 hours = 21600 seconds
INIT_INCREMENT = 21600

LOG_TC_GEN_VERBOSITY = 2

# optional list of strings to loop over and call the tool multiple times
# value of each item can be referenced in filename templates with {custom?fmt=%s}
TC_GEN_CUSTOM_LOOP_LIST =

TC_GEN_CONFIG_FILE = {CONFIG_DIR}/TCGenConfig_wrapped

# The following variables set values in the MET configuration file used by this example
# Leaving these values commented will use the value found in the default MET configuration file
# See the MET documentation for this tool for more information on the settings

# sets init_freq in the MET configuration file - must be an integer value
TC_GEN_INIT_FREQUENCY = 6

# sets lead_window { beg } in the MET configuration file - must be an integer value
TC_GEN_LEAD_WINDOW_BEGIN = 24

# sets lead_window { end } in the MET configuration file - must be an integer value
TC_GEN_LEAD_WINDOW_END = 120

# sets min_duration in the MET configuration file - must be an integer value
TC_GEN_MIN_DURATION = 12

# sets fcst_genesis { vmax_thresh } in the MET configuration file - must be a valid threshold value (i.e. gt4) or NA
TC_GEN_FCST_GENESIS_VMAX_THRESH = NA

# sets fcst_genesis { mslp_thresh} in the MET configuration file - must be a valid threshold value (i.e. gt4) or NA
TC_GEN_FCST_GENESIS_MSLP_THRESH = NA


# sets best_genesis { technique } in the MET configuration file
TC_GEN_BEST_GENESIS_TECHNIQUE = BEST

# sets best_genesis { category } in the MET configuration file - can be a list of items
TC_GEN_BEST_GENESIS_CATEGORY = TD, TS

# sets best_genesis { vmax_thresh } in the MET configuration file - must be a valid threshold value (i.e. gt4) or NA
TC_GEN_BEST_GENESIS_VMAX_THRESH = NA

# sets best_genesis { mslp_thresh} in the MET configuration file - must be a valid threshold value (i.e. gt4) or NA
TC_GEN_BEST_GENESIS_MSLP_THRESH = NA


# sets oper_genesis { technique } in the MET configuration file
TC_GEN_OPER_GENESIS_TECHNIQUE = CARQ

# sets oper_genesis { category } in the MET configuration file - can be a list of items
TC_GEN_OPER_GENESIS_CATEGORY = DB, LO, WV

# sets oper_genesis { vmax_thresh } in the MET configuration file - must be a valid threshold value (i.e. gt4) or NA
TC_GEN_OPER_GENESIS_VMAX_THRESH = NA

# sets oper_genesis { mslp_thresh} in the MET configuration file - must be a valid threshold value (i.e. gt4) or NA
TC_GEN_OPER_GENESIS_MSLP_THRESH = NA


# 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;

# sets model in the MET configuration file - can be a list of items
MODEL =

# sets storm_id in the MET configuration file - can be a list of items
TC_GEN_STORM_ID =

# sets storm_name in the MET configuration file - can be a list of items
TC_GEN_STORM_NAME =


# sets init_beg in the MET configuration file
TC_GEN_INIT_BEG =

# sets init_end in the MET configuration file
TC_GEN_INIT_END =

# sets valid_beg in the MET configuration file
TC_GEN_VALID_BEG =

# sets valid_end in the MET configuration file
TC_GEN_VALID_END =

# sets init_hour in the MET configuration file - can be a list of items
TC_GEN_INIT_HOUR_LIST =

# forecast lead sequence - used in TCGen to set lead list in the MET configuration
LEAD_SEQ =


# sets vx_mask in the MET configuration file
TC_GEN_VX_MASK =

# sets genesis_window { beg } in the MET configuration file
TC_GEN_GENESIS_WINDOW_BEGIN = -24

# sets genesis_window { beg } in the MET configuration file
TC_GEN_GENESIS_WINDOW_END = 24

# sets genesis_radius in the MET configuration file
TC_GEN_GENESIS_RADIUS = 300

# sets dland_file in the MET configuration file
TC_GEN_DLAND_FILE = MET_BASE/tc_data/dland_global_tenth_degree.nc

#
#  DIRECTORIES
#
[dir]

# location of configuration files used by MET applications
CONFIG_DIR={PARM_BASE}/met_config

# Location of input data directory for track data
TC_GEN_TRACK_INPUT_DIR = {INPUT_BASE}/met_test/tc_data/genesis/atcf

# Location of input data directory for genesis data
TC_GEN_GENESIS_INPUT_DIR = {INPUT_BASE}/met_test/tc_data/genesis/suite1

# directory to write output files generated by tc_gen
TC_GEN_OUTPUT_DIR = {OUTPUT_BASE}/met_tool_wrapper/TCGen

#
#  FILENAME TEMPLATES
#
[filename_templates]
# Location of input track data relative to INPUT_DIR and specific to the current run time
TC_GEN_TRACK_INPUT_TEMPLATE = {init?fmt=%Y}

# Location of input genesis data relative to INPUT_DIR and specific to the current run time
TC_GEN_GENESIS_INPUT_TEMPLATE = {init?fmt=%Y}*/genesis*{init?fmt=%Y}*

# Prefix to add to output files. Relative to OUTPUT_DIR and specific to the current run time
TC_GEN_OUTPUT_TEMPLATE = tc_gen_{init?fmt=%Y}

MET Configuration

METplus sets environment variables based on the values in the METplus configuration file. These variables are referenced in the MET configuration file. 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 not controlled by an environment variable, you can add additional environment variables to be set only within the METplus environment using the [user_env_vars] section of the METplus configuration files. See the ‘User Defined Config’ section on the ‘System Configuration’ page of the METplus User’s Guide for more information.

////////////////////////////////////////////////////////////////////////////////
//
// 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}

//
// Lead times in hours to be searched for genesis events.
//
${LEAD_WINDOW_DICT}

//
// Minimum track duration for genesis event in hours.
//
${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_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_DICT}

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

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

//
// Filter is an array of dictionaries containing the track filtering options
// listed below.  If empty, a single filter is defined using the top-level
// settings.
//
${FILTER}

//
// Description written to output DESC column
//
//desc = "NA";

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

//
// BEST and operational track storm identifiers
//
${STORM_ID}

//
// BEST and operational track storm names
//
${STORM_NAME}

//
// Forecast and operational initialization time window
//

${INIT_BEG}
${INIT_END}

//
// Forecast, BEST, and operational valid time window
//

${VALID_BEG}
${VALID_END}

//
// Forecast and operational initialization hours
//
${INIT_HOUR}

//
// Forecast and operational lead times in hours
//
${LEAD_LIST}

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

//
// Distance to land threshold
//
//dland_thresh = NA;

//
// Genesis matching time window, in hours relative to the forecast genesis time
//
${GENESIS_WINDOW_DICT}

//
// Genesis matching search radius in km.
//
${GENESIS_RADIUS}

////////////////////////////////////////////////////////////////////////////////
//
// Global settings.
//
////////////////////////////////////////////////////////////////////////////////

//
// Confidence interval alpha value
//
//ci_alpha = 0.05;

//
// Statistical output types
//
//output_flag = {
//   fho    = NONE;
//   ctc    = BOTH;
//   cts    = BOTH;
//}

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

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

Note the following variables are referenced in the MET configuration file.

  • ${INIT_FREQ} - Corresponds to TC_GEN_INIT_FREQUENCY in the METplus configuration file.

  • ${LEAD_WINDOW_DICT} - Corresponds to TC_GEN_LEAD_WINDOW_[BEGIN/END] in the METplus configuration file.

  • ${MIN_DURATION} - Corresponds to TC_GEN_MIN_DURATION in the METplus configuration file.

  • ${FCST_GENESIS_DICT} - Corresponds to TC_GEN_FCST_GENESIS_[VMAX_THRESH/MSLP_THRESH] in the METplus configuration file.

  • ${BEST_GENESIS_DICT} - Corresponds to TC_GEN_FCST_GENESIS_[TECHNIQUE/CATEGORY/VMAX_THRESH/MSLP_THRESH] in the METplus configuration file.

  • ${OPER_GENESIS_DICT} - Corresponds to TC_GEN_OPER_GENESIS_[TECHNIQUE/CATEGORY/VMAX_THRESH/MSLP_THRESH] in the METplus configuration file.

  • ${FILTER} - Corresponds to TC_GEN_FILTER_<n> in the METplus configuration file.

  • ${MODEL} - Corresponds to MODEL in the METplus configuration file.

  • ${STORM_ID} - Corresponds to TC_GEN_STORM_ID in the METplus configuration file.

  • ${STORM_NAME} - Corresponds to TC_GEN_STORM_NAME in the METplus configuration file.

  • ${INIT_BEG} - Corresponds to TC_GEN_INIT_BEG in the METplus configuration file.

  • ${INIT_END - Corresponds to TC_GEN_INIT_END in the METplus configuration file.

  • ${VALID_BEG} - Corresponds to TC_GEN_VALID_BEG in the METplus configuration file.

  • ${VALID_END - Corresponds to TC_GEN_VALID_END in the METplus configuration file.

  • ${INIT_HOUR_LIST} - Corresponds to TC_GEN_INIT_HOUR_LIST in the METplus configuration file.

  • ${LEAD_LIST} - Corresponds to LEAD_SEQ in the METplus configuration file.

  • ${GENESIS_WINDOW_DICT} - Corresponds to TC_GEN_GENESIS_WINDOW_[BEGIN/END] in the METplus configuration file.

  • ${GENESIS_RADIUS} - Corresponds to TC_GEN_GENESIS_RADIUS in the METplus configuration file.

  • ${DLAND_FILE} - Corresponds to TC_GEN_DLAND_FILE in the METplus configuration file.

Running METplus

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

master_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:

    master_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,

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