Merge pull request #2506 from dtcenter/feature_1344_stratosphere_bias

Feature 1344 stratosphere bias

.github/parm/use_case_groups.json

@@ -194,11 +194,6 @@
     "index_list": "5",
     "run": false
   },
-  {
-    "category": "s2s",
-    "index_list": "6",
-    "run": false
-  },
   {
     "category": "s2s_mid_lat",
     "index_list": "0-2",
@@ -224,6 +219,11 @@
     "index_list": "4",
     "run": false
   },
+  {
+    "category": "s2s_stratosphere",
+    "index_list": "0",
+    "run": false
+  },
   {
     "category": "short_range",
     "index_list": "0",

docs/Contributors_Guide/add_use_case.rst

@@ -56,6 +56,7 @@ one of the following:
 * s2s (Subseasonal to Seasonal)
 * s2s_mid_lat (Subseasonal to Seasonal: Mid-Latitude)
 * s2s_mjo (Subseasonal to Seasonal: Madden-Julian Oscillation)
+* s2s_stratosphere (Subseasonal to Seasonal: Stratosphere)
 * short_range (formerly convection_allowing_models)
 * space_weather
 * tc_and_extra_tc (Tropical Cyclone and Extratropical Cyclone)
@@ -150,18 +151,24 @@ Use Case Rules
 - The use case should be run by someone other than the author to ensure that it
   runs smoothly outside of the development environment set up by the author.
 
-.. _memory-intense-use-cases:
+.. _actions-failure-use-cases:
 
-Use Cases That Exceed Github Actions Memory Limit
--------------------------------------------------
+Use Cases That Cannot be Run in GitHub Actions
+----------------------------------------------
 
-Below is a list of use cases in the repository that cannot be run in Github
-Actions  due to their excessive memory usage. They have been tested and
-cleared by reviewers of any other issues and can be used by METplus users in
-the same manner as all other use cases.
+Below is a list of use cases in the repository that cannot be run in GitHub
+Actions  due to either excessive memory or excessive disk space usage. They have 
+been tested and cleared by reviewers of any other issues and can be used by METplus 
+users in the same manner as all other use cases.
 
+Use Cases that Exceed GitHub Actions Memory Limit
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 - *model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsGHRSST_climWOA_sst*
 
+Use Cases that Exceed GitHub Actions Disk Space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- *model_applications/s2s/UserScript_fcstGFS_obsERA_StratospherePolar*
+
 .. _use_case_documentation:
 
 Document New Use Case
@@ -790,9 +797,11 @@ environment, potential reasons include:
 - Referencing variables set in the user's configuration file or local
   environment
 - Memory usage of the use case exceeds the available memory in the
-  Github Actions environment
+  GitHub Actions environment
+- Disk space usage of the use casee exceeds the available space in the
+  GitHub Actions environment
 
-Github Actions has
+GitHub Actions has
 `limited memory <https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources>`_
 available and will cause the use case to fail when exceeded. A failure
 caused by exceeding the memory allocation in a Python Embedding script
@@ -802,9 +811,15 @@ memory profiler to check the
 Python script's memory usage. If the use case exceeds the limit, try to pare 
 down the data held in memory and use less memory intensive Python routines.
 
+Additionally, GitHub Actions has limited disk space available.  The use case will
+fail if the data files exceed the available disk space.  If this is the case, consider
+removing any unneeded variables from the data files, reducing the time steps run, or
+creating a new use case category to keep file sizes down for each group.
+
 If memory mitigation cannot move the use case’s memory usage below the
-Github Actions limit, 
-see :ref:`exceeded-Github-Actions` for next steps.
+GitHub Actions limit or data cannot be reduced further to fit inside
+the available disk space
+see :ref:`exceeded-GitHub-Actions` for next steps.
 
 Verify that the use case ran in a reasonable amount of time
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -859,19 +874,22 @@ processed in the automated tests. In **ci_overrides.conf**, set::
     OBS_VAR1_THRESH = gt0, lt10.0
 
 
-.. _exceeded-Github-Actions:
+.. _exceeded-GitHub-Actions:
 
-Use Cases That Exceed Memory Allocations of Github Actions
-----------------------------------------------------------
+Use Cases That Cannot be Run in GitHub Actions
+----------------------------------------------
 
 If a use case utilizing Python embedding does not run successfully in 
-Github Actions due to exceeding the memory limit and memory mitigation 
-steps were unsuccessful in lowering memory usage, please take the following steps.
+GitHub Actions due to exceeding the memory limit and memory mitigation 
+steps were unsuccessful in lowering memory usage, or if a use case does 
+run successfully in GitHub Actions due to exceeding available disk space 
+and the data cannot be further pared down, please take the following steps.
 
-- Document the Github Actions failure in the Github use case issue. 
+- Document the GitHub Actions failure in the GitHub use case issue. 
   Utilize a Python memory profiler to identify as specifically as possible 
-  where the script exceeds the memory limit.
-- Add the use case to the :ref:`memory-intense-use-cases` list.
+  where the script exceeds the memory limit (if the failure is due to exceeding 
+  the memory limit).
+- Add the use case to the :ref:`actions-failure-use-cases` list.
 - In the *internal/tests/use_cases/all_use_cases.txt* file, ensure that the 
   use case is listed as the lowest-listed use case in its respective category. 
   Change the number in front of the new use case to an 'X', preceded 
@@ -882,13 +900,13 @@ steps were unsuccessful in lowering memory usage, please take the following step
 - In the *.github/parm/use_case_groups.json* file, remove the entry that 
   was added during the :ref:`add_new_category_to_test_runs` 
   for the new use case. This will stop the use case from running on a pull request. 
-- Push these two updated files to the working branch in Github and
+- Push these two updated files to the working branch in GitHub and
   confirm that it now compiles successfully.
 - During the :ref:`create-a-pull-request` creation, inform the reviewer of 
-  the Github Actions failure. The reviewer should confirm the use case is 
+  the GitHub Actions failure. The reviewer should confirm the use case is 
   successful when run manually, that the memory profiler output confirms that 
-  the Python embedding script exceeds the Github Actions limit, and that 
-  there are no other Github Actions compiling errors.
+  the Python embedding script exceeds the GitHub Actions limit, and that 
+  there are no other GitHub Actions compiling errors.
 
 .. _create-a-pull-request:
 

docs/use_cases/model_applications/s2s_stratosphere/README.rst

@@ -0,0 +1,3 @@
+Subseasonal to Seasonal: Stratosphere
+-------------------------------------
+Subseasonal-to-Seasonal model configurations for Stratosphere evaluation

docs/use_cases/model_applications/s2s/UserScript_obsERA_obsOnly_Stratosphere.py → docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py

@@ -1,10 +1,10 @@
 """
-UserScript: Make zonal and meridonial means 
-========================================================================
+Bias Plot on Zonal Mean Wind and Temperature: UserScript, Series-Analysis
+==========================================================================
 
 model_applications/
-s2s/
-UserScript_obsERA_obsOnly_Stratosphere.py
+s2s_stratosphere/
+UserScript_fcstGFS_obsERA_StratosphereBias.py
 
 """
 
@@ -13,21 +13,25 @@
 # --------------------
 #
 # This use case calls functions in METcalcpy to create zonal and meridonial 
-# means 
+# means on U and T.  It then runs Series-Analysis on the output zonal means 
+# and creates a contour plot of bias in latitude and pressure level.
 #
 
 ##############################################################################
 # Datasets
 # --------
 #
-# SSWC_v1.0_varFull_ERAi_d20130106_s20121107_e20130307_c20160701.nc
+# GFS 24 hour forecasts: GFS_2018_02_24h.nc
+# ERA: ERA_2018_02.nc
+#
 
 ##############################################################################
 # METplus Components
 # ------------------
 #
 # This use case runs the UserScript wrapper tool to run a user provided script,
-# in this case, meridonial.py.
+# in this case, zonal_mean_driver.py, runs Series-Analysis to compute the bias,
+# and then runs another UserScript, bias_plot_driver.py, to create the bias plots.
 #
 
 ##############################################################################
@@ -36,9 +40,9 @@
 #
 # This use case does not loop but plots the entire time period of data
 # 
-# UserScript
-# This uses data from 20130106,20121107,20130307,20160701 
-#
+# UserScript: Computes zonal and meridional means
+# Series-Analysis: Computes the bias on zonal mean wind and temperature
+# UserScript: Creates bias plots
 #
 
 ##############################################################################
@@ -47,24 +51,40 @@
 #
 # 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/s2s/UserScript_obsERA_obsOnly_Stratosphere.conf
+# with the -c option, i.e. -c parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf
 #
 # .. highlight:: bash
-# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s/UserScript_obsERA_obsOnly_Stratosphere.conf
+# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf
 #
 
 #############################################################################
 # MET Configuration
 # ---------------------
 #
-# There are no MET tools used in this use case.
+# 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>`
+#
+# **SeriesAnalysisConfig_wrapped**
+#
+# .. note:: See the :ref:`Series-Analysis MET Configuration<series-analysis-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/SeriesAnalysisConfig_wrapped
 #
 
 ##############################################################################
 # Python Embedding
 # ----------------
 #
-# There is no python embedding in this use case
+# This use case uses a Python embedding script to read in the zonal mean data to Series-Analysis
+#
+# .. highlight:: bash
+# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias/read_met_axis_mean.py
 #
 
 ##############################################################################
@@ -73,14 +93,14 @@
 #
 # This use case can be run two ways:
 #
-# 1) Passing in meridonial_means.conf, 
+# 1) Passing in UserScript_fcstGFS_obsERA_StratosphereBias.conf, 
 # then a user-specific system configuration file::
 #
-#        run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s/UserScript_obsERA_obsOnly_Stratosphere.conf -c /path/to/user_system.conf
+#        run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf -c /path/to/user_system.conf
 #
-# 2) Modifying the configurations in parm/metplus_config, then passing in meridonial.conf::
+# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_fcstGFS_obsERA_StratosphereBias.conf:
 #
-#        run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s/UserScript_obsERA_obsOnly_Stratosphere.conf
+#        run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf
 #
 # The former method is recommended. Whether you add them to a user-specific configuration file or modify the metplus_config files, the following variables must be set correctly:
 #
@@ -89,9 +109,7 @@
 # * **MET_INSTALL_DIR** - Path to location where MET is installed locally
 #
 #  and for the [exe] section, you will need to define the location of NON-MET executables.
-#  If the executable is in the user's path, METplus will find it from the name. 
-#  If the executable is not in the path, specify the full path to the executable here (i.e. RM = /bin/rm)  
-#  The following executables are required for performing series analysis use cases:
+#  No executables are required for performing this use case.
 #
 # Example User Configuration File::
 #
@@ -100,13 +118,6 @@
 #   OUTPUT_BASE = /path/to/output/dir
 #   MET_INSTALL_DIR = /path/to/met-X.Y
 #
-#   [exe]
-#   RM = /path/to/rm
-#   CUT = /path/to/cut
-#   TR = /path/to/tr
-#   NCAP2 = /path/to/ncap2
-#   CONVERT = /path/to/convert
-#   NCDUMP = /path/to/ncdump
 #
 
 ##############################################################################
@@ -126,10 +137,13 @@
 #
 #   * UserScriptUseCase
 #   * S2SAppUseCase
+#   * S2SStratosphereAppUseCase
+#   * SeriesAnalysisUseCase
 #   * METcalcpyUseCase
+#   * METplotpyUseCase
 #
 #   Navigate to the :ref:`quick-search` page to discover other similar use cases.
 #
 #
 #
-# sphinx_gallery_thumbnail_path = '_static/s2s-zonal_means.png'
+# sphinx_gallery_thumbnail_path = '_static/s2s_stratosphere-UserScript_fcstGFS_obsERA_StratosphereBias.png'