Feature #1626 TCDiag updates to wrapper and basic use case (#2248)

Co-authored-by: Jonathan Vigh <jvigh@ucar.edu>
dtcenter · Jul 18, 2023 · 050a833 · 050a833
1 parent 618103f
commit 050a833
Show file tree

Hide file tree

Showing 27 changed files with 234 additions and 85 deletions.
diff --git a/.github/parm/use_case_groups.json b/.github/parm/use_case_groups.json
@@ -9,6 +9,11 @@
     "index_list": "30-58",
     "run": false
   },
+  {
+    "category": "met_tool_wrapper",
+    "index_list": "62",
+    "run": false
+  },
   {
     "category": "air_quality_and_comp",
     "index_list": "0",

diff --git a/docs/Contributors_Guide/add_use_case.rst b/docs/Contributors_Guide/add_use_case.rst
@@ -327,6 +327,12 @@ file.grib2, run the following command::
 
     wgrib2 file.grib2 | grep TMP | wgrib2 -i file.grib2 -grib_out subset.grib2
 
+The egrep command can be used for more complex subsetting of grib2 data.
+Example: To create a file called subset.grib2 from file.grib2 that contains
+PRMSL data and TMP data on 1000, 900, 800, 700, 500, and 100 mb levels::
+
+    wgrib2 file.grib2 -s | egrep '(:TMP:1000 mb:|:TMP:900 mb:|:TMP:800 mb:|:TMP:700 mb:|:TMP:500 mb:|:TMP:100 mb:|:PRMSL)' | wgrib2 -i file.grib2 -grib subset.grib2
+
 If the input data is in NetCDF format, the
 `ncks <http://nco.sourceforge.net/nco.html>`_ tool can be used to subset
 the file(s).

diff --git a/docs/Users_Guide/quicksearch.rst b/docs/Users_Guide/quicksearch.rst
@@ -10,6 +10,7 @@ METplus Quick Search for Use Cases
 
 
 Use Cases by MET Tool:
+======================
 
 .. only:: html
 
@@ -163,6 +164,7 @@ Use Cases by METplus Feature:
    | `Runtime Frequency <../search.html?q=RuntimeFreqUseCase&check_keywords=yes&area=default>`_
    | `Series by Initialization <../search.html?q=SeriesByInitUseCase&check_keywords=yes&area=default>`_
    | `Series by Forecast Lead <../search.html?q=SeriesByLeadUseCase&check_keywords=yes&area=default>`_
+   | `Tropical Cyclone <../search.html?q=TropicalCycloneUseCase&check_keywords=yes&area=default>`_
    | `Validation of Models or Analyses <../search.html?q=ValidationUseCase&check_keywords=yes&area=default>`_
    | `User Defined Script <../search.html?q=UserScriptUseCase&check_keywords=yes&area=default>`_
 
@@ -191,6 +193,7 @@ Use Cases by METplus Feature:
    | **Runtime Frequency**: *RuntimeFreqUseCase*
    | **Series by Initialization**: *SeriesByInitUseCase*
    | **Series by Forecast Lead**: *SeriesByLeadUseCase*
+   | **Tropical Cyclone**: *TropicalCycloneUseCase*
    | **Validation of Models or Analyses**: *ValidationUseCase*
    | **User Defined Script**: *UserScriptUseCase*
 

diff --git a/docs/Users_Guide/wrappers.rst b/docs/Users_Guide/wrappers.rst
@@ -7692,7 +7692,7 @@ TCDiag
 Description
 -----------
 
-Used to configure the MET tool TC-Diag.
+The TC-Diag wrapper encapsulates the behavior of the MET `tc_diag <https://met.readthedocs.io/en/develop/Users_Guide/tc-diag.html>`_ tool. It provides the infrastructure to compute diagnostics from model fields and tracks. It can be configured to run over a single intialization time, all of the initialization times for a given storm, or over many storms. Configuration also allows a user to select which domain(s) of the input model data to use in the diagnostics calculations, set which levels and variables will be used as well as details about the azimuth-range grid used for the calculations, and to control which output files are generated. Future functionality of the tc_diag tool, such as vortex removal, will also be configurable from this wrapper.
 
 METplus Configuration
 ---------------------

diff --git a/docs/use_cases/met_tool_wrapper/TCDiag/TCDiag.py b/docs/use_cases/met_tool_wrapper/TCDiag/TCDiag.py
@@ -5,18 +5,48 @@
 met_tool_wrapper/TCDiag/TCDiag.conf
 
 """
+##############################################################################
+# Overview
+# --------------------
+#
+# This use case illustrates the use of tc_diag tool, which is currently
+# considered a beta-level release that lacks full functionality.
+# The use case illustrates running the
+# tc_diag tool for a tropical cyclone forecast case and generating
+# intermediate NetCDF output files of the input model's data transformed
+# onto an azimuth-range grid. When the full functionality of the
+# tc_diag tool is released in MET v12.0.0, this use case will be also
+# output environmental diagnostics computed from callable Python scripts.
+#
+# The diagnostics are computed on a range-azimuth grid that follows the
+# projected storm track. For inputs, it uses 0.25 deg gridded GRIB files from the
+# a retrospective reforecast of the Global Forecast System (GFS). For the track, it uses the
+# GFS's predicted track to ensure that the model's simulated storm doesn't
+# contaminate the diagnostics result as a result of the model's simulated
+# storm being mistaken for environmental factors. (Note:
+# a future version of the tc_diag tool will include removal of the model's vortex,
+# allowing diagnostics to be computed along any arbitrarily defined track.)
+#
+# Novel aspects of this use case:
+#    * This is the first example use case to run the tc_diag tool.
+#    * Example of running for a single tropical cyclone forecast case from
+#      Tropical Storm Bret (2023) using GFS data.
+
 ##############################################################################
 # Scientific Objective
 # --------------------
 #
-# TODO: Add content here
+# Generate intermediate data files, in which the input model's data have been
+# transformed to a range-azimuth grid, in preparation for further diagnostic
+# calculations using Python-based routines.
 
 ##############################################################################
 # Datasets
 # --------
 #
-# **Forecast:** GFS FV3
-# **Track:** A Deck
+# **Forecast:** GFS grib files
+#
+# **Track:** a-deck file (Automated Tropical Cyclone Forecast System format)
 #
 # **Location:** All of the input data required for this use case can be found
 # in the met_test sample data tarball. Click here to the METplus releases page
@@ -26,6 +56,11 @@
 # This tarball should be unpacked into the directory that you will set the
 # value of INPUT_BASE. See `Running METplus`_ section for more information.
 #
+# **Data source:** Users may obtain real-time data from the deterministic GFS runs from
+# NOAA's NOMADS server:
+# https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/gfs.YYYYMMDD/ZZ/atmos/
+# where YYYYMMDD is the date (4-digit year, 2-digit month, 2-digit day),
+# ZZ is the initialization hour of the desired model cycle (00, 06, 12, 18).
 
 ##############################################################################
 # METplus Components
@@ -42,8 +77,8 @@
 # TCDiag is the only tool called in this example. It processes the following
 # run times:
 #
-# **Init:** 2016-09-29- 00Z
-# **Forecast lead:** 141, 143, and 147 hour
+# **Init:** 2023-06-20 0000Z
+# **Forecast lead:** 0, 6, and 12 hours
 #
 
 ##############################################################################
@@ -67,7 +102,7 @@
 # If there is a setting in the MET configuration file that is currently not supported by METplus you'd like to control, please refer to:
 # :ref:`Overriding Unsupported MET config file settings<met-config-overrides>`
 #
-# .. note:: See the :ref:`TCDiag MET Configuration<tc-rmw-met-conf>` section of the User's Guide for more information on the environment variables used in the file below:
+# .. note:: See the :ref:`TCDiag MET Configuration<tc-diag-met-conf>` section of the User's Guide for more information on the environment variables used in the file below:
 #
 # .. highlight:: bash
 # .. literalinclude:: ../../../../parm/met_config/TCDiagConfig_wrapped
@@ -96,7 +131,8 @@
 # Output for this use case will be found in met_tool_wrapper/TCDiag (relative to **OUTPUT_BASE**)
 # and will contain the following files:
 #
-# * tc_diag_aal142016.nc
+# * tc_diag_AL032023_GFSO_2023062012_cyl_grid_nest.nc
+# * tc_diag_AL032023_GFSO_2023062012_cyl_grid_parent.nc
 #
 
 ##############################################################################
@@ -105,8 +141,10 @@
 #
 # .. note::
 #
+#   * DiagnosticsUseCase
 #   * TCDiagToolUseCase
 #   * GRIB2FileUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/met_tool_wrapper/TCGen/TCGen.py b/docs/use_cases/met_tool_wrapper/TCGen/TCGen.py
@@ -124,6 +124,7 @@
 #
 #   * TCGenToolUseCase
 #   * DTCOrgUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/met_tool_wrapper/TCMPRPlotter/TCMPRPlotter.py b/docs/use_cases/met_tool_wrapper/TCMPRPlotter/TCMPRPlotter.py
@@ -110,6 +110,7 @@
 # .. note::
 #
 #   * TCMPRPlotterUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #
diff --git a/docs/use_cases/met_tool_wrapper/TCPairs/TCPairs_extra_tropical.py b/docs/use_cases/met_tool_wrapper/TCPairs/TCPairs_extra_tropical.py
@@ -124,6 +124,7 @@
 #
 #   * TCPairsToolUseCase
 #   * SBUOrgUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/met_tool_wrapper/TCPairs/TCPairs_tropical.py b/docs/use_cases/met_tool_wrapper/TCPairs/TCPairs_tropical.py
@@ -128,6 +128,7 @@
 #
 #   * TCPairsToolUseCase
 #   * DTCOrgUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/met_tool_wrapper/TCRMW/TCRMW.py b/docs/use_cases/met_tool_wrapper/TCRMW/TCRMW.py
@@ -122,6 +122,7 @@
 #
 #   * TCRMWToolUseCase
 #   * GRIB2FileUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/met_tool_wrapper/TCStat/TCStat.py b/docs/use_cases/met_tool_wrapper/TCStat/TCStat.py
@@ -120,6 +120,7 @@
 # .. note::
 #
 #   * TCStatToolUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/...cations/medium_range/TCStat_SeriesAnalysis_fcstGFS_obsGFS_FeatureRelative_SeriesByInit.py b/...cations/medium_range/TCStat_SeriesAnalysis_fcstGFS_obsGFS_FeatureRelative_SeriesByInit.py
@@ -252,6 +252,7 @@
 #   * SBUOrgUseCase
 #   * DiagnosticsUseCase
 #   * RuntimeFreqUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/...cations/medium_range/TCStat_SeriesAnalysis_fcstGFS_obsGFS_FeatureRelative_SeriesByLead.py b/...cations/medium_range/TCStat_SeriesAnalysis_fcstGFS_obsGFS_FeatureRelative_SeriesByLead.py
@@ -244,6 +244,7 @@
 #   * SBUOrgUseCase
 #   * DiagnosticsUseCase
 #   * RuntimeFreqUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/...eriesAnalysis_fcstGFS_obsGFS_FeatureRelative_SeriesByLead_PyEmbed_Multiple_Diagnostics.py b/...eriesAnalysis_fcstGFS_obsGFS_FeatureRelative_SeriesByLead_PyEmbed_Multiple_Diagnostics.py
@@ -334,6 +334,7 @@
 #   * SBUOrgUseCase
 #   * DiagnosticsUseCase
 #   * RuntimeFreqUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/...es/model_applications/tc_and_extra_tc/CyclonePlotter_fcstGFS_obsGFS_UserScript_ExtraTC.py b/...es/model_applications/tc_and_extra_tc/CyclonePlotter_fcstGFS_obsGFS_UserScript_ExtraTC.py
@@ -162,6 +162,7 @@
 #   * TCPairsToolUseCase
 #   * SBUOrgUseCase
 #   * CyclonePlotterUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/model_applications/tc_and_extra_tc/GridStat_fcstHAFS_obsTDR_NetCDF.py b/docs/use_cases/model_applications/tc_and_extra_tc/GridStat_fcstHAFS_obsTDR_NetCDF.py
@@ -152,6 +152,7 @@
 #
 #   * TCandExtraTCAppUseCase
 #   * GridStatToolUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/model_applications/tc_and_extra_tc/Plotter_fcstGFS_obsGFS_ExtraTC.py b/docs/use_cases/model_applications/tc_and_extra_tc/Plotter_fcstGFS_obsGFS_ExtraTC.py
@@ -139,6 +139,7 @@
 #   * NOAAEMCOrgUseCase
 #   * SBUOrgUseCase
 #   * DTCOrgUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/model_applications/tc_and_extra_tc/Plotter_fcstGFS_obsGFS_RPlotting.py b/docs/use_cases/model_applications/tc_and_extra_tc/Plotter_fcstGFS_obsGFS_RPlotting.py
@@ -157,6 +157,7 @@
 #   * MediumRangeAppUseCase
 #   * SBUOrgUseCase
 #   * DTCOrgUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/model_applications/tc_and_extra_tc/TCGen_fcstGFS_obsBDECK_2021season.py b/docs/use_cases/model_applications/tc_and_extra_tc/TCGen_fcstGFS_obsBDECK_2021season.py
@@ -135,6 +135,7 @@
 # .. note::
 #
 #   * TCGenToolUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/...model_applications/tc_and_extra_tc/TCPairs_TCStat_fcstADECK_obsBDECK_ATCF_BasicExample.py b/...model_applications/tc_and_extra_tc/TCPairs_TCStat_fcstADECK_obsBDECK_ATCF_BasicExample.py
@@ -149,6 +149,7 @@
 #
 #   * TCPairsToolUseCase
 #   * TCStatToolUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/docs/use_cases/model_applications/tc_and_extra_tc/TCRMW_fcstGFS_fcstOnly_gonzalo.py b/docs/use_cases/model_applications/tc_and_extra_tc/TCRMW_fcstGFS_fcstOnly_gonzalo.py
@@ -123,6 +123,7 @@
 #
 #   * TCRMWToolUseCase
 #   * GRIB2FileUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/...odel_applications/tc_and_extra_tc/UserScript_ASCII2NC_PointStat_fcstHAFS_obsFRD_NetCDF.py b/...odel_applications/tc_and_extra_tc/UserScript_ASCII2NC_PointStat_fcstHAFS_obsFRD_NetCDF.py
@@ -164,6 +164,7 @@
 #   * UserScriptUseCase
 #   * PointStatToolUseCase
 #   * ASCII2NCToolUseCase
+#   * TropicalCycloneUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #

diff --git a/internal/tests/pytests/wrappers/tc_diag/test_tc_diag_wrapper.py b/internal/tests/pytests/wrappers/tc_diag/test_tc_diag_wrapper.py
@@ -9,7 +9,7 @@
 
 deck_template = 'aal14{date?fmt=%Y}_short.dat'
 input_template = 'gfs.subset.t00z.pgrb2.0p25.f*'
-output_template = 'tc_diag_aal14{date?fmt=%Y}.nc'
+output_template = '{date?fmt=%Y}'
 
 time_fmt = '%Y%m%d%H'
 run_times = ['2016092900']
@@ -24,6 +24,9 @@
     '{ name="TMP"; level="P100"; }];'
 )
 
+input_domain = 'parent'
+input_tech_id_list = 'GFSO'
+
 
 def get_data_dir(config):
     return os.path.join(config.getdir('METPLUS_BASE'),
@@ -46,9 +49,11 @@ def set_minimum_config_settings(config):
     config.set('config', 'TC_DIAG_CONFIG_FILE',
                '{PARM_BASE}/met_config/TCDiagConfig_wrapped')
     config.set('config', 'TC_DIAG_DECK_TEMPLATE', deck_template)
-    config.set('config', 'TC_DIAG_INPUT_TEMPLATE', input_template)
+    config.set('config', 'TC_DIAG_INPUT1_TEMPLATE', input_template)
+    config.set('config', 'TC_DIAG_INPUT1_DOMAIN', input_domain)
+    config.set('config', 'TC_DIAG_INPUT1_TECH_ID_LIST', input_tech_id_list)
     config.set('config', 'TC_DIAG_OUTPUT_DIR',
-               '{OUTPUT_BASE}/TCDiag/output')
+               '{OUTPUT_BASE}/tc_diag')
     config.set('config', 'TC_DIAG_OUTPUT_TEMPLATE', output_template)
 
     config.set('config', 'BOTH_VAR1_NAME', 'PRMSL')
@@ -231,13 +236,11 @@ def test_tc_diag_run(metplus_config, config_overrides,
     config_file = wrapper.c_dict.get('CONFIG_FILE')
     out_dir = wrapper.c_dict.get('OUTPUT_DIR')
 
-    expected_cmds = [(f"{app_path} "
-                      f"-deck {deck_dir}/aal142016_short.dat "
-                      f"-data {file_list_file} "
-                      f"-config {config_file} "
-                      f"-out {out_dir}/tc_diag_aal142016.nc "
-                      f"{verbosity}"),
-                     ]
+    expected_cmds = [
+        (f"{app_path} -deck {deck_dir}/aal142016_short.dat "
+         f"-data {input_domain} {input_tech_id_list} {file_list_file} "
+         f"-config {config_file} -outdir {out_dir}/2016/ {verbosity}"),
+    ]
 
     all_cmds = wrapper.run_all_times()
     print(f"ALL COMMANDS: {all_cmds}")

diff --git a/internal/tests/use_cases/all_use_cases.txt b/internal/tests/use_cases/all_use_cases.txt
@@ -61,7 +61,7 @@ Category: met_tool_wrapper
 59::IODA2NC::met_tool_wrapper/IODA2NC/IODA2NC.conf
 60::PointStat_python_embedding_obs:: met_tool_wrapper/PointStat/PointStat_python_embedding_obs.conf
 61::PlotPointObs:: met_tool_wrapper/PlotPointObs/PlotPointObs.conf
-#62::TCDiag:: met_tool_wrapper/TCDiag/TCDiag.conf
+62::TCDiag:: met_tool_wrapper/TCDiag/TCDiag.conf
 
 Category: air_quality_and_comp
 0::EnsembleStat_fcstICAP_obsMODIS_aod::model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.conf