From cbf10e6b61c09f25422a04b5e8ab97048eebb78f Mon Sep 17 00:00:00 2001 From: lisagoodrich <33230218+lisagoodrich@users.noreply.github.com> Date: Fri, 13 Nov 2020 13:05:52 -0700 Subject: [PATCH] Task 1455 doc (#1557) * first stab at converting to sphinx * removing all slashes * adding new link to README.rst file * working on lists * Made formatting changes * Finished fcst section * fixing spelling, bolding and italics issues * updating web links * working on formatting * updating formatting * formatting * first attempt to clean up formatting completed. * adding README to the index file * fixing warning errors * Bringing README_TC into sphinx. Updating section headers * Adding README_TC * Made formatting updates to README.rst * corrected section under wavelet * small changes * removing met/data/config/README since it is now in met/docs/Users_Guide * Added some formatting for headers * fixing chapters & sections * Fixed warnings from building * adding in code blocks * removing slashes * changes * Made changes to formatting * removing For example code blocks * major updates * fist pass at document conversion complete. * cleaning up questions about dashes * Made some formatting modifications * Removing README_TC because it is being replaced by README_TC.rst in met/docs/Users_Guide * Removing the reference to the README_TC file * Making title capitalization consistent with README * Added a space in timestring * changing to 'time string' with a space between the words. * adding a link to the new README_TC location in met/docs/Users_Guide * Modified references to README and README_TC Co-authored-by: Julie.Prestopnik --- met/data/config/Ascii2NcConfig_default | 2 +- met/data/config/EnsembleStatConfig_default | 2 +- met/data/config/GridDiagConfig_default | 2 +- met/data/config/GridStatConfig_default | 2 +- met/data/config/MODEAnalysisConfig_default | 2 +- met/data/config/MODEConfig_default | 2 +- met/data/config/MTDConfig_default | 2 +- met/data/config/Madis2NcConfig_default | 2 +- met/data/config/Makefile.am | 3 +- met/data/config/PB2NCConfig_default | 2 +- met/data/config/PlotModeFieldConfig_default | 2 +- met/data/config/Point2GridConfig_default | 2 +- met/data/config/PointStatConfig_default | 2 +- met/data/config/README_TC | 793 -------- met/data/config/RMWAnalysisConfig_default | 2 +- met/data/config/STATAnalysisConfig_default | 2 +- met/data/config/SeriesAnalysisConfig_default | 2 +- met/data/config/TCGenConfig_default | 2 +- met/data/config/TCPairsConfig_default | 2 +- met/data/config/TCRMWConfig_default | 2 + met/data/config/TCStatConfig_default | 2 +- met/data/config/WWMCARegridConfig_default | 2 +- met/data/config/WaveletStatConfig_default | 2 +- met/docs/Users_Guide/README.rst | 43 +- met/docs/Users_Guide/README_TC.rst | 1805 ++++++++++-------- met/docs/Users_Guide/tc-stat.rst | 4 +- 26 files changed, 1108 insertions(+), 1582 deletions(-) delete mode 100644 met/data/config/README_TC diff --git a/met/data/config/Ascii2NcConfig_default b/met/data/config/Ascii2NcConfig_default index 4013eb595c..053e93e543 100644 --- a/met/data/config/Ascii2NcConfig_default +++ b/met/data/config/Ascii2NcConfig_default @@ -2,7 +2,7 @@ // // ASCII2NC configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/EnsembleStatConfig_default b/met/data/config/EnsembleStatConfig_default index 8ade30bc36..f912f80fb6 100644 --- a/met/data/config/EnsembleStatConfig_default +++ b/met/data/config/EnsembleStatConfig_default @@ -2,7 +2,7 @@ // // Ensemble-Stat configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/GridDiagConfig_default b/met/data/config/GridDiagConfig_default index 04b4bdb9d2..0ff5819908 100644 --- a/met/data/config/GridDiagConfig_default +++ b/met/data/config/GridDiagConfig_default @@ -2,7 +2,7 @@ // // Grid-Diag configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/GridStatConfig_default b/met/data/config/GridStatConfig_default index 8ac8e8f904..19da5f7a8c 100644 --- a/met/data/config/GridStatConfig_default +++ b/met/data/config/GridStatConfig_default @@ -2,7 +2,7 @@ // // Grid-Stat configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/MODEAnalysisConfig_default b/met/data/config/MODEAnalysisConfig_default index b00eb45d35..b0efcec11d 100644 --- a/met/data/config/MODEAnalysisConfig_default +++ b/met/data/config/MODEAnalysisConfig_default @@ -2,7 +2,7 @@ // // MODE-Analysis configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/MODEConfig_default b/met/data/config/MODEConfig_default index 64ea613878..4de1bba7ee 100644 --- a/met/data/config/MODEConfig_default +++ b/met/data/config/MODEConfig_default @@ -2,7 +2,7 @@ // // MODE configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/MTDConfig_default b/met/data/config/MTDConfig_default index 5fe490ea1b..fed6df9abb 100644 --- a/met/data/config/MTDConfig_default +++ b/met/data/config/MTDConfig_default @@ -2,7 +2,7 @@ // // MODE Time Domain configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/Madis2NcConfig_default b/met/data/config/Madis2NcConfig_default index d83411df92..8e0fda7994 100644 --- a/met/data/config/Madis2NcConfig_default +++ b/met/data/config/Madis2NcConfig_default @@ -2,7 +2,7 @@ // // MADIS2NC configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/Makefile.am b/met/data/config/Makefile.am index 09d8ebdaef..78a8d8844d 100644 --- a/met/data/config/Makefile.am +++ b/met/data/config/Makefile.am @@ -42,8 +42,7 @@ config_DATA = \ WaveletStatConfig_default \ WWMCARegridConfig_default \ PlotModeFieldConfig_default \ - Point2GridConfig_default \ - README_TC + Point2GridConfig_default EXTRA_DIST = ${config_DATA} diff --git a/met/data/config/PB2NCConfig_default b/met/data/config/PB2NCConfig_default index 9f9c0772d5..896a7278d4 100644 --- a/met/data/config/PB2NCConfig_default +++ b/met/data/config/PB2NCConfig_default @@ -2,7 +2,7 @@ // // PB2NC configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/PlotModeFieldConfig_default b/met/data/config/PlotModeFieldConfig_default index 2149d36410..5b425edda8 100644 --- a/met/data/config/PlotModeFieldConfig_default +++ b/met/data/config/PlotModeFieldConfig_default @@ -2,7 +2,7 @@ // // Plot-MODE-Field configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/Point2GridConfig_default b/met/data/config/Point2GridConfig_default index 32d9f7b91d..bc10e72698 100644 --- a/met/data/config/Point2GridConfig_default +++ b/met/data/config/Point2GridConfig_default @@ -2,7 +2,7 @@ // // Point2Grid configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/PointStatConfig_default b/met/data/config/PointStatConfig_default index a487f27126..b3e1ff343d 100644 --- a/met/data/config/PointStatConfig_default +++ b/met/data/config/PointStatConfig_default @@ -2,7 +2,7 @@ // // Point-Stat configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/README_TC b/met/data/config/README_TC deleted file mode 100644 index 25cc27d010..0000000000 --- a/met/data/config/README_TC +++ /dev/null @@ -1,793 +0,0 @@ -//////////////////////////////////////////////////////////////////////////////// -// -// Configuration file overview. -// -//////////////////////////////////////////////////////////////////////////////// - -See README for configuration file overview. - -//////////////////////////////////////////////////////////////////////////////// -// -// Configuration settings common to multiple tools -// -//////////////////////////////////////////////////////////////////////////////// - -// -// Specify a comma-separated list of storm id's to be used: -// 2-letter basin, 2-digit cyclone number, 4-digit year -// An empty list indicates that all should be used. -// -// e.g. storm_id = [ "AL092011" ]; -// -// This may also be set using basin, cyclone, and timing information below. -// -storm_id = []; - -// -// Specify a comma-separated list of basins to be used. -// Expected format is 2-letter basin identifier. -// An empty list indicates that all should be used. -// Valid basins: WP, IO, SH, CP, EP, AL, SL -// -// e.g. basin = [ "AL", "EP" ]; -// -basin = []; - -// -// Specify a comma-separated list of cyclone numbers (01-99) to be used. -// An empty list indicates that all should be used. -// -// e.g. cyclone = [ "01", "02", "03" ]; -// -cyclone = []; - - -// -// Specify a comma-separated list of storm names to be used. -// An empty list indicates that all should be used. -// -// e.g. storm_name = [ "KATRINA" ]; -// -storm_name = []; - -// -// Specify a model initialization time window in YYYYMMDD[_HH[MMSS]] format -// or provide a list of specific initialization times to include (inc) -// or exclude (exc). Tracks whose initial time meets the specified -// criteria will be used. An empty string indicates that all times -// should be used. -// -// e.g. init_beg = "20100101"; -// init_end = "20101231"; -// init_inc = [ "20101231_06" ]; -// init_exc = [ "20101231_00" ]; -// -init_beg = ""; -init_end = ""; -init_inc = []; -init_exc = []; - -// -// Specify a model valid time window in YYYYMMDD[_HH[MMSS]] format. -// Tracks for which all valid times fall within the time window will be used. -// An empty string indicates that all times should be used. -// -// e.g. valid_beg = "20100101"; -// valid_end = "20101231"; -// -valid_beg = ""; -valid_end = ""; - -// -// Specify a comma-separated list of model initialization hours to be used -// in HH[MMSS] format. An empty list indicates that all hours should be used. -// -// e.g. init_hour = [ "00", "06", "12", "18" ]; -// -init_hour = []; - -// -// Specify the required lead time in HH[MMSS] format. -// Tracks that contain all of these required times will be -// used. If a track has additional lead times, it will be -// retained. An empty list indicates that no lead times -// are required to determine which tracks are to be used; -// all lead times will be used. -// -lead_req = []; - -// -// Specify lat/lon polylines defining masking regions to be applied. -// Tracks whose initial location falls within init_mask will be used. -// Tracks for which all locations fall within valid_mask will be used. -// -// e.g. init_mask = "MET_BASE/poly/EAST.poly"; -// -init_mask = ""; -valid_mask = ""; - -// -// Indicate the version number for the contents of this configuration file. -// The value should generally not be modified. -// -version = "V6.0"; - -//////////////////////////////////////////////////////////////////////////////// -// -// Settings specific to individual tools -// -//////////////////////////////////////////////////////////////////////////////// - -//////////////////////////////////////////////////////////////////////////////// -// -// TCPairsConfig_default -// -//////////////////////////////////////////////////////////////////////////////// - -// -// The "model" entry specifies an array of model names to be verified. If -// verifying multiple models, choose descriptive model names (no whitespace) -// to distinguish between their output. -// e.g. model = [ "AHW4", "AHWI" ]; -// -model = []; - -// -// Specify whether the code should check for duplicate ATCF lines when -// building tracks. Setting this to FALSE makes the parsing of tracks quicker. -// -// e.g. check_dup = FALSE; -// -check_dup = FALSE; - -// -// Specify whether special processing should be performed for interpolated model -// names ending in 'I' (e.g. AHWI). Search for corresponding tracks whose model -// name ends in '2' (e.g. AHW2) and apply the following logic: -// - "NONE" to do nothing. -// - "FILL" to create a copy of '2' track and rename it as 'I' only when the -// 'I' track does not already exist. -// - "REPLACE" to create a copy of the '2' track and rename it as 'I' in all -// cases, replacing any 'I' tracks that may already exist. -// -interp12 = REPLACE; - -// -// Specify how consensus forecasts should be defined: -// name = consensus model name -// members = array of consensus member model names -// required = array of TRUE/FALSE for each member -// if empty, default is FALSE -// min_req = minimum number of members required for the consensus -// -// e.g. -// consensus = [ -// { -// name = "CON1"; -// members = [ "MOD1", "MOD2", "MOD3" ]; -// required = [ TRUE, FALSE, FALSE ]; -// min_req = 2; -// } -// ]; -// -consensus = []; - -// -// Specify a comma-separated list of forecast lag times to be used in HH[MMSS] -// format. For each ADECK track identified, a lagged track will be derived -// for each entry listed. -// -// e.g. lag_time = [ "06", "12" ]; -// -lag_time = []; - -// -// Specify comma-separated lists of CLIPER/SHIFOR baseline forecasts to be -// derived from the BEST and operational tracks, as defined by the -// best_technique and oper_technique settings. -// -// Derived from BEST tracks: BCLP, BCS5, BCD5, BCLA -// Derived from OPER tracks: OCLP, OCS5, OCD5, OCDT -// -// e.g. best_technique = [ "BEST" ]; -// base_baseline = [ "BCLP", "BCS5", "BCD5", "BCLA" ]; -// oper_technique = [ "CARQ" ]; -// oper_baseline = [ "OCLP", "OCS5", "OCD5", "OCDT" ]; -// -best_technique = [ "BEST" ]; -best_baseline = []; -oper_technique = [ "CARQ" ]; -oper_baseline = []; - -// -// Analysis tracks consist of multiple track points with a lead time of zero -// for the same storm. An analysis track may be generated by running model -// analysis fields through a tracking algorithm. Specify which datasets should -// be searched for analysis track data by setting this to NONE, ADECK, BDECK, -// or BOTH. Use BOTH to create pairs using two different analysis tracks. -// -// e.g. anly_track = BDECK; -// -anly_track = BDECK; - -// -// Specify whether only those track points common to both the ADECK and BDECK -// tracks should be written out. -// -// e.g. match_points = FALSE; -// -match_points = FALSE; - -// -// Specify the NetCDF output of the gen_dland tool containing a gridded -// representation of the minimum distance to land. -// -dland_file = "MET_BASE/tc_data/dland_nw_hem_tenth_degree.nc"; - -// -// Specify watch/warning information. Specify an ASCII file containing -// watch/warning information to be used. At each track point, the most severe -// watch/warning status in effect, if any, will be written to the output. -// Also specify a time offset in seconds to be added to each watch/warning -// time processed. NHC applies watch/warning information to all track points -// occurring 4 hours (-14400 second) prior to the watch/warning time. -// -watch_warn = { - file_name = "MET_BASE/tc_data/wwpts_us.txt"; - time_offset = -14400; -} - -// -// The basin_map entry defines a mapping of input names to output values. -// Whenever the basin string matches "key" in the input ATCF files, it is -// replaced with "val". This map can be used to modify basin names to make them -// consistent across the ATCF input files. -// -// Many global modeling centers use ATCF basin identifiers based on region -// (e.g., 'SP' for South Pacific Ocean, etc.), however the best track data -// provided by the Joint Typhoon Warning Center (JTWC) use just one basin -// identifier 'SH' for all of the Southern Hemisphere basins. Additionally, -// some modeling centers may report basin identifiers separately for the Bay -// of Bengal (BB) and Arabian Sea (AB) whereas JTWC uses 'IO'. -// -// The basin mapping allows MET to map the basin identifiers to the expected -// values without having to modify your data. For example, the first entry -// in the list below indicates that any data entries for 'SI' will be matched -// as if they were 'SH'. In this manner, all verification results for the -// Southern Hemisphere basins will be reported together as one basin. -// -// An empty list indicates that no basin mapping should be used. Use this if -// you are not using JTWC best tracks and you would like to match explicitly -// by basin or sub-basin. Note that if your model data and best track do not -// use the same basin identifier conventions, using an empty list for this -// parameter will result in missed matches. -// -basin_map = [ - { key = "SI"; val = "SH"; }, - { key = "SP"; val = "SH"; }, - { key = "AU"; val = "SH"; }, - { key = "AB"; val = "IO"; }, - { key = "BB"; val = "IO"; } -]; - -//////////////////////////////////////////////////////////////////////////////// -// -// TCStatConfig_default -// -//////////////////////////////////////////////////////////////////////////////// - -// -// Stratify by the AMODEL or BMODEL columns. -// Specify comma-separated lists of model names to be used for all analyses -// performed. May add to this list using the "-amodel" and "-bmodel" -// job command options. -// e.g. amodel = [ "AHW4" ]; -// bmodel = [ "BEST" ]; -// -amodel = []; -bmodel = []; - -// -// Stratify by the VALID times. -// Define beginning and ending time windows in YYYYMMDD[_HH[MMSS]] -// or provide a list of specific valid times to include or exclude. -// May modify using the "-valid_beg", "-valid_end", "-valid_inc", -// and "-valid_exc" job command options. -// -// e.g. valid_beg = "20100101"; -// valid_end = "20101231_12"; -// valid_inc = [ "20101231_06" ]; -// valid_exc = [ "20101231_00" ]; -// -valid_beg = ""; -valid_end = ""; -valid_inc = []; -valid_exc = []; - -// -// Stratify by the initialization and valid hours and lead time. -// Specify a comma-separated list of initialization hours, -// valid hours, and lead times in HH[MMSS] format. -// May add using the "-init_hour", "-valid_hour", "-lead", -// and "-lead_req" job command options. -// -// e.g. init_hour = [ "00" ]; -// valid_hour = [ "12" ]; -// lead = [ "24", "36" ]; -// lead_req = [ "72", "84", "96", "108" ]; -// -init_hour = []; -valid_hour = []; -lead = []; -lead_req = []; - -// -// Stratify by the LINE_TYPE column. May add using the "-line_type" -// job command option. -// -// e.g. line_type = [ "TCMPR" ]; -// -line_type = []; - -// -// Stratify by checking the watch/warning status for each track point -// common to both the ADECK and BDECK tracks. If the watch/warning status -// of any of the track points appears in the list, retain the entire track. -// Individual watch/warning status by point may be specified using the -// -column_str options below, but this option filters by the track maximum. -// May add using the "-track_watch_warn" job command option. -// The value "ALL" matches HUWARN, TSWARN, HUWATCH, and TSWATCH. -// -// e.g. track_watch_warn = [ "HUWATCH", "HUWARN" ]; -// -track_watch_warn = []; - -// -// Stratify by applying thresholds to numeric data columns. -// Specify a comma-separated list of columns names and thresholds -// to be applied. May add using the "-column_thresh name thresh" job command -// options. -// -// e.g. column_thresh_name = [ "ADLAND", "BDLAND" ]; -// column_thresh_val = [ >200, >200 ]; -// -column_thresh_name = []; -column_thresh_val = []; - -// -// Stratify by performing string matching on non-numeric data columns. -// Specify a comma-separated list of columns names and values -// to be checked. May add using the "-column_str name string" job command -// options. -// -// e.g. column_str_name = [ "LEVEL", "LEVEL" ]; -// column_str_val = [ "HU", "TS" ]; -// -column_str_name = []; -column_str_val = []; - -// -// Just like the column_thresh options above, but apply the threshold only -// when lead = 0. If lead = 0 value does not meet the threshold, discard -// the entire track. May add using the "-init_thresh name thresh" job command -// options. -// -// e.g. init_thresh_name = [ "ADLAND" ]; -// init_thresh_val = [ >200 ]; -// -init_thresh_name = []; -init_thresh_val = []; - -// -// Just like the column_str options above, but apply the string matching only -// when lead = 0. If lead = 0 string does not match, discard the entire track. -// May add using the "-init_str name thresh" job command options. -// -// e.g. init_str_name = [ "LEVEL" ]; -// init_str_val = [ "HU" ]; -// -init_str_name = []; -init_str_val = []; - -// -// Stratify by the ADECK and BDECK distances to land. Once either the ADECK or -// BDECK track encounters land, discard the remainder of the track. -// -// e.g. water_only = FALSE; -// -water_only = FALSE; - -// -// Specify whether only those track points for which rapid intensification -// or weakening of the maximum wind speed occurred in the previous time -// step should be retained. -// -// The NHC considers a 24-hour change >=30 kts to constitute rapid -// intensification or weakening. -// -// May modify using the following job command options: -// "-rirw_track" -// "-rirw_time" for both or "-rirw_time_adeck" and "-rirw_time_bdeck" -// "-rirw_exact" for both or "-rirw_exact_adeck" and "-rirw_exact_bdeck" -// "-rirw_thresh" for both or "-rirw_thresh_adeck" and "-rirw_thresh_bdeck" -// - -rirw = { - track = NONE; // Specify which track types to search (NONE, ADECK, - // BDECK, or BOTH) - adeck = { - time = "24"; // Rapid intensification/weakening time period in HHMMSS - // format. - exact = TRUE; // Use the exact or maximum intensity difference over the - // time period. - thresh = >=30.0; // Threshold for the intensity change. - } - bdeck = adeck; // Copy settings to the BDECK or specify different logic. -} - -// -// Specify whether only those track points occurring near landfall should be -// retained, and define the landfall retention window as a timestring in HH[MMSS] -// format (or as an integer number of seconds) offset from the landfall time. -// Landfall is defined as the last BDECK track point before the distance to land -// switches from positive to 0 or negative. -// -// May modify using the "-landfall_window" job command option, which -// automatically sets -landfall to TRUE. -// -// The "-landfall_window" job command option takes 1 or 2 arguments in HH[MMSS] -// format. Use 1 argument to define a symmetric time window. For example, -// "-landfall_window 06" defines the time window +/- 6 hours around the landfall -// time. Use 2 arguments to define an asymmetric time window. For example, -// "-landfall_window 00 12" defines the time window from the landfall event to 12 -// hours after. -// -// e.g. landfall = FALSE; -// landfall_beg = "-24"; (24 hours prior to landfall) -// landfall_end = "00"; -// -landfall = FALSE; -landfall_beg = "-24"; -landfall_end = "00"; - -// -// Specify whether only those cases common to all models in the dataset should -// be retained. May modify using the "-event_equal" job command option. -// -// e.g. event_equal = FALSE; -// -event_equal = FALSE; - -// -// Specify lead times that must be present for a track to be included in the -// event equalization logic. -// -event_equal_lead = [ "12", "24", "36" ]; - -// -// Apply polyline masking logic to the location of the ADECK track at the -// initialization time. If it falls outside the mask, discard the entire track. -// May modify using the "-out_init_mask" job command option. -// -// e.g. out_init_mask = ""; -// -out_init_mask = ""; - -// -// Apply polyline masking logic to the location of the ADECK track at the -// valid time. If it falls outside the mask, discard only the current track -// point. May modify using the "-out_valid_mask" job command option. -// -// e.g. out_valid_mask = ""; -// -out_valid_mask = ""; - -// -// The "jobs" entry is an array of TCStat jobs to be performed. -// Each element in the array contains the specifications for a single analysis -// job to be performed. The format for an analysis job is as follows: -// -// -job job_name -// OPTIONAL ARGS -// -// Where "job_name" is set to one of the following: -// -// "filter" -// To filter out the TCST lines matching the job filtering criteria -// specified above and using the optional arguments below. The -// output TCST lines are written to the file specified using the -// "-dump_row" argument. -// Required Args: -dump_row -// -// To further refine the TCST data: Each optional argument may be used -// in the job specification multiple times unless otherwise indicated. -// When multiple optional arguments of the same type are indicated, the -// analysis will be performed over their union -// -// "-amodel name" -// "-bmodel name" -// "-lead HHMMSS" -// "-valid_beg YYYYMMDD[_HH[MMSS]]" (use once) -// "-valid_end YYYYMMDD[_HH[MMSS]]" (use once) -// "-valid_inc YYYYMMDD[_HH[MMSS]]" (use once) -// "-valid_exc YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_beg YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_end YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_inc YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_exc YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_hour HH[MMSS]" -// "-valid_hour HH[MMSS] -// "-init_mask name" -// "-valid_mask name" -// "-line_type name" -// "-track_watch_warn name" -// "-column_thresh name thresh" -// "-column_str name string" -// "-init_thresh name thresh" -// "-init_str name string" -// -// Additional filtering options that may be used only when -line_type -// has been listed only once. These options take two arguments: the name -// of the data column to be used and the min, max, or exact value for -// that column. If multiple column eq/min/max/str options are listed, -// the job will be performed on their intersection: -// -// "-column_min col_name value" e.g. -column_min TK_ERR 100.00 -// "-column_max col_name value" -// "-column_eq col_name value" -// "-column_str col_name string" separate multiple filtering strings -// with commas -// -// Required Args: -dump_row -// -// "summary" -// To compute the mean, standard deviation, and percentiles -// (0th, 10th, 25th, 50th, 75th, 90th, and 100th) for the statistic -// specified using the "-line_type" and "-column" arguments. -// For TCStat, the "-column" argument may be set to: -// -// "TRACK" for track, along-track, and cross-track errors. -// "WIND" for all wind radius errors. -// "TI" for track and maximum wind intensity errors. -// "AC" for along-track and cross-track errors. -// "XY" for x-track and y-track errors. -// "col" for a specific column name. -// "col1-col2" for a difference of two columns. -// "ABS(col or col1-col2)" for the absolute value. -// -// Use the -column_union TRUE/FALSE job command option to compute -// summary statistics across the union of input columns rather than -// processing them separately. -// -// Required Args: -line_type, -column -// Optional Args: -by column_name to specify case information -// -out_alpha to override default alpha value -// -column_union to summarize multiple columns -// -// "rirw" -// To define rapid intensification/weakening contingency table using -// the ADECK and BDECK RI/RW settings and the matching time window -// and output contingency table counts and statistics. -// -// Optional Args: -// -rirw_window width in HH[MMSS] format to define a symmetric time -// window -// -rirw_window beg end in HH[MMSS] format to define an asymmetric -// time window -// Default search time window is 0 0, requiring exact match -// -rirw_time or -rirw_time_adeck and -rirw_time_bdeck to override -// defaults -// -rirw_exact or -rirw_exact_adeck and -rirw_exact_bdeck to override -// defaults -// -rirw_thresh or -rirw_thresh_adeck and -rirw_thresh_bdeck to -// override defaults -// -by column_name to specify case information -// -out_alpha to override default alpha value -// -out_line_type to specify output line types (CTC, CTS, and MPR) -// -// Note that the "-dump_row path" option results in 4 files being -// created: -// path_FY_OY.tcst, path_FY_ON.tcst, path_FN_OY.tcst, and -// path_FN_ON.tcst, containing the TCST lines that were hits, false -// alarms, misses, and correct negatives, respectively. These files -// may be used as input for additional TC-Stat analysis. -// -// "probrirw" -// To define an Nx2 probabilistic contingency table by reading the -// PROBRIRW line type, binning the forecast probabilities, and writing -// output probabilistic counts and statistics. -// -// Required Args: -// -probrirw_thresh to define the forecast probabilities to be -// evaluated (e.g. -probrirw_thresh 30) -// -// Optional Args: -// -probrirw_exact TRUE/FALSE to verify against the exact (e.g. -// BDELTA column) or maximum (e.g. BDELTA_MAX column) intensity -// change in the BEST track -// -probrirw_bdelta_thresh to define BEST track change event -// threshold (e.g. -probrirw_bdelta_thresh >=30) -// -probrirw_prob_thresh to define output probability thresholds -// (e.g. -probrirw_prob_thresh ==0.1) -// -by column_name to specify case information -// -out_alpha to override default alpha value -// -out_line_type to specify output line types (PCT, PSTD, PRC, and -// PJC) -// -// For the PROBRIRW line type, PROBRIRW_PROB is a derived column name. -// For example, the following options select 30 kt probabilities and match -// probability values greater than 0: -// -probrirw_thresh 30 -column_thresh PROBRIRW_PROB >0 -// -// e.g. -// jobs = [ -// "-job filter -amodel AHW4 -dumprow ./tc_filter_job.tcst", -// "-job filter -column_min TK_ERR 100.000 \ -// -dumprow ./tc_filter_job.tcst", -// "-job summary -line_type TCMPR -column AC \ -// -dumprow ./tc_summary_job.tcst", -// "-job rirw -amodel AHW4 -dump_row ./tc_rirw_job" ] -// -jobs = []; - -//////////////////////////////////////////////////////////////////////////////// -// -// TCGenConfig_default -// -//////////////////////////////////////////////////////////////////////////////// - -// -// Model initialization frequency in hours, starting at 0. -// -init_freq = 6; - -// -// Lead times in hours to be searched for genesis events. -// -lead_window = { - beg = 24; - end = 120; -} - -// -// Minimum track duration for genesis event in hours. -// -min_duration = 12; - -// -// 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 = { - vmax_thresh = NA; - mslp_thresh = NA; -} - -// -// 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 = { - technique = "BEST"; - category = [ "TD", "TS" ]; - vmax_thresh = NA; - mslp_thresh = NA; -} - -// -// 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 = { - technique = "CARQ"; - category = [ "DB", "LO", "WV" ]; - vmax_thresh = NA; - mslp_thresh = NA; -} - -//////////////////////////////////////////////////////////////////////////////// -// -// 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 = []; - -// -// 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 = { - beg = -24; - end = 24; -} - -// -// Genesis matching search radius in km. -// -genesis_radius = 300; - -//////////////////////////////////////////////////////////////////////////////// -// -// Global settings. -// -//////////////////////////////////////////////////////////////////////////////// - -// -// Confidence interval alpha value -// -ci_alpha = 0.05; - -// -// Statistical output types -// -output_flag = { - fho = NONE; - ctc = BOTH; - cts = BOTH; -} diff --git a/met/data/config/RMWAnalysisConfig_default b/met/data/config/RMWAnalysisConfig_default index ad9b08b517..1fc117637b 100644 --- a/met/data/config/RMWAnalysisConfig_default +++ b/met/data/config/RMWAnalysisConfig_default @@ -2,7 +2,7 @@ // // RMW-Analysis configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/STATAnalysisConfig_default b/met/data/config/STATAnalysisConfig_default index 56b2b21e76..f4b3d3ffff 100644 --- a/met/data/config/STATAnalysisConfig_default +++ b/met/data/config/STATAnalysisConfig_default @@ -2,7 +2,7 @@ // // STAT-Analysis configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/SeriesAnalysisConfig_default b/met/data/config/SeriesAnalysisConfig_default index 20b60097c4..f1c1407fa4 100644 --- a/met/data/config/SeriesAnalysisConfig_default +++ b/met/data/config/SeriesAnalysisConfig_default @@ -2,7 +2,7 @@ // // Series-Analysis configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/TCGenConfig_default b/met/data/config/TCGenConfig_default index 39519d1e24..448044e3ee 100644 --- a/met/data/config/TCGenConfig_default +++ b/met/data/config/TCGenConfig_default @@ -2,7 +2,7 @@ // // TC-Gen configuration file. // -// For additional information, see the MET_BASE/config/README_TC file. +// For additional information, see the README_TC file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/TCPairsConfig_default b/met/data/config/TCPairsConfig_default index 13e1f9ea89..79a495c674 100644 --- a/met/data/config/TCPairsConfig_default +++ b/met/data/config/TCPairsConfig_default @@ -2,7 +2,7 @@ // // TC-Pairs configuration file. // -// For additional information, see the MET_BASE/config/README_TC file. +// For additional information, see the README_TC file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/TCRMWConfig_default b/met/data/config/TCRMWConfig_default index 7a96c43e64..1926164d10 100644 --- a/met/data/config/TCRMWConfig_default +++ b/met/data/config/TCRMWConfig_default @@ -2,6 +2,8 @@ // // TC-RMW configuration file. // +// For additional information, see the README_TC file in the MET User's Guide. +// //////////////////////////////////////////////////////////////////////////////// // diff --git a/met/data/config/TCStatConfig_default b/met/data/config/TCStatConfig_default index c7e3e952b9..f8f610e2c1 100644 --- a/met/data/config/TCStatConfig_default +++ b/met/data/config/TCStatConfig_default @@ -2,7 +2,7 @@ // // TC-Stat configuration file. // -// For additional information, see the MET_BASE/config/README_TC file. +// For additional information, see the README_TC file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/WWMCARegridConfig_default b/met/data/config/WWMCARegridConfig_default index 343b7f3381..6dead45f95 100644 --- a/met/data/config/WWMCARegridConfig_default +++ b/met/data/config/WWMCARegridConfig_default @@ -2,7 +2,7 @@ // // WWMCA-Regrid configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/data/config/WaveletStatConfig_default b/met/data/config/WaveletStatConfig_default index d102439249..327f178eda 100644 --- a/met/data/config/WaveletStatConfig_default +++ b/met/data/config/WaveletStatConfig_default @@ -2,7 +2,7 @@ // // Wavelet-Stat configuration file. // -// For additional information, see the MET_BASE/config/README file. +// For additional information, see the README file in the MET User's Guide. // //////////////////////////////////////////////////////////////////////////////// diff --git a/met/docs/Users_Guide/README.rst b/met/docs/Users_Guide/README.rst index 486c9c31fc..2d54bc534c 100644 --- a/met/docs/Users_Guide/README.rst +++ b/met/docs/Users_Guide/README.rst @@ -1,7 +1,8 @@ .. _README: -README - Configuration File Overview -==================================== +====================================== + README - Configuration File Overview +====================================== The configuration files that control many of the MET tools contain formatted ASCII text. This format has been updated for MET version |version| and @@ -288,11 +289,11 @@ References: Configuration settings used by the MET tools -____________________________________________ +============================================ Settings common to multiple tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- **exit_on_warning** @@ -2180,10 +2181,10 @@ are empty. Note: grib_code 11 is equivalent to obs_var "TMP". } Settings specific to individual tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- EnsembleStatConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ **ens** @@ -2474,7 +2475,7 @@ used for random assignment of ranks when they are tied. } MODEAnalysisConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ MODE line options are used to create filters that determine which MODE output lines are read in and processed. The MODE line options are numerous. They @@ -2812,7 +2813,7 @@ MET User's Guide for a description of these attributes. MODEConfig_default -^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~ **quilt** @@ -3101,7 +3102,7 @@ much more flexible "regrid" option may be used instead. shift_right = 0; PB2NCConfig_default -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ The PB2NC tool filters out observations from PREPBUFR or BUFR files using the following criteria: @@ -3399,7 +3400,7 @@ stack (most quality controlled) or the bottom of the event stack (most raw). event_stack_flag = TOP; SeriesAnalysisConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **block_size** @@ -3448,7 +3449,7 @@ grid is large. } STATAnalysisConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~ **jobs** @@ -3470,6 +3471,8 @@ Where "job_name" is set to one of the following: "-dump_row" argument. Required Args: -dump_row +| + * "summary" To compute summary information for a set of statistics. @@ -3487,16 +3490,18 @@ Where "job_name" is set to one of the following: * apply fisher transform (applied to columns listed in "wmo_fisher_stats") - + +| + The columns of data to be summarized are specified in one of two ways: - * Specify the -line_type option once and specify one or more - - * column names. + * Specify the -line_type option once and specify one or more column names. * Format the -column option as LINE_TYPE:COLUMN. +| + Use the -derive job command option to automatically derive statistics on the fly from input contingency tables and partial sums. @@ -3542,6 +3547,8 @@ Where "job_name" is set to one of the following: ISC, ECNT, RPS, RHIST, PHIST, RELP, SSVAR Required Args: -line_type + +| * "aggregate_stat" @@ -3655,6 +3662,8 @@ Where "job_name" is set to one of the following: Required Args: None +| + * "ramp" The ramp job operates on a time-series of forecast and observed @@ -3904,7 +3913,7 @@ confidence intervals computed for the aggregated statistics. vif_flag = FALSE; WaveletStatConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ **grid_decomp_flag** @@ -3987,7 +3996,7 @@ similar to the "fcst_raw_plot" described in the "Settings common to multiple tools" section. WWMCARegridConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ **to_grid** diff --git a/met/docs/Users_Guide/README_TC.rst b/met/docs/Users_Guide/README_TC.rst index 02957931a2..b4c6fe81bb 100644 --- a/met/docs/Users_Guide/README_TC.rst +++ b/met/docs/Users_Guide/README_TC.rst @@ -1,789 +1,1098 @@ .. _README_TC: -README_TC Configuration file overview -_____________________________________ +README_TC Configuration File Overview +===================================== -See :numref:`README` for configuration file overview. +See :ref:`README` Configuration settings common to multiple tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +_______________________________________________ **storm_id** -// Specify a comma-separated list of storm id's to be used: -// 2-letter basin, 2-digit cyclone number, 4-digit year -// An empty list indicates that all should be used. -// +Specify a comma-separated list of storm id's to be used: -For example: +| 2-letter basin, 2-digit cyclone number, 4-digit year +| -.. code-block:: none +An empty list indicates that all should be used. - storm_id = [ "AL092011" ]; +For example: + +| storm_id = [ "AL092011" ]; +| -// This may also be set using basin, cyclone, and timing information below. +This may also be set using basin, cyclone, and timing information below. .. code-block:: none storm_id = []; -// -// Specify a comma-separated list of basins to be used. -// Expected format is 2-letter basin identifier. -// An empty list indicates that all should be used. -// Valid basins: WP, IO, SH, CP, EP, AL, SL -// +**basin** + +Specify a comma-separated list of basins to be used. Expected format is +a 2-letter basin identifier. An empty list indicates that all should be used. + +| Valid basins: WP, IO, SH, CP, EP, AL, SL +| + For example: +| basin = [ "AL", "EP" ]; +| + .. code-block:: none + + basin = []; + - basin = [ "AL", "EP" ]; +**cyclone** + +Specify a comma-separated list of cyclone numbers (01-99) to be used. +An empty list indicates that all should be used. + +For example: + +| cyclone = [ "01", "02", "03" ]; +| .. code-block:: none - basin = []; + cyclone = []; + +**storm_name** + +Specify a comma-separated list of storm names to be used. An empty list +indicates that all should be used. -// -// Specify a comma-separated list of cyclone numbers (01-99) to be used. -// An empty list indicates that all should be used. -// -// e.g. cyclone = [ "01", "02", "03" ]; -// -cyclone = []; +For example: +| storm_name = [ "KATRINA" ]; +| -// -// Specify a comma-separated list of storm names to be used. -// An empty list indicates that all should be used. -// -// e.g. storm_name = [ "KATRINA" ]; -// -storm_name = []; +.. code-block:: none + + storm_name = []; **init_beg, init_end, init_inc, init_exc** -// -// Specify a model initialization time window in YYYYMMDD[_HH[MMSS]] format -// or provide a list of specific initialization times to include (inc) -// or exclude (exc). Tracks whose initial time meets the specified -// criteria will be used. An empty string indicates that all times -// should be used. -// -// e.g. init_beg = "20100101"; -// init_end = "20101231"; -// init_inc = [ "20101231_06" ]; -// init_exc = [ "20101231_00" ]; -// -init_beg = ""; -init_end = ""; -init_inc = []; -init_exc = []; - -// -// Specify a model valid time window in YYYYMMDD[_HH[MMSS]] format. -// Tracks for which all valid times fall within the time window will be used. -// An empty string indicates that all times should be used. -// -// e.g. valid_beg = "20100101"; -// valid_end = "20101231"; -// -valid_beg = ""; -valid_end = ""; - -// -// Specify a comma-separated list of model initialization hours to be used -// in HH[MMSS] format. An empty list indicates that all hours should be used. -// -// e.g. init_hour = [ "00", "06", "12", "18" ]; -// -init_hour = []; - -// -// Specify the required lead time in HH[MMSS] format. -// Tracks that contain all of these required times will be -// used. If a track has additional lead times, it will be -// retained. An empty list indicates that no lead times -// are required to determine which tracks are to be used; -// all lead times will be used. -// -lead_req = []; - -// -// Specify lat/lon polylines defining masking regions to be applied. -// Tracks whose initial location falls within init_mask will be used. -// Tracks for which all locations fall within valid_mask will be used. -// -// e.g. init_mask = "MET_BASE/poly/EAST.poly"; -// -init_mask = ""; -valid_mask = ""; - -// -// Indicate the version number for the contents of this configuration file. -// The value should generally not be modified. -// -version = "V6.0"; +Specify a model initialization time window in YYYYMMDD[_HH[MMSS]] format +or provide a list of specific initialization times to include (inc) +or exclude (exc). Tracks whose initial time meets the specified +criteria will be used. An empty string indicates that all times +should be used. + +For example: + +| init_beg = "20100101"; +| init_end = "20101231"; +| init_inc = [ "20101231_06" ]; +| init_exc = [ "20101231_00" ]; +| + +.. code-block:: none + + init_beg = ""; + init_end = ""; + init_inc = []; + init_exc = []; + + +**valid_beg, valid_end** + +Specify a model valid time window in YYYYMMDD[_HH[MMSS]] format. +Tracks for which all valid times fall within the time window will be used. +An empty string indicates that all times should be used. + + +For example: + +| valid_beg = "20100101"; +| valid_end = "20101231"; +| + +.. code-block:: none + + valid_beg = ""; + valid_end = ""; + +**init_hour** + +Specify a comma-separated list of model initialization hours to be used +in HH[MMSS] format. An empty list indicates that all hours should be used. + +For example: + +| init_hour = [ "00", "06", "12", "18" ]; +| + +.. code-block:: none + + init_hour = []; + +**lead_req** + +Specify the required lead time in HH[MMSS] format. +Tracks that contain all of these required times will be +used. If a track has additional lead times, it will be +retained. An empty list indicates that no lead times +are required to determine which tracks are to be used; +all lead times will be used. + +.. code-block:: none + + lead_req = []; + +**init_mask, valid_mask** + +Specify lat/lon polylines defining masking regions to be applied. +Tracks whose initial location falls within init_mask will be used. +Tracks for which all locations fall within valid_mask will be used. + +For example: + +| init_mask = "MET_BASE/poly/EAST.poly"; +| + +.. code-block:: none + + init_mask = ""; + valid_mask = ""; + +**version** + +Indicate the version number for the contents of this configuration file. +The value should generally not be modified. + +.. code-block:: none + + version = "V10.0"; Settings specific to individual tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +_____________________________________ + TCPairsConfig_default -^^^^^^^^^^^^^^^^^^^^^ - -// -// The "model" entry specifies an array of model names to be verified. If -// verifying multiple models, choose descriptive model names (no whitespace) -// to distinguish between their output. -// e.g. model = [ "AHW4", "AHWI" ]; -// -model = []; - -// -// Specify whether the code should check for duplicate ATCF lines when -// building tracks. Setting this to FALSE makes the parsing of tracks quicker. -// -// e.g. check_dup = FALSE; -// -check_dup = FALSE; - -// -// Specify whether special processing should be performed for interpolated model -// names ending in 'I' (e.g. AHWI). Search for corresponding tracks whose model -// name ends in '2' (e.g. AHW2) and apply the following logic: -// - "NONE" to do nothing. -// - "FILL" to create a copy of '2' track and rename it as 'I' only when the -// 'I' track does not already exist. -// - "REPLACE" to create a copy of the '2' track and rename it as 'I' in all -// cases, replacing any 'I' tracks that may already exist. -// -interp12 = REPLACE; - -// -// Specify how consensus forecasts should be defined: -// name = consensus model name -// members = array of consensus member model names -// required = array of TRUE/FALSE for each member -// if empty, default is FALSE -// min_req = minimum number of members required for the consensus -// -// e.g. -// consensus = [ -// { -// name = "CON1"; -// members = [ "MOD1", "MOD2", "MOD3" ]; -// required = [ TRUE, FALSE, FALSE ]; -// min_req = 2; -// } -// ]; -// -consensus = []; - -// -// Specify a comma-separated list of forecast lag times to be used in HH[MMSS] -// format. For each ADECK track identified, a lagged track will be derived -// for each entry listed. -// -// e.g. lag_time = [ "06", "12" ]; -// -lag_time = []; - -// -// Specify comma-separated lists of CLIPER/SHIFOR baseline forecasts to be -// derived from the BEST and operational tracks, as defined by the -// best_technique and oper_technique settings. -// -// Derived from BEST tracks: BCLP, BCS5, BCD5, BCLA -// Derived from OPER tracks: OCLP, OCS5, OCD5, OCDT -// -// e.g. best_technique = [ "BEST" ]; -// base_baseline = [ "BCLP", "BCS5", "BCD5", "BCLA" ]; -// oper_technique = [ "CARQ" ]; -// oper_baseline = [ "OCLP", "OCS5", "OCD5", "OCDT" ]; -// -best_technique = [ "BEST" ]; -best_baseline = []; -oper_technique = [ "CARQ" ]; -oper_baseline = []; - -// -// Analysis tracks consist of multiple track points with a lead time of zero -// for the same storm. An analysis track may be generated by running model -// analysis fields through a tracking algorithm. Specify which datasets should -// be searched for analysis track data by setting this to NONE, ADECK, BDECK, -// or BOTH. Use BOTH to create pairs using two different analysis tracks. -// -// e.g. anly_track = BDECK; -// -anly_track = BDECK; - -// -// Specify whether only those track points common to both the ADECK and BDECK -// tracks should be written out. -// -// e.g. match_points = FALSE; -// -match_points = FALSE; - -// -// Specify the NetCDF output of the gen_dland tool containing a gridded -// representation of the minimum distance to land. -// -dland_file = "MET_BASE/tc_data/dland_nw_hem_tenth_degree.nc"; - -// -// Specify watch/warning information. Specify an ASCII file containing -// watch/warning information to be used. At each track point, the most severe -// watch/warning status in effect, if any, will be written to the output. -// Also specify a time offset in seconds to be added to each watch/warning -// time processed. NHC applies watch/warning information to all track points -// occurring 4 hours (-14400 second) prior to the watch/warning time. -// -watch_warn = { - file_name = "MET_BASE/tc_data/wwpts_us.txt"; - time_offset = -14400; -} - -// -// The basin_map entry defines a mapping of input names to output values. -// Whenever the basin string matches "key" in the input ATCF files, it is -// replaced with "val". This map can be used to modify basin names to make them -// consistent across the ATCF input files. -// -// Many global modeling centers use ATCF basin identifiers based on region -// (e.g., 'SP' for South Pacific Ocean, etc.), however the best track data -// provided by the Joint Typhoon Warning Center (JTWC) use just one basin -// identifier 'SH' for all of the Southern Hemisphere basins. Additionally, -// some modeling centers may report basin identifiers separately for the Bay -// of Bengal (BB) and Arabian Sea (AB) whereas JTWC uses 'IO'. -// -// The basin mapping allows MET to map the basin identifiers to the expected -// values without having to modify your data. For example, the first entry -// in the list below indicates that any data entries for 'SI' will be matched -// as if they were 'SH'. In this manner, all verification results for the -// Southern Hemisphere basins will be reported together as one basin. -// -// An empty list indicates that no basin mapping should be used. Use this if -// you are not using JTWC best tracks and you would like to match explicitly -// by basin or sub-basin. Note that if your model data and best track do not -// use the same basin identifier conventions, using an empty list for this -// parameter will result in missed matches. -// -basin_map = [ - { key = "SI"; val = "SH"; }, - { key = "SP"; val = "SH"; }, - { key = "AU"; val = "SH"; }, - { key = "AB"; val = "IO"; }, - { key = "BB"; val = "IO"; } -]; +~~~~~~~~~~~~~~~~~~~~~ + +**model** + +The "model" entry specifies an array of model names to be verified. If +verifying multiple models, choose descriptive model names (no whitespace) +to distinguish between their output. + +For example: + +| model = [ "AHW4", "AHWI" ]; +| + +.. code-block:: none + + model = []; + + +**check_dup** + +Specify whether the code should check for duplicate ATCF lines when +building tracks. Setting this to FALSE makes the parsing of tracks quicker. + +For example: + +| check_dup = FALSE; +| + +.. code-block:: none + + check_dup = FALSE; + +**interp12** + +Specify whether special processing should be performed for interpolated model +names ending in 'I' (e.g. AHWI). Search for corresponding tracks whose model +name ends in '2' (e.g. AHW2) and apply the following logic: + +* "NONE" to do nothing. + +* "FILL" to create a copy of '2' track and rename it as 'I' only when the + 'I' track does not already exist. + +* "REPLACE" to create a copy of the '2' track and rename it as 'I' in all + cases, replacing any 'I' tracks that may already exist. + +.. code-block:: none + + interp12 = REPLACE; + +**consensus** + +Specify how consensus forecasts should be defined: + +| name = consensus model name +| members = array of consensus member model names +| required = array of TRUE/FALSE for each member if empty, default is FALSE +| min_req = minimum number of members required for the consensus +| + +For example: + +| consensus = [ +| { +| name = "CON1"; +| members = [ "MOD1", "MOD2", "MOD3" ]; +| required = [ TRUE, FALSE, FALSE ]; +| min_req = 2; +| } +| ]; +| + +.. code-block:: none + + consensus = []; + + +**lag_time** + +Specify a comma-separated list of forecast lag times to be used in HH[MMSS] +format. For each ADECK track identified, a lagged track will be derived +for each entry listed. + +For example: + +| lag_time = [ "06", "12" ]; +| + +.. code-block:: none + + lag_time = []; + + +**best_technique, best_baseline, oper_technique, oper_baseline** + +Specify comma-separated lists of CLIPER/SHIFOR baseline forecasts to be +derived from the BEST and operational tracks, as defined by the +best_technique and oper_technique settings. + +| Derived from BEST tracks: +| BCLP, BCS5, BCD5, BCLA +| Derived from OPER tracks: +| OCLP, OCS5, OCD5, OCDT +| + +For example: + +| best_technique = [ "BEST" ]; +| + +.. code-block:: none + + best_technique = [ "BEST" ]; + best_baseline = []; + oper_technique = [ "CARQ" ]; + oper_baseline = []; + + +**anly_track** + +Analysis tracks consist of multiple track points with a lead time of zero +for the same storm. An analysis track may be generated by running model +analysis fields through a tracking algorithm. Specify which datasets should +be searched for analysis track data by setting this to NONE, ADECK, BDECK, +or BOTH. Use BOTH to create pairs using two different analysis tracks. + +For example: + +| anly_track = BDECK; +| + +.. code-block:: none + + anly_track = BDECK; + + +**match_points** + +Specify whether only those track points common to both the ADECK and BDECK +tracks should be written out. + + +For example: + +| match_points = FALSE; +| + +.. code-block:: none + + match_points = FALSE; + + +**dland_file** + +Specify the NetCDF output of the gen_dland tool containing a gridded +representation of the minimum distance to land. + + +.. code-block:: none + + dland_file = "MET_BASE/tc_data/dland_nw_hem_tenth_degree.nc"; + + +**watch_warn** + +Specify watch/warning information. Specify an ASCII file containing +watch/warning information to be used. At each track point, the most severe +watch/warning status in effect, if any, will be written to the output. +Also specify a time offset in seconds to be added to each watch/warning +time processed. NHC applies watch/warning information to all track points +occurring 4 hours (-14400 second) prior to the watch/warning time. + + +.. code-block:: none + + watch_warn = { + file_name = "MET_BASE/tc_data/wwpts_us.txt"; + time_offset = -14400; + } + + +**basin_map** + +The basin_map entry defines a mapping of input names to output values. +Whenever the basin string matches "key" in the input ATCF files, it is +replaced with "val". This map can be used to modify basin names to make them +consistent across the ATCF input files. + +Many global modeling centers use ATCF basin identifiers based on region +(e.g., 'SP' for South Pacific Ocean, etc.), however the best track data +provided by the Joint Typhoon Warning Center (JTWC) use just one basin +identifier 'SH' for all of the Southern Hemisphere basins. Additionally, +some modeling centers may report basin identifiers separately for the Bay +of Bengal (BB) and Arabian Sea (AB) whereas JTWC uses 'IO'. + +The basin mapping allows MET to map the basin identifiers to the expected +values without having to modify your data. For example, the first entry +in the list below indicates that any data entries for 'SI' will be matched +as if they were 'SH'. In this manner, all verification results for the +Southern Hemisphere basins will be reported together as one basin. + +An empty list indicates that no basin mapping should be used. Use this if +you are not using JTWC best tracks and you would like to match explicitly +by basin or sub-basin. Note that if your model data and best track do not +use the same basin identifier conventions, using an empty list for this +parameter will result in missed matches. + + +.. code-block:: none + + basin_map = [ + { key = "SI"; val = "SH"; }, + { key = "SP"; val = "SH"; }, + { key = "AU"; val = "SH"; }, + { key = "AB"; val = "IO"; }, + { key = "BB"; val = "IO"; } + ]; TCStatConfig_default -~~~~~~~~~~~~~~~~~~~~ - -// -// Stratify by the AMODEL or BMODEL columns. -// Specify comma-separated lists of model names to be used for all analyses -// performed. May add to this list using the "-amodel" and "-bmodel" -// job command options. -// e.g. amodel = [ "AHW4" ]; -// bmodel = [ "BEST" ]; -// -amodel = []; -bmodel = []; - -// -// Stratify by the VALID times. -// Define beginning and ending time windows in YYYYMMDD[_HH[MMSS]] -// or provide a list of specific valid times to include or exclude. -// May modify using the "-valid_beg", "-valid_end", "-valid_inc", -// and "-valid_exc" job command options. -// -// e.g. valid_beg = "20100101"; -// valid_end = "20101231_12"; -// valid_inc = [ "20101231_06" ]; -// valid_exc = [ "20101231_00" ]; -// -valid_beg = ""; -valid_end = ""; -valid_inc = []; -valid_exc = []; - -// -// Stratify by the initialization and valid hours and lead time. -// Specify a comma-separated list of initialization hours, -// valid hours, and lead times in HH[MMSS] format. -// May add using the "-init_hour", "-valid_hour", "-lead", -// and "-lead_req" job command options. -// -// e.g. init_hour = [ "00" ]; -// valid_hour = [ "12" ]; -// lead = [ "24", "36" ]; -// lead_req = [ "72", "84", "96", "108" ]; -// -init_hour = []; -valid_hour = []; -lead = []; -lead_req = []; - -// -// Stratify by the LINE_TYPE column. May add using the "-line_type" -// job command option. -// -// e.g. line_type = [ "TCMPR" ]; -// -line_type = []; - -// -// Stratify by checking the watch/warning status for each track point -// common to both the ADECK and BDECK tracks. If the watch/warning status -// of any of the track points appears in the list, retain the entire track. -// Individual watch/warning status by point may be specified using the -// -column_str options below, but this option filters by the track maximum. -// May add using the "-track_watch_warn" job command option. -// The value "ALL" matches HUWARN, TSWARN, HUWATCH, and TSWATCH. -// -// e.g. track_watch_warn = [ "HUWATCH", "HUWARN" ]; -// -track_watch_warn = []; - -// -// Stratify by applying thresholds to numeric data columns. -// Specify a comma-separated list of columns names and thresholds -// to be applied. May add using the "-column_thresh name thresh" job command -// options. -// -// e.g. column_thresh_name = [ "ADLAND", "BDLAND" ]; -// column_thresh_val = [ >200, >200 ]; -// -column_thresh_name = []; -column_thresh_val = []; - -// -// Stratify by performing string matching on non-numeric data columns. -// Specify a comma-separated list of columns names and values -// to be checked. May add using the "-column_str name string" job command -// options. -// -// e.g. column_str_name = [ "LEVEL", "LEVEL" ]; -// column_str_val = [ "HU", "TS" ]; -// -column_str_name = []; -column_str_val = []; - -// -// Just like the column_thresh options above, but apply the threshold only -// when lead = 0. If lead = 0 value does not meet the threshold, discard -// the entire track. May add using the "-init_thresh name thresh" job command -// options. -// -// e.g. init_thresh_name = [ "ADLAND" ]; -// init_thresh_val = [ >200 ]; -// -init_thresh_name = []; -init_thresh_val = []; - -// -// Just like the column_str options above, but apply the string matching only -// when lead = 0. If lead = 0 string does not match, discard the entire track. -// May add using the "-init_str name thresh" job command options. -// -// e.g. init_str_name = [ "LEVEL" ]; -// init_str_val = [ "HU" ]; -// -init_str_name = []; -init_str_val = []; - -// -// Stratify by the ADECK and BDECK distances to land. Once either the ADECK or -// BDECK track encounters land, discard the remainder of the track. -// -// e.g. water_only = FALSE; -// -water_only = FALSE; - -// -// Specify whether only those track points for which rapid intensification -// or weakening of the maximum wind speed occurred in the previous time -// step should be retained. -// -// The NHC considers a 24-hour change >=30 kts to constitute rapid -// intensification or weakening. -// -// May modify using the following job command options: -// "-rirw_track" -// "-rirw_time" for both or "-rirw_time_adeck" and "-rirw_time_bdeck" -// "-rirw_exact" for both or "-rirw_exact_adeck" and "-rirw_exact_bdeck" -// "-rirw_thresh" for both or "-rirw_thresh_adeck" and "-rirw_thresh_bdeck" -// - -rirw = { - track = NONE; // Specify which track types to search (NONE, ADECK, - // BDECK, or BOTH) - adeck = { - time = "24"; // Rapid intensification/weakening time period in HHMMSS - // format. - exact = TRUE; // Use the exact or maximum intensity difference over the - // time period. - thresh = >=30.0; // Threshold for the intensity change. - } - bdeck = adeck; // Copy settings to the BDECK or specify different logic. -} - -// -// Specify whether only those track points occurring near landfall should be -// retained, and define the landfall retention window as a timestring in HH[MMSS] -// format (or as an integer number of seconds) offset from the landfall time. -// Landfall is defined as the last BDECK track point before the distance to land -// switches from positive to 0 or negative. -// -// May modify using the "-landfall_window" job command option, which -// automatically sets -landfall to TRUE. -// -// The "-landfall_window" job command option takes 1 or 2 arguments in HH[MMSS] -// format. Use 1 argument to define a symmetric time window. For example, -// "-landfall_window 06" defines the time window +/- 6 hours around the landfall -// time. Use 2 arguments to define an asymmetric time window. For example, -// "-landfall_window 00 12" defines the time window from the landfall event to 12 -// hours after. -// -// e.g. landfall = FALSE; -// landfall_beg = "-24"; (24 hours prior to landfall) -// landfall_end = "00"; -// -landfall = FALSE; -landfall_beg = "-24"; -landfall_end = "00"; - -// -// Specify whether only those cases common to all models in the dataset should -// be retained. May modify using the "-event_equal" job command option. -// -// e.g. event_equal = FALSE; -// -event_equal = FALSE; - -// -// Specify lead times that must be present for a track to be included in the -// event equalization logic. -// -event_equal_lead = [ "12", "24", "36" ]; - -// -// Apply polyline masking logic to the location of the ADECK track at the -// initialization time. If it falls outside the mask, discard the entire track. -// May modify using the "-out_init_mask" job command option. -// -// e.g. out_init_mask = ""; -// -out_init_mask = ""; - -// -// Apply polyline masking logic to the location of the ADECK track at the -// valid time. If it falls outside the mask, discard only the current track -// point. May modify using the "-out_valid_mask" job command option. -// -// e.g. out_valid_mask = ""; -// -out_valid_mask = ""; - -// -// The "jobs" entry is an array of TCStat jobs to be performed. -// Each element in the array contains the specifications for a single analysis -// job to be performed. The format for an analysis job is as follows: -// -// -job job_name -// OPTIONAL ARGS -// -// Where "job_name" is set to one of the following: -// -// "filter" -// To filter out the TCST lines matching the job filtering criteria -// specified above and using the optional arguments below. The -// output TCST lines are written to the file specified using the -// "-dump_row" argument. -// Required Args: -dump_row -// -// To further refine the TCST data: Each optional argument may be used -// in the job specification multiple times unless otherwise indicated. -// When multiple optional arguments of the same type are indicated, the -// analysis will be performed over their union -// -// "-amodel name" -// "-bmodel name" -// "-lead HHMMSS" -// "-valid_beg YYYYMMDD[_HH[MMSS]]" (use once) -// "-valid_end YYYYMMDD[_HH[MMSS]]" (use once) -// "-valid_inc YYYYMMDD[_HH[MMSS]]" (use once) -// "-valid_exc YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_beg YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_end YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_inc YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_exc YYYYMMDD[_HH[MMSS]]" (use once) -// "-init_hour HH[MMSS]" -// "-valid_hour HH[MMSS] -// "-init_mask name" -// "-valid_mask name" -// "-line_type name" -// "-track_watch_warn name" -// "-column_thresh name thresh" -// "-column_str name string" -// "-init_thresh name thresh" -// "-init_str name string" -// -// Additional filtering options that may be used only when -line_type -// has been listed only once. These options take two arguments: the name -// of the data column to be used and the min, max, or exact value for -// that column. If multiple column eq/min/max/str options are listed, -// the job will be performed on their intersection: -// -// "-column_min col_name value" e.g. -column_min TK_ERR 100.00 -// "-column_max col_name value" -// "-column_eq col_name value" -// "-column_str col_name string" separate multiple filtering strings -// with commas -// -// Required Args: -dump_row -// -// "summary" -// To compute the mean, standard deviation, and percentiles -// (0th, 10th, 25th, 50th, 75th, 90th, and 100th) for the statistic -// specified using the "-line_type" and "-column" arguments. -// For TCStat, the "-column" argument may be set to: -// -// "TRACK" for track, along-track, and cross-track errors. -// "WIND" for all wind radius errors. -// "TI" for track and maximum wind intensity errors. -// "AC" for along-track and cross-track errors. -// "XY" for x-track and y-track errors. -// "col" for a specific column name. -// "col1-col2" for a difference of two columns. -// "ABS(col or col1-col2)" for the absolute value. -// -// Use the -column_union TRUE/FALSE job command option to compute -// summary statistics across the union of input columns rather than -// processing them separately. -// -// Required Args: -line_type, -column -// Optional Args: -by column_name to specify case information -// -out_alpha to override default alpha value -// -column_union to summarize multiple columns -// -// "rirw" -// To define rapid intensification/weakening contingency table using -// the ADECK and BDECK RI/RW settings and the matching time window -// and output contingency table counts and statistics. -// -// Optional Args: -// -rirw_window width in HH[MMSS] format to define a symmetric time -// window -// -rirw_window beg end in HH[MMSS] format to define an asymmetric -// time window -// Default search time window is 0 0, requiring exact match -// -rirw_time or -rirw_time_adeck and -rirw_time_bdeck to override -// defaults -// -rirw_exact or -rirw_exact_adeck and -rirw_exact_bdeck to override -// defaults -// -rirw_thresh or -rirw_thresh_adeck and -rirw_thresh_bdeck to -// override defaults -// -by column_name to specify case information -// -out_alpha to override default alpha value -// -out_line_type to specify output line types (CTC, CTS, and MPR) -// -// Note that the "-dump_row path" option results in 4 files being -// created: -// path_FY_OY.tcst, path_FY_ON.tcst, path_FN_OY.tcst, and -// path_FN_ON.tcst, containing the TCST lines that were hits, false -// alarms, misses, and correct negatives, respectively. These files -// may be used as input for additional TC-Stat analysis. -// -// "probrirw" -// To define an Nx2 probabilistic contingency table by reading the -// PROBRIRW line type, binning the forecast probabilities, and writing -// output probabilistic counts and statistics. -// -// Required Args: -// -probrirw_thresh to define the forecast probabilities to be -// evaluated (e.g. -probrirw_thresh 30) -// -// Optional Args: -// -probrirw_exact TRUE/FALSE to verify against the exact (e.g. -// BDELTA column) or maximum (e.g. BDELTA_MAX column) intensity -// change in the BEST track -// -probrirw_bdelta_thresh to define BEST track change event -// threshold (e.g. -probrirw_bdelta_thresh >=30) -// -probrirw_prob_thresh to define output probability thresholds -// (e.g. -probrirw_prob_thresh ==0.1) -// -by column_name to specify case information -// -out_alpha to override default alpha value -// -out_line_type to specify output line types (PCT, PSTD, PRC, and -// PJC) -// -// For the PROBRIRW line type, PROBRIRW_PROB is a derived column name. -// For example, the following options select 30 kt probabilities and match -// probability values greater than 0: -// -probrirw_thresh 30 -column_thresh PROBRIRW_PROB >0 -// -// e.g. -// jobs = [ -// "-job filter -amodel AHW4 -dumprow ./tc_filter_job.tcst", -// "-job filter -column_min TK_ERR 100.000 \ -// -dumprow ./tc_filter_job.tcst", -// "-job summary -line_type TCMPR -column AC \ -// -dumprow ./tc_summary_job.tcst", -// "-job rirw -amodel AHW4 -dump_row ./tc_rirw_job" ] -// -jobs = []; +____________________ + +**amodel, bmodel** + +Stratify by the AMODEL or BMODEL columns. +Specify comma-separated lists of model names to be used for all analyses +performed. May add to this list using the "-amodel" and "-bmodel" +job command options. + +For example: + +| amodel = [ "AHW4" ]; +| bmodel = [ "BEST" ]; +| + +.. code-block:: none + + amodel = []; + bmodel = []; + + +**valid_beg, valid_end, valid_inc, valid_exc** + +Stratify by the VALID times. +Define beginning and ending time windows in YYYYMMDD[_HH[MMSS]] +or provide a list of specific valid times to include or exclude. +May modify using the "-valid_beg", "-valid_end", "-valid_inc", +and "-valid_exc" job command options. + +For example: + +| valid_beg = "20100101"; +| valid_end = "20101231_12"; +| valid_inc = [ "20101231_06" ]; +| valid_exc = [ "20101231_00" ]; +| + +.. code-block:: none + + valid_beg = ""; + valid_end = ""; + valid_inc = []; + valid_exc = []; + +**ini_hour, valid_hour, lead, lead_req** + +Stratify by the initialization and valid hours and lead time. +Specify a comma-separated list of initialization hours, +valid hours, and lead times in HH[MMSS] format. +May add using the "-init_hour", "-valid_hour", "-lead", +and "-lead_req" job command options. + +For example: + +| init_hour = [ "00" ]; +| valid_hour = [ "12" ]; +| lead = [ "24", "36" ]; +| lead_req = [ "72", "84", "96", "108" ]; +| + +.. code-block:: none + + init_hour = []; + valid_hour = []; + lead = []; + lead_req = []; + + +**line_type** + +Stratify by the LINE_TYPE column. May add using the "-line_type" +job command option. + +For example: + +| line_type = [ "TCMPR" ]; +| + +.. code-block:: none + + line_type = []; + +**track_watch_warn** + +Stratify by checking the watch/warning status for each track point +common to both the ADECK and BDECK tracks. If the watch/warning status +of any of the track points appears in the list, retain the entire track. +Individual watch/warning status by point may be specified using the +-column_str options below, but this option filters by the track maximum. +May add using the "-track_watch_warn" job command option. +The value "ALL" matches HUWARN, TSWARN, HUWATCH, and TSWATCH. + +For example: + +| track_watch_warn = [ "HUWATCH", "HUWARN" ]; +| + +.. code-block:: none + + track_watch_warn = []; + + +**column_thresh_name, column_thresh_val** + +Stratify by applying thresholds to numeric data columns. +Specify a comma-separated list of columns names and thresholds +to be applied. May add using the "-column_thresh name thresh" job command +options. + +For example: + +| column_thresh_name = [ "ADLAND", "BDLAND" ]; +| column_thresh_val = [ >200, >200 ]; +| + +.. code-block:: none + + column_thresh_name = []; + column_thresh_val = []; + +**column_str_name, column_str_val** + +Stratify by performing string matching on non-numeric data columns. +Specify a comma-separated list of columns names and values +to be checked. May add using the "-column_str name string" job command +options. + +For example: + +| column_str_name = [ "LEVEL", "LEVEL" ]; +| column_str_val = [ "HU", "TS" ]; +| + +.. code-block:: none + + column_str_name = []; + column_str_val = []; + + +**init_thresh_name, init_thresh_val** + +Just like the column_thresh options above, but apply the threshold only +when lead = 0. If lead = 0 value does not meet the threshold, discard +the entire track. May add using the "-init_thresh name thresh" job command +options. + +For example: + +| init_thresh_name = [ "ADLAND" ]; +| init_thresh_val = [ >200 ]; +| + +.. code-block:: none + + init_thresh_name = []; + init_thresh_val = []; + +**init_str_name, init_str_val** + +Just like the column_str options above, but apply the string matching only +when lead = 0. If lead = 0 string does not match, discard the entire track. +May add using the "-init_str name thresh" job command options. + +For example: + +| init_str_name = [ "LEVEL" ]; +| init_str_val = [ "HU" ]; +| + +.. code-block:: none + + init_str_name = []; + init_str_val = []; + +**water_only** + +Stratify by the ADECK and BDECK distances to land. Once either the ADECK or +BDECK track encounters land, discard the remainder of the track. + +For example: + +| water_only = FALSE; +| + +.. code-block:: none + + water_only = FALSE; + +**rirw** + +Specify whether only those track points for which rapid intensification +or weakening of the maximum wind speed occurred in the previous time +step should be retained. + +The NHC considers a 24-hour change >=30 kts to constitute rapid +intensification or weakening. + +May modify using the following job command options: + +| "-rirw_track" +| "-rirw_time" for both or "-rirw_time_adeck" and "-rirw_time_bdeck" +| "-rirw_exact" for both or "-rirw_exact_adeck" and "-rirw_exact_bdeck" +| "-rirw_thresh" for both or "-rirw_thresh_adeck" and "-rirw_thresh_bdeck" +| + +.. code-block:: none + + rirw = { + track = NONE; Specify which track types to search (NONE, ADECK, + BDECK, or BOTH) + adeck = { + time = "24"; Rapid intensification/weakening time period in HHMMSS + format. + exact = TRUE; Use the exact or maximum intensity difference over the + time period. + thresh = >=30.0; Threshold for the intensity change. + } + bdeck = adeck; Copy settings to the BDECK or specify different logic. + } + +**landfall, landfall_beg, landfall_end** + +Specify whether only those track points occurring near landfall should be +retained, and define the landfall retention window as a time string in HH[MMSS] +format (or as an integer number of seconds) offset from the landfall time. +Landfall is defined as the last BDECK track point before the distance to land +switches from positive to 0 or negative. + +May modify using the "-landfall_window" job command option, which +automatically sets -landfall to TRUE. + +The "-landfall_window" job command option takes 1 or 2 arguments in HH[MMSS] +format. Use 1 argument to define a symmetric time window. For example, +"-landfall_window 06" defines the time window +/- 6 hours around the landfall +time. Use 2 arguments to define an asymmetric time window. For example, +"-landfall_window 00 12" defines the time window from the landfall event to 12 +hours after. + +For example: + +| landfall = FALSE; +| landfall_beg = "-24"; (24 hours prior to landfall) +| landfall_end = "00"; +| + +.. code-block:: none + + landfall = FALSE; + landfall_beg = "-24"; + landfall_end = "00"; + +**event_equal** + +Specify whether only those cases common to all models in the dataset should +be retained. May modify using the "-event_equal" job command option. + +For example: + +| event_equal = FALSE; +| + +.. code-block:: none + + event_equal = FALSE; + + +**event_equal_lead** + +Specify lead times that must be present for a track to be included in the +event equalization logic. + +.. code-block:: none + + event_equal_lead = [ "12", "24", "36" ]; + + +**out_int_mask** + +Apply polyline masking logic to the location of the ADECK track at the +initialization time. If it falls outside the mask, discard the entire track. +May modify using the "-out_init_mask" job command option. + +For example: + +| out_init_mask = ""; +| + +.. code-block:: none + + out_init_mask = ""; + + +**out_valid_mask** + +Apply polyline masking logic to the location of the ADECK track at the +valid time. If it falls outside the mask, discard only the current track +point. May modify using the "-out_valid_mask" job command option. + +For example: + +| out_valid_mask = ""; +| + +.. code-block:: none + + out_valid_mask = ""; + +**job** + +The "jobs" entry is an array of TCStat jobs to be performed. +Each element in the array contains the specifications for a single analysis +job to be performed. The format for an analysis job is as follows: + +| -job job_name +| OPTIONAL ARGS +| + +Where "job_name" is set to one of the following: + +* "filter" + + To filter out the TCST lines matching the job filtering criteria + specified above and using the optional arguments below. The + output TCST lines are written to the file specified using the + "-dump_row" argument. + + Required Args: -dump_row + + To further refine the TCST data: Each optional argument may be used + in the job specification multiple times unless otherwise indicated. + When multiple optional arguments of the same type are indicated, the + analysis will be performed over their union. + + .. code-block:: none + + "-amodel name" + "-bmodel name" + "-lead HHMMSS" + "-valid_beg YYYYMMDD[_HH[MMSS]]" (use once) + "-valid_end YYYYMMDD[_HH[MMSS]]" (use once) + "-valid_inc YYYYMMDD[_HH[MMSS]]" (use once) + "-valid_exc YYYYMMDD[_HH[MMSS]]" (use once) + "-init_beg YYYYMMDD[_HH[MMSS]]" (use once) + "-init_end YYYYMMDD[_HH[MMSS]]" (use once) + "-init_inc YYYYMMDD[_HH[MMSS]]" (use once) + "-init_exc YYYYMMDD[_HH[MMSS]]" (use once) + "-init_hour HH[MMSS]" + "-valid_hour HH[MMSS] + "-init_mask name" + "-valid_mask name" + "-line_type name" + "-track_watch_warn name" + "-column_thresh name thresh" + "-column_str name string" + "-init_thresh name thresh" + "-init_str name string" + + Additional filtering options that may be used only when -line_type + has been listed only once. These options take two arguments: the name + of the data column to be used and the min, max, or exact value for + that column. If multiple column eq/min/max/str options are listed, + the job will be performed on their intersection: + + .. code-block:: none + + "-column_min col_name value" For example: -column_min TK_ERR 100.00 + "-column_max col_name value" + "-column_eq col_name value" + "-column_str col_name string" separate multiple filtering strings + with commas + + Required Args: -dump_row + +| + +* "summary" + + To compute the mean, standard deviation, and percentiles + (0th, 10th, 25th, 50th, 75th, 90th, and 100th) for the statistic + specified using the "-line_type" and "-column" arguments. + For TCStat, the "-column" argument may be set to: + + * "TRACK" for track, along-track, and cross-track errors. + * "WIND" for all wind radius errors. + * "TI" for track and maximum wind intensity errors. + * "AC" for along-track and cross-track errors. + * "XY" for x-track and y-track errors. + * "col" for a specific column name. + * "col1-col2" for a difference of two columns. + * "ABS(col or col1-col2)" for the absolute value. + + Use the -column_union TRUE/FALSE job command option to compute + summary statistics across the union of input columns rather than + processing them separately. + + Required Args: -line_type, -column + + Optional Args: + + .. code-block:: none + + -by column_name to specify case information + -out_alpha to override default alpha value + -column_union to summarize multiple columns + +* "rirw" + + To define rapid intensification/weakening contingency table using + the ADECK and BDECK RI/RW settings and the matching time window + and output contingency table counts and statistics. + + Optional Args: + + .. code-block:: none + + -rirw_window width in HH[MMSS] format to define a symmetric time window + -rirw_window beg end in HH[MMSS] format to define an asymmetric time window + Default search time window is 0 0, requiring exact match + -rirw_time or -rirw_time_adeck and -rirw_time_bdeck to override defaults + -rirw_exact or -rirw_exact_adeck and -rirw_exact_bdeck to override defaults + -rirw_thresh or -rirw_thresh_adeck and -rirw_thresh_bdeck to override defaults + -by column_name to specify case information + -out_alpha to override default alpha value + -out_line_type to specify output line types (CTC, CTS, and MPR) + + + Note that the "-dump_row path" option results in 4 files being + created: + +| path_FY_OY.tcst, path_FY_ON.tcst, path_FN_OY.tcst, and +| path_FN_ON.tcst, containing the TCST lines that were hits, false +| alarms, misses, and correct negatives, respectively. These files +| may be used as input for additional TC-Stat analysis. +| + +* "probrirw" + + To define an Nx2 probabilistic contingency table by reading the + PROBRIRW line type, binning the forecast probabilities, and writing + output probabilistic counts and statistics. + + Required Args: + + .. code-block:: none + + -probrirw_thresh to define the forecast probabilities to be + evaluated (For example: -probrirw_thresh 30) + + Optional Args: + + .. code-block:: none + + -probrirw_exact TRUE/FALSE to verify against the exact (for example: + BDELTA column) or maximum (for example: BDELTA_MAX column) intensity + change in the BEST track + -probrirw_bdelta_thresh to define BEST track change event + threshold (For example: -probrirw_bdelta_thresh >=30) + -probrirw_prob_thresh to define output probability thresholds + (for example: -probrirw_prob_thresh ==0.1) + -by column_name to specify case information + -out_alpha to override default alpha value + -out_line_type to specify output line types (PCT, PSTD, PRC, and PJC) + + + For the PROBRIRW line type, PROBRIRW_PROB is a derived column name. + For example, the following options select 30 kt probabilities and match + probability values greater than 0: + +| -probrirw_thresh 30 -column_thresh PROBRIRW_PROB >0 +| + + For example: + +| jobs = [ +| "-job filter -amodel AHW4 -dumprow ./tc_filter_job.tcst", +| "-job filter -column_min TK_ERR 100.000 \ +| -dumprow ./tc_filter_job.tcst", +| "-job summary -line_type TCMPR -column AC \ +| -dumprow ./tc_summary_job.tcst", +| "-job rirw -amodel AHW4 -dump_row ./tc_rirw_job" ] +| + +.. code-block:: none + + jobs = []; TCGenConfig_default -~~~~~~~~~~~~~~~~~~~ - -// -// Model initialization frequency in hours, starting at 0. -// -init_freq = 6; - -// -// Lead times in hours to be searched for genesis events. -// -lead_window = { - beg = 24; - end = 120; -} - -// -// Minimum track duration for genesis event in hours. -// -min_duration = 12; - -// -// 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 = { - vmax_thresh = NA; - mslp_thresh = NA; -} - -// -// 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 = { - technique = "BEST"; - category = [ "TD", "TS" ]; - vmax_thresh = NA; - mslp_thresh = NA; -} - -// -// 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 = { - technique = "CARQ"; - category = [ "DB", "LO", "WV" ]; - vmax_thresh = NA; - mslp_thresh = NA; -} - -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 = []; - -// -// 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 = { - beg = -24; - end = 24; -} - -// -// Genesis matching search radius in km. -// -genesis_radius = 300; +___________________ + +**int_freq** + +Model initialization frequency in hours, starting at 0. + +.. code-block:: none + + init_freq = 6; + +**lead_window** + +Lead times in hours to be searched for genesis events. + + +.. code-block:: none + + lead_window = { + beg = 24; + end = 120; + } + +**min_duration** + +Minimum track duration for genesis event in hours. + +.. code-block:: none + + min_duration = 12; + +**fcst_genesis** + +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. + + +.. code-block:: none + + fcst_genesis = { + vmax_thresh = NA; + mslp_thresh = NA; + } + +**best_genesis** + +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. + +.. code-block:: none + + best_genesis = { + technique = "BEST"; + category = [ "TD", "TS" ]; + vmax_thresh = NA; + mslp_thresh = NA; + } + +**oper_genesis** + +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. + +.. code-block:: none + + oper_genesis = { + technique = "CARQ"; + category = [ "DB", "LO", "WV" ]; + vmax_thresh = NA; + mslp_thresh = NA; + } + +Track filtering options which may be specified separately in each filter array entry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**filter** + +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. + +.. code-block:: none + + filter = []; + +**desc** + +Description written to output DESC column + +.. code-block:: none + + desc = "NA"; + +**model** + +Forecast ATCF ID's +If empty, all ATCF ID's found will be processed. +Statistics will be generated separately for each ATCF ID. + + +.. code-block:: none + + model = []; + +**storm_id** + +BEST and operational track storm identifiers + +.. code-block:: none + + storm_id = []; + +**storm_name** + +BEST and operational track storm names + +.. code-block:: none + + storm_name = []; + +**init_beg, init_end** + +Forecast and operational initialization time window + +.. code-block:: none + + init_beg = ""; + init_end = ""; + +**valid_beg, valid_end** + +Forecast, BEST, and operational valid time window + +.. code-block:: none + + valid_beg = ""; + valid_end = ""; + +**init_hour** + +Forecast and operational initialization hours + +.. code-block:: none + + init_hour = []; + +**lead** + +Forecast and operational lead times in hours + +.. code-block:: none + + lead = []; + +**vx_mask** + +Spatial masking region (path to gridded data file or polyline file) + +.. code-block:: none + + vx_mask = ""; + +**dland_thresh** + +Distance to land threshold + +.. code-block:: none + + dland_thresh = NA; + +**genesis_window** + +Genesis matching time window, in hours relative to the forecast genesis time + +.. code-block:: none + + genesis_window = { + beg = -24; + end = 24; + } + +**genesis_radius** + +Genesis matching search radius in km. + +.. code-block:: none + + genesis_radius = 300; Global settings -~~~~~~~~~~~~~~~ - -// -// Confidence interval alpha value -// -ci_alpha = 0.05; - -// -// Statistical output types -// -output_flag = { - fho = NONE; - ctc = BOTH; - cts = BOTH; -} +_______________ + +**ci_alpha** + +Confidence interval alpha value + +.. code-block:: none + + ci_alpha = 0.05; + +**output_flag** + +Statistical output types + +.. code-block:: none + + output_flag = { + fho = NONE; + ctc = BOTH; + cts = BOTH; + } diff --git a/met/docs/Users_Guide/tc-stat.rst b/met/docs/Users_Guide/tc-stat.rst index 70aca58a6d..6cecdfabbc 100644 --- a/met/docs/Users_Guide/tc-stat.rst +++ b/met/docs/Users_Guide/tc-stat.rst @@ -292,7 +292,7 @@ _________________________ The **rirw** field specifies those track points for which rapid intensification (RI) or rapid weakening (RW) occurred, based on user defined RI/RW thresholds. The **track** entry specifies that RI/RW is not turned on **(NONE)**, is computed based on the bmodel only **(BDECK)**, is computed based on the amodel only **(ADECK)**, or computed when both the amodel and bmodel (the union of the two) indicate RI/RW (BOTH). If **track** is set to **ADECK, BDECK**, or **BOTH**, only tracks exhibiting rapid intensification will be retained. Rapid intensification is officially defined as when the change in the maximum wind speed over a 24-hour period is greater than or equal to 30 kts. This is the default setting, however flexibility in this definition is provided through the use of the **time, exact** and **thresh** options. The **time** field specifies the time window (HH[MMSS] format) for which the RI/RW occurred. The **exact** field specifies whether to only count RI/RW when the intensity change is over the exact time window (TRUE), which follows the official RI definition, or if the intensity threshold is met anytime during the time window (FALSE). Finally, the **thresh** field specifies the user defined intensity threshold (where ">=" indicates RI, and "<=" indicates RW). -Using the **-rirw_track, -rirw_time_adeck, -rirw_time_bdeck, -rirw_exact_adeck, -rirw_exact_bdeck, -rirw_thresh_adeck, -rirw_thresh_bdeck** options within the job command lines may further refine these selections. See README_TC in data/config for how to use these options. +Using the **-rirw_track, -rirw_time_adeck, -rirw_time_bdeck, -rirw_exact_adeck, -rirw_exact_bdeck, -rirw_thresh_adeck, -rirw_thresh_bdeck** options within the job command lines may further refine these selections. See :ref:`README_TC` for how to use these options. _________________________ @@ -342,7 +342,7 @@ _________________________ jobs = []; -The user may specify one or more analysis jobs to be performed on the TCST lines that remain after applying the filtering parameters listed above. Each entry in the joblist contains the task and additional filtering options for a single analysis to be performed. There are three types of jobs available including *filter, summary, and rirw.* Please refer to the README_TC in data/config for details on how to call each job. The format for an analysis job is as follows: +The user may specify one or more analysis jobs to be performed on the TCST lines that remain after applying the filtering parameters listed above. Each entry in the joblist contains the task and additional filtering options for a single analysis to be performed. There are three types of jobs available including *filter, summary, and rirw.* Please refer to the :ref:`README_TC` for details on how to call each job. The format for an analysis job is as follows: _________________________