diff --git a/data/config/TCDiagConfig_default b/data/config/TCDiagConfig_default index 2f4adaa86d..1660d8a09c 100644 --- a/data/config/TCDiagConfig_default +++ b/data/config/TCDiagConfig_default @@ -79,7 +79,7 @@ domain_info = [ // // Data censoring and conversion -// May be set separately in each diag_data "field" entry +// May be set separately in each data "field" array entry // // censor_thresh = []; // censor_val = []; diff --git a/docs/Flowchart/MET_flowchart.pptx b/docs/Flowchart/MET_flowchart.pptx index cc386d57d2..cc62a9a960 100644 Binary files a/docs/Flowchart/MET_flowchart.pptx and b/docs/Flowchart/MET_flowchart.pptx differ diff --git a/docs/Flowchart/MET_flowchart_v11.1.0.png b/docs/Flowchart/MET_flowchart_v11.1.0.png new file mode 100644 index 0000000000..b7b11f32c2 Binary files /dev/null and b/docs/Flowchart/MET_flowchart_v11.1.0.png differ diff --git a/docs/Users_Guide/data_io.rst b/docs/Users_Guide/data_io.rst index 395b66a96d..7003a123a0 100644 --- a/docs/Users_Guide/data_io.rst +++ b/docs/Users_Guide/data_io.rst @@ -307,7 +307,7 @@ The following is a summary of the input and output formats for each of the tools * **Output**: One ASCII file containing 2D object attributes, four ASCII files containing 3D object attributes, and one NetCDF file containing object indices for the gridded simple and cluster object fields. -#. **TC-Dland Tool** +#. **TC-DLand Tool** * **Input**: One or more files containing the longitude (Degrees East) and latitude (Degrees North) of all the coastlines and islands considered to be a significant landmass. diff --git a/docs/Users_Guide/figure/overview-figure.png b/docs/Users_Guide/figure/overview-figure.png index 201e9b7a53..b7b11f32c2 100644 Binary files a/docs/Users_Guide/figure/overview-figure.png and b/docs/Users_Guide/figure/overview-figure.png differ diff --git a/docs/Users_Guide/met-tc_overview.rst b/docs/Users_Guide/met-tc_overview.rst index 41ad7e5fc0..d7930b6a75 100644 --- a/docs/Users_Guide/met-tc_overview.rst +++ b/docs/Users_Guide/met-tc_overview.rst @@ -9,14 +9,14 @@ Introduction The purpose of this User's Guide is to provide basic information to the users of the Model Evaluation Tools - Tropical Cyclone (MET-TC) to enable users to apply MET-TC to their tropical cyclone datasets and evaluation studies. MET-TC is intended for use with model forecasts run through a vortex tracking software or with operational model forecasts in Automated Tropical Cyclone Forecast (ATCF) file format. -The following sections provide an overview of MET-TC and its components, as well as basic information on the software build. The required input, including file format and the MET-TC are discussed followed by a description of the TC-Dland tool, TC-Pairs, and TC-Stat tools. Each section covers the input, output and practical usage including a description of the configuration files. This is followed by a short overview of graphical utilities available within the MET-TC release. +The following sections provide an overview of MET-TC and its components, as well as basic information on the software build. The required input, including file format and the MET-TC are discussed followed by a description of the TC-DLand, TC-Diag, TC-Pairs, TC-Stat, TC-RMW, and RMW-Analysis tools. Each section covers the input, output and practical usage including a description of the configuration files. This is followed by a short overview of graphical utilities available within the MET-TC release. MET-TC components ================= The MET tools used in the verification of Tropical Cyclones are referred to as MET-TC. These tools are shown across the bottom of the flowchart in :numref:`overview-figure`. The MET-TC tools are described in more detail in later sections. -The TC-Dland tool is used to generate a gridded file that determines the location of coastlines and islands, and is used as input to the TC-Pairs tool to determine the distance from land of a particular track point. The TC-Pairs tool matches pairs of input model data and BEST track (or any reference forecast) and calculates position errors. The TC-Stat tool uses the TC-Pairs output to perform filter and summary jobs over the matched pair dataset. The TC-Gen tool performs a categorical analysis for tropical cyclone genesis forecasts. The TC-RMW tool performs a coordinate transformation of gridded model data, centered on the storm's location. The RMW-Analysis tool aggregates TC-RMW output across multiple cases. +Tropical cyclone forecasts and observations are quite different than numerical model forecasts, and thus they have their own set of tools. These consist of TC-DLand, TC-Diag, TC-Pairs, TC-Stat, TC-Gen, TC-RMW, and RMW-Analysis. The TC-DLand module calculates the distance to land from all locations on a specified grid. This information can be used in later modules to eliminate tropical cyclones that are over land from being included in the statistics. TC-Diag converts gridded model output into cylindrical coordinates for each storm location, calls Python scripts to compute storm-relative diagnostics, and writes ASCII output to be read by TC-Pairs. TC-Pairs matches up tropical cyclone forecasts and observations and writes all output to a file. In TC-Stat, these forecast / observation pairs are analyzed according to user preference to produce statistics. TC-Gen evaluates the performance of Tropical Cyclone genesis forecast using contingency table counts and statistics. TC-RMW performs a coordinate transformation for gridded model or analysis fields centered on the current storm location. RMW-Analysis filters and aggregates the output of TC-RMW across multiple cases. Input data format ================= @@ -112,4 +112,4 @@ If a user has gridded model output, the model data must be run through a vortex Output data format ================== -The MET package produces output in four basic file formats: STAT files, ASCII files, NetCDF files, and Postscript plots. The MET-TC tool produces output in TCSTAT, which stands for Tropical Cyclone - STAT. This output format consists of tabular ASCII data that can be easily read by many analysis tools and software packages, making the output from MET-TC very versatile. Like STAT, TCSTAT is a specialized ASCII format containing one record on each line. Currently, the only line type available in MET-TC is TCMPR (Tropical Cyclone Matched Pairs). As more line types are included in future releases, all line types will be included in a single TCSTAT file. MET-TC also outputs a NetCDF format file in the TC-Dland tool, as input to the TC-Pairs tool. +The MET package produces output in four basic file formats: STAT files, ASCII files, NetCDF files, and PostScript plots. The MET-TC tool produces output in TCSTAT, which stands for Tropical Cyclone - STAT. This output format consists of tabular ASCII data that can be easily read by many analysis tools and software packages, making the output from MET-TC very versatile. Like STAT, TCSTAT is a specialized ASCII format containing one record on each line. Currently, the only line type available in MET-TC is TCMPR (Tropical Cyclone Matched Pairs). As more line types are included in future releases, all line types will be included in a single TCSTAT file. The TC-DLand, TC-Diag, TC-RMW, and RMW-Analysis tools also write NetCDF files containing a variety of output data types. diff --git a/docs/Users_Guide/overview.rst b/docs/Users_Guide/overview.rst index 9e7d26d882..dff4c81fc1 100644 --- a/docs/Users_Guide/overview.rst +++ b/docs/Users_Guide/overview.rst @@ -9,7 +9,7 @@ Purpose and organization of the User's Guide The goal of this User's Guide is to provide basic information for users of the Model Evaluation Tools (MET) to enable them to apply MET to their datasets and evaluation studies. MET was originally designed for application to the post-processed output of the `Weather Research and Forecasting (WRF) `_ model. However, MET may also be used for the evaluation of forecasts from other models or applications, including the `Unified Forecast System (UFS) `_, and the `System for Integrated Modeling of the Atmosphere (SIMA) `_ if certain file format definitions (described in this document) are followed. -The MET User's Guide is organized as follows. :numref:`overview` provides an overview of MET and its components. :numref:`installation` contains basic information about how to get started with MET - including system requirements, required software (and how to obtain it), how to download MET, and information about compilers, libraries, and how to build the code. :numref:`data_io` - :numref:`masking` focuses on the data needed to run MET, including formats for forecasts, observations, and output. These sections also document the reformatting and masking tools available in MET. :numref:`point-stat` - :numref:`gsi_tools` focuses on the main statistics modules contained in MET, including the Point-Stat, Grid-Stat, Ensemble-Stat, Wavelet-Stat and GSI Diagnostic Tools. These sections include an introduction to the statistical verification methodologies utilized by the tools, followed by a section containing practical information, such as how to set up configuration files and the format of the output. :numref:`stat-analysis` and :numref:`series-analysis` focus on the analysis modules, Stat-Analysis and Series-Analysis, which aggregate the output statistics from the other tools across multiple cases. :numref:`mode` - :numref:`mode-td` describes a suite of object-based tools, including MODE, MODE-Analysis, and MODE-TD. :numref:`met-tc_overview` - :numref:`rmw-analysis` describes tools focused on tropical cyclones, including MET-TC Overview, TC-Dland, TC-Pairs, TC-Stat, TC-Gen, TC-RMW and RMW-Analysis. Finally, :numref:`plotting` includes plotting tools included in the MET release for checking and visualizing data, as well as some additional tools and information for plotting MET results. The appendices provide further useful information, including answers to some typical questions (:numref:`Appendix A, Section %s `) and links and information about map projections, grids, and polylines (:numref:`Appendix B, Section %s `). :numref:`Appendix C, Section %s ` and :numref:`Appendix D, Section %s ` provide more information about the verification measures and confidence intervals that are provided by MET. Sample code that can be used to perform analyses on the output of MET and create particular types of plots of verification results is posted on the `MET website `_). Note that the MET development group also accepts contributed analysis and plotting scripts which may be posted on the MET website for use by the community. It should be noted there are References (:numref:`refs`) in this User's Guide as well. +The MET User's Guide is organized as follows. :numref:`overview` provides an overview of MET and its components. :numref:`installation` contains basic information about how to get started with MET - including system requirements, required software (and how to obtain it), how to download MET, and information about compilers, libraries, and how to build the code. :numref:`data_io` - :numref:`masking` focuses on the data needed to run MET, including formats for forecasts, observations, and output. These sections also document the reformatting and masking tools available in MET. :numref:`point-stat` - :numref:`gsi_tools` focuses on the main statistics modules contained in MET, including the Point-Stat, Grid-Stat, Ensemble-Stat, Wavelet-Stat and GSI Diagnostic Tools. These sections include an introduction to the statistical verification methodologies utilized by the tools, followed by a section containing practical information, such as how to set up configuration files and the format of the output. :numref:`stat-analysis` and :numref:`series-analysis` focus on the analysis modules, Stat-Analysis and Series-Analysis, which aggregate the output statistics from the other tools across multiple cases. :numref:`mode` - :numref:`mode-td` describes a suite of object-based tools, including MODE, MODE-Analysis, and MODE-TD. :numref:`met-tc_overview` - :numref:`rmw-analysis` describes tools focused on tropical cyclones, including MET-TC Overview, TC-DLand, TC-Diag, TC-Pairs, TC-Stat, TC-Gen, TC-RMW and RMW-Analysis. Finally, :numref:`plotting` includes plotting tools included in the MET release for checking and visualizing data, as well as some additional tools and information for plotting MET results. The appendices provide further useful information, including answers to some typical questions (:numref:`Appendix A, Section %s `) and links and information about map projections, grids, and polylines (:numref:`Appendix B, Section %s `). :numref:`Appendix C, Section %s ` and :numref:`Appendix D, Section %s ` provide more information about the verification measures and confidence intervals that are provided by MET. Sample code that can be used to perform analyses on the output of MET and create particular types of plots of verification results is posted on the `MET website `_). Note that the MET development group also accepts contributed analysis and plotting scripts which may be posted on the MET website for use by the community. It should be noted there are References (:numref:`refs`) in this User's Guide as well. The remainder of this section includes information about the context for MET development, as well as information on the design principles used in developing MET. In addition, this section includes an overview of the MET package and its specific modules. @@ -66,7 +66,7 @@ Results from the statistical analysis stage are output in ASCII, NetCDF and Post The Stat-Analysis and MODE-Analysis tools aggregate the output statistics from the previous steps across multiple cases. The Stat-Analysis tool reads the STAT output of Point-Stat, Grid-Stat, Ensemble-Stat, and Wavelet-Stat and can be used to filter the STAT data and produce aggregated continuous and categorical statistics. Stat-Analysis also reads matched pair data (i.e. MPR line type) via python embedding. The MODE-Analysis tool reads the ASCII output of the MODE tool and can be used to produce summary information about object location, size, and intensity (as well as other object characteristics) across one or more cases. -Tropical cyclone forecasts and observations are quite different than numerical model forecasts, and thus they have their own set of tools. These consist of TC-Dland, TC-Pairs, TC-Stat, TC-Gen, TC-RMW, and RMW-Analysis. The TC-Dland module calculates the distance to land from all locations on a specified grid. This information can be used in later modules to eliminate tropical cyclones that are over land from being included in the statistics. TC-Pairs matches up tropical cyclone forecasts and observations and writes all output to a file. In TC-Stat, these forecast / observation pairs are analyzed according to user preference to produce statistics. TC-Gen evaluates the performance of Tropical Cyclone genesis forecast using contingency table counts and statistics. TC-RMW performs a coordinate transformation for gridded model or analysis fields centered on the current storm location. RMW-Analysis filters and aggregates the output of TC-RMW across multiple cases. +Tropical cyclone forecasts and observations are quite different than numerical model forecasts, and thus they have their own set of tools. These consist of TC-DLand, TC-Diag, TC-Pairs, TC-Stat, TC-Gen, TC-RMW, and RMW-Analysis. The TC-DLand module calculates the distance to land from all locations on a specified grid. This information can be used in later modules to eliminate tropical cyclones that are over land from being included in the statistics. TC-Diag converts gridded model output into cylindrical coordinates for each storm location, calls Python scripts to compute storm-relative diagnostics, and writes ASCII output to be read by TC-Pairs. TC-Pairs matches up tropical cyclone forecasts and observations and writes all output to a file. In TC-Stat, these forecast / observation pairs are analyzed according to user preference to produce statistics. TC-Gen evaluates the performance of Tropical Cyclone genesis forecast using contingency table counts and statistics. TC-RMW performs a coordinate transformation for gridded model or analysis fields centered on the current storm location. RMW-Analysis filters and aggregates the output of TC-RMW across multiple cases. The following sections of this MET User's Guide contain usage statements for each tool, which may be viewed if you type the name of the tool. Alternatively, the user can also type the name of the tool followed by **-help** to obtain the usage statement. Each tool also has a **-version** command line option associated with it so that the user can determine what version of the tool they are using. diff --git a/docs/Users_Guide/tc-diag.rst b/docs/Users_Guide/tc-diag.rst index f9cef3d479..6061fdcf1c 100644 --- a/docs/Users_Guide/tc-diag.rst +++ b/docs/Users_Guide/tc-diag.rst @@ -1,13 +1,40 @@ .. _tc-diag: ************ -TC-DIAG Tool +TC-Diag Tool ************ Introduction ============ -The TC-Diag tool compute Tropical Cyclone diagnostics. More details to be added. +.. note:: As of MET version 11.1.0, the TC-Diag tool is still in development. Each time it is run, the warning message listed below is printed. + +.. code-block:: none + + WARNING: + WARNING: The TC-Diag tool is provided in BETA status for MET V11.1.0. + WARNING: Please see the release notes of future MET versions for updates. + WARNING: + +A diagnosis of the large-scale environment of tropical cyclones (TCs) is foundational for many prediction techniques, including statistical-dynamical forecast aids and techniques based on artificial intelligence. Such diagnostics can also be used by forecasters seeking to understand how a given model's forecast will pan out. Finally, TC diagnostics can be useful in verification to stratify the performance of models in different environmental regimes over a longer period of time, thereby providing useful insights on model biases or deficiencies for model developers and forecasters. + +Originally developed for the Statistical Hurricane Intensity Prediction Scheme (SHIPS), and later as a stand-alone package called 'Model Diagnostics', by the Cooperative Institute for Research in the Atmosphere (CIRA), MET now integrates these capabilities into the an extensible framework called the TC-Diag tool. This tool allows users compute diagnostics for the large-scale environment of TCs using ATCF track and gridded model data inputs. Importantly, the tool computes diagnostics along one or more user-specified tracks. The current version of the TC-Diag tool requires that the tracks and fields be self-consistent [i.e., the track should be the model's (or ensemble's) own predicted track(s)]. The reason is that the diagnostics are computed in a coordinate system centered on the model's moving model storm and the current version of the tool does not yet include vortex removal. If the track is not consistent with the underlying fields, the diagnostics output are unlikely to be useful because the model's simulated storm would contaminate the diagnostics calculations. + +.. note:: A future version of the tool will include the capability to remove the model's own vortex, which will allow the user to specify any arbitrary track (such as the operational center's official forecast). Until then, users are advised that the track selected must be consistent with the model's predicted track. + +TC-Diag is run once for each initialization time. The user provides track data (such as one or more ATCF a-deck track files), along with track filtering criteria as needed, to select one or more tracks to be processed. The user also provides gridded model data from which diagnostics should be computed. Gridded data can be provided for multiple concurrent storms, multiple models, and/or multiple domains (i.e. parent and nest) in a single run. + +TC-Diag first determines the list of valid times that appear in any one of the tracks. For each valid time, it processes all track points for that time. For each track point, it reads the gridded model fields requested in the configuration file and transforms the gridded data to a range-azimuth cyclindrical coordinates grid. For each domain, it writes the range-azimuth data to a temporary NetCDF file. + +.. note:: The current version of the tool does not yet include the capabilities described in the next three paragraphs. These additional capabilities are planned to be added in the MET v12.0.0 release later in 2023. + +Once the input data have been processed into the temporary NetCDF files, TC-Diag then calls one or more Python diagnostics scripts, as specified in the configuration file, to compute tropical cyclone diagnostic values. The computed diagnostics values are retrieved from the Python script and stored in memory. + +After processing all valid times and all corresponding track points, the computed diagnostics are written to ASCII and/or NetCDF output files. If requested in the configuration file, the temporary range-azimuth cylindrical coordinates files are combined into a single NetCDF file and written to the output for each combination of model track and domain. + +The default Python diagnostics scripts included with the MET release provide the standard set of CIRA diagnostics. However, users can copy/modify the logic in those scripts as they see fit to refine and/or add to the diagnostics computed. + +.. _tc-diag_practical_info: Practical information ===================== @@ -20,10 +47,10 @@ The following sections describe the usage statement, required arguments, and opt .. code-block:: none Usage: tc_diag - -data file_1 ... file_n | data_file_list + -data domain tech_id_list [ file_1 ... file_n | data_file_list ] -deck file -config file - -out file + [-outdir path] [-log file] [-v level] @@ -32,17 +59,17 @@ tc_diag has required arguments and can accept several optional arguments. Required arguments for tc_diag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. The **-data file_1 ... file_n | data_file_list** options specify the gridded data files or an ASCII file containing a list of files to be used. - -2. The **-deck source** argument is the ATCF format data source. +1. The **-data domain tech_id_list [ file_1 ... file_n | data_file_list ]** option specifies a domain name, a comma-separated list of ATCF tech ID's, and a list of gridded data files or an ASCII file containing a list of files to be used. Specify **-data** one for each gridded data source. -3. The **-config file** argument is the configuration file to be used. The contents of the configuration file are discussed below. +2. The **-deck source** option is the ATCF format track data source. -4. The **-out** argument is the NetCDF output file to be written. +3. The **-config file** option is the TCDiagConfig file to be used. The contents of the configuration file are discussed below. Optional arguments for tc_diag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +4. The **-outdir path** option overrides the default output directory (current working directory) with the output directory path provided. + 5. The **-log file** option directs output and errors to the specified log file. All messages will be written to that file as well as standard out and error. Thus, users can save the messages without having to redirect the output on the command line. The default behavior is no logfile. 6. The **-v level** option indicates the desired level of verbosity. The contents of "level" will override the default setting of 2. Setting the verbosity to 0 will make the tool run with no log messages, while increasing the verbosity above 1 will increase the amount of logging. @@ -50,11 +77,10 @@ Optional arguments for tc_diag tc_diag configuration file -------------------------- -The default configuration file for the TC-Diag tool named **TCDiagConfig_default** can be found in the installed *share/met/config/* directory. It is encouraged for users to copy these default files before modifying their contents. The contents of the configuration file are described in the subsections below. - -The TC-Diag tool should be configured to filter the input track data (**-deck**) down to the subset of tracks that correspond to the gridded data files provided (**-data**). The filtered tracks should contain data for only one initialization time but may contain tracks for multiple models. +The default configuration file for the TC-Diag tool named **TCDiagConfig_default** can be found in the installed *share/met/config/* directory. Users are encouraged to copy these default files before modifying their contents. The contents of the configuration file are described in the subsections below. -_______________________ +Configuring input tracks and time +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -70,123 +96,262 @@ _______________________ valid_hour = []; lead = []; - censor_thresh = []; - censor_val = []; - convert(x) = x; +The TC-Diag tool should be configured to filter the input track data (**-deck**) down to the subset of tracks that correspond to the gridded data files provided (**-data**). The filtered tracks should contain data for only *one initialization time* but may contain tracks for multiple models. - data = { - field = [ - { - name = "PRMSL"; - level = ["L0"]; - }, - { - name = "TMP"; - level = ["P1000", "P500"]; - }, - { - name = "UGRD"; - level = ["P1000", "P500"]; - }, - { - name = "VGRD"; - level = ["P1000", "P500"]; - } - ]; - } - regrid = { ... } +The configuration options listed above are used to filter the input track data down to those that should be processed in the current run. These options are common to multiple MET tools and are described in :numref:`config_options_tc`. -The configuration options listed above are common to many MET tools and are described in :numref:`config_options`. The name and level entries in the data dictionary define the data to be processed. The regrid dictionary defines if and how regridding will be performed. - -_______________________ +Configuring domain information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none - n_range = 100; - -The **n_range** parameter is the number of equally spaced range intervals in the range-azimuth grid. + diag_script = [ "MET_BASE/python/tc_diag/compute_tc_diagnostics.py" ]; -_______________________ + domain_info = [ + { + domain = "parent"; + n_range = 150; + n_azimuth = 8; + delta_range_km = 10.0; + }, + { + domain = "nest"; + n_range = 150; + n_azimuth = 8; + delta_range_km = 2.0; + } + ]; -.. code-block:: none - - n_azimuth = 180; +The **domain_info** entry is an array of dictionaries. Each dictionary consists of five entries. The **domain** entry is a user-specified string that provides a name for the domain. Each **domain** name must also appear in a **-deck** command line option, and the reverse is also true. -The **n_azimuth** parameter is the number of equally spaced azimuth intervals in the range-azimuth grid. The azimuthal grid spacing is 360 / **n_azimuth** degrees. +The **n_range** entry is an integer specifying the number of equally spaced range intervals in the range-azimuth grid to be used for this data source. -_______________________ +The **n_azimuth** entry is an integer specifying the number of equally spaced azimuth intervals in the range-azimuth grid to be used for this data source. The azimuthal grid spacing is 360 / **n_azimuth** degrees. -.. code-block:: none +The **delta_range_km** entry is a floating point value specifying the spacing of the range rings in kilometers. - max_range_km = 100.0; +The **diag_script** entry is an array of strings. Each string specifies the path to a Python script to be executed to compute diagnostics from the transformed cyclindrical coordinates data for this domain. While the **diag_script** entry can be specified separately for each **domain_info** array entry, specifying it once at a higher level of context, as seen above, allows the same setting to be applied to all array entries. When multiple Python diagnostics scripts are run, the union of the diagnostics computed are written to the output. -The **max_range_km** parameter specifies the maximum range of the range-azimuth grid, in kilometers. If this parameter is specified and not **rmw_scale**, the radial grid spacing will be **max_range_km / n_range**. +.. note:: As of MET version 11.1.0, no tropical cyclone diagnostics are actually computed or written to the output. -_______________________ +Configuring data censoring and conversion options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none - delta_range_km = 10.0; + censor_thresh = []; + censor_val = []; + convert(x) = x; -The **delta_range_km** parameter specifies the spacing of the range rings, in kilometers. +These data censoring and conversion options are common to multiple MET tools and are described in :numref:`config_options`. They can be specified separately in each **data.field** array entry, described below. If provided, those operations are performed after reading the gridded data but prior to conveting to the cylindrical coordinate range-azimuth grid. -_______________________ +Configuring fields, levels, and domains +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none - rmw_scale = 0.2; + data = { -The **rmw_scale** parameter overrides the **max_range_km** parameter. When this is set the radial grid spacing will be **rmw_scale** in units of the RMW, which varies along the storm track. + // If empty, the field is processed for all domains + domain = []; -_______________________ - -.. code-block:: none + // Pressure levels to be used, unless overridden below + level = [ "P1000", "P925", "P850", "P700", "P500", + "P400", "P300", "P250", "P200", "P150", + "P100" ]; - compute_tangential_and_radial_winds = TRUE; + field = [ + { name = "TMP"; }, + { name = "UGRD"; }, + { name = "VGRD"; }, + { name = "RH"; }, + { name = "HGT"; }, + { name = "PRMSL"; level = "Z0"; }, + { name = "PWAT"; level = "L0"; }, + { name = "TMP"; level = "Z0"; }, + { name = "TMP"; level = "Z2"; }, + { name = "RH"; level = "Z2"; }, + { name = "UGRD"; level = "Z10"; }, + { name = "VGRD"; level = "Z10"; } + ]; + } -The **compute_tangential_and_radial_winds** parameter is a flag controlling whether a conversion from U/V to Tangential/Radial winds is done or not. If set to TRUE, additional parameters are used, otherwise they are not. +The **data** entry is a dictionary that contains the **field** entry to define what gridded data should be processed. The **field** entry is an array of dictionaries. Each **field** dictionary consists of at least three entries. -_______________________ +The **name** and **level** entries are common to multiple MET tools and are described in :numref:`config_options`. -.. code-block:: none +The **domain** entry is an array of strings. Each string specifies a domain name. If the **domain_info** domain name appears in this **domain** list, then this field will be read from that **domain_info** data source. If **domain** is set to an empty list, then this field will be read from all domain data sources. - u_wind_field_name = "UGRD"; - v_wind_field_name = "VGRD"; - -The **u_wind_field_name** and **v_wind_field_name** parameters identify which input data to use in converting to tangential/radial winds. The parameters are used only if **compute_tangential_and_radial_winds** is set to TRUE. - -_______________________ +Configuring regridding options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none - tangential_velocity_field_name = "VT"; - tangential_velocity_long_field_name = "Tangential Velocity"; + regrid = { ... } + +These **regrid** dictionary is common to multiple MET tools and is described in :numref:`config_options`. These regridding options control the transformation to cylindrical coordinates. - -The **tangential_velocity_field_name** and **tangential_velocity_long_field_name** parameters define the field names to give the output tangential velocity grid in the netCDF output file. The parameters are used only if **compute_tangential_and_radial_winds** is set to TRUE. +.. note:: As of MET version 11.1.0, the nearest neighbor regridding method is used rather than this configuration file option. -_______________________ +Configuring vortex removal option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none - radial_velocity_field_name = "VT"; - radial_velocity_long_field_name = "Radial Velocity"; + vortex_removel = FALSE; - -The **radial_velocity_field_name** and **radial_velocity_long_field_name** parameters define the field names to give the output radial velocity grid in the netCDF output file. The parameters are used only if **compute_radial_and_radial_winds** is set to TRUE. +These **vortex_removal** flag entry is a boolean specifying whether or not vortex removal logic should be applied. +.. note:: As of MET version 11.1.0, vortex removal logic is not yet supported. -tc_diag output file -------------------- +Configuring data output options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The NetCDF output file contains the following dimensions: +.. code-block:: none -1. *range* - the radial dimension of the range-azimuth grid + nc_rng_azi_flag = TRUE; + nc_diag_flag = FALSE; + cira_diag_flag = FALSE; -2. *azimuth* - the azimuthal dimension of the range-azimuth grid +These three flag entries are booleans specifying what output data types should be written. The **nc_rng_azi_flag** entry controls the writing of a NetCDF file containing the cylindrical coordinate range-azimuth data used to compute the diagnostics. The **nc_diag_file** entry controls the writing of the computed diagnostics to a NetCDF file. The **cira_diag_flage** entry controls the writing of the computed diagnostics to a formatted ASCII output file. At least one of these flags must be set to true. -3. *pressure* - if any pressure levels are specified in the data variable list, they will be sorted and combined into a 3D NetCDF variable, which pressure as the vertical dimension and range and azimuth as the horizontal dimensions +.. note:: As of MET version 11.1.0, **nc_rng_azi_flag** is the only supported output type. These configuration options will automatically be reset at runtime to the settings listed above. -4. *track_point* - the track points corresponding to the model output valid times +Configuring MET version, output prefix, and temp directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none -For each data variable specified in the data variable list, a corresponding NetCDF variable will be created with the same name and units. + tmp_dir = "/tmp"; + output_prefix = ""; + version = "V11.1.0"; + +These options are common to multiple MET tools and are described in :numref:`config_options`. + +tc_diag output +-------------- + +The TC-Diag tool writes up to three output data types, as specified by flags in the configuration file. Each time TC-Diag is run it processes track data for a single initialization time. The actual number of output files varies depending on the number of model tracks provided. + +.. note:: As of MET version 11.1.0, **nc_rng_azi_flag** is the only supported output type. + +**CIRA Diagnostics Output** + +When the **cira_diag_flag** configuration entry is set to true, an ASCII CIRA diagnostics output file is written for each model track provided. + +Details will be provided when support for this output type is added. + +**NetCDF Diagnostics Output** + +When the **nc_diag_flag** configuration entry is set to true, a NetCDF output file containing the computed diagnostics is written for each model track provided. + +Details will be provided when support for this output type is added. + +**NetCDF Range-Azimuth Output** + +When the **nc_rng_azi_flag** configuration entry is set to true, a NetCDF output file containing the cylindrical coordinate range-azimuth data is written for each combination of model track provided and domain specified. For example, if three model tracks are provided and data for both *parent* and *nest* domains are provided, six of these NetCDF output files will be written. + +The NetCDF range-azimuth output is named using the following naming convention: + +**tc_diag_STORMID_TECH_YYYYMMDDHH_cyl_grid_DOMAIN.nc** where STORMID is the 2-letter basin name, 2-digit storm number, and 4-digit year, TECH is the acronym for the objective technique, YYYYMMDDHH is the track initialization time, and DOMAIN is the domain name. + +The NetCDF range-azimuth file contains the dimensions and variables shown in :numref:`table_TC-Diag_Dimensions_NetCDF_range_azimuth` and :numref:`table_TC-Diag_Variables_NetCDF_range_azimuth`. + +.. _table_TC-Diag_Dimensions_NetCDF_range_azimuth: + +.. list-table:: Dimensions defined in NetCDF Range-Azimuth output + :widths: auto + :header-rows: 2 + + * - tc_diag NETCDF DIMENSIONS + - + * - NetCDF Dimension + - Description + * - track_line + - Dimension for the raw ATCF track lines written to the **TrackLines** variable + * - time + - Time dimension for the number of track point valid times + * - range + - Dimension for the number of range rings in the range-azimuth grid + * - azimuth + - Dimension for the number of azimuths in the range-azimuth grid + * - pressure + - Vertical dimension for the number of pressure levels + +.. role:: raw-html(raw) + :format: html + +.. _table_TC-Diag_Variables_NetCDF_range_azimuth: + +.. list-table:: Variables defined in NetCDF Range-Azimuth output + :widths: auto + :header-rows: 2 + + * - tc_diag NETCDF VARIABLES + - + - + * - NetCDF Variable + - Dimension + - Description + * - storm_id + - NA + - Tropical Cyclone Storm ID (BBNNYYYY) consisting of 2-letter basin name, 2-digit storm number, and 4-digit year + * - model + - NA + - Track ATCF ID model name + * - TrackLines + - track_lines + - Raw input ATCF track lines + * - TrackLat + - time + - Track point location latitude + * - TrackLon + - time + - Track point location longitude + * - TrackMSLP + - time + - Track point minimum sea level pressure + * - TrackVMax + - time + - Track point maximum wind speed + * - init_time + - NA + - Track initialization time string in YYYYMMDD_HHMMSS format + * - init_time_ut + - NA + - Track initialization time string in unixtime (seconds since January 1, 1970) format + * - valid_time + - time + - Track point valid time string in YYYYMMDD_HHMMSS format + * - valid_time_ut + - time + - Track point valid time string in unixtime (seconds since January 1, 1970) format + * - lead_time + - time + - Track point forecast lead time string in HHMMSS format + * - lead_time_sec + - time + - Track point forecast lead time integer number of seconds + * - range + - range + - Range ring coordinate variable in kilometers + * - azimuth + - azimuth + - Azimuth coordinate variable in degrees clockwise from north + * - pressure + - pressure + - Vertical level pressure coordinate variable in millibars + * - lat + - time, range, azimuth + - Latitude in degrees north for each range-azimuth grid point + * - lon + - time, range, azimuth + - Longitude in degrees east for each range-azimuth grid point + * - single level data + (e.g. TMP_Z2, PRMSL_L0) + - time, range, azimuth + - Gridded range-azimuth data on a single level + * - pressure level data + (e.g. TMP, HGT) + - time, pressure, range, azimuth + - Gridded range-azimuth data on pressure levels diff --git a/docs/Users_Guide/tc-dland.rst b/docs/Users_Guide/tc-dland.rst index 078d4d3a9e..c88ea33e0b 100644 --- a/docs/Users_Guide/tc-dland.rst +++ b/docs/Users_Guide/tc-dland.rst @@ -1,7 +1,7 @@ .. _tc-dland: ************* -TC-Dland Tool +TC-DLand Tool ************* Introduction diff --git a/internal/test_unit/config/TCDiagConfig_ian b/internal/test_unit/config/TCDiagConfig_ian index 8c9d199f62..b74fa5f238 100644 --- a/internal/test_unit/config/TCDiagConfig_ian +++ b/internal/test_unit/config/TCDiagConfig_ian @@ -73,7 +73,7 @@ domain_info = [ // // Data censoring and conversion -// May be set separately in each "data.field" entry +// May be set separately in each data "field" array entry // // censor_thresh = []; // censor_val = [];