Feature #1330 MJO ENSO use case (#1794)

Co-authored-by: cristianastan2 <cstan@gmu.edu>

.github/parm/use_case_groups.json

@@ -179,6 +179,11 @@
     "index_list": "3",
     "run": false
   },
+  {
+    "category": "s2s_mjo",
+    "index_list": "4",
+    "run": false
+  },
   {
     "category": "space_weather",
     "index_list": "0-1",

docs/use_cases/model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO.py

@@ -0,0 +1,145 @@
+"""
+UserScript: Make MaKE-MaKI plot from calculated MaKE and MaKI indices
+=====================================================================
+
+model_applications/
+s2s_mjo/
+UserScript_obsCFSR_obsOnly_MJO_ENSO.py
+
+"""
+
+##############################################################################
+# Scientific Objective
+# --------------------
+#
+# To compute the MJO-Kelvin wave-ENSO (MaKE) and MJO-Kelvin wave-Influence (MaKI) indices* using the zonal and meridional components of winds tress (TAUX,TAUY), zonal and meridional components of surface ocean currents (UCUR,VCUR), and sea surface temperature (SST). Specifically, MaKE and MaKI indices are computed using TAUX, TAUY, UCUR, VCUR and SST data between 30S and 30N and 125E and 80W. Daily anomalies of wind stress components are filtered for 30-90 days using a Convolutional Neural Network (CNN)-based filter. The weights of the filter are computed offline. The bandpass filtered wind stress components are projected onto 4 Empirical Orthogonal Functions (EOFs) data. The obtained timeseries (PCs) are standardized and combined with the EOFs to obtain the MJO component of the surface wind stress (TAUX_MJO,TAUY_MJO). UCUR and VCUR daily anomalies are multiplied by the meridional structure of Kelvin wave (UCUR_K,VCUR_K). Windpower due to the MJO component of the wind stress and oceanic Kelvin waves (W_MJO,K) is then computed as TAUX_MJO*UCUR_K+TAUY_MJO*VCUR_K. The standardized windpower and SST are projected onto the first two multivariate EOFs of W_MJO,K and SST. The resulting daily time series (PCs) are normalized and used to compute monthly values of MaKE and MaKI. Monthly values of MaKE and MaKI are saved into a text (.csv) file and plotted as time series.     
+# 
+# * Lybarger, N.D., C.-S. Shin, and C. Stan, 2020: MJO Wind energy and prediction of El Nino, Journal of Geophysical Research - Oceans, 125, e2020JC016732. doi:10.1029/2020JC016732
+
+##############################################################################
+# Datasets
+# --------
+#
+#  * Forecast dataset:  None
+#  * Observation dataset: CFSR Reanalysis 
+
+##############################################################################
+# External Dependencies
+# ---------------------
+#
+# You will need to use a version of Python 3.6+ that has the following packages installed::
+#
+# * numpy
+# * netCDF4
+# * datetime
+# * xarray
+# * matplotlib
+# * pandas 
+#
+# If the version of Python used to compile MET did not have these libraries at the time of compilation, you will need to add these packages or create a new Python environment with these packages.
+#
+# If this is the case, you will need to set the MET_PYTHON_EXE environment variable to the path of the version of Python you want to use. If you want this version of Python to only apply to this use case, set it in the [user_env_vars] section of a METplus configuration file.:
+#
+#    [user_env_vars]
+#    MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python
+#
+
+##############################################################################
+# METplus Components
+# ------------------
+#
+# This use case runs the MJO-ENSO driver, which first computes the MJO components of taux and tauy, then the MJO wind power, the MJO-ENSO indices, their plot. Inputs to the MJO-ENSO driver include netCDF files that are in MET's netCDF version.  In addition, a text file containing the listing of these input netCDF files for taux, tauy, u, v, and SST is required.  Some optional pre-processing steps include RegridDataPlane for regridding  the data. 
+#
+
+##############################################################################
+# METplus Workflow
+# ----------------
+# The MJO-ENSO driver script python code is run for each lead time on the forecast and observations data. This example loops by valid time for the model pre-processing, and valid time for the other steps.  This version is set to only process the regridding, and MaKE and MaKI calculation, omitting the caluclation of the mean daily annucal cycle and daily anomalies pre-processing steps.  However, the configurations for pre-processing are available for user reference.
+#
+
+##############################################################################
+# 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
+# i.e. parm/use_cases/model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO.conf.
+# The file UserScript_obsCFSR_obsOnly_MJO_ENSO/mjo_enso_driver.py runs the python program and  
+# UserScript_obsCFSR_obsOnly_MJO_ENSO.conf sets the variables for all steps of the MJO-ENSO use case.
+#
+# .. highlight:: bash
+# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO.conf
+
+##############################################################################
+# MET Configuration
+# ---------------------
+#
+# METplus sets environment variables based on the values in the METplus configuration file.
+# These variables are referenced in the MET configuration file. **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 not controlled by an environment variable, you can add additional environment variables to be set only within the METplus environment using the [user_env_vars] section of the METplus configuration files. See the 'User Defined Config' section on the 'System Configuration' page of the METplus User's Guide for more information.
+#
+#
+
+##############################################################################
+# Python Scripts
+# ----------------
+#
+# The MJO-ENSO driver script orchestrates the calculation of the MaKE and MaKI indices and 
+# the generation of a text file and a plot for the indices:
+# parm/use_cases/model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO/mjo_enso_driver.py:
+#
+# .. highlight:: python
+# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO/mjo_enso_driver.py
+#
+
+##############################################################################
+# Running METplus
+# ---------------
+#
+# This use case is run in the following ways:
+#
+# 1) Passing in UserScript_obsCFSR_obsOnly_MJO_ENSO.conf then a user-specific system configuration file::
+#
+#        run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO.conf -c /path/to/user_system.conf
+#
+# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_obsCFSR_obsOnly_MJO_ENSO.py::
+#
+#        run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO.conf
+#
+# The following variables must be set correctly:
+#
+# * **INPUT_BASE** - Path to directory where sample data tarballs are unpacked (See Datasets section to obtain tarballs). This is not required to run METplus, but it is required to run the examples in parm/use_cases
+# * **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 
+#
+
+##############################################################################
+# Expected Output
+# ---------------
+#
+# 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 model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO. This may include the regridded data. In addition, a text (.csv) file will be generated and a time serie plot. The name of the text file can be specified as MAKE_MAKI_OUTPUT_TEXT_FILE. The output location can be specified as PLOT_OUTPUT_DIR. If it is not specified, plot will be sent to model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO/plots (relative to **OUTPUT_BASE**). The name of the plot file can be specified as OBS_PLOT_OUTPUT_NAME.
+# 
+
+##############################################################################
+# Keywords
+# --------
+#
+#
+# .. note::
+#
+#   * S2SAppUseCase
+#   * S2SMJOAppUseCase
+#   * NetCDFFileUseCase
+#   * RegridDataPlaneUseCase
+#   * PCPCombineUseCase
+#
+#   Navigate to :ref:`quick-search` to discover other similar use cases.
+#
+# sphinx_gallery_thumbnail_path = '_static/s2s_mjo-UserScript_obsCFSr_obsOnly_MJO_ENSO.png'
+#

internal_tests/use_cases/all_use_cases.txt

@@ -146,6 +146,7 @@ Category: s2s_mjo
 1:: UserScript_fcstGFS_obsERA_OMI:: model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.conf:: spacetime_env, metdataio
 2:: UserScript_obsERA_obsOnly_OMI:: model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.conf:: spacetime_env, metdataio
 3:: UserScript_obsERA_obsOnly_RMM:: model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.conf:: spacetime_env, metdataio
+4:: UserScript_obsCFSR_obsOnly_MJO_ENSO:: model_applications/s2s_mjo/UserScript_obsCFSR_obsOnly_MJO_ENSO.conf:: spacetime_env, metdataio
 
 
 Category: space_weather