Update develop-ref after #2094 (#2108)

Co-authored-by: Julie Prestopnik <[email protected]>
Co-authored-by: johnhg <[email protected]>
Co-authored-by: cristianastan2 <[email protected]>
Co-authored-by: John Halley Gotway <[email protected]>
Co-authored-by: bikegeek <[email protected]>
Co-authored-by: Lisa Goodrich <[email protected]>
Co-authored-by: Julie Prestopnik <[email protected]>
Co-authored-by: George McCabe <[email protected]>
Co-authored-by: Hank Fisher <[email protected]>
Co-authored-by: Dan Adriaansen <[email protected]>
Co-authored-by: jprestop <[email protected]>
Co-authored-by: Tracy Hertneky <[email protected]>
Co-authored-by: j-opatz <[email protected]>
Co-authored-by: lisagoodrich <[email protected]>
Co-authored-by: bikegeek <[email protected]>
Co-authored-by: j-opatz <[email protected]>
Co-authored-by: Will Mayfield <[email protected]>
Co-authored-by: metplus-bot <[email protected]>
Co-authored-by: Tracy Hertneky <[email protected]>
fixing some spacing #770
Fixing formatting, typos etc.  #770
Fixing formatting  #770
fixing typos, spacing, etc. #770
fixing typos, grammar and punctuation. #770
Fixing TOC and coding block #770
fixing note #770
fix.  Updating bolding and italics for file names and directories #770
fixing space #770
fixing conflict #2 #770
fixing typos #770
fixing typos #2 #770
fixing formatting #770
fixing errors #650
fixing errors take 2 #650
fixing errors take 3 #650
fixing errors take 4 #650
fixing errors take 5 #650
fixing question order #650
fix #1706 fix PhaseDiagram use case to avoid writing into INPUT_BASE (#1708)
fix #1713 develop METPLOTPY_BASE (#1715)
fix #1691 remove whitespace from output file paths (#1721)
fix Contributor's Guide GitHub Workflow page (#1774)
fix release (#1790)
fix GitHub Actions warnings (#1864)
fix #1884 develop PCPCombine {custom} in subtract method (#1887)
fix #1939 develop - failure reading obs when zipped file also exists (#1941)
Closes #1986
fix develop Fix broken documentation links (#2004)
fix #2026 develop StatAnalysis looping (#2028)
fix priority of obs_window config variables so that wrapper-specific version is preferred over generic OBS_WINDOW_BEGIN/END (#2062)
fix #2070 var list numeric order (#2072)
fix #2087 develop docs_pdf (#2091)
fix #2096/#2098 develop - fix skip if output exists and do not error if no commands were run (#2099)

.github/parm/use_case_groups.json

@@ -54,6 +54,11 @@
     "index_list": "10-12",
     "run": false
   },
+  {
+    "category": "short_range",
+    "index_list": "13",
+    "run": false
+  },
   {
     "category": "data_assimilation",
     "index_list": "0-1",

.github/workflows/documentation.yml

@@ -24,6 +24,7 @@ jobs:
         run: |
           python -m pip install --upgrade sphinx sphinx-gallery sphinx_rtd_theme
           python -m pip install python-dateutil requests Pillow
+          python -m pip install -r docs/requirements.txt
       - name: Build Documentation
         run: ./.github/jobs/build_documentation.sh
       - uses: actions/upload-artifact@v3

docs/Users_Guide/statistics_list.rst

@@ -2295,7 +2295,7 @@ ____________________
       Use Case
     - n/a
   * - Spatial distance between :raw-html:`<br />`
-      (𝑥,𝑦)(x,y) coordinates of :raw-html:`<br />`
+      :math:`(x,y)` coordinates of :raw-html:`<br />`
       object spacetime centroid
     - SPACE :raw-html:`<br />`
       _CENTROID :raw-html:`<br />`

docs/conf.py

@@ -113,6 +113,7 @@
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.intersphinx',
               'sphinx_gallery.gen_gallery',
+              'sphinx_design', 
              ]
 
 # settings for ReadTheDocs PDF creation

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx-gallery==0.11.1
-sphinx==6.0.0
-sphinx-rtd-theme==1.2.0rc2
+sphinx==5.3.0
+sphinx-rtd-theme==1.2.0
+sphinx-design==0.3.0

docs/use_cases/model_applications/short_range/GenEnsProd_fcstHRRR_fcstOnly_SurrogateSevere.py

@@ -13,12 +13,14 @@
 # --------------------
 #
 # Run PCPCombine, GenEnsProd, and RegridDataPlane tools to create surrogate severe probability
-# forecasts (SSPFs) for a given date. SSPFs are a severe weather forecasting tool and is a techniqu
-# used by the Storm Prediction Center (SPC) as well as others. SSPFs are based on updraft helicity 
-# (UH; UH = ∫z0 to zt (ω * ζ) dz) since certain thresholds of UH have been shown as good proxies for# severe weather. SSPFs can be thought of as the perfect model forecast. They are derived as follows:
+# forecasts (SSPFs) for a given date. SSPFs are a severe weather forecasting tool and is a technique
+# used by the Storm Prediction Center (SPC) as well as others. SSPFs are based on updraft helicity
+# (UH; :math:`\text{UH} = \int_{z_0}^{z_t} ( \omega * \zeta ) dz`) since certain thresholds of UH
+# have been shown as good proxies for severe weather. SSPFs can be thought of as the perfect model
+# forecast. They are derived as follows:
 #
 #    1. Regrid the maximum UH value over the 2-5km layer at each grid point to the NCEP 211 grid (dx = ~80km).
-#    2. Create a binary mask of points that meet a given threshold of UH)
+#    2. Create a binary mask of points that meet a given threshold of UH.
 #    3. Convert the binary mask into a probability field by applying a Gaussian filter.
 # 
 # For more information, please reference Sobash et al. 2011 (https://journals.ametsoc.org/doi/full/10.1175/WAF-D-10-05046.1).

docs/use_cases/model_applications/short_range/MODEMultivar_fcstHRRR_obsMRMS_HRRRanl.py

@@ -0,0 +1,196 @@
+"""
+MODE: Multivariate  
+=========================================================================
+
+model_applications/
+short_range/
+MODEMultivar_fcstHRRR_obsMRMS_HRRRanl.conf
+
+"""
+##############################################################################
+# Scientific Objective
+# --------------------
+#
+# This use case demonstrates how to run Multivariate MODE to identify complex
+# objects from two or more fields, defined by a logical expression. This use
+# case identifies blizzard-like objects defined by: 1) the presence of snow
+# precipitation type, 2) 10-m winds > 20 mph, and  3) visibility < 1/2 mile.
+# The use of multivariate MODE is well-suited to assess the structure and
+# placement of complex high-impact events such as blizzard conditions and heavy
+# snow bands. Output from this use-case consists of the MODE forecast and observation
+# super objects and the MODE ASCII, NetCDF, and PostScript files.
+#
+
+##############################################################################
+# Datasets
+# --------
+#
+# **Forecast dataset:** 1-hour HRRR in grib2
+#
+# **Observation dataset:** MRMS and HRRR analysis in grib2
+# 
+# The forecast and observation fields are only a subset of the full domain in
+# order for a faster run-time of Multivariate MODE. An example command using
+# wgrib2 to create the HRRR subdomain is::
+#
+#   wgrib2 infile.grib2 -new_grid_winds earth -new_grid lambert:262.5:38.5:38.5:38.5 -83.0:400:3000 37.0:400:3000 outfile.grib2 
+#
+# **Location:** All of the input data required for this use case can be found
+# in the *short_range* sample data tarball.
+# Navigate to `METplus Releases <https://github.com/dtcenter/METplus/releases>`_
+# and download sample data for the appropriate release.
+#
+# This tarball should be unpacked into the directory that you will set the
+# value of INPUT_BASE. See :ref:`running-metplus` for more information.
+
+
+##############################################################################
+# METplus Components
+# ------------------
+#
+# This use case runs MODE using multiple variables to output the super objects
+# based on a user-defined logical expression. Currently, the initial multivariate
+# MODE run only outputs the super objects and additional steps are required to
+# produce the statistical output. GenVxMask is run on a field(s) of interest
+# using the super objects to mask the field(s). Finally, MODE is run a second
+# time on the super-object-masked field(s) to output attribute statistics for
+# the field(s).
+#
+# **Note:** The second MODE run can also be run directly on the super objects if
+# field-specific statistics, such as intensity, is not desired.
+# 
+
+##############################################################################
+# METplus Workflow
+# ----------------
+#
+# The following tools are used for each run time:
+#
+# MODE(mv), GenVxMask(fcst_super), GenVxMask(obs_super), MODE(super)
+# 
+# Where the first instance of MODE runs over multiple variables to identify
+# super objects for the forecast and observation, GenVxMask masks the raw input
+# field(s) using the super objects, and the second instance of MODE is run
+# traditionally to compare the masked forecast and observed super objects and
+# and provide statistics.
+#
+# This example runs a single forecast hour.
+#
+# | **Initialization:** 2021020100
+# | **Forecast lead:** 21
+#
+
+##############################################################################
+# 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:
+# parm/use_cases/model_applications/short_range/MODEMultivar_fcstHRRR_obsMRMS_HRRRanl.conf
+#
+# .. highlight:: bash
+# .. literalinclude:: ../../../../parm/use_cases/model_applications/short_range/MODEMultivar_fcstHRRR_obsMRMS_HRRRanl.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:`MODE MET Configuration<mode-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/MODEConfig_wrapped
+
+##############################################################################
+# Running METplus
+# ---------------
+#
+# Pass the use case configuration file to the run_metplus.py script
+# along with any user-specific system configuration files if desired::
+#
+#    run_metplus.py /path/to/METplus/parm/use_cases/model_applications/short_range/MODEMultivar_fcstHRRR_obsMRMS_HRRRanl.conf /path/to/user_system.conf
+#
+# See :ref:`running-metplus` for more information.
+
+##############################################################################
+# 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 OUTPUT_BASE for the various MET tools
+# and will contain the following files:
+#
+# **mode/2021020100/f21**
+#
+# Multivariate output - first instance
+#
+# Precipitation type = snow
+#
+# * 00/mode_210000L_20210201_210000V_000000A_cts.txt
+# * 00/mode_210000L_20210201_210000V_000000A_obj.nc
+# * 00/mode_210000L_20210201_210000V_000000A_obj.txt
+# * 00/mode_210000L_20210201_210000V_000000A.ps
+#
+# Visibility
+#
+# * 01/mode_210000L_20210201_210000V_000000A_cts.txt
+# * 01/mode_210000L_20210201_210000V_000000A_obj.nc
+# * 01/mode_210000L_20210201_210000V_000000A_obj.txt
+# * 01/mode_210000L_20210201_210000V_000000A.ps
+#
+# 10-m Winds
+#
+# * 02/mode_210000L_20210201_210000V_000000A_cts.txt
+# * 02/mode_210000L_20210201_210000V_000000A_obj.nc
+# * 02/mode_210000L_20210201_210000V_000000A_obj.txt
+# * 02/mode_210000L_20210201_210000V_000000A.ps
+#
+# Super Objects
+#
+# * f_super.nc
+# * o_super.nc
+#
+# MODE 10-m wind super object output - second instance
+#
+# * mode_HRRR_vs_ANALYSIS_WIND_super_Z10_210000L_20210201_210000V_000000A_cts.txt
+# * mode_HRRR_vs_ANALYSIS_WIND_super_Z10_210000L_20210201_210000V_000000A_obj.nc
+# * mode_HRRR_vs_ANALYSIS_WIND_super_Z10_210000L_20210201_210000V_000000A_obj.txt
+# * mode_HRRR_vs_ANALYSIS_WIND_super_Z10_210000L_20210201_210000V_000000A.ps
+#
+# **gen_vx_mask/2021020100**
+#
+# * fcst_wind_super_2021020100_f21.nc
+# * obs_wind_super_2021020121.nc
+
+##############################################################################
+# Keywords
+# --------
+#
+# .. note::
+#
+#   * MODEToolUseCase 
+#   * GenVxMaskToolUseCase 
+#   * ShortRangeAppUseCase
+#   * GRIB2FileUseCase 
+#   * RegriddingInToolUseCase 
+#   * NOAAWPCOrgUseCase
+#   * NCAROrgUseCase 
+#   * DiagnosticsUseCase
+#
+#
+#   Navigate to the :ref:`quick-search` page to discover other similar use cases.
+#
+#
+# sphinx_gallery_thumbnail_path = '_static/short_range-MODEMultivar_fcstHRRR_obsMRMS_HRRRanl.png'
+#