diff --git a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py index 39df20f592..ef35181c10 100644 --- a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py +++ b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py @@ -1,178 +1,249 @@ """ -Blocking Calculation: GFS and ERA RegridDataPlane, PcpCombine, and Blocking python code -======================================================================================== +UserScript and StatAnalysis: Calculate and evaluate Blocking for the GFS and ERA +================================================================================ -model_applications/ -s2s_mid_lat/ -UserScript_fcstGFS_obsERA_Blocking.py +model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # -# To compute the Central Blocking Latitude, Instantaneousy blocked latitudes, -# Group Instantaneousy blocked latitudes, and the frequency of atmospheric -# blocking using the Pelly-Hoskins Method. After these are computed, contingency -# table statistics are computed on the Instantaneous blocked latitudes and blocks -# using stat_analysis. -# +# Atmospheric blocking is associated with extreme weather events. This use case computes +# atmospheric blocking events using the methodology in Miller & Wang (2019, 2022), which +# identifies blocks from 500 mb height. Various studies (Masato et al. 2013; Kitano and +# Yamada 2016) have suggested that 500 mb height produces a similar blocking climatology as +# results from potential temperature on a 2-PVU surface. +# +# The methodology in Miller & Wang (2019, 2022) first computes the Central Blocking Latitude +# (CBL) or storm track. Allowing for an offset north and south of the storm track, reversals +# in geopotential height are then identified as Instantaneously Blocked longitudes (IBLs). These +# IBLs are grouped when consective longitudes are blocked (GIBLs) and then blocks are identified +# by applying thresholds to ensure the large-scale, quasi-stationary characteristics of blocking +# anticyclones are met. The IBLs, GIBLs, and blocks are computed separately for the model and +# observations, and contingency table statistics are computed to compare model performance at +# identifying IBLs and blocks. The original code for computing blocking came from Douglas Miller. +# +# * Miller, D. E., and Z. Wang, 2019a: Skillful seasonal prediction of Eurasian winter blocking and extreme temperature frequency. Geophys. Res. Lett., 46, 11 530–11 538, https://doi.org/10.1029/2019GL085035. +# * Miller, D. E., and Z. Wang, 2022: Northern Hemisphere Winter Blocking: Differing Onset Mechanisms across regions. J. Atmos. Sci., 79, 1291-1309, https://doi.org/10.1175/JAS-D-21-0104.1. +# * Masato, G., B. J. Hoskins, and T. J. Woollings, 2013: Winter and summer Northern Hemisphere blocking in CMIP5 models. J. Climate, 26, 7044–7059, https://doi.org/10.1175/JCLI-D-12-00466.1. +# * Kitano, Y., and T. J. Yamada, 2016: Relationship between atmospheric blocking and cold day extremes in current and RCP8.5 future climate conditions over Japan and the surrounding area. Atmos. Sci. Lett., 17, 616–622, https://doi.org/10.1002/asl.711. ############################################################################## -# Datasets -# -------- -# -# * Forecast dataset: GFS Forecast 500 mb height. -# * Observation dataset: ERA Reanlaysis 500 mb height. +# Version Added +# ------------- # +# METplus version 4.0.0 ############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: -# -# * numpy -# * netCDF4 -# * datetime -# * bisect -# * scipy +# Datasets +# -------- # -# 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. +# **Forecast:** GFS Forecast 500 mb height for DJF 2000 - 2017 # -# 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.: +# **Observation:** ERA Reanlaysis 500 mb height for DJF 2000 - 2017 for the blocking evaluation and 1979 - 2017 for the CBL calculation # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **Climatology:** None # +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the blocking driver script which runs the steps the user -# lists in STEPS_OBS. The possible steps are regridding, time averaging, computing a running -# mean, computing anomalies, computing CBLs (CBL), plotting CBLs (PLOTCBL), computing IBLs (IBL), -# plotting IBL frequency (PLOTIBL), computing GIBLs (GIBL), computing blocks (CALCBLOCKS), plotting -# the blocking frequency (PLOTBLOCKS) and using stat_analysis to compute statistics on the IBL or -# blocking results. Regridding, time averaging, running means, anomaloies, and stat_analysis are set -# up in the UserScript .conf file and are formatted as follows: -# PROCESS_LIST = RegridDataPlane(regrid_fcst), RegridDataPlane(regrid_obs), PcpCombine(daily_mean_fcst), PcpCombine(daily_mean_obs), PcpCombine(running_mean_obs), PcpCombine(anomaly_obs), UserScript(create_cbl_filelist), UserScript(script_blocking), StatAnalysis(sanal_ibls), StatAnalysis(sanal_blocks) +# This use case calls UserScript twice and StatAnalysis twice. The first StatAnalysis +# run computes contingency table statistics on the IBLs, while the second computes contintency +# table statistics on the computed blocks. There are 6 optional pre-processing steps, 2 calls to +# RegridDataPlane and 4 calls to PCP-Combine. Additionally, METcalcpy and METplotpy are +# required to run this use case. The METcalcpy scripts accessed include the following: # -# The other steps are listed in the Blocking .conf file and are formatted as follows: -# FCST_STEPS = CBL+IBL+PLOTIBL+GILB+CALCBLOCKS+PLOTBLOCKS -# OBS_STEPS = CBL+PLOTCBL+IBL+PLOTIBL+GILB+CALCBLOCKS+PLOTBLOCKS +# * metcalcpy/contributed/blocking_weather_regime/Blocking.py # +# * metcalcpy/contributed/blocking_weather_regime/Blocking_WeatherRegime_util.py +# +# * metcalcpy/util/write_mpr.py +# +# The METplopty scrips accessed include the following: +# +# * metplotpy/contributed/blocking_s2s/CBL_plot.py +# +# * metplotpy/contributed/blocking_s2s/plot_blocking.py ############################################################################## # METplus Workflow # ---------------- # -# The blocking python code is run for each time for the forecast and observations data. This -# example loops by init time for the model pre-processing, and valid time for the other steps. -# This version is set to only process the blocking steps (CBL, PLOTCBL, IBL, PLOTIBL) and stat_analysis, -# omitting the regridding, time averaging, running mean, and anomaly pre-processing steps. However, the -# configurations for pre-processing are available for user reference. +# **Beginning time (VALID_BEG):** 12-01-2000 +# +# **End time (VALID_END):** 02-28-2017 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 1 day # +# **Sequence of forecast leads to process (LEAD_SEQ):** 24 hours +# +# This use case does not loop, but the 2 UserScripts calls are run once for +# all valid times of the forecast and observations. The first UserScript creates a file list +# with the observed ERA data to use for the storm track climatology. This is done separately +# because it's a different (longer) time frame from the data used in the other steps of the blocking +# calculation. The second UserScript runs the blocking driver which calls the code to perform the +# blocking calculation. The blocking calculation is divided up into steps, which the user can select +# by setting STEPS_OBS and STEPS_FCST in the [user_env_vars] section of the configuration. More +# information on the steps and how the calculation proceeds is given in the User Scripting section +# below. +# +# The two calls to StatAnalysis also don't loop but are run once for all valid times. The first +# StatAnalysis run computes contingency table statistics on the IBLs, while the second computes +# contintency table statistics on the computed blocks. +# +# The 6 optional pre-processing steps loop by loop by valid time with different timing settings +# needed used for the different steps. These include 2 runs of RegridDataPlane to regrid both +# the model and observations to a 1 degree grid. Then, there are 2 calls to PcpCombine. These +# compute daily average 500 mb height for the model and observations. The next two calls to +# PcpCombine compute a 5 day running mean and daily anomalies on the observations, which are used +# to compute the storm track climatology. These omitted steps can be turned back on by using the +# PROCESS_LIST that is commented out: +# +# PROCESS_LIST = RegridDataPlane(regrid_fcst), RegridDataPlane(regrid_obs), PcpCombine(daily_mean_fcst), PcpCombine(daily_mean_obs), PcpCombine(running_mean_obs), PcpCombine(anomaly_obs), UserScript(create_cbl_filelist), UserScript(script_blocking), StatAnalysis(sanal_ibls), StatAnalysis(sanal_blocks) +# +# Settings for the optional pre-processing steps can be found in the respective sections of +# the configuration, regrid_fcst, regrid_obs, daily_mean_fcst, daily_mean_obs, running_mean_obs, +# and anomaly_obs. Data is not provided in the tarball to run these steps, but the configurations +# are provided for reference on how to set up these calculations. ############################################################################## # 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_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py. -# The file UserScript_fcstGFS_obsERA_Blocking.conf runs the python program, and the -# variables for all steps of the Blocking calculation are given in the [user_env_vars] -# section of the .conf file. +# then it loads any configuration files passed to METplus via the command line, i.e. +# parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.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. +# METplus sets environment variables based on user settings in the METplus +# configuration file. See :ref:`How METplus controls MET config file settings` for more details. # -# See the following files for more information about the environment variables set in this configuration file. +# **YOU SHOULD NOT SET ANY OF THESE ENVIRONMENT VARIABLES YOURSELF! THEY WILL BE OVERWRITTEN BY METPLUS WHEN IT CALLS THE MET TOOLS!** # -# parm/use_cases/met_tool_wrapper/RegridDataPlane/RegridDataPlane.py -# parm/use_cases/met_tool_wrapper/PCPCombine/PCPCOmbine_derive.py -# parm/use_cases/met_tool_wrapper/PCPCombine/PCPCOmbine_subtract.py -# parm/use_cases/met_tool_wrapper/StatAnalysis/StatAnalysis.py +# 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` # +# .. dropdown:: StatAnalysisConfig_wrapped +# +# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped ############################################################################## -# Python Scripts +# Python Embedding # ---------------- # -# This use case uses Python scripts to perform the blocking calculation -# -# parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/Blocking_driver.py: -# This script calls the requested steps in the blocking analysis for a forecast, observation, or both. The possible -# steps are computing CBLs, plotting CBLs, computing IBLs, plotting IBLs, computing GIBLs, computing blocks, and -# plotting blocks. -# -# metcalcpy/contributed/blocking_weather_regime/Blocking.py: -# This script runs the requested steps, containing the code for computing CBLs, computing IBLs, computing GIBLs, -# and computing blocks. See the METcalcpy `Blocking Calculation Script `_ for more information. -# -# metcalcpy/contributed/blocking_weather_regime/Blocking_WeatherRegime_util.py: -# This script contains functions used by both the blocking anwd weather regime analysis, including the code for -# determining which steps the user wants to run, and finding and reading the input files in the format from the output -# pre-processing steps. See the METcalcpy `Utility script `_ for more information. -# -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/Blocking_driver.py -# +# This use case does not use python embedding. + +############################################################################## +# User Scripting +# -------------- +# +# This use case runs the blocking driver. The blocking driver runs the user selected steps +# of the blocking calculation for both the forecast and observation. These steps are specified +# in FCST_STEPS and OBS_STEPS in the [user_env_vars] section fo the configuration file in the +# following format: +# +# | FCST_STEPS = CBL+IBL+PLOTIBL+GILB+CALCBLOCKS+PLOTBLOCKS +# | OBS_STEPS = CBL+PLOTCBL+IBL+PLOTIBL+GILB+CALCBLOCKS+PLOTBLOCKS +# +# The possible steps are computing the CBLs or central blocking latitude (CBL), plotting CBLs +# (PLOTCBL), computing instantaneously blocked longitudes (IBL), plotting IBL frequency (PLOTIBL), +# computing grouped instantaneously blocked longitudes (GIBL), computing blocks (CALCBLOCKS), and +# plotting the blocking frequency (PLOTBLOCKS). This use case runs all steps although not all of +# them are required to be run. The CBL, IBL, GIBL, and CALCBLOCKS steps must be run in order as the +# IBL step requires previously computed CBLs, and GIBLs requires previously computed IBLs. Plotting +# also requires the associated step to be run (e.g. PLOTCBL requires CBL to be run first). The +# methodology used in these calculations is described in Miller & Wang (2019, 2022) listed in the +# Scientific Objective section. +# +# There are many input variables that can be changed for the driver script and blocking calculation. +# These can be changed and are described in the [user_env_vars] section of the configuration file. +# +# .. dropdown:: parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/Blocking_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking/Blocking_driver.py ############################################################################## # Running METplus # --------------- # -# This use case is run in the following ways: +# Pass the use case configuration file to the run_metplus.py script along with any +# user-specific system configuration files if desired:: # -# 1) Passing in UserScript_fcstGFS_obsERA_Blocking.py then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_fcstGFS_obsERA_Blocking.py:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.py -# -# 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 +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. ############################################################################## # 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_mid_lat/Blocking (relative to **OUTPUT_BASE**) and will contain output -# for the steps requested. This may include the regridded data, daily averaged files, running mean files, -# and anomaly files. In addition, output CBL, IBL, and Blocking frequency plots can be generated. The location -# of these output plots can be specified as BLOCKING_PLOT_OUTPUT_DIR. If it is not specified, plots will be sent -# to OUTPUT_BASE/plots. MET format matched pair output will also be generated for IBLs and blocks if a user runs -# these steps on both the model and observation data. The location the matched pair output can be specified as -# BLOCKING_MPR_OUTPUT_DIR. If it is not specified, plots will be sent to OUTPUT_BASE/mpr. An output contingency -# table statistics line from stat_analysis is also generated from the IBL and Blocks matched pair files. The -# location of the output is set as STAT_ANALYSIS_OUTPUT_DIR. +# A successful run will output the following both to the screen and to the logfile:: +# +# INFO: METplus has successfully finished running. # +# Warnings of missing files will also be output to the log file. In this case, the warnings are a result of +# the 5 day running mean calculation. They should alert the user about missing data fir 12/01, 12/02, 02/27, +# and 02/28 of each year the calculation runs. +# +# 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}/model_applications/s2s_mid_lat/Blocking. There should be 4 different +# graphics output to the plot directory in the location above, but each will have png and pdf version to make +# for 8 output plots:: +# +# * ERA_CBL_avg.png +# * ERA_CBL_avg.pdf +# * GFS_ERA_IBL_Freq_DJF.png +# * GFS_ERA_IBL_Freq_DJF.pdf +# * obs_Block_Freq.png +# * obs_Block_Freq.pdf +# * fcst_Block_Freq.png +# * fcst_Block_Freq.pdf +# +# There are numerous matched pair files output in two subdirectories of the mpr directory. These contain +# output computed IBLs and blocks. For the IBLs, one file is written for each day to the IBL subdirectory +# in the format below for 12-02-2000:: +# +# * IBL_stat_GFS_240000L_20001202_000000V.stat +# +# For the blocks .stat files, one file is also written for each day to the Blocks subdirectory in the format +# below for 12-02-2000:: +# +# * blocking_stat_GFS_240000L_20001202_000000V.stat +# +# There are also 2 files output from the StatAnalysis runs containing contingency table statistics:: +# +# * GFS_ERA_IBLS_240000L_CTS_CNT.stat +# * GFS_ERA_Blocks_240000L_CTS.stat +# +# If the pre-processing steps are turned on, regridded data, daily averaged files, running mean files, +# and anomaly files will also be output to Regrid, Daily,Rmean5d, and Anomaly directories in the ERA +# directory and Regrid and Daily directories in the GFS directory. ############################################################################## # Keywords @@ -185,8 +256,11 @@ # * StatAnalysisToolUseCase # * S2SAppUseCase # * S2SMidLatAppUseCase +# * UserScriptUseCase # * NetCDFFileUseCase # * GRIB2FileUseCase +# * METcalcpyUseCase +# * METplotpyUseCase # # Navigate to the :ref:`quick-search` page to discover other similar use cases. # diff --git a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py index 053704c2c7..a5f8f7ed69 100644 --- a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py +++ b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py @@ -1,187 +1,233 @@ """ -WeatherRegime Calculation: GFS and ERA RegridDataPlane, PcpCombine, and WeatherRegime python code -================================================================================================== +UserScript and StatAnalysis: Calculate and Evaluate Weather Regimes for GFS and ERA +=================================================================================== -model_applications/ -s2s_mid_lat/ -UserScript_fcstGFS_obsERA_WeatherRegime.py +model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # -# To perform a weather regime analysis using 500 mb height data. There are 2 pre- -# processing steps, RegridDataPlane and PcpCombine, and 4 steps in the weather regime -# analysis, elbow, EOFs, K means, and the Time frequency. The elbow and K means steps -# begin with K means clustering. Elbow then computes the sum of squared distances for -# clusters 1 - 14 and draws a straight line from the sum of squared distance for the -# clusters. This helps determine the optimal cluster number by examining the largest -# difference between the curve and the straight line. The EOFs step is optional. It -# computes an empirical orthogonal function analysis. The K means step uses clustering -# to compute the frequency of occurrence and anomalies for each cluster to give the most -# common weather regimes. Then, the time frequency computes the frequency of each weather -# regime over a user specified time frame. Finally, stat_analysis can be run to compute -# an categorical analysis of the weather regime classification or an anomaly correlation of -# the time frequency data. +# Weather regimes are defined as atmospheric patterns with high likelihoods of recurrence. +# They can modulate many atmospheric phenomena including tornado and severe weather +# occurrence. This use case computes the top 6 most frequent weather regimes using K-means +# clustering for the forecast and observations, and computes multi-category contingency table +# statistics on these regimes. It also computes the frequency of occurrence of each +# weather regime over a 7 day period for the forecast and observation and continuous +# statistics are computed comparing these two frequencies. +# +# The code for computing weather regimes comes from Douglas Miller. # +# * Miller, D. E., Wang, Z., Trapp, R. J., &Harnos, D. S., 2020: Hybrid prediction of weekly tornado activity out to Week 3: Utilizing weather regimes. Geophysical Research Letters, 47, https://doi.org/10.1029/2020GL087253. ############################################################################## -# Datasets -# -------- +# Version Added +# ------------- # -# * Forecast dataset: GFS Forecast 500 mb height. -# * Observation dataset: ERA Reanlaysis 500 mb height. +# METplus version 4.0.0 ############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: -# -# * numpy -# * netCDF4 -# * datetime -# * pylab -# * scipy -# * sklearn -# * eofs +# Datasets +# -------- # -# 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. +# **Forecast:** GFS Forecast 500 mb height # -# 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.: +# **Observation:** ERA Reanlaysis 500 mb height # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **Climatology:** None # +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the weather regime driver script which runs the steps the user -# lists in STEPS_OBS. The possible steps are regridding, time averaging, creating a list of input -# files for the weather regime calculation, computing the elbow (ELBOW), plotting the elbow -# (PLOTELBOW), computing EOFs (EOF), plotting EOFs (PLOTEOF), computing K means (KMEANS), plotting -# the K means (PLOTKMEANS), computing a time frequency of weather regimes (TIMEFREQ) and plotting -# the time frequency (PLOTFREQ). All variables are set up in the UserScript .conf file. The pre- -# processing steps and stat_analysis are listed in the process list, and are formatted as follows: -# -# PROCESS_LIST = RegridDataPlane(regrid_obs), PcpCombine(daily_mean_obs), UserScript(script_wr) -# -# The other steps are listed in the [user_env_vars] section of the UserScript .conf file -# in the following format: -# OBS_STEPS = ELBOW+PLOTELBOW+EOF+PLOTEOF+KMEANS+PLOTKMEANS+TIMEFREQ+PLOTFREQ -# FCST_STEPS = ELBOW+PLOTELBOW+EOF+PLOTEOF+KMEANS+PLOTKMEANS+TIMEFREQ+PLOTFREQ +# This use case calles UserScript once and Stat-Analysis twice. There are two optional +# pre-processing steps, Regrid-Data-Plane and PCP-Combine. Additionally, METcalcpy +# and METplotpy are required to run this use case. The METcalcpy scripts accessed include +# the following: +# +# * metcalcpy/contributed/blocking_weather_regime/WeatherRegime.py +# +# * metcalcpy/contributed/blocking_weather_regime/Blocking_WeatherRegime_util.py +# +# * metcalcpy/util/write_mpr.py # +# The METplopty scrips accessed include the following: +# +# * metplotpy/contributed/weather_regime/plot_weather_regime.py ############################################################################## # METplus Workflow # ---------------- # -# The weather regime python code is run for each time for the forecast and observations -# data. This example loops by valid time. This version is set to only process the weather -# regime steps (ELBOW, PLOTELBOW, EOF, PLOTEOF, KMEANS, PLOTKMEANS, TIMEFREQ, PLOTFREQ) and -# stat_analysis, omitting the regridding, time averaging, and creating the file list pre-processing -# steps. However, the configurations for pre-processing are available for user reference. +# **Beginning time (VALID_BEG):** 12-01-2000 +# +# **End time (VALID_END):** 02-28-2017 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 24 hours +# +# This use case does not loop, but the UserScript and both calls to Stat-Analysis are +# each run once. The UserScript runs the weather regime driver script. The weather regime +# driver script performs the weather regime calculation for the forecast and observation. This +# calculation is divided up into steps, which the user can select by setting STEPS_FCST and +# STEPS_OBS in the [user_env_vars] section of the configuration. More information on the steps and +# how the calculation proceeds is given in the User Scripting section below. # +# The two optional pre-processing steps loop by valid time when they are turned on, with different timing +# settings needed for the different steps. These steps are turned off due to data size and processing +# time. The first optional step calls Regrid-Data-Plane to regrid the data to a 1 degree latitude/longitude +# grid. The second calls PCP-Combine to compute daily means. These omitted steps can be turned back on by +# using the PROCESS_LIST that is commented out: +# +# PROCESS_LIST = RegridDataPlane(regrid_obs), PcpCombine(daily_mean_obs), UserScript(script_wr), StatAnalysis(sanal_wrclass), StatAnalysis(sanal_wrfreq) +# +# Settings for the optional pre-processing steps can be found in the respective sections of the configuration, +# regrid_obs and daily_mean_obs. Data is not provided in the tarball to run these steps, but the +# configurations are provided for reference on how to set up these calculations. ############################################################################## # 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_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py. -# The file UserScript_fcstGFS_obsERA_WeatherRegime.conf runs the python program and -# sets the variables for all steps of the Weather Regime use case including data paths. +# then it loads any configuration files passed to METplus via the command line, i.e. +# parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.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. +# METplus sets environment variables based on user settings in the METplus configuration file. +# See :ref:`How METplus controls MET config file settings` for more details. # -# See the following files for more information about the environment variables set in this configuration file. +# **YOU SHOULD NOT SET ANY OF THESE ENVIRONMENT VARIABLES YOURSELF! THEY WILL BE OVERWRITTEN BY METPLUS WHEN IT CALLS THE MET TOOLS!** # -# parm/use_cases/met_tool_wrapper/RegridDataPlane/RegridDataPlane.py -# parm/use_cases/met_tool_wrapper/PCPCombine/PCPCOmbine_derive.py -# parm/use_cases/met_tool_wrapper/StatAnalysis/StatAnalysis.py +# 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` # +# .. dropdown:: StatAnalysisConfig_wrapped +# +# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped ############################################################################## -# Python Scripts +# Python Embedding # ---------------- # -# This use case uses Python scripts to perform the blocking calculation +# This use case does not use python embedding. + +############################################################################## +# User Scripting +# -------------- +# +# This use case runs WeatherRegime_driver.py. This driver script runs the selected steps +# of the weather regime calculation that are specified in FCST_STEPS and OBS_STEPS in the +# [user_env_vars] section of the UserScript .conf file. All steps are run for this use +# case, as specified in the following format: +# +# | OBS_STEPS = ELBOW+PLOTELBOW+EOF+PLOTEOF+KMEANS+PLOTKMEANS+TIMEFREQ+PLOTFREQ +# | FCST_STEPS = ELBOW+PLOTELBOW+EOF+PLOTEOF+KMEANS+PLOTKMEANS+TIMEFREQ+PLOTFREQ +# +# The possible steps are computing the elbow or optimal number of clusters (ELBOW), plotting the elbow +# (PLOTELBOW), computing EOFs (EOF), plotting EOFs (PLOTEOF), computing the weather regimes using +# K means clustering (KMEANS), plotting the weather regimes (PLOTKMEANS), computing a user specified +# time frequency of weather regimes (TIMEFREQ) and plotting the time frequency (PLOTFREQ). The +# TIMEFREQ and PLOTFREQ steps require that the KMEANS step be run first, while the ELBOW, EOF, and +# KMEANS steps can be run individally. Input variables to the WeatherRegime driver are set and +# described in the [user_env_vars] section of the configuration file. +# +# Elbow computes the optimal number of clusters using the sum of squared distances for +# clusters 1 - 14 and draws a straight line from the sum of squared distance for the +# clusters. This helps determine the optimal cluster number by examining the largest +# difference between the curve and the straight line. The EOFs step computes empirical orthogonal +# functions. These EOFs are used to reconstruct the height field, with this reconstructed data used +# in the K means calculation. If EOFs are not compted, the original height field is used in the K means +# calculation. The K means step uses clustering to compute the frequency of occurrence and anomalies +# for each cluster to give the most common weather regimes. Then, the time frequency computes the +# frequency of each weather regime over a user specified time frame. # -# parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime/WeatherRegime_driver.py: -# This script calls the requested steps in the blocking analysis for a forecast, observation, or both. The possible -# steps are computing the elbow, computing EOFs, and computing weather regimes using k means clustering. +# .. dropdown:: parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime/WeatherRegime_driver.py # -# metcalcpy/contributed/blocking_weather_regime/WeatherRegime.py: -# This script runs the requested steps, containing the code for computing the bend in the elbow, computing EOFs, and -# computing weather regimes using k means clustering. See the METcalcpy `Weather Regime Calculation Script `_ for more information. +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime/WeatherRegime_driver.py + +############################################################################## +# Running METplus +# --------------- # -# metcalcpy/contributed/blocking_weather_regime/Blocking_WeatherRegime_util.py: -# This script contains functions used by both the blocking anwd weather regime analysis, including the code for -# determining which steps the user wants to run, and finding and reading the input files in the format from the output -# pre-processing steps. See the METcalcpy `Utility script `_ for more information. +# Pass the use case configuration file to the run_metplus.py script along with any +# user-specific system configuration files if desired:: # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime/WeatherRegime_driver.py +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. ############################################################################## -# Running METplus +# Expected Output # --------------- # -# This use case is run in the following ways: +# A successful run will output the following both to the screen and to the logfile:: # -# 1) Passing in UserScript_fcstGFS_obsERA_WeatherRegime.py then a user-specific system configuration file:: +# INFO: METplus has successfully finished running. # -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py -c /path/to/user_system.conf +# 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}/model_applications/s2s_mid_lat/WeatherRegime +# and will contain output for the steps requested. The output includes 8 plots in the plots directory:: # -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_fcstGFS_obsERA_WeatherRegime.py:: +# * fcst_elbow.png +# * obs_elbow.png +# * fcst_eof.png +# * obs_eof.png +# * fcst_kmeans.png +# * obs_kmeans.png +# * fcst_freq.png +# * obs_freq.png # -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_WeatherRegime.py +# The output also includes a daily classification of weather regimes as text files for both +# the forecast and observation:: # -# The following variables must be set correctly: +# * fcst_weather_regime_class.txt +# * obs_weather_regime_class.txt # -# * **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 +# There are numerous matched pair files output in two subdirectories of the mpr directory. These contain +# output classified weather regimes and also the frequency for each weather regime. For the classified +# weather regimes, one file is written for each day to the WeatherRegime subdirectory (1513 files total) +# in the format below for 12-02-2000:: # -# Example User Configuration File:: +# * weather_regime_stat_GFS_240000L_20001202_000000V.stat # -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y +# for the frequency matched pair files, one file is written for each day and each weather regime (8466 files +# total) to the freq subdirectory in the format below for 12-02-2000, weather regime 1:: # - -############################################################################## -# Expected Output -# --------------- +# * weather_regime01_freq_stat_GFS_240000L_20001202_000000V.stat +# +# Stat-Analysis 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_mid_lat/WeatherRegime (relative to **OUTPUT_BASE**) and will contain output -# for the steps requested. This may include the regridded data, daily averaged files, a text file containing the -# list of input files, and text files for the weather regime classification and time frequency (if KMEANS and -# TIMEFREQ are run for both the forecast and observation data). In addition, output elbow, EOF, and Kmeans weather -# regime plots can be generated. The location of these output plots can be specified as WR_OUTPUT_DIR. If it is -# not specified, plots will be sent to {OUTPUT_BASE}/plots. The output location for the matched pair files can be -# specified as WR_MPR_OUTPUT_DIR. If it is not specified, it will be sent to {OUTPUT_BASE}/mpr. The output weather -# regime text or netCDF file location is set in WR_OUTPUT_FILE_DIR. If this is not specified, the output text/netCDF -# file will be sent to {OUTPUT_BASE}. The stat_analysis contingency table statistics and anomaly correlation files -# will be sent to the locations given in STAT_ANALYSIS_OUTPUT_DIR for their respective configuration sections. +# * GFS_ERA_WRClass_240000L_MCTS.stat +# * GFS_ERA_WR_freq_240000L_CNT.stat # +# If the pre-processing steps are turned on, the output will include the regridded data and daily averaged files. ############################################################################## # Keywords @@ -194,8 +240,11 @@ # * StatAnalysisToolUseCase # * S2SAppUseCase # * S2SMidLatAppUseCase +# * UserScriptUseCase # * NetCDFFileUseCase # * GRIB2FileUseCase +# * METcalcpyUseCase +# * METplotpyUseCase # # Navigate to the :ref:`quick-search` page to discover other similar use cases. # diff --git a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.py b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.py index 68af4fa32b..31e4af1457 100644 --- a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.py +++ b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.py @@ -1,173 +1,207 @@ """ -Blocking Calculation: ERA RegridDataPlane, PcpCombine, and Blocking python code -================================================================================ +UserScript: Calculate Blocking for the ERA +====================================================================================== -model_applications/ -s2s_mid_lat/ -UserScript_obsERA_obsOnly_Blocking.py +model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # -# To compute the frequency of blocking using the Pelly-Hoskins method. Specifically -# the blocking calculation consits of computing the Central Blocking Latitude (CBL), -# Instantaneousy blocked latitudes (IBL), Group Instantaneousy blocked latitudes (GIBL), -# and the frequency of atmospheric blocking. The CBL calculation had an option to use an -# observed climatology. -# -# The following reference contains the specific equations and methodology used to compute -# blocking: -# +# Atmospheric blocking is associated with extreme weather events. This use case computes +# atmospheric blocking events using the methodology in Miller & Wang (2019, 2022), which +# identifies blocks from 500 mb height. Various studies (Masato et al. 2013; Kitano and +# Yamada 2016) have suggested that 500 mb height produces a similar blocking climatology as +# results from potential temperature on a 2-PVU surface. +# +# The methodology in Miller & Wang (2019, 2022) first computes the Central Blocking Latitude +# (CBL) or storm track. Allowing for an offset north and south of the storm track, reversals +# in geopotential height are then identified as Instantaneously Blocked Longitudes (IBLs). These +# IBLs are grouped when consective longitudes are blocked (GIBLs) and then blocks are identified +# by applying thresholds to ensure the large-scale, quasi-stationary characteristics of blocking +# anticyclones are met. +# +# This use case is a simplified version of the UserScript_fcstGFS_obs_ERA_Blocking use case. While +# that use case evaluates blocking for both the model and observations, this case shows how to run +# the blocking calculation on observations only. The setup is simpler and requires fewer MET runs +# than the UserScript_fcstGFS_obs_ERA_Blocking use case. The original code for computing blocking +# came from Douglas Miller. +# +# * Miller, D. E., and Z. Wang, 2019a: Skillful seasonal prediction of Eurasian winter blocking and extreme temperature frequency. Geophys. Res. Lett., 46, 11 530–11 538, https://doi.org/10.1029/2019GL085035. +# * Miller, D. E., and Z. Wang, 2022: Northern Hemisphere Winter Blocking: Differing Onset Mechanisms across regions. J. Atmos. Sci., 79, 1291-1309, https://doi.org/10.1175/JAS-D-21-0104.1. +# * Masato, G., B. J. Hoskins, and T. J. Woollings, 2013: Winter and summer Northern Hemisphere blocking in CMIP5 models. J. Climate, 26, 7044–7059, https://doi.org/10.1175/JCLI-D-12-00466.1. +# * Kitano, Y., and T. J. Yamada, 2016: Relationship between atmospheric blocking and cold day extremes in current and RCP8.5 future climate conditions over Japan and the surrounding area. Atmos. Sci. Lett., 17, 616–622, https://doi.org/10.1002/asl.711. ############################################################################## -# Datasets -# -------- +# Version Added +# ------------- # -# * Forecast dataset: None -# * Observation dataset: ERA Reanlaysis 500 mb height. +# METplus version 4.0.0 ############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: -# -# * numpy -# * netCDF4 -# * datetime -# * bisect -# * scipy +# Datasets +# -------- # -# 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. +# **Forecast:** None # -# 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.: +# **Observation:** ERA Reanlaysis 500 mb height for DJF 1979 - 2017 # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **Climatology:** None # +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the blocking driver script which runs the steps the user -# lists in STEPS_OBS. The possible steps are regridding, time averaging, computing a -# running mean, computing anomalies, computing CBLs (CBL), plotting CBLs (PLOTCBL), -# computing IBLs (IBL), plotting IBL frequency (PLOTIBL), computing GIBLs (GIBL), -# computing blocks (CALCBLOCKS), and plotting the blocking frequency (PLOTBLOCKS). -# Regridding, time averaging, running means, and anomaloies are set up in the UserScript -# .conf file and are formatted as follows: -# PROCESS_LIST = RegridDataPlane(regrid_obs), PcpCombine(daily_mean_obs), PcpCombine(running_mean_obs), PcpCombine(anomaly_obs), UserScript(script_blocking) +# This use case calls UserScript once. There are 4 optional pre-processing steps, +# RegridDataPlane and 3 calls to PcpCombine. METcalcpy and METplotpy are also +# required to run this use case. The METcalcpy scripts accessed include the +# following: +# +# * metcalcpy/contributed/blocking_weather_regime/Blocking.py +# +# * metcalcpy/contributed/blocking_weather_regime/Blocking_WeatherRegime_util.py +# +# The METplopty scrips accessed include the following: # -# The other steps are listed in the Blocking .conf file and are formatted as follows: -# OBS_STEPS = CBL+PLOTCBL+IBL+PLOTIBL+GIBL+CALCBLOCKS+PLOTBLOCKS +# * metplotpy/contributed/blocking_s2s/CBL_plot.py # +# * metplotpy/contributed/blocking_s2s/plot_blocking.py ############################################################################## # METplus Workflow # ---------------- # -# The blocking python code is run for each time for the forecast and observations -# data. This example loops by valid time. This version is set to only process the blocking -# steps (CBL, PLOTCBL, IBL, PLOTIBL, GIBL, CALCBLOCKS, PLOTBLOCKS), omitting the regridding, -# time averaging, running mean, and anomaly pre-processing steps. However, the configurations -# for pre-processing are available for user reference. +# **Beginning time (VALID_BEG):** 12-01-1979 +# +# **End time (VALID_END):** 02-28-2017 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 hour +# +# This use case does not loop. It runs UserScript once over the entire time period. The +# UserScript runs the blocking driver script which performs the blocking calculation. This +# calculation is divided up into steps, which the user can select by setting STEPS_OBS in +# the [user_env_vars] section of the configuration. More information on the steps and +# how the calculation proceeds is given in the User Scripting section below. +# +# The four optional pre-processings steps loop by valid time with different timing settings +# needed used for the different steps. These steps are turned off due to data size and processing +# time. The first optional step calls Regrid-Data-Plane to regrid the data to a 1 degree +# latitude/longitude grid. The second calls PCP-Combine to compute daily means of 500 mb height. +# The third calls PCP-Combine to compute a 5 day running mean, while the last uses PCP-Combine +# to compute anomalies by subtracting the 5 day running mean from the daily mean. These omitted steps +# can be turned on by using the PROCESS_LIST that is commented out: # +# PROCESS_LIST = RegridDataPlane(regrid_obs), PcpCombine(daily_mean_obs), PcpCombine(running_mean_obs), PcpCombine(anomaly_obs), UserScript(script_blocking) +# +# Settings for the optional pre-processing steps can be found in the respective sections of +# the configuration, regrid_obs, daily_mean_obs, running_mean_obs, and anomaly_obs. Data is not +# provided in the tarball to run these steps, but the configurations are provided as an example +# of how to set up these steps. ############################################################################## # 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_mid_lat/UserScript_obsERA_obsOnly_Blocking.py. -# The file UserScript_obsERA_obsOnly_Blocking.conf runs the python program, and the -# variables for all steps of the Blocking use case are set in the [user_env_vars] -# section. +# then it loads any configuration files passed to METplus via the command line, i.e. +# parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.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. -# -# See the following files for more information about the environment variables set in this configuration file. -# -# parm/use_cases/met_tool_wrapper/RegridDataPlane/RegridDataPlane.py -# parm/use_cases/met_tool_wrapper/PCPCombine/PCPCombine_derive.py -# parm/use_cases/met_tool_wrapper/PCPCombine/PCPCombine_subtract.py +# This case does not use MET configuration files. ############################################################################## -# Python Scripts +# Python Embedding # ---------------- # -# This use case uses Python scripts to perform the blocking calculation +# This use case does not use python embedding. + +############################################################################## +# User Scripting +# -------------- # -# parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking/Blocking_driver.py: -# This script calls the requested steps in the blocking analysis for a forecast, observation, or both. +# This use case runs the blocking driver. The blocking driver runs the user selected steps +# of the blocking calculation. These steps are specified in OBS_STEPS in the [user_env_vars] +# section fo the configuration file in the following format: # -# metcalcpy/contributed/blocking_weather_regime/Blocking.py: -# This script runs the requested steps, containing the code for computing CBLs, computing IBLs, computing GIBLs, -# and computing blocks. See the METcalcpy `Blocking Calculation Script `_ for more information. +# | OBS_STEPS = CBL+PLOTCBL+IBL+PLOTIBL+GILB+CALCBLOCKS+PLOTBLOCKS # -# metcalcpy/contributed/blocking_weather_regime/Blocking_WeatherRegime_util.py: -# This script contains functions used by both the blocking anwd weather regime analysis, including the code for -# determining which steps the user wants to run, and finding and reading the input files in the format from the output -# pre-processing steps. See the METcalcpy `Utility script `_ for more information. +# The possible steps are computing the CBLs or Central Blocking Latitude (CBL), plotting CBLs +# (PLOTCBL), computing Instantaneously Blocked Longitudes (IBL), plotting IBL frequency (PLOTIBL), +# computing grouped instantaneously blocked longitudes (GIBL), computing blocks (CALCBLOCKS), and +# plotting the blocking frequency (PLOTBLOCKS). This use case runs all steps although not all of +# them are required to be run. The CBL, IBL, GIBL, and CALCBLOCKS steps must be run in order as the +# IBL step requires previously computed CBLs, and GIBLs requires previously computed IBLs. Plotting +# also requires the associated step to be run (e.g. PLOTCBL requires CBL to be run first). The +# methodology used in these calculations is described in Miller & Wang (2019, 2022) listed in the +# Scientific Objective section. # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking/Blocking_driver.py +# There are many input variables that can be changed for the driver script and blocking calculation. +# These can be changed and are described in the [user_env_vars] section of the configuration file. # +# .. dropdown:: parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking/Blocking_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking/Blocking_driver.py ############################################################################## # Running METplus # --------------- # -# This use case is run in the following ways: -# -# 1) Passing in UserScript_obsERA_obsOnly_Blocking.py then a user-specific system configuration file:: +# 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 -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.py -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_obsERA_obsOnly_Blocking.py:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.py -# -# 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 +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_Blocking.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. ############################################################################## # 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_mid_lat/Blocking (relative to **OUTPUT_BASE**) and will contain output -# for the steps requested. This may include the regridded data, daily averaged files, running mean files, -# and anomaly files. In addition, output CBL, IBL, and Blocking frequency plots can be generated. The location -# of these output plots can be specified as BLOCKING_PLOT_OUTPUT_DIR. If it is not specified, plots will be sent -# to OUTPUT_BASE/plots. MET format matched pair output will also be generated for IBLs and blocks if a user runs -# these steps on both the model and observation data. The location the matched pair output can be specified as -# BLOCKING_MPR_OUTPUT_DIR. If it is not specified, plots will be sent to OUTPUT_BASE/mpr. +# 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}/model_applications/s2s_mid_lat/Blocking. There should be +# 3 different graphics output to the plot directory in the above location. Each will have png and pdf +# versions to make for 6 output plots:: +# +# * ERA_CBL_avg.png +# * ERA_CBL_avg.pdf +# * ERA_IBL_Freq_DJF.png +# * ERA_IBL_Freq_DJF.pdf +# * obs_Block_Freq_DJF.png +# * obs_Block_Freq_DJF.pdf +# +# If the pre-processing steps are turned on, regridded data, daily averaged files, running mean files, +# and anomaly files will also be output to Regrid, Daily,Rmean5d, and Anomaly directories in the +# ERA directory. ############################################################################## # Keywords @@ -177,8 +211,10 @@ # # * RegridDataPlaneToolUseCase # * PCPCombineToolUseCase +# * StatAnalysisToolUseCase # * S2SAppUseCase # * S2SMidLatAppUseCase +# * UserScriptUseCase # * NetCDFFileUseCase # * GRIB2FileUseCase # * METcalcpyUseCase @@ -189,4 +225,3 @@ # # # sphinx_gallery_thumbnail_path = '_static/s2s_mid_lat-UserScript_obsERA_obsOnly_Blocking.png' -# diff --git a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py index 2502c32968..7e14308e18 100644 --- a/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py +++ b/docs/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py @@ -1,186 +1,191 @@ """ -WeatherRegime Calculation: ERA RegridDataPlane, PcpCombine, and WeatherRegime python code -========================================================================================== +UserScript: Calculate Weather Regimes for ERA +========================================================================================= -model_applications/ -s2s_mid_lat/ -UserScript_obsERA_obsOnly_WeatherRegime.py +model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # -# To perform a weather regime analysis using 500 mb height data. There are 2 pre- -# processing steps, RegridDataPlane and PcpCombine, and 4 steps in the weather regime -# analysis, elbow, EOFs, K means, and the Time frequency. The elbow and K means steps -# begin with K means clustering. Elbow then computes the sum of squared distances for -# clusters 1 - 14 and draws a straight line from the sum of squared distance for the -# clusters. This helps determine the optimal cluster number by examining the largest -# difference between the curve and the straight line. The EOFs step is optional. It -# computes an empirical orthogonal function analysis. The K means step uses clustering -# to compute the frequency of occurrence and anomalies for each cluster to give the most -# common weather regimes. Then, the time frequency computes the frequency of each weather -# regime over a user specified time frame. Finally, stat_analysis can be run to compute -# an categorical analysis of the weather regime classification or an anomaly correlation of -# the time frequency data. +# Weather regimes are defined as atmospheric patterns with high likelihoods of recurrence. +# They can modulate many atmospheric phenomena including tornado and severe weather +# occurrence. This use case computes the top 6 most frequent weather regimes using K-means +# clustering for the ERA observations. It also computes the frequency of occurrence of each +# weather regime over a 7 day period. The code for computing weather regimes comes from Douglas Miller. # +# * Miller, D. E., Wang, Z., Trapp, R. J., &Harnos, D. S., 2020: Hybrid prediction of weekly tornado activity out to Week 3: Utilizing weather regimes. Geophysical Research Letters, 47, https://doi.org/10.1029/2020GL087253. ############################################################################## -# Datasets -# -------- +# Version Added +# ------------- # -# * Forecast dataset: None. -# * Observation dataset: ERA Reanlaysis 500 mb height. +# METplus version 4.0.0 ############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: -# -# * numpy -# * netCDF4 -# * datetime -# * pylab -# * scipy -# * sklearn -# * eofs +# Datasets +# -------- # -# 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. +# **Forecast:** None # -# 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.: +# **Observation:** ERA Reanlaysis 500 mb height for DJF 1979 - 2017 # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **Climatology:** None # +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the weather regime driver script which runs the steps the user -# lists in STEPS_OBS. The possible steps are regridding, time averaging, creating a list of input -# files for the weather regime calculation, computing the elbow (ELBOW), plotting the elbow -# (PLOTELBOW), computing EOFs (EOF), plotting EOFs (PLOTEOF), computing K means (KMEANS), plotting -# the K means (PLOTKMEANS), computing a time frequency of weather regimes (TIMEFREQ) and plotting -# the time frequency (PLOTFREQ). All variables are set up in the UserScript .conf file. The pre- -# processing steps and stat_analysis are listed in the process list, and are formatted as follows: -# -# PROCESS_LIST = RegridDataPlane(regrid_obs), PcpCombine(daily_mean_obs), UserScript(script_wr) +# This use case calles UserScript once and Stat-Analysis twice. There are two optional +# pre-processing steps, Regrid-Data-Plane and PCP-Combine. Additionally, METcalcpy +# and METplotpy are required to run this use case. The METcalcpy scripts accessed include +# the following: # -# The other steps are listed in the [user_env_vars] section of the UserScript .conf file -# in the following format: -# OBS_STEPS = ELBOW+PLOTELBOW+EOF+PLOTEOF+KMEANS+PLOTKMEANS+TIMEFREQ+PLOTFREQ +# * metcalcpy/contributed/blocking_weather_regime/WeatherRegime.py +# +# * metcalcpy/contributed/blocking_weather_regime/Blocking_WeatherRegime_util.py # +# The METplopty scripts accessed include the following: +# +# * metplotpy/contributed/weather_regime/plot_weather_regime.py ############################################################################## # METplus Workflow # ---------------- # -# The weather regime python code is run for each time for the forecast and observations -# data. This example loops by valid time. This version is set to only process the weather -# regime steps (ELBOW, PLOTELBOW, EOF, PLOTEOF, KMEANS, PLOTKMEANS, TIMEFREQ, PLOTFREQ) and -# stat_analysis, omitting the regridding, time averaging, and creating the file list pre-processing -# steps. However, the configurations for pre-processing are available for user reference. +# **Beginning time (VALID_BEG):** 12-01-2000 +# +# **End time (VALID_END):** 02-28-2017 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 hour +# +# This use case does not loop, but the UserScript that runs the weather regime driver script +# is run once over the entire time period. The weather regime driver script performs the weather +# regime calculation for the observations. This calculation is divided up into steps, which the +# user can select by setting STEPS_OBS in the [user_env_vars] section of the configuration. More +# information on the steps and how the calculation proceeds is given in the User Scripting section below. +# +# The two optional pre-processing steps loop by valid time when they are turned on, with different timing +# settings needed for the different steps. These steps are turned off due to data size and processing +# time. The first optional step calls Regrid-Data-Plane to regrid the data to a 1 degree latitude/longitude +# grid. The second calls PCP-Combine to compute daily means. These omitted steps can be turned back on by +# using the PROCESS_LIST that is commented out: +# +# PROCESS_LIST = RegridDataPlane(regrid_obs), PcpCombine(daily_mean_obs), UserScript(script_wr) # +# Settings for the optional pre-processing steps can be found in the respective sections of the configuration, +# regrid_obs and daily_mean_obs. Data is not provided in the tarball to run these steps, but the +# configurations are provided for reference on how to set up these calculations. ############################################################################## # 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_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py. -# The file UserScript_obsERA_obsOnly_WeatherRegime.conf runs the python program and -# sets the variables for all steps of the Weather Regime use case including data paths. +# then it loads any configuration files passed to METplus via the command line, i.e. +# parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherREgime.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.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. -# -# See the following files for more information about the environment variables set in this configuration file. -# -# parm/use_cases/met_tool_wrapper/RegridDataPlane/RegridDataPlane.py -# parm/use_cases/met_tool_wrapper/PCPCombine/PCPCOmbine_derive.py -# parm/use_cases/met_tool_wrapper/StatAnalysis/StatAnalysis.py -# +# This case does not use MET configuration files. ############################################################################## -# Python Scripts +# Python Embedding # ---------------- # -# This use case uses Python scripts to perform the blocking calculation +# This use case does not use python embedding. + +############################################################################## +# User Scripting +# -------------- +# +# This use case runs WeatherRegime_driver.py. This driver script runs the selected steps +# of the weather regime calculation that are specified in OBS_STEPS in the [user_env_vars] +# section of the UserScript .conf file. All steps are run for this use case, as specified +# in the following format: # -# parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime/WeatherRegime_driver.py: -# This script calls the requested steps in the blocking analysis for a forecast, observation, or both. The possible -# steps are computing the elbow, computing EOFs, and computing weather regimes using k means clustering. +# | OBS_STEPS = ELBOW+PLOTELBOW+EOF+PLOTEOF+KMEANS+PLOTKMEANS+TIMEFREQ+PLOTFREQ # -# metcalcpy/contributed/blocking_weather_regime/WeatherRegime.py: -# This script runs the requested steps, containing the code for computing the bend in the elbow, computing EOFs, and -# computing weather regimes using k means clustering. See the METcalcpy `Weather Regime Calculation Script `_ for more information. +# The possible steps are computing the elbow or optimal number of clusters (ELBOW), plotting the elbow +# (PLOTELBOW), computing EOFs (EOF), plotting EOFs (PLOTEOF), computing the weather regimes using +# K means clustering (KMEANS), plotting the weather regimes (PLOTKMEANS), computing a user specified +# time frequency of weather regimes (TIMEFREQ) and plotting the time frequency (PLOTFREQ). The +# TIMEFREQ and PLOTFREQ steps require that the KMEANS step be run first, while all other steps +# can be run individally. Input variables to the WeatherRegime driver are set and described +# in the [user_env_vars] section of the configuration file. # -# metcalcpy/contributed/blocking_weather_regime//Blocking_WeatherRegime_util.py: -# This script contains functions used by both the blocking anwd weather regime analysis, including the code for -# determining which steps the user wants to run, and finding and reading the input files in the format from the output -# pre-processing steps. See the METcalcpy `Utility script `_ for more information. +# Elbow computes the optimal number of clusters using the sum of squared distances for +# clusters 1 - 14 and draws a straight line from the sum of squared distance for the +# clusters. This helps determine the optimal cluster number by examining the largest +# difference between the curve and the straight line. The EOFs step computes empirical orthogonal +# functions. These EOFs are used to reconstruct the height field, with this reconstructed data used +# in the K means calculation. If EOFs are not compted, the original height field is used in the K means +# calculation. The K means step uses clustering to compute the frequency of occurrence and anomalies +# for each cluster to give the most common weather regimes. Then, the time frequency computes the +# frequency of each weather regime over a user specified time frame. # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime/WeatherRegime_driver.py +# .. dropdown:: parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime/WeatherRegime_driver.py # +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime/WeatherRegime_driver.py ############################################################################## # Running METplus # --------------- # -# This use case is run in the following ways: +# Pass the use case configuration file to the run_metplus.py script along with any +# user-specific system configuration files if desired:: # -# 1) Passing in UserScript_obsERA_obsOnly_WeatherRegime.py then a user-specific system configuration file:: +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.conf /path/to/user_system.conf # -# master_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_obsERA_obsOnly_WeatherRegime.py:: -# -# master_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mid_lat/UserScript_obsERA_obsOnly_WeatherRegime.py +# See :ref:`running-metplus` for more information. + +############################################################################## +# Expected Output +# --------------- # -# The following variables must be set correctly: +# A successful run will output the following both to the screen and to the logfile:: # -# * **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 +# INFO: METplus has successfully finished running. # -# Example User Configuration File:: +# 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}/model_applications/s2s_mid_lat/WeatherRegime +# and will contain output for the steps requested. The output includes 4 plots in the plots directory:: # -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y +# * obs_elbow.png +# * obs_eof.png +# * obs_kmeans.png +# * obs_freq.png # - -############################################################################## -# Expected Output -# --------------- +# The output also includes a daily classification of weather regimes as a text file:: # -# 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_mid_lat/WeatherRegime (relative to **OUTPUT_BASE**) and will contain output -# for the steps requested. This may include the regridded data, daily averaged files, a text file containing the -# list of input files, and text files for the weather regime classification and time frequency (if KMEANS and -# TIMEFREQ are run for both the forecast and observation data). In addition, output elbow, EOF, and Kmeans weather -# regime plots can be generated. The location of these output plots can be specified as WR_OUTPUT_DIR. If it is -# not specified, plots will be sent to {OUTPUT_BASE}/plots. The output location for the matched pair files can be -# specified as WR_MPR_OUTPUT_DIR. If it is not specified, it will be sent to {OUTPUT_BASE}/mpr. The output weather -# regime text or netCDF file location is set in WR_OUTPUT_FILE_DIR. If this is not specified, the output text/netCDF -# file will be sent to {OUTPUT_BASE}. The stat_analysis contingency table statistics and anomaly correlation files -# will be sent to the locations given in STAT_ANALYSIS_OUTPUT_DIR for their respective configuration sections. +# * obs_weather_regime_class.txt # +# If the pre-processing steps are turned on, the output will include the regridded data and daily averaged files. ############################################################################## # Keywords @@ -190,8 +195,10 @@ # # * RegridDataPlaneToolUseCase # * PCPCombineToolUseCase +# * StatAnalysisToolUseCase # * S2SAppUseCase # * S2SMidLatAppUseCase +# * UserScriptUseCase # * NetCDFFileUseCase # * GRIB2FileUseCase # * METcalcpyUseCase diff --git a/docs/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.py b/docs/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.py index 4ef6a1123a..f945717868 100644 --- a/docs/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.py +++ b/docs/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.py @@ -1,129 +1,181 @@ """ -UserScript: Make OMI plot from calculated MJO indices -===================================================== +UserScript: Make GFS and ERA OMI plot from calculated MJO indices +================================================================= -model_applications/ -s2s_mjo/ -UserScript_fcstGFS_obsERA_OMI.py +model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # -# To use Outgoing Longwave Radiation (OLR) to compute the OLR based MJO Index (OMI). Specifically, OMI is computed using OLR data between 20N and 20S. The OLR data are then projected onto Empirical Orthogonal Function (EOF) data that is computed for each day of the year, latitude, and longitude. The OLR is then filtered for 20 - 96 days, and regressed onto the daily EOFs. Finally, it's normalized and these normalized components are plotted on a phase diagram. Separate phase diagrams are created for the model and observations. +# The Madden-Julian Oscillation (MJO) is the largest element of intraseasonal variability in the +# tropics and is characterized by eastward moving regions of enhanced and suppressed rainfall. These +# phases are typically grouped into numbers 1 - 8 based on the geographic location of the enhanced and +# suppressed rainfall. The MJO affects global weather including summer monsoons, tropical cyclone +# development, and sudden stratospheric warming events, and has teloconnections to mid latitude weather +# systems. # +# This use case uses outgoing longwave radiation (OLR) to compute the OLR based MJO Index (OMI), which is +# a convective index of the MJO. OMI is computed separately for the model and observations and then displayed +# on phase diagrams to evaluate the model reprentation of this important oscillation. The code for computing OMI +# came from Maria Gehne at the NOAA Physical Science Laboratory (PSL). ############################################################################## -# Datasets -# -------- +# Version Added +# ------------- # -# * Forecast dataset: GFS Model Outgoing Longwave Radiation -# * Observation dataset: ERA Reanlaysis Outgoing Longwave Radiation. +# METplus version 4.1.0 ############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: -# -# * numpy -# * netCDF4 -# * datetime -# * xarray -# * matplotlib -# * scipy -# * pandas +# Datasets +# -------- # -# 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. +# **Forecast:** GFS Model Outgoing Longwave Radiation, 2017 - 2018 # -# 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.: +# **Observation:** ERA Reanlaysis Outgoing Longwave Radiation, 2017 - 2018 # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **EOFs:** Observed OMI EOF1 and EOF2 patterns from the PSL Website (https://psl.noaa.gov/mjo/mjoindex/) # +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the OMI driver which computes OMI and creates a phase diagram. Inputs to the OMI driver include netCDF files that are in MET's netCDF version. In addition, a txt file containing the listing of these input netCDF files is required, as well as text file listings of the EOF1 and EOF2 files. These text files can be generated using the USER_SCRIPT_INPUT_TEMPLATES in the [create_eof_filelist] and [script_omi] sections. Some optional pre-processing steps include using regrid_data_plane to either regrid your data or cut the domain to 20N - 20S. +# This use case calls UserScript twice, first to create a list of EOF files and then to run +# the OMI calculation. In addition, there are three optional pre-processing steps, PCP-Combine +# and two calls to Regrid-Data-Plane. +# +# This use case requires METcalcpy, METplotpy, and METdataio to run. The METcalcpy scripts accessed include the following: +# +# * metcalcpy/contributed/rmm_omi/compute_mjo_indices.py # +# The METplotpy scripts accessed include the following: +# +# * metplotpy/contributed/mjo_rmm_omi/plot_mjo_indioces.py +# +# The METdataio scripts accessed include the following: +# +# * METreadnc/util/read_netcdf.py ############################################################################## # METplus Workflow # ---------------- -# -# The OMI 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 OMI calculation and creating a text file listing of the EOF files, omitting the creation of daily means for the model and the regridding pre-processing steps. However, the configurations for pre-processing are available for user reference. +# +# **Beginning time (VALID_BEG):** 01-01-2017 +# +# **End time (VALID_END):** 12-31-2018 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 hour +# +# This use case does not loop, but the UserScript to create and EOF filelist is run once and the UserScript which +# runs the OMI driver script is also run once for both the model and observations across the entire time period. +# The EOF filelist is created separately since the EOF files are needed for each day of the year while the OMI +# calculation is on a separate time frame. +# +# The 3 optional pre-processing steps loop by valid time when they are turned on. The steps include using PcpCombine to +# compute daily averages for the model, and using RegridDataPlane for both the model and observations to cut the grid down +# to -20 to 20 latitude. These omitted steps can be turned back on by using the PROCESS_LIST that is commented out: +# +# PROCESS_LIST = PcpCombine(daily_mean_fcst), RegridDataPlane(regrid_obs_olr), RegridDataPlane(regrid_fcst_olr), UserScript(create_eof_filelist), UserScript(script_omi) +# +# Settings for the optional pre-processing steps can be found in the respective sections of the configuration, +# daily_mean_fcst, regrid_obs_olr, and regrid_fcst_olr. Data is not provided in the tarball to run these steps, +# but the configurations are provided for reference on how to set up these calculations. +# +# The Phase diagram plots are created over a different time frame than the +# calculation, 01-01-2017 to 03-31-2017 for both plots. ############################################################################## # 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 +# then it loads any configuration files passed to METplus via the command line, # i.e. parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.conf. -# The file UserScript_fcstGFS_obsERA_OMI/OMI_driver.py runs the python program and -# UserScript_fcstGFS_obsERA_OMI.conf sets the variables for all steps of the OMI use case. # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.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. +# ----------------- # +# There are no MET configuration files used in this use case. + +############################################################################## +# Python Embedding +# ---------------- # +# This use case does not use python embedding. ############################################################################## -# Python Scripts +# User Scripting # ---------------- # -# The OMI driver script orchestrates the calculation of the MJO indices and -# the generation of a phase diagram OMI plot: -# parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py: +# This use case runs the OMI driver which computes OMI and creates a phase diagram. Inputs to the +# OMI driver include netCDF files formatted in MET's netCDF version. In addition, a text file containing +# the listing of these input netCDF files is required, as well as text file listings of the EOF1 and +# EOF2 files. These text files can be generated using the USER_SCRIPT_INPUT_TEMPLATES in the +# [create_eof_filelist] and [script_omi] sections. Variables for the OMI calculation are set in the +# [user_env_vars] section of the .conf file. +# +# For the OMI calculation, the OLR data are projected onto Empirical Orthogonal Function (EOF) +# data that is computed for each day of the year, latitude, and longitude. The OLR is then filtered +# for 20 - 96 days, and regressed onto the daily EOFs. Finally, it's normalized and these normalized +# components are plotted on a phase diagram. The OMI driver script orchestrates the calculation of the +# MJO indices and the generation of a phase diagram OMI plot. Separate phase diagrams are created for +# the model and observations. # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py +# .. dropdown:: parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py # +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py ############################################################################## # Running METplus # --------------- # -# This use case is run in the following ways: -# -# 1) Passing in UserScript_fcstGFS_obsERA_OMI.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.conf -c /path/to/user_system.conf +# Pass the use case configuration file to the run_metplus.py script along with any +# user-specific system configuration files if desired:: # -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_fcstGFS_obsERA_OMI.py:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI.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 +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_OMI.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. ############################################################################## # 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_fcstGFS_obsERA_OMI. This may include the regridded data and daily averaged files. In addition, the phase diagram plots will be generated and the output location can be specified as OMI_PLOT_OUTPUT_DIR. If it is not specified, plots will be sent to model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/plots (relative to **OUTPUT_BASE**). +# 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}/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/plots. Phase +# diagram plots will be generated and will include 2 files:: +# +# * fcst_OMI_comp_phase.png +# * obs_OMI_comp_phase.png +# +# If the pre-processing steps are turned on, the output will include the regridded data and daily averaged files. ############################################################################## # Keywords @@ -133,12 +185,13 @@ # # * S2SAppUseCase # * S2SMJOAppUseCase +# * UserScriptUseCase # * RegridDataPlaneUseCase # * PCPCombineUseCase +# * METdataioUseCase # * METcalcpyUseCase # * METplotpyUseCase # # Navigate to :ref:`quick-search` to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/s2s_mjo-UserScript_fcstGFS_obsERA_OMI.png' -# diff --git a/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.py b/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.py index 2c95d3031b..e3ac832806 100644 --- a/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.py +++ b/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.py @@ -1,129 +1,174 @@ """ -UserScript: Make OMI plot from calculated MJO indices -===================================================== +UserScript: Make ERA OMI plot from calculated MJO indices +========================================================= -model_applications/ -s2s_mjo/ -UserScript_obsERA_obsOnly_OMI.py +model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none ############################################################################## # Scientific Objective # -------------------- # -# To use Outgoing Longwave Radiation (OLR) to compute the OLR based MJO Index (OMI). Specifically, OMI is computed using OLR data between 20N and 20S. The OLR data are then projected onto Empirical Orthogonal Function (EOF) data that is computed for each day of the year, latitude, and longitude. The OLR is then filtered for 20 - 96 days, and regressed onto the daily EOFs. Finally, it's normalized and these normalized components are plotted on a phase diagram. +# The Madden-Julian Oscillation (MJO) is the largest element of intraseasonal variability in the +# tropics and is characterized by eastward moving regions of enhanced and suppressed rainfall. These +# phases are typically grouped into numbers 1 - 8 based on the geographic location of the enhanced and +# suppressed rainfall. The MJO affects global weather including summer monsoons, tropical cyclone +# development, and sudden stratospheric warming events, and has teleconnections to mid latitude weather +# systems. # +# This use case uses outgoing longwave radiation (OLR) to compute the OLR based MJO Index (OMI), which is +# a convective index of the MJO. OMI is computed for the ERA observations and then displayed on a phase +# diagram to evaluate the model reprentation of this important oscillation. The code for computing OMI +# came from Maria Gehne at PSL. ############################################################################## -# Datasets -# -------- +# Version Added +# ------------- # -# * Forecast dataset: None -# * Observation dataset: ERA Reanlaysis Outgoing Longwave Radiation. +# METplus version 4.1.0 ############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: -# -# * numpy -# * netCDF4 -# * datetime -# * xarray -# * matplotlib -# * scipy -# * pandas +# Datasets +# -------- # -# 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. +# **Forecast:** None # -# 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.: +# **Observation:** ERA Reanlaysis Outgoing Longwave Radiation, 1979 - 2012 # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **EOFs:** Observed OMI EOF1 and EOF2 patterns from the PSL Website (https://psl.noaa.gov/mjo/mjoindex/) # +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the OMI driver which computes OMI and creates a phase diagram. Inputs to the OMI driver include netCDF files that are in MET's netCDF version. In addition, a txt file containing the listing of these input netCDF files is required, as well as text file listings of the EOF1 and EOF2 files. These text files can be generated using the USER_SCRIPT_INPUT_TEMPLATES in the [create_eof_filelist] and [script_omi] sections. Some optional pre-processing steps include using regrid_data_plane to either regrid your data or cut the domain to 20N - 20S. +# This use case calls UserScript twice, first to create a list of EOF files and then to run +# the OMI calculation. In addition, there is one optional pre-processing steps, using +# Regrid-Data-Plane. +# +# This use case requires METcalcpy, METplotpy, and METdataio to run. The METcalcpy scripts accessed include the following: +# +# * metcalcpy/contributed/rmm_omi/compute_mjo_indices.py +# +# The METplotpy scripts accessed include the following: +# +# * metplotpy/contributed/mjo_rmm_omi/plot_mjo_indioces.py +# +# The METdataio scripts accessed include the following: # +# * METreadnc/util/read_netcdf.py ############################################################################## # METplus Workflow # ---------------- -# -# The OMI 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 OMI calculation and creating a text file listing of the EOF files, omitting the creation of daily means for the model and the regridding pre-processing steps. However, the configurations for pre-processing are available for user reference. +# +# **Beginning time calculation (VALID_BEG):** 01-01-1979 +# +# **End time calculation (VALID_END):** 12-30-2012 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 hour +# +# This use case does not loop, but the UserScript to create and EOF filelist is run once and the OMI driver script is +# run once. The EOF filelist is done separately since the EOF files are needed for each day of the year while the OMI +# calculation is on a separate time frame. The optional pre-processing step loops by valid time. The optional +# pre-processing step uses Regrid-Data-Plane to cut the observation grid to only include -20 to 20 latitude. This +# omitted step can be turned back on by using the PROCESS_LIST that is commented out in the file: +# +# PROCESS_LIST = RegridDataPlane(regrid_obs_olr), UserScript(create_eof_filelist), UserScript(script_omi) +# +# Settings for the optional pre-processing step can be found in the regrid_obs_olr section of the configuration. +# Data is not provided in the tarball to run this steps, but the configuration is provided for reference on +# how to set up this step. +# +# The Phase diagram plot is created over a different time frame than the calculation, 10-01-2012 to 03-30-2012. ############################################################################## # 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 +# 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_obsERA_obsOnly_OMI.conf. -# The file UserScript_obsERA_obsOnly_OMI/OMI_driver.py runs the python program and -# UserScript_fcstGFS_obsERA_OMI.conf sets the variables for all steps of the OMI use case. # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.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. +# ----------------- # +# There are no MET configuration files used in this use case. + +############################################################################## +# Python Embedding +# ---------------- # +# This use case does not use python embedding ############################################################################## -# Python Scripts +# Python Scripting # ---------------- # -# The OMI driver script orchestrates the calculation of the MJO indices and -# the generation of a phase diagram OMI plot: -# parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI/OMI_driver.py: +# This use case runs the OMI driver which computes OMI and creates a phase diagram. Inputs to the +# OMI driver include netCDF files formatted in MET's netCDF version. In addition, a text file containing +# the listing of these input netCDF files is required, as well as text file listings of the EOF1 and +# EOF2 files. These text files can be generated using the USER_SCRIPT_INPUT_TEMPLATES in the +# [create_eof_filelist] and [script_omi] sections. +# +# For the OMI calculation, the OLR data are then projected onto Empirical Orthogonal Function (EOF) +# data that is computed for each day of the year, latitude, and longitude. The OLR is then filtered +# for 20 - 96 days, and regressed onto the daily EOFs. Finally, it's normalized and these normalized +# components are plotted on a phase diagram. The OMI driver script orchestrates the calculation of the +# MJO indices and the generation of a phase diagram OMI plot. Variables for the OMI calculation are set +# in the [user_env_vars] section of the .conf file. # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI/OMI_driver.py +# .. dropdown:: parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI/OMI_driver.py # +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI/OMI_driver.py ############################################################################## # Running METplus # --------------- # -# This use case is run in the following ways: -# -# 1) Passing in UserScript_obsERA_obsOnly_OMI.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.conf -c /path/to/user_system.conf +# Pass the use case configuration file to the run_metplus.py script along with any +# user-specific system configuration files if desired:: # -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_obsERA_obsOnly_OMI.py:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI.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 +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_obsERA_obsOnly_OMI.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. ############################################################################## # 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_obsERA_obsOnly_OMI. This may include the regridded data and daily averaged files. In addition, the phase diagram plots will be generated and the output location can be specified as OMI_PLOT_OUTPUT_DIR. If it is not specified, plots will be sent to model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI/plots (relative to **OUTPUT_BASE**). +# 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}/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/plots. +# A Phase diagram plots will be generated:: +# +# * obs_OMI_comp_phase.png +# +# If the pre-processing steps are turned on, the output will include the regridded data and daily averaged files. ############################################################################## # Keywords @@ -135,8 +180,11 @@ # * S2SMJOAppUseCase # * RegridDataPlaneUseCase # * PCPCombineUseCase +# * UserScriptUseCase +# * METdataioUseCase +# * METcalcpyUseCase +# * METplotpyUseCase # # Navigate to :ref:`quick-search` to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/s2s_mjo-UserScript_obsERA_obsOnly_OMI.png' -# diff --git a/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram.py b/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram.py index a877bd4d10..39c6f880fb 100644 --- a/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram.py +++ b/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram.py @@ -15,7 +15,9 @@ # Scientific Objective # -------------------- # -# To produce a phase diagram using either OLR based MJO Index (OMI) or the Real-time Multivariate MJO index (RMM) +# Phase diagrams are used to Indices for MJO and QBO. This use case produces a +# phase diagram using either OLR based MJO Index (OMI) or the Real-time Multivariate +# MJO index (RMM) ############################################################################## # Version Added @@ -27,77 +29,85 @@ # Datasets # -------- # -# * Forecast dataset: None. -# * Observation dataset: ERA Reanlaysis Outgoing Longwave Radiation. - -############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: -# -# * numpy -# * netCDF4 -# * datetime -# * xarray -# * matplotlib -# * scipy -# * 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. +# **Forecast:** None # -# 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.: +# **Observation:** ERA Reanlaysis Outgoing Longwave Radiation # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **Climatology:** None # +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the Phase Diagram driver which and creates a phase diagram. Inputs to the driver are a text file containing the following columns, yyyy,mm,dd,hh,pc1,pc2,amp for OMI, or yyyy,mm,dd,pc1,pc2,phase,amp,source for RMM. -# +# This use case runs UserScript twice, once to create a text file containing a listing +# of input files and then to create a Phase Diagram. ############################################################################## # METplus Workflow # ---------------- # -# The Phase diagram 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. It creates the phase diagram plot and a text file listing of the valid times to use in creating the plots. +# **Beginning time (INIT_BEG):** 2012-01-01 +# +# **End time (INIT_END):** 2012-03-31 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 hour +# +# The UserScript that creates a filelist is run once for each valid time, while the UserScript to create +# a phase diagram is run only once. It creates a phase diagram plot using the input files. Variables for +# the phase diagram are set in the [user_env_vars] section of the .conf file. ############################################################################## # 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_obsERA_obsERA_OMI.conf. -# The file UserScript_obsERA_obsOnly_PhaseDiagram/PhaseDiagram_driver.py runs the python -# program and UserScript_obsERA_obsOnly_PhaseDiagram.conf sets the variables for all steps -# of the use case. +# 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_obsERA_obsOnly_PhaseDiagram.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram.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. +# There are no MET configuration files in this use case. + +############################################################################### +# Python Embedding +# ---------------- # +# This use case does not use python embedding. ############################################################################## -# Python Scripts -# ---------------- +# User Scripting +# -------------- # -# The phase diagram driver script orchestrates the generation of a phase diagram plot: -# parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_OMI/PhaseDiagram_driver.py: +# The first UserScript creates a listing of text file (save_inpput_file_txt). The second, +# PhaseDiagram_driver.py orchestrates the generation of a phase diagram plot. Inputs to the +# phase diagram driver are a text file containing the following columns, yyyy,mm,dd,hh,pc1,pc2,amp for OMI, +# or yyyy,mm,dd,pc1,pc2,phase,amp,source for RMM. # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/PhaseDiagram_driver.py -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/save_input_files_txt.py +# .. dropdown:: parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/save_input_files_txt.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/save_input_files_txt.py # +# .. dropdown:: parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/PhaseDiagram_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/PhaseDiagram_driver.py ############################################################################## # Running METplus @@ -114,7 +124,16 @@ # 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_obsERA_obsOnly_PhaseDiagram. This may include the regridded data and daily averaged files. In addition, the phase diagram plots will be generated and the output location can be specified as PHASE_DIAGRAM_PLOT_OUTPUT_DIR. If it is not specified, plots will be sent to model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/plots (relative to **OUTPUT_BASE**). +# 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}/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_PhaseDiagram/plots +# The output is one plot:: +# +# * RMM_phase_diagram.png ############################################################################## # Keywords @@ -125,9 +144,9 @@ # # * S2SAppUseCase # * S2SMJOAppUseCase +# * UserScriptUseCase # * METplotpyUseCase # # Navigate to :ref:`quick-search` to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/s2s_mjo-UserScript_obsERA_obsOnly_PhaseDiagram.png' -# diff --git a/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.py b/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.py index 5475735876..36886e1a62 100644 --- a/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.py +++ b/docs/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.py @@ -1,61 +1,112 @@ """ -UserScript: Make RMM plots from calculated MJO indices -====================================================== +UserScript: Make ERA RMM plots from calculated MJO indices +========================================================== -model_applications/ -s2s_mjo/ -UserScript_obsERA_obsOnly_RMM.py +model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none ############################################################################## # Scientific Objective # -------------------- # -# To compute the Real-time Multivariate MJO Index (RMM) using Outgoing Longwave Radiation (OLR), 850 hPa wind (U850), and 200 hPa wind (U200). Specifically, RMM is computed using OLR, U850, and U200 data between 15N and 15S. Anomalies of OLR, U850, and U200 are created using a harmonic analysis, 120 day day mean removed, and the data are normalized by normalization factors (generally the square root of the average variance) The anomalies are projected onto Empirical Orthogonal Function (EOF) data. The OLR is then filtered for 20 - 96 days, and regressed onto the daily EOFs. Finally, it's normalized and these normalized components are plotted on a phase diagram and timeseries plot. +# The Madden-Julian Oscillation (MJO) is the largest element of intraseasonal variability in the +# tropics and is characterized by eastward moving regions of enhanced and suppressed rainfall. These +# phases are typically grouped into numbers 1 - 8 based on the geographic location of the enhanced and +# suppressed rainfall. The MJO affects global weather including summer monsoons, tropical cyclone +# development, and sudden stratospheric warming events, and has teleconnections to mid latitude weather +# systems. # +# This use case uses anomalies of outgoing longwave radiation (OLR), 850 hPa wind (U850), and 200 hPa +# wind (U200) to compute the Real-time Multivariate MJO Index (RMM). In contrast to OMI, which is a +# convective index of MJO, RMM is a dynamical index. The code for computing RMM came from Maria +# Gehne at the NOAA Physical Sciences Laboratory (PSL). + +############################################################################## +# Version Added +# ------------- +# +# METplus version 4.1.0 ############################################################################## # Datasets # -------- # -# * Forecast dataset: None -# * Observation dataset: ERA Reanlaysis Outgoing Longwave Radiation, 850 hPa wind and 200 hPa wind +# **Forecast:** None +# +# **Observation:** ERA Reanlaysis Outgoing Longwave Radiation, 850 hPa wind and 200 hPa wind, 2000 - 2002 +# +# **EOFs:** EOF patterns for OLR, U850, and U200 from Matthew Wheeler +# +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## -# External Dependencies -# --------------------- -# -# You will need to use a version of Python 3.6+ that has the following packages installed:: +# METplus Components +# ------------------ # -# * numpy -# * netCDF4 -# * datetime -# * xarray -# * matplotlib -# * scipy -# * pandas +# This use case calls UserScript 5 times and Regrid-Data-Plane three times. The UserScript calls run +# the harmonic pre-processing on all three variables, create a filelist, and run the RMM calculation. +# There are four optional pre-processing steps. # -# 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. +# This use case requires METcalcpy, METplotpy, and METdataio to run. The METcalcpy scripts accessed include the following: # -# 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.: +# * metcalcpy/contributed/rmm_omi/compute_mjo_indices.py # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# The METplotpy scripts accessed include the following: # - -############################################################################## -# METplus Components -# ------------------ +# * metplotpy/contributed/mjo_rmm_omi/plot_mjo_indioces.py # -# This use case runs the RMM driver which computes first computes anomalies of outgoing longwave raidation, 850 hPa wind and 200 hPa wind. Then, it regrids the data to 15S to 15N. Next, RMM is computed and a phase diagram, time series, and EOF plot are created. Inputs to the RMM 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 OLR, u850 and u200 is required. Some optional pre-processing steps include using pcp_combine to compute daily means and the mean daily annual cycle for the data. +# The METdataio scripts accessed include the following: # +# * METreadnc/util/read_netcdf.py ############################################################################## # METplus Workflow # ---------------- -# The RMM 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 creation of anomalies, regridding, and RMM calculation, omitting the caluclation of daily means and the mean daily annucal cycle pre-processing steps. However, the configurations for pre-processing are available for user reference. # +# **Beginning time (VALID_BEG):** 01-01-2000 +# +# **End time (VALID_END):** 12-30-2002 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 hour +# +# # The UserScript calls do not loop, but are each run once. The first call creates a list of +# the mean daily annual data files for OLR, U850, and U200. It is done separately since the mean +# daily annual files span across all years whereas the RMM calculation can proceed on a different +# time frame. The second, third, and fourth calls to UserScript run the pre-processing to compute +# anomalies OLR, U850, and U200 using a harmonic analysis program in python. Then, RegridDataPlane is +# run for all valid times for the 3 variables. This step cuts the grid to only include -15 to 15 latitude. +# Finally, the last (fifth) call to UserScript runs the RMM calculation once on the observations. +# +# There are four optional pre-processing steps loop by valid time with different timing settings needed for +# the different steps. These steps are turned off due to data size and processing time. Two of the steps are +# calls to Pcp-Combine to compute the mean daily annual data for OLR, wind (U850 and U200). The other two steps +# also call Pcp-Combine but these compute daily means for OLR and wind. These omitted steps can be turned back +# on by using the PROCESS_LIST that is commented out in the file: +# +# PROCESS_LIST = PcpCombine(mean_daily_annual_cycle_obs_wind), PcpCombine(mean_daily_annual_cycle_obs_olr), PcpCombine(daily_mean_obs_wind), PcpCombine(daily_mean_obs_olr), UserScript(create_mda_filelist), UserScript(harmonic_anomalies_olr), UserScript(harmonic_anomalies_u850), UserScript(harmonic_anomalies_u200), RegridDataPlane(regrid_obs_olr), RegridDataPlane(regrid_obs_u850), RegridDataPlane(regrid_obs_u200), UserScript(script_rmm) +# +# Settings for the optional pre-processing steps can be found in the respective sections of the configuration, +# mean_daily_annual_cycle_obs_wind, mean_daily_annual_cycle_obs_olr, daily_mean_obs_wind, and daily_mean_obs_olr. +# Data is not provided in the tarball to run these steps, but the configurations is provided for reference on how +# to set up these calculations. +# +# The Phase diagram and timeseries plots are created over a different time frame, 01-01-2002 +# to 12-30-2002 for both plots. ############################################################################## # METplus Configuration @@ -64,87 +115,122 @@ # 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_obsERA_obsOnly_RMM.conf. -# The file UserScript_obsERA_obsOnly_RMM/RMM_driver.py runs the python program and -# UserScript_obsERA_obsOnly_RMM.conf sets the variables for all steps of the RMM use case. # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.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. -# +# ----------------- # +# There are no MET configuration files used in this use case. ############################################################################## -# Python Scripts +# Python Embedding # ---------------- # -# The RMM driver script orchestrates the calculation of the MJO indices and -# the generation of three RMM plots: -# parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/RMM_driver.py: -# The harmonic anomalies script creates anomalies of input data using a harmonic analysis: -# parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/compute_harmonic_anomalies.py -# -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/RMM_driver.py -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/compute_harmonic_anomalies.py -# +# This use case does not use Python embedding. ############################################################################## -# Running METplus -# --------------- +# User Scripting +# -------------- # -# This use case is run in the following ways: +# There are two Python scripts used in this use case. The RMM driver script (RMM_driver.py) +# orchestrates the calculation of the MJO indices and the generation of three RMM plots. The +# calculation proceeds using OLR, U850, and U200 data between 15N and 15S. The 120 day mean is first +# removed and the data are normalized by normalization factors (generally the square root of the +# average variance). The anomalies are projected onto Empirical Orthogonal Function (EOF) data. The +# OLR is then filtered for 20 - 96 days, and regressed onto the daily EOFs. Finally, it's normalized +# and these normalized components are plotted on a phase diagram and timeseries plot. # -# 1) Passing in UserScript_obsERA_obsOnly_RMM.conf then a user-specific system configuration file:: +# The anomalies are created using a harmonic analysis for OLR, U850, and U200 with the Python script +# compute_harmonic_anomalies.py. Input to the harmonic analysis script include a text file containing the +# list of input files, the daily mean variable name, mean daily average varable name, output directory and output file +# basename. These are defined in the [harmonic_anomalies_olr], [harmonic_anomalies_u850], and harmonic_anomalies_u200] +# sections of the configuration file. Additional variables for the RMM calculation and harmonic analysis are set in the +# [user_env_vars] section of the .conf file. # -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.conf -c /path/to/user_system.conf +# .. dropdown:: parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/RMM_driver.py # -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_obsERA_obsOnly_RMM.py:: +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/RMM_driver.py # -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM.conf +# .. dropdown:: parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/compute_harmonic_anomalies.py # -# The following variables must be set correctly: +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/compute_harmonic_anomalies.py + +############################################################################## +# Running METplus +# --------------- # -# * **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 +# Pass the use case configuration file to the run_metplus.py script along with any +# user-specific system configuration files if desired:: # -# Example User Configuration File:: +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_obsERA_obsOnly_RMM.conf /path/to/user_system.conf # -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y +# See :ref:`running-metplus` for more information. # ############################################################################## # 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_obsERA_obsOnly_RMM. This may include the regridded data and daily averaged files. In addition, three plots will be generated, a phase diagram, time series, and EOF plot, and the output location can be specified as RMM_PLOT_OUTPUT_DIR. If it is not specified, plots will be sent to model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/plots (relative to **OUTPUT_BASE**). -# +# 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}/model_applications/s2s_mjo/UserScript_obsERA_obsOnly_RMM/plots. The +# output may include the regridded data and daily averaged files if those steps are turned on. Three output +# plots will be generated, a phase diagram, time series, and EOF plot:: +# +# * obs_RMM_comp_phase.png +# * obs_RMM_time_series.png +# * RMM_EOFs.png +# +# Output from the Harmonic analysis pre-processing includes multiple files, one for each variable and day in the +# following format:: +# +# * ERA_OLR_anom_000000L_YYYYMMDD_000000V.nc +# * ERA_U200_anom_000000L_YYYYMMDD_000000V.nc +# * ERA_U850_anom_000000L_YYYYMMDD_000000V.nc +# +# One variabe is output in each of the above files (not including the lat/lon fields). Those variables are:: +# +# * olr_anom(lat, lon) +# * U_P200_mean_anom(lat, lon) +# * U_P850_mean_anom(lat, lon) +# +# Output from the regridding also includes one file for each day and variable with the following format:: +# +# * ERA_OLR_YYYYMMDD.nc +# * ERA_U200_YYYYMMDD.nc +# * ERA_U850_YYYYMMDD.nc +# +# One variabe is output in each of the regriddwed files (not including the lat/lon fields). Those variables +# are:: +# +# * OLR_anom(lat, lon) +# * U_P200_anom(lat, lon) +# * U_P850_anom(lat, lon) ############################################################################## # Keywords # -------- # -# # .. note:: # # * S2SAppUseCase # * S2SMJOAppUseCase +# * UserScriptUseCase # * NetCDFFileUseCase # * RegridDataPlaneUseCase # * PCPCombineUseCase +# * METdataioUseCase # * METcalcpyUseCase # * METplotpyUseCase # # Navigate to :ref:`quick-search` to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/s2s_mjo-UserScript_obsERA_obsOnly_RMM.png' -# diff --git a/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py b/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py index 29d9f26d7c..57a64fb562 100644 --- a/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py +++ b/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py @@ -1,61 +1,108 @@ """ -Bias Plot on Zonal Mean Wind and Temperature: UserScript, Series-Analysis -========================================================================== +UserScript and SeriesAnalysis: Compute Zonal Mean Bias and Create Plots for Temperature and Wind +================================================================================================ -model_applications/ -s2s_stratosphere/ -UserScript_fcstGFS_obsERA_StratosphereBias.py +model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # -# This use case calls functions in METcalcpy to create zonal and meridonial -# 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. +# Many common modes of variability in the troposphere have stratospheric teleconnection +# pathways. Thus, the stratosphere can be a source of predictability for surface weather. +# However, the predictive skill gained from the stratosphere can be limited by biases in +# the representation of these stratospheric processes. This use case investigates +# stratospheric biases in temperature and wind. Model biases are plotted for a month time +# period based on latitude and pressure between 100 and 1 hPa. +# +# In addition, this use case also demonstrates how to read semi-structured grids into +# MET. Specifically zonal mean data (on a grid of latitude and pressure) is read into +# Series-Analysis in the second step of this use case. + +############################################################################## +# Version Added +# ------------- # +# METplus version 6.0 ############################################################################## # Datasets # -------- # -# GFS 24 hour forecasts: GFS_2018_02_24h.nc -# ERA: ERA_2018_02.nc +# **Forecast:** GFS 24 hour forecasts for February 2018 +# +# **Observation:** ERA reanalysis for February 2018 # +# **Climatology:** None +# +# **Location:** All of the input data required for this use case can be +# found in a sample data tarball. Each use case category will have +# one or more sample data tarballs. It is only necessary to download +# the tarball with the use case’s dataset and not the entire collection +# of sample data. Click here to access the METplus releases page and download sample data +# for the appropriate release: https://github.com/dtcenter/METplus/releases +# This tarball should be unpacked into the directory that you will +# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information. ############################################################################## # METplus Components # ------------------ # -# This use case runs the UserScript wrapper tool to run a user provided script, -# 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. +# This use case calls UserScript first, Series-Analysis, and then UserScript +# a second time. METcalcpy, METplotpy, and METdataio are needed for this use case to run. +# The METcalcpy scripts accessed include the following: +# +# * metcalcpy/pre_processing/directional_means.py +# +# The METplotpy scripts accessed include the following: # +# * metplotpy/stratosphere_diagnostics/stratosphere_plots.py +# +# The METdataio scripts accessed include the following: +# +# * METreadnc/util/read_netcdf.py + ############################################################################## # METplus Workflow # ---------------- # -# This use case does not loop but plots the entire time period of data -# -# UserScript: Computes zonal and meridional means -# Series-Analysis: Computes the bias on zonal mean wind and temperature -# UserScript: Creates bias plots +# **Beginning time (INIT_BEG):** 02-01-2018 +# +# **End time (INIT_END):** 02-28-2018 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 30 days # +# **Sequence of forecast leads to process (LEAD_SEQ):** 24 hours +# +# This use case does not loop. The two calls to UserScript are run once. Series- +# Analysis is also run once. The first call to UserScript runs zonal_mean_driver.py. +# This script computes zonal and meridional mean data from the directional_means program in +# METplotpy. Then, Series-Analysis is run on the zonal mean output to compute +# continuous statistics. Finally, the second call to UserScript runs bias_plot_driver.py +# which creates bias plots for temperature and wind. +# +# METcalcpy 3.0.0 or higher, METplotpy 3.0.0 or higher, and METdataio 2.1 or higher are needed +# for this use case. ############################################################################## # 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/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf -# ############################################################################# # MET Configuration @@ -69,65 +116,107 @@ # 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` # -# **SeriesAnalysisConfig_wrapped** -# -# .. note:: See the :ref:`Series-Analysis MET Configuration` 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 +# .. dropdown:: SeriesAnalysisConfig_wrapped # +# .. literalinclude:: ../../../../parm/met_config/SeriesAnalysisConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case uses a Python embedding script to read in the zonal mean data to Series-Analysis +# This use case uses a Python embedding script to read in the semi-structured zonal mean data to Series-Analysis. Inputs to +# this script include the filename to be read in, variable name, and the axis over which the mean is taken. The script +# returns a numpy array containing the zonal mean data (semi-structured grid). # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias/read_met_axis_mean.py +# .. dropdown:: read_met_axis_mean.py # +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias/read_met_axis_mean.py + +############################################################################## +# User Scripting +# -------------- +# +# This use case runs both zonal_mean_driver.py and bias_plot_driver.py. The zonal mean driver takes an input netCDF +# file and the time variable. Then it computes zonal and meridional means for u and T from directional_means.py in +# METcalcpy. It writes the zonal mean data to output netCDF files. +# +# The bias plot driver reads output netCDF files from Series-Analysis and creates plots of the bias over +# latitude and pressure level. Inputs to both of the Python scripts can be found in the [user_env_vars] +# section of the UserScript_fcstGFS_obsERA_StratosphereBias.conf file +# +# .. dropdown:: parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias/zonal_mean_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias/zonal_mean_driver.py +# +# .. dropdown:: parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias/bias_plot_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias/bias_plot_driver.py ############################################################################## # Running METplus # --------------- # -# This use case can be run two ways: +# 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/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf /path/to/user_system.conf +# +# See :ref:`running-metplus` for more information. + +############################################################################## +# Expected Output +# --------------- # -# 1) Passing in UserScript_fcstGFS_obsERA_StratosphereBias.conf, -# then a user-specific system configuration file:: +# A successful run will output the following both to the screen and to the logfile:: # -# 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 +# INFO: METplus has successfully finished running. # -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_fcstGFS_obsERA_StratosphereBias.conf: +# 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}/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar +# The output includes the netCDF zonal mean files for the forecast and observations, netCDF output +# from Series-Analysis, and bias plots. There are two bias plots output:: # -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereBias.conf +# * plots/GFS_ERA_ME_2018_02_zonal_mean_T.png +# * plots/GFS_ERA_ME_2018_02_zonal_mean_U.png # -# 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: +# The statistics output from Series-Analysis output is two netCDF files, one for temperature and one for wind:: # -# * **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 +# * SeriesAnalysis/zonal_mean_T_stats_2018_02.nc +# * SeriesAnalysis/zonal_mean_U_stats_2018_02.nc # -# and for the [exe] section, you will need to define the location of NON-MET executables. -# No executables are required for performing this use case. +# There are 7 variable fields present in the Series-Analysis output netCDF files (not +# including the lat/lon fields). Those variables are:: # -# Example User Configuration File:: +# * level(level) +# * n_series +# * series_cnt_TOTAL(lat, level) +# * series_cnt_ME(lat, level) +# * series_cnt_RMSE(lat, level) +# * series_cnt_FBAR(lat, level) +# * series_cnt_OBAR(lat, level) # -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y +# Text files with a listing of the files input to Series-Analysis are also output:: # +# * SeriesAnalysis/series_analysis_files_fcst_init_ALL_valid_ALL_lead_ALL.txt +# * SeriesAnalysis/series_analysis_files_obs_init_ALL_valid_ALL_lead_ALL.txt # - -############################################################################## -# Expected Output -# --------------- +# The zonal mean output includes 28 files for the forecast +# and observations, one for each day. The file format for February 1 is:: # -# A successful run will output the following both to the screen and to the logfile:: +# * FCST/FCST_zonal_mean_U_T_20180201_000000.nc +# * OBS/OBS_zonal_mean_U_T_20180201_000000.nc # -# INFO: METplus has successfully finished running. +# There are 4 variable fields present in the zonal mean netCDF file (not including the +# latitude and pressure fields). Those variables are:: # +# * time +# * u(pres, latitude) +# * T(pres, latitude) +# * lead_time ############################################################################## # Keywords @@ -138,7 +227,9 @@ # * UserScriptUseCase # * S2SAppUseCase # * S2SStratosphereAppUseCase +# * UserScriptUseCase # * SeriesAnalysisUseCase +# * METdataioUseCase # * METcalcpyUseCase # * METplotpyUseCase # diff --git a/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py b/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py index e4c8af1857..aeb178ffa1 100644 --- a/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py +++ b/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py @@ -1,126 +1,162 @@ """ -Bias Plot on Polar Cap Temperature and Polar Vortex U: UserScript, Stat-Analysis -================================================================================ +UserScript and StatAnalysis: Compute Polar Cap Temperature and Polar Vortex U and Create Plots +============================================================================================== -model_applications/ -s2s_stratosphere/ -UserScript_fcstGFS_obsERA_StratospherePolar.py +model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # +# Many common modes of variability in the troposphere have stratospheric teleconnection +# pathways. Thus, the stratosphere can be a source of predictability for surface weather. # This use case calls functions in METcalcpy to create polar cap temperature # and polar vortex wind. It then runs Stat-Analysis on the output zonal means # and creates a contour plot of bias in lead time and pressure level. + +############################################################################## +# Version Added +# ------------- # +# METplus version 6.0 ############################################################################## # Datasets # -------- # -# * Forecast dataset: GFS Forecast U and T at multiple pressure levels -# * Observation dataset: ERA Reanlaysis U and T at multiple pressure levels +# **Forecast:** GFS Forecast U and T at multiple pressure levels +# +# **Observation:** ERA Reanlaysis U and T at multiple pressure levels # -# Data for this use case is not contained in the sample data tar files due to -# its size. Rather, it is stored as additional data in a separate tar file. +# **Climatology:** None # +# **Location:** Data for this use case is not contained in the sample data tar files due to +# its size. Rather, it is stored as additional data in a separate tar file, named +# additional_data_UserScript_fcstGFS_obsERA_StratosphereQBO.tar.gz and can be +# downloaded at https://dtcenter.ucar.edu/dfiles/code/METplus/METplus_Data/v6.0/. ############################################################################## # METplus Components # ------------------ # -# This use case runs the UserScript wrapper tool to run a user provided script, -# in this case, polar_t_u_driver.py which output data into MET's matched pair format. -# It then runs Stat-Analysis to compute the bias and RMSE, and another UserScript, -# bias_rmse_plot_driver.py, to create the plots. +# This use case runs UserScript twice and Stat-Analysis once. The UserScripts compute +# polar cap temperature and polar vortex wind and create plots. METcalcpy, METplotpy, +# and METdataio are needed for this use case. The METcalcpy scripts accessed include +# the following: # +# * metcalcpy/pre_processing/directional_means.py +# +# * metcalcpy/util/write_mpr.py +# +# The METplotpy scripts accessed include the following: +# +# * metplotpy/contributed/stratosphere_diagnostics/stratosphere_plots.py +# +# The METdataio scripts accessed include the following: +# +# * METreadnc/util/read_netcdf.py + ############################################################################## # METplus Workflow # ---------------- # -# This use case loops over lead times for the first UserScript and Stat-Analysis, -# and the plotting proceeds over the entire time period -# -# UserScript: Computes polar cap temperature and polar vortex U -# Stat-Analysis: Computes ME and RMSE on polar cap temperature and polar vortex U -# UserScript: Creates ME and RMSE plots +# **Beginning time (VALID_BEG):** 2018-02-01 +# +# **End time (VALID_END):** 2018-02-28 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 30 days # +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 - 384 hours at 24 hour intervals +# +# This use case loops over lead times for the first UserScript and Stat-Analysis, +# and the second UserScript runs once over the entire time period. The first UserScript +# runs polar_t_u_driver.py which computes polar cap temperature and polar vortex wind +# and outputs that data to .stat files in MET's matched pair format. Then, Stat-Analysis +# is run to compute bias and RMSE on the polar cap temperature and polar vortex wind. +# Finally, the second UserScript runs the bias_rmse_plot_driver.py which creates plots +# of bias and RMSE over lead time and pressure level. +# +# METcalcpy 3.0.0 or higher, METplotpy 3.0.0 or higher, and METdataio 2.1 or higher are needed +# for this use case ############################################################################## # 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/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.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` for more details. +# METplus sets environment variables based on user settings in the METplus +# configuration file. See :ref:`How METplus controls MET config file settings` 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: +# 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` # -# **STATAnalysisConfig_wrapped** -# -# .. note:: See the :ref:`Series-Analysis MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: -# -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped +# .. dropdown:: STATAnalysisConfig_wrapped # +# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case does not use python embedding -# +# This use case does not use python embedding. ############################################################################## -# Running METplus -# --------------- -# -# This use case can be run two ways: -# -# 1) Passing in UserScript_fcstGFS_obsERA_StratospherePolar.conf, -# then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.conf -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in UserScript_fcstGFS_obsERA_StratospherePolar.conf: +# User Scripting +# -------------- # -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.conf +# There are two Python scripts in the is use case. The first, polar_t_u_driver.py reads in netCDF files for the +# forecast and observations and computes zonal means for temperature and wind. Then, polar cap temperature is +# computed by taking the meridional mean between 60 and 90 latitude, while polar vortex u is computed by taking +# the meridional mean between 50 and 80 latitude. This data is written to output files in MET's matched pair +# format. # -# 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: +# The second python script, bias_rmse_plot_driver.py reads in the output of Stat-Analysis and creates plots of bias +# and RMSE for polar cap temperature and polar vortex u. Variables input to this script are given in the +# [user_env_vars] section of the configuration file. # -# * **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 -# -# and for the [exe] section, you will need to define the location of NON-MET executables. -# No executables are required for performing this use case. +# .. dropdown:: parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar/polar_t_u_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar/polar_t_u_driver.py # -# Example User Configuration File:: +# .. dropdown:: parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar/bias_rmse_plot_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar/bias_rmse_plot_driver.py + +############################################################################## +# Running METplus +# --------------- # -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y +# 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/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. + ############################################################################## # Expected Output @@ -130,6 +166,27 @@ # # 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}/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratospherePolar +# The output includes matched pair files, one for each lead time and valid time in mpr directory. +# The output files have the following format:: +# +# * polar_cap_T_stat_GFS_HH0000L_YYYYMMDD_000000V.stat +# * polar_cap_T_stat_GFS_HHH0000L_YYYYMMDD_000000V.stat +# +# Additionally, CNT statistics will be output to the StatAnalysis directory with one file for each lead +# time and variable. The files have the following format:: +# +# * GFS_ERA_20180201_20180228_HH0000L_PolarCapT_CNT.stat +# * GFS_ERA_20180201_20180228_HH0000L_PolarVortexU_CNT.stat +# +# Four plot are also output to the plots directory:: +# +# * ME_2018_02_polar_cap_T.png +# * ME_2018_02_polar_vortex_U.png +# * RMSE_2018_02_polar_cap_T.png +# * RMSE_2018_02_polar_vortex_U.png ############################################################################## # Keywords @@ -137,10 +194,11 @@ # # .. note:: # -# * UserScriptUseCase # * S2SAppUseCase # * S2SStratosphereAppUseCase +# * UserScriptUseCase # * StatAnalysisUseCase +# * METdataioUseCase # * METcalcpyUseCase # * METplotpyUseCase # diff --git a/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py b/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py index 79dacccb40..5346b56c34 100644 --- a/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py +++ b/docs/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py @@ -1,123 +1,170 @@ """ -QBO Phase plots and QBO Index: UserScript, Stat-Analysis -================================================================================ +UserScript and StatAnalysis: Compute QBO Phase Plots and QBO Index +================================================================== -model_applications/ -s2s_stratosphere/ -UserScript_fcstGFS_obsERA_StratosphereQBO.py +model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.py """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # -# Many common modes of variability in the troposphere have stratospheric teloconnection +# Many common modes of variability in the troposphere have stratospheric teleconnection # pathways. This use case performs evaluation of the Quasi-biennial Oscillation (QBO), -# one of the key players of stratosphereic varability, using several different calculations -# and plots. Specifically, phase diagrams can be used to compare the QBO plhase progression +# one of the key players of stratospheric variability, using several different calculations +# and plots. Specifically, phase diagrams can be used to compare the QBO phase progression # between the model and observations. Additionally, timeseries of U at 30 and 50mb are also # plotted to compare the speed of propagation of QBO in the model versus observations. -# Continuous statistics (ME, RMSE, etc.) are calculated for U at 30 and 50mb, and are also +# Continuous statistics (ME, RMSE, etc.) are calculated for U at 30 and 50mb and are also # computed separately to evaluate QBO in the easterly phase versus the westerly phase. + +############################################################################## +# Version Added +# ------------- # +# METplus version 6.0 ############################################################################## # Datasets # -------- # -# * GFS: 0-24 hour forecasts for 10/2017 - 2/2018 -# * ERA: 30 year climatology for EOFs and 10/2017 - 2/2018 +# **Forecast:** GFS 0-24 hour forecasts for 10/2017 - 2/2018 +# +# **Observation:** ERA 30 year climatology for EOFs and 10/2017 - 2/2018 # -# Data for this use case is not contained in the sample data tar files due to -# its size. Rather, it is stored as additional data in a separate tar file, -# named additional_data_UserScript_fcstGFS_obsERA_StratosphereQBO.tar.gz at -# https://dtcenter.ucar.edu/dfiles/code/METplus/METplus_Data/v6.0/. +# **EOFs:** EOFs computed for 10/1991 - 12/2020 # +# **Location:** Data for this use case is not contained in the sample data tar files +# due to its size. Rather, it is stored as additional data in a separate tar file, +# named additional_data_UserScript_fcstGFS_obsERA_StratosphereQBO.tar.gz and can be +# downloaded at https://dtcenter.ucar.edu/dfiles/code/METplus/METplus_Data/v6.0/. ############################################################################## # METplus Components # ------------------ # -# This use case calls UserScript and StatAnalysis. The UserScript accesses calculation -# in METcalcpy, METplotpy, and METdataio. For it to run, the following versions of those -# repositories are needed, METcalcpy 3.0.0, METplotpy 3.0.0, and METdataio 2.1. +# This use case calls UserScript once and StatAnalysis once. Additionally, METcalcpy, +# METplotpy, and METdataio are required to run. The METcalcpy scripts accessed include +# the following: # +# * metcalcpy/pre_processing/directional_means.py +# +# * metcalcpy/util/write_mpr.py +# +# The METplotpy scripts accessed include the following: +# +# * metplotpy/contributed/stratosphere_diagnostics/stratosphere_plots.py +# +# The METdataio scripts accessed include the following: +# +# * METreadnc/util/read_netcdf.py ############################################################################## # METplus Workflow # ---------------- # -# This use case does not loop but UserScript and StatAnalysis are each run once. -# The UserScript call runs the driver script stratosphere_qbo_driver.py which first -# computes zonal and meridional means using directional_means.py in METcalcpy on U from -# -10 S to 10N latitude. Then, an EOF analysis is performed on this zonal and meridional -# mean data, and two phase diagrams of QBO are created using the plot_qbo_phase_circuits and -# plot_qbo_phase_space functions from stratosphere_plots.py in METplotpy. Additionally the -# zonal and meridional mean at 30 and 50mb are output as time series to matched pair (MPR) -# files using write_mpr.py in METcalcpy and are also plotted as timeseries using the -# plot_u_timeseries function from stratosphere_plots.py in METplotpy. Finally StatAnalysis is -# run on the 30 and 50mb U mpr files to compute the bias (ME). +# **Beginning time (INIT_BEG):** 2018-02-01 +# +# **End time (INIT_END):** 2018-02-28 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 30 days +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0, 3, 6, 9, 12, 15, 18, 21 hours +# +# This use case does not loop but UserScript and StatAnalysis are each run once using data +# from the entire time period. The UserScript call runs stratosphere_qbo_driver.py to compute +# a QBO index. The output QBO index is run through Stat-Analysis to compute the continuous +# statistics. +# +# There is an optional step to calculate EOFs rather than providing an input file. This +# calculation is performed inside qbo_driver.py, but requires building a list of input +# files to use to create EOFs using a call to UserScript. This step is turned off due to +# the length of time it needs to run, but can be turned back on using the PROCESS_LIST that +# is commented out. +# +# PROCESS_LIST = UserScript(create_obs_eofs_filelist), UserScript(compute_plot_qbo), StatAnalysis(qbo_bias) +# +# Other changes needed to calculate EOFs are described in the User Scripting section below. Data is not +# provided for the EOF calculation. # +# METcalcpy 3.0.0 or higher, METplotpy 3.0.0 or higher, and METdataio 2.1 or higher are needed +# for this use case. ############################################################################## # 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 +# then it loads any configuration files passed to METplus via the command line, i.e. # parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.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` for more details. +# METplus sets environment variables based on user settings in the METplus +# configuration file. See :ref:`How METplus controls MET config file settings` 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: +# 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` # -# **StatAnalysisConfig_wrapped** -# -# .. note:: See the :ref:`Stat-Analysis MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: -# -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped +# .. dropdown:: StatAnalysisConfig_wrapped # +# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped ############################################################################## # Python Embedding # ---------------- # # This use case does not use python embedding -# ############################################################################## -# Python Scripting -# ---------------- +# User Scripting +# -------------- # -# This use case runs the stratospher_qbo_driver.py python script. The processing -# performed by the script are detailed in the METplus Workflow section above. +# This use case runs the stratosphere_qbo_driver.py Python script, which first +# computes zonal and meridional means using directional_means.py in METcalcpy on U from +# -10 S to 10N latitude. Then, an EOF analysis is performed on this zonal and meridional +# mean data, and two phase diagrams of QBO are created using the plot_qbo_phase_circuits and +# plot_qbo_phase_space functions from stratosphere_plots.py in METplotpy. Additionally, the +# zonal and meridional mean at 30 and 50mb are output as time series in MET's matched pair +# (MPR) format using write_mpr.py in METcalcpy. They are also plotted as timeseries using the +# plot_u_timeseries function from stratosphere_plots.py in METplotpy. Finally, StatAnalysis is +# run on the 30 and 50mb U mpr files to compute the bias (ME). +# +# Variables input to this script are given in the [user_env_vars] section of the configuration +# file. As mentioned above, the option exists to compute EOFs inside the script. To do this, +# the COMPUTE_EOF_ZONAL_MERIDIONAL_MEAN variable should be set to true, and an input file list +# provided by turning on the UserScipt call for [create_eof_filelist]. # +# .. dropdown:: parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO/stratosphere_qbo_driver.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO/stratosphere_qbo_driver.py ############################################################################## # Running METplus # --------------- # # Pass the use case configuration file to the run_metplus.py script along with any -# user-specific system configuration files if desired: +# user-specific system configuration files if desired:: # # run_metplus.py /path/to/METplus/parm/use_cases/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO.conf /path/to/user_system.conf # # See :ref:`running-metplus` for more information. -# ############################################################################## # Expected Output @@ -127,22 +174,25 @@ # # INFO: METplus has successfully finished running. # -# There should be 4 graphics output to the plot directory in the location set as OUTPUT_DIR -# in the [user_env_vars] section of the configuration file: +# 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}/model_applications/s2s_stratosphere/UserScript_fcstGFS_obsERA_StratosphereQBO +# There should be 4 graphics output to the plot directory:: # # * ERA_GFS_QBO_circuits.png # * ERA5_QBO_PhaseSpace.png # * ERA_GFS_timeseries_30mb_u_201710_201802.png # * ERA_GFS_timeseries_50mb_u_201710_201802.png # -# The name of the output graphics can be changed using PLOT_PHASE_CIRCUITS_OUTPUT_NAME, -# PLOT_PHASE_SPACE_OUTPUT_NAME, PLOT_TIME_SERIES_OUTPUT_NAME_30, and PLOT_TIME_SERIES_OUTPUT_NAME_50 -# also in the [user_env_vars] section. Additionally many matched pair .stat files will be output to -# OUTPUT_DIR/mpr, and tow computed continuous statistics will be output to OUTPUT_DIR/StatAnalysis: +# Additionally matched pair .stat files for each day will be output to the mpr directory. These +# files have the following format:: +# +# * qbo_u_GFS_210000L_YYYYMMDD_000000V.stat +# +# Two computed continuous statistics will be output to the StatAnalysis directory:: # # * GFS_ERA_20171001_20180228_210000L_zonal_wind_byphase_CNT.stat # * GFS_ERA_20171001_20180228_210000L_zonal_wind_CNT.stat -# ############################################################################## # Keywords @@ -150,10 +200,11 @@ # # .. note:: # -# * UserScriptUseCase # * S2SAppUseCase # * S2SStratosphereAppUseCase +# * UserScriptUseCase # * StatAnalysisUseCase +# * METdataioUseCase # * METcalcpyUseCase # * METplotpyUseCase # diff --git a/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.conf b/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.conf index 8fb960e2e0..af0848eb39 100644 --- a/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.conf +++ b/parm/use_cases/model_applications/s2s_mid_lat/UserScript_fcstGFS_obsERA_Blocking.conf @@ -355,7 +355,7 @@ OBS_CBL_PLOT_OUTPUT_NAME = ERA_CBL_avg # IBL plot title and output name IBL_PLOT_TITLE = DJF Instantaneous Blocked Longitude -IBL_PLOT_OUTPUT_NAME = FV3_ERA_IBL_Freq_DJF +IBL_PLOT_OUTPUT_NAME = GFS_ERA_IBL_Freq_DJF # IBL plot legend for forecast and obs IBL_PLOT_OBS_LABEL = ERA Reanalysis diff --git a/parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py b/parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py index 9e1ab61d05..683717cf09 100755 --- a/parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py +++ b/parm/use_cases/model_applications/s2s_mjo/UserScript_fcstGFS_obsERA_OMI/OMI_driver.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """ -Driver Script to Compute RMM index from input U850, U200 and OLR data. Data is averaged from 20S-20N +Driver Script to Compute OMI from input OLR data. Data is averaged from 20S-20N """ import numpy as np