Feature 2198 use case amdar pbl (#2206)

Co-authored-by: Daniel Adriaansen <dadriaan@ucar.edu>
Co-authored-by: George McCabe <23407799+georgemccabe@users.noreply.github.com>

.github/parm/use_case_groups.json

@@ -119,6 +119,11 @@
     "index_list": "9",
     "run": false
   },
+  {
+    "category": "pbl",
+    "index_list": "0",
+    "run": false
+  },
   {
     "category": "precipitation",
     "index_list": "0",

docs/Users_Guide/quicksearch.rst

@@ -81,6 +81,7 @@ Use Cases by Application:
    | `Land Surface <../search.html?q=LandSurfaceAppUseCase&check_keywords=yes&area=default>`_
    | `Marine and Cryosphere <../search.html?q=MarineAndCryosphereAppUseCase&check_keywords=yes&area=default>`_
    | `Medium Range <../search.html?q=MediumRangeAppUseCase&check_keywords=yes&area=default>`_
+   | `PBL <../search.html?q=PBLAppUseCase&check_keywords=yes&area=default>`_
    | `Precipitation <../search.html?q=PrecipitationAppUseCase&check_keywords=yes&area=default>`_
    | `Space Weather <../search.html?q=SpaceWeatherAppUseCase&check_keywords=yes&area=default>`_
    | `Subseasonal to Seasonal <../search.html?q=S2SAppUseCase&check_keywords=yes&area=default>`_
@@ -99,6 +100,7 @@ Use Cases by Application:
    | **LandSurface**: *LandSurfaceAppUseCase*
    | **Marine and Cryosphere**: *MarineAndCryosphereAppUseCase*
    | **Medium Range**: *MediumRangeAppUseCase*
+   | **PBL**: *PBLAppUseCase*
    | **Precipitation**: *PrecipitationAppUseCase*
    | **Space Weather**: *SpaceWeatherAppUseCase*
    | **Subseasonal to Seasonal**: *S2SAppUseCase*

docs/use_cases/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.py

@@ -0,0 +1,150 @@
+"""
+GenVxMask and Point-Stat: Computing PBLH from AMDAR data using "Theta-increase" method
+======================================================================================
+
+model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.conf
+
+"""
+##############################################################################
+# Scientific Objective
+# --------------------
+#
+# The Planetary Boundary Layer Height (PBLH) arises from a complex interaction of 
+# lower atmosphere and surface processes, and is therefore a useful metric to
+# evaluate models. This PointStat use case computes PBLH from AMDAR aircraft data
+# using the "Theta-increase" method (Nielsen-Gammon et al., 2008, J. App. Met. Clim.),
+# which computes PBLH by finding the lowest altitude in an aircraft profile that 
+# exceeds a specified increase in potential temperature from a base value.
+# Generally this theta-increase (pt_delta) ranges from 1.0-2.5 K. The pt_delta,
+# list of airports to process, and sounding are specified in the configuration
+# script.
+# 
+
+##############################################################################
+# Datasets
+# --------------------
+#
+# Forecast: HRRR, RRFS (reads the "HPBL" grib2 field)
+# Observation: AMDAR hourly 1-d netcdf files
+#
+
+##############################################################################
+# METplus Components
+# --------------------
+# 
+# This use case utilizes GenVxMask and the METplus PointStat tool to compare PBLH 
+# from AMDAR data to model output. The python embedding script "calc_amdar_pblh.py" 
+# computes PBLH and sends data MET via python embedding. The configuration file also filters 
+# output through static geographic masks generated by GenVxMask.
+#
+
+##############################################################################
+# METplus Workflow
+# --------------------
+# GenVxMask and PointStat are called in this example. The following run times are processed:
+#
+# | **Valid:** 2022-07-01_20Z
+# | **Forecast lead:** 12 hour
+#
+# GenVxMask input file is a two-row text file (met_mask_AIRPORT.txt): row 1: AIRPORT row 2: lat lon
+# GenVxMask output file is a netcdf file w/ geographic radius part of the file name (met_mask_AIRPORT_100km.nc)
+# Input file provided in this example: (met_mask_DENVER.txt): row 1: DENVER  row2: 39.856 -104.6764
+
+# PointStat is run with Python embedding (calc_amdar_pblh.py).
+
+##############################################################################
+# METplus Configuration
+# ---------------------
+#
+# METplus first loads all of the configuration files found in parm/metplus_config,
+# then it loads any configuration files passed to METplus via the command line
+# with the -c option, i.e. -c parm/use_cases/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.conf
+#
+# .. highlight:: bash
+# .. literalinclude:: ../../../../parm/use_cases/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.conf
+
+##############################################################################
+# MET Configuration
+# -----------------
+#
+# METplus sets environment variables based on user settings in the METplus configuration file. 
+# See :ref:`How METplus controls MET config file settings<metplus-control-met>` for more details. 
+#
+# **YOU SHOULD NOT SET ANY OF THESE ENVIRONMENT VARIABLES YOURSELF! THEY WILL BE OVERWRITTEN BY METPLUS WHEN IT CALLS THE MET TOOLS!**
+#
+# If there is a setting in the MET configuration file that is currently not supported by METplus you'd like to control, please refer to:
+# :ref:`Overriding Unsupported MET config file settings<met-config-overrides>`
+#
+# .. note:: See the :ref:`PointStat MET Configuration<point-stat-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/PointStatConfig_wrapped
+#
+
+##############################################################################
+# Python Embedding
+# -----------------
+#
+# This use case uses a Python embedding script to read input data
+#
+# parm/use_cases/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed/calc_amdar_pblh.py
+#
+# .. highlight:: python
+# .. literalinclude:: ../../../../parm/use_cases/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed/calc_amdar_pblh.py
+#
+
+##############################################################################
+# Running METplus
+# ---------------
+#
+# It is recommended to run this use case by:
+#
+# Passing in PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.conf then a user-specific system configuration file::
+#
+#   run_metplus.py -c /path/to/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.conf -c /path/to/user_system.conf
+#
+# The following METplus configuration variables must be set correctly to run this example.:
+#
+# * **INPUT_BASE** - Path to directory where sample data tarballs are unpacked (See Datasets section to obtain tarballs).
+# * **OUTPUT_BASE** - Path where METplus output will be written. This must be in a location where you have write permissions
+# * **MET_INSTALL_DIR** - Path to location where MET is installed locally
+#
+# Example User Configuration File::
+#
+#   [dir]
+#   INPUT_BASE = /path/to/sample/input/data
+#   OUTPUT_BASE = /path/to/output/dir
+#   MET_INSTALL_DIR = /path/to/met-X.Y 
+#
+# **NOTE:** All of these items must be found under the [dir] section.
+#
+
+##############################################################################
+# Expected Output
+# ---------------
+#
+# A successful run will output the following both to the screen and to the logfile::
+#
+#   INFO: METplus has successfully finished running.
+#
+# Refer to the value set for **OUTPUT_BASE** to find where the output data was generated.
+# Output for this use case will be found in point_stat_pblh  (relative to **OUTPUT_BASE**)
+# with subdirectories for valid time (YYYYMMDD) and will contain .stat files with the following naming convention:
+#
+# convention: point_stat_{AIRPORT}_{SOUNDING_FLAG}_{PT_DELTA}_{LEADTIME}L_{VALIDTIME}.stat
+#    example: point_stat_DENVER_ALL_1.25_120000L_20220701_200000V.stat
+
+##############################################################################
+# Keywords
+# --------
+#
+# .. note::
+#
+#   * GenVxMaskToolUseCase 
+#   * PointStatToolUseCase 
+#   * PythonEmbeddingFileUseCase 
+#   * PBLAppUseCase
+#
+#   Navigate to the :ref:`quick-search` page to discover other similar use cases.
+#
+# sphinx_gallery_thumbnail_path = '_static/pbl-PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.png'

docs/use_cases/model_applications/pbl/README.rst

@@ -0,0 +1,3 @@
+Planetary Boundary Layer
+------------------------
+Planetary Boundary Layer (PBL) applications

internal/tests/use_cases/all_use_cases.txt

@@ -115,6 +115,9 @@ Category: medium_range
 9::GridStat_fcstGEFS_obsCADB_BinaryObsPOE:: model_applications/medium_range/GridStat_fcstGEFS_obsCADB_BinaryObsPOE.conf:: netcdf4_env
 
 
+Category: pbl
+0::PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed:: model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.conf
+
 Category: precipitation
 0::GenEnsProd_fcstHRRRE_FcstOnly_NetCDF:: model_applications/precipitation/GenEnsProd_fcstHRRRE_FcstOnly_NetCDF.conf
 1::GridStat_fcstHREFmean_obsStgIV_Gempak:: model_applications/precipitation/GridStat_fcstHREFmean_obsStgIV_Gempak.conf:: gempak_env

parm/use_cases/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.conf

@@ -0,0 +1,143 @@
+[config]
+
+# Documentation for this use case can be found at
+# https://metplus.readthedocs.io/en/latest/generated/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed.html
+
+# For additional information, please see the METplus Users Guide.
+# https://metplus.readthedocs.io/en/latest/Users_Guide
+
+###
+# Processes to run
+# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#process-list
+###
+
+PROCESS_LIST = GenVxMask, PointStat
+
+###
+# Time Info
+# LOOP_BY options are INIT, VALID, RETRO, and REALTIME
+# If set to INIT or RETRO:
+#   INIT_TIME_FMT, INIT_BEG, INIT_END, and INIT_INCREMENT must also be set
+# If set to VALID or REALTIME:
+#   VALID_TIME_FMT, VALID_BEG, VALID_END, and VALID_INCREMENT must also be set
+# LEAD_SEQ is the list of forecast leads to process
+# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#timing-control
+###
+
+LOOP_BY = INIT
+INIT_TIME_FMT = %Y%m%d%H
+INIT_BEG = 2022070108
+INIT_END = 2022070108
+INIT_INCREMENT = 1H
+
+LEAD_SEQ = 12
+
+# USER SETTINGS HERE
+# CUSTOM_LOOP_LIST = DENVER, DALLAS, BOSTON, MINNEAPOLIS   [list of airports sepearated by commas; each needs a mask file]
+# PY_SOUNDING_FLAG = ALL, ASC, DESC  [only one value here]
+# PY_PT_DELTA =  Potential Temperature delta setting (K) [usually 1.0-2.5]
+# Valid_Time(YYYYMMDD_HHMMSS)
+GEN_VX_MASK_AIRPORT_RADIUS_KM = 100
+CUSTOM_LOOP_LIST = DENVER
+PY_SOUNDING_FLAG = ALL  
+PY_PT_DELTA = 1.25
+PY_VAL_TIME = {valid?fmt=%Y%m%d_%H0000}
+
+###
+# File I/O
+# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#directory-and-filename-template-info
+###
+
+GEN_VX_MASK_INPUT_DIR = {INPUT_BASE}/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed
+GEN_VX_MASK_INPUT_TEMPLATE = {init?fmt=%Y%m%d%H}/pblh_22{init?fmt=%j}{init?fmt=%H}0000{lead?fmt=%HH}
+GEN_VX_MASK_INPUT_MASK_DIR = {INPUT_BASE}/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed
+GEN_VX_MASK_INPUT_MASK_TEMPLATE = met_mask_{custom?fmt=%s}.txt
+
+GEN_VX_MASK_OUTPUT_DIR = {INPUT_BASE}/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed
+GEN_VX_MASK_OUTPUT_TEMPLATE = {OUTPUT_BASE}/gen_vx_mask_pblh/met_mask_{custom?fmt=%s}_{GEN_VX_MASK_AIRPORT_RADIUS_KM}km.nc
+
+FCST_POINT_STAT_INPUT_DIR = {INPUT_BASE}/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed
+FCST_POINT_STAT_INPUT_TEMPLATE = {init?fmt=%Y%m%d%H}/pblh_22{init?fmt=%j}{init?fmt=%H}0000{lead?fmt=%HH}
+
+OBS_POINT_STAT_INPUT_DIR =
+OBS_POINT_STAT_INPUT_TEMPLATE = PYTHON_NUMPY= {PARM_BASE}/use_cases/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed/calc_amdar_pblh.py {INPUT_BASE}/model_applications/pbl/PointStat_fcstHRRR_obsAMDAR_PBLH_PyEmbed/22{valid?fmt=%j}{valid?fmt=%H}00q.cdf
+
+POINT_STAT_OUTPUT_DIR = {OUTPUT_BASE}/point_stat_pblh
+POINT_STAT_OUTPUT_TEMPLATE = {valid?fmt=%Y%m%d}
+
+POINT_STAT_CLIMO_MEAN_INPUT_DIR =
+POINT_STAT_CLIMO_MEAN_INPUT_TEMPLATE =
+
+POINT_STAT_CLIMO_STDEV_INPUT_DIR =
+POINT_STAT_CLIMO_STDEV_INPUT_TEMPLATE =
+
+
+###
+# Field Info
+# https://metplus.readthedocs.io/en/latest/Users_Guide/systemconfiguration.html#field-info
+###
+
+POINT_STAT_ONCE_PER_FIELD = False
+
+FCST_VAR1_NAME = HPBL
+FCST_VAR1_LEVELS = L0
+FCST_VAR1_THRESH = <=0, >10000
+OBS_VAR1_NAME = HPBL
+OBS_VAR1_LEVELS = L0
+OBS_VAR1_THRESH = <=0, >10000
+OBS_VAR1_OPTIONS = set_attr_units = "m"
+
+
+###
+# GenVxMask Settings
+# https://metplus.readthedocs.io/en/latest/Users_Guide/wrappers.html#genvxmask
+###
+
+GEN_VX_MASK_SKIP_IF_OUTPUT_EXISTS = True
+GEN_VX_MASK_OPTIONS = -type "circle" -thresh le{GEN_VX_MASK_AIRPORT_RADIUS_KM}
+
+# PointStat Settings
+# https://metplus.readthedocs.io/en/latest/Users_Guide/wrappers.html#pointstat
+###
+
+LOG_POINT_STAT_VERBOSITY = 4
+
+POINT_STAT_CONFIG_FILE ={PARM_BASE}/met_config/PointStatConfig_wrapped
+
+POINT_STAT_CLIMO_MEAN_TIME_INTERP_METHOD = NEAREST
+POINT_STAT_INTERP_TYPE_METHOD = BILIN
+POINT_STAT_INTERP_TYPE_WIDTH = 2
+
+POINT_STAT_OUTPUT_FLAG_SL1L2 = STAT
+POINT_STAT_OUTPUT_FLAG_VL1L2 = STAT
+POINT_STAT_OUTPUT_FLAG_MPR = STAT
+
+OBS_POINT_STAT_WINDOW_BEGIN = -3600
+OBS_POINT_STAT_WINDOW_END = 3600
+
+POINT_STAT_OFFSETS = 0
+
+MODEL = HRRR
+
+POINT_STAT_DESC = {PY_SOUNDING_FLAG}_{PY_PT_DELTA}
+OBTYPE =
+
+POINT_STAT_REGRID_TO_GRID = NONE
+POINT_STAT_REGRID_METHOD = BILIN
+POINT_STAT_REGRID_WIDTH = 2
+
+POINT_STAT_OUTPUT_PREFIX = {custom?fmt=%s}_{PY_SOUNDING_FLAG}_{PY_PT_DELTA}
+
+POINT_STAT_MASK_GRID =  
+POINT_STAT_MASK_POLY = {OUTPUT_BASE}/gen_vx_mask_pblh/met_mask_{custom?fmt=%s}_{GEN_VX_MASK_AIRPORT_RADIUS_KM}km.nc
+POINT_STAT_MASK_SID =
+
+POINT_STAT_MESSAGE_TYPE = ADPSFC
+
+# INFO TO PASS TO PYTHON SCRIPT
+[user_env_vars]
+
+AIRPORT = {custom?fmt=%s}    
+SOUNDING_FLAG = {PY_SOUNDING_FLAG}  
+PT_DELTA = {PY_PT_DELTA}
+VAL_TIME = {PY_VAL_TIME}