diff --git a/docs/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.py b/docs/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.py index c8fdfcf57e..f9207a5317 100644 --- a/docs/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.py +++ b/docs/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.py @@ -1,11 +1,17 @@ """ + EnsembleStat: Using Python Embedding for Aerosol Optical Depth -============================================================================= +============================================================== -model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS\ -_aod.conf +model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################ # Scientific Objective # -------------------- @@ -14,40 +20,68 @@ # observation data for aersol optical depth (AOD) to an ensemble forecast. # These values can be used to help correct ensemble member deviations from observed values. +############################################################################## +# Version Added +# ------------- +# +# METplus version 4.0 ############################################################################## # Datasets # -------- # -# | **Forecast:** International Cooperative for Aerosol Prediction (ICAP) ensemble netCDF file, 7 members -# | **Observation:** Aggregate netCDF file with MODIS observed AOD field +# **Forecast:** International Cooperative for Aerosol Prediction (ICAP) ensemble netCDF file, 7 members +# +# **Observation:** Aggregate netCDF file with MODIS observed AOD field # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to the METplus releases page and download sample data for the appropriate release: https://github.com/dtcenter/METplus/releases -# | The tarball should be unpacked into the directory that you will set the value of INPUT_BASE. See `Running METplus`_ section for more information. -# | +# **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 utilizes the METplus EnsembleStat wrapper to read in files using Python Embedding -# +# This use case utilizes the METplus EnsembleStat wrapper to read in files using Python Embedding. ############################################################################## # METplus Workflow # ---------------- # -# EnsembleStat is the only tool called in this example. It processes a single run time with seven ensemble members. Three of the members do not have data for the AOD field, so EnsembleStat will only process four of the members for statistics. +# **Beginning time (INIT_BEG):** 201608150000 +# +# **End time (INIT_END):** 201608150000 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 06H # +# **Sequence of forecast leads to process (LEAD_SEQ):** 12H +# +# EnsembleStat is the only tool called in this example. It processes a single run time with seven ensemble members, +# with each ensemble member receiving its own verification. +# Preprocessing of the ensemble forecast data is completed with Python Embedding, which takes 4 inputs: +# the full path to the forecast file, variable name, valid time of verification, and ensemble member number. The script passes +# back the variable field requested to EnsembleStat for verification. A similar process is completed +# for the observation data, which is preprocessed by a separate Python Embedding script which takes 3 inputs: +# the full path to the observation file, group name that contains the variable field, and variable name. +# The script passes back the requested variable field and begins the verification process. +# Three of the ensemble members do not have data for the AOD field, so EnsembleStat +# will only process four of the members for statistics. +# After a successful run, EnsembleStat will create the requested output and its corresponding files. ############################################################################## # 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/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.conf +# 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/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.conf @@ -56,64 +90,74 @@ # 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` # -# .. note:: See the :ref:`EnsembleStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: EnsembleStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/EnsembleStatConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/EnsembleStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case uses two Python embedding scripts to read input data +# This use case uses two Python embedding scripts to read input data: one for +# the forecast ensemble data, and one for the observation data. The script processing +# the ensemble data receives four input arguments: the full path to the forecast file, +# variable name, valid time of verification, and ensemble member number. Since seven ensemble +# members are being verified, this script will run seven times. The processing is very simple, +# with the script grabbing the initialization time from the file name, calculating the lead +# by finding the difference between the valid time argument and the initialization time, grabbing +# the variable name and index corresponding to the ensemble member input value, and then masking bad data +# (anything less than -800) to the expected METplus bad data value of -9999. The latitude and longitude +# variables are also extracted, and all of the information is returned to METplus for +# verification via array and accompanying attribute dictionary. +# +# The second script for observational data behaves very similarly to the ensemble data +# script. The script receives three inputs at runtime: +# the full path to the observation file, group name that contains the variable field, and variable name. +# The requested variable field is extracted from the group name provided at runtime, bad data is +# deemed to be any value less than -800 and reset to METplus' bad value of -9999, and the data +# array is inverted to properly align with METplus' expected orientation. The latitude and longitude +# variables are also extracted, and all of the information is returned to METplus for +# verification via array and accompanying attribute dictionary. # -# parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/forecast_embedded.py +# For more information on the basic requirements to utilize Python Embedding in METplus, +# please refer to the MET User’s Guide section on `Python embedding `_ # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/forecast_embedded.py # -# parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/analysis_embedded.py +# .. dropdown:: parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/forecast_embedded.py # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/analysis_embedded.py +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/forecast_embedded.py # +# .. dropdown:: parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/analysis_embedded.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod/analysis_embedded.py +############################################################################## +# User Scripting +# -------------- +# User Scripting is not used in this use case. ############################################################################## # Running METplus # --------------- # -# It is recommended to run this use case by: -# -# Passing in EnsembleStat_python_embedding.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.conf -c /path/to/user_system.conf -# -# The following METplus configuration variables must be set correctly to run this example.: -# -# * **INPUT_BASE** - Path to directory where sample data tarballs are unpacked (See Datasets section to obtain tarballs). -# * **OUTPUT_BASE** - Path where METplus output will be written. This must be in a location where you have write permissions -# * **MET_INSTALL_DIR** - Path to location where MET is installed locally +# 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/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod.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 -# -# **NOTE:** All of these items must be found under the [dir] section. -# - - +# See :ref:`running-metplus` for more information. ############################################################################## # Expected Output @@ -123,9 +167,10 @@ # # 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 model_applications/air_quality/AOD (relative to **OUTPUT_BASE**) -# and will contain the following files: +# 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/air_quality_and_comp/EnsembleStat_fcstICAP_obsMODIS_aod +# and will contain the following files:: # # * ensemble_stat_aod_20160815_120000V_ecnt.txt # * ensemble_stat_aod_20160815_120000V_ens.nc @@ -135,7 +180,6 @@ # * ensemble_stat_aod_20160815_120000V_rhist.txt # * ensemble_stat_aod_20160815_120000V_ssvar.txt # * ensemble_stat_aod_20160815_120000V.stat -# ############################################################################## # Keywords @@ -153,4 +197,3 @@ # # # sphinx_gallery_thumbnail_path = '_static/air_quality_and_comp-EnsembleStat_fcstICAP_obsMODIS_aod.png' -# diff --git a/docs/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.py b/docs/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.py index 24cd004586..8c3a9d759f 100644 --- a/docs/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.py +++ b/docs/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.py @@ -1,11 +1,17 @@ """ Grid-Stat: CESM and GFS Analysis CONUS Temp -============================================================================ -model_applications/climate/ -GridStat_fcstCESM_obsGFS -_ConusTemp.conf +=========================================== + +model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.conf + """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- @@ -15,13 +21,30 @@ # was developed as part of the NCAR System for Integrated Modeling of the # Atmosphere (SIMA) project. +############################################################################## +# Version Added +# ------------- +# +# METplus version 3.1 + ############################################################################## # Datasets # -------- # -# * Forecast dataset: CESM Surface Temperature Data -# * Observation dataset: GFS Analysis 2m Temperature +# **Forecast:** CESM Surface Temperature Data +# +# **Observation:** GFS Analysis 2m Temperature # +# **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 @@ -34,29 +57,36 @@ # METplus Workflow # ---------------- # -# The grid_stat tool is run for each time. This example loops by initialization -# time. It processes 4 valid times, listed below. +# **Beginning time (INIT_BEG):** 2014080100 +# +# **End time (INIT_END):** 2014080200 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 1 day (86400 seconds) +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 6, 12 +# +# The grid_stat tool is run for each time. This example loops by initialization +# time. It processes 4 valid times, listed below. # # | **Valid:** 2014-08-01_06Z # | **Forecast lead:** 06 -# | -# | **Init:** 2014-08-01_12Z +# +# | **Valid:** 2014-08-01_12Z # | **Forecast lead:** 12 -# | -# | **Init:** 2014-08-02_06Z +# +# | **Valid:** 2014-08-02_06Z # | **Forecast lead:** 06 -# | -# | **Init:** 2014-08-02_12Z +# +# | **Valid:** 2014-08-02_12Z # | **Forecast lead:** 12 -# | ############################################################################## # 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/climate/GridStat_fcstCESM_obsGFS_ConusTemp.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.conf @@ -73,39 +103,34 @@ # 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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # # .. highlight:: bash # .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## -# Running METplus -# --------------- -# -# This use case can be run two ways: -# -# 1) Passing in GridStat_fcstCESM_obsGFS_ConusTemp.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.conf -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in GridStat_fcstCESM_obsGFS_ConusTemp.conf:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/climate/GridStat_fcstCESM_obsGFS_ConusTemp.conf +# Python Embedding +# ---------------- # -# 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: +# This use case does not use Python embedding. + +############################################################################## +# User Scripting +# -------------- # -# * **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 +# This use case does not use additional scripts. + + +############################################################################## +# Running METplus +# --------------- # -# Example User Configuration File:: +# Pass the use case configuration file to the run_metplus.py script along +# with any user-specific system configuration files if desired:: # -# [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/climate/GridStat_fcstCESM_obsGFS_ConusTemp.conf /path/to/user_system.conf # -# **NOTE:** All of these items must be found under the [dir] section. +# See :ref:`running-metplus` for more information. ############################################################################## # Expected Output @@ -116,13 +141,13 @@ # 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 model_applications/climate/CESM_GridStat/grid_stat (relative to **OUTPUT_BASE**) -# and will contain the following files: +# Output for this use case will be found in {OUTPUT_BASE}/model_applications/climate/CESM_GridStat/grid_stat +# and will contain the following files:: # -# grid_stat_CESM_TMP_vs_GFS_ANALYS_060000L_20140801_060000V.stat -# grid_stat_CESM_TMP_vs_GFS_ANALYS_120000L_20140801_120000V.stat -# grid_stat_CESM_TMP_vs_GFS_ANALYS_060000L_20140802_060000V.stat -# grid_stat_CESM_TMP_vs_GFS_ANALYS_120000L_20140802_120000V.stat +# * grid_stat_CESM_TMP_vs_GFS_ANALYS_060000L_20140801_060000V.stat +# * grid_stat_CESM_TMP_vs_GFS_ANALYS_120000L_20140801_120000V.stat +# * grid_stat_CESM_TMP_vs_GFS_ANALYS_060000L_20140802_060000V.stat +# * grid_stat_CESM_TMP_vs_GFS_ANALYS_120000L_20140802_120000V.stat ############################################################################## # Keywords @@ -137,5 +162,6 @@ # # Navigate to the :ref:`quick-search` page to discover other similar use cases. # -# sphinx_gallery_thumbnail_path = '_static/climate-GridStat_fcstCESM_obsGFS_ConusTemp.png' # +# +# sphinx_gallery_thumbnail_path = '_static/climate-GridStat_fcstCESM_obsGFS_ConusTemp.png' diff --git a/docs/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.py b/docs/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.py index d4ee20e41e..c49c2cc783 100644 --- a/docs/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.py +++ b/docs/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.py @@ -1,10 +1,15 @@ """ MODE: CESM and GPCP Asian Monsoon Precipitation ============================================================================ -model_applications/climate/\ -MODE_fcstCESM_obsGPCP_\ -AsianMonsoonPrecip.conf + +model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf + """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none ############################################################################## # Scientific Objective @@ -15,13 +20,30 @@ # output statistics. This was developed as part of the NCAR System for # Integrated Modeling of the Atmosphere (SIMA) project. +############################################################################## +# Version Added +# ------------- +# +# METplus version 3.1 + ############################################################################## # Datasets # -------- # -# * Forecast dataset: CESM Daily Precipitation -# * Observation dataset: GPCP Daily Precipitation +# **Forecast**: CESM Daily Precipitation +# +# **Observation**: GPCP Daily Precipitation +# +# **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 @@ -34,32 +56,38 @@ # METplus Workflow # ---------------- # +# **Beginning time (INIT_BEG):** 2014060100 +# +# **End time (INIT_END):** 2014060200 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 1 day +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 24, 48 +# # The mode tool is run for each time. This example loops by model -# initialization time. It processes 4 valid times, listed below. +# initialization time. It processes two initialization times and two lead times +# for each for a total of 4 valid times, listed below. # -# | **Valid:** 2014-08-02 +# | **Valid:** 2014-06-02_0Z # | **Forecast lead:** 24 -# | # -# | **Init:** 2014-08-03 +# | **Valid:** 2014-06-03_0Z # | **Forecast lead:** 48 -# | # -# | **Init:** 2014-08-03 +# | **Init:** 2014-06-03_0Z # | **Forecast lead:** 24 -# | # -# | **Init:** 2014-08-04 +# | **Init:** 2014-06-04_0Z # | **Forecast lead:** 48 -# | + ############################################################################## # 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/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf +# then it loads any configuration files passed to METplus via the command line, +# parm/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf @@ -78,37 +106,34 @@ # # .. note:: See the :ref:`MODE 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/MODEConfig_wrapped +# .. dropdown:: MODEConfig_wrapped +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/MODEConfig_wrapped + +############################################################################## +# Python Embedding +# ---------------- +# +# This use case does not use Python embedding. + +############################################################################## +# User Scripting +# -------------- +# This use case does not use additional scripts. However, a sample NCL script to plot +# the output is available on the `Sample Analysis Scripts `_ +# page. ############################################################################## # Running METplus # --------------- # -# This use case can be run two ways: -# -# 1) Passing in MODE_fcstCESM_obsGPCP_ConusPrecip.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf:: +# 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/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/climate/MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.conf /path/to/user_system.conf # -# The former method is recommended. Whether you add them to a user-specific configuration file or modify the metplus_config files, the following variables must be set correctly: -# -# * **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 -# -# **NOTE:** All of these items must be found under the [dir] section. +# See :ref:`running-metplus` for more information. ############################################################################## # Expected Output @@ -119,41 +144,65 @@ # 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 model_applications/climate/CESM_MODE (relative to **OUTPUT_BASE**) -# and will contain the following files: -# -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1_cts.txt -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1_obj.nc -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1_obj.txt -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1.ps -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2_cts.txt -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2_obj.nc -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2_obj.txt -# 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2.ps -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1_cts.txt -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.nc -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.txt -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1.ps -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2_cts.txt -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.nc -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.txt -# 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2.ps -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1_cts.txt -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.nc -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.txt -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1.ps -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2_cts.txt -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.nc -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.txt -# 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2.ps -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1_cts.txt -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1_obj.nc -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1_obj.txt -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1.ps -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2_cts.txt -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2_obj.nc -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2_obj.txt -# 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2.ps +# Output for this use case will be found in +# {OUTPUT_BASE}/model_applications/climate/CESM_MODE +# and will contain the following files:: +# +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1_cts.txt +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1_obj.nc +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1_obj.txt +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T1.ps +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2_cts.txt +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2_obj.nc +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2_obj.txt +# * 2014_06_01_000000/mode_000000L_20140602_000000V_000000A_R1_T2.ps +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1_cts.txt +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.nc +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.txt +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T1.ps +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2_cts.txt +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.nc +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.txt +# * 2014_06_01_000000/mode_000000L_20140603_000000V_000000A_R1_T2.ps +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1_cts.txt +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.nc +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1_obj.txt +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T1.ps +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2_cts.txt +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.nc +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2_obj.txt +# * 2014_06_02_000000/mode_000000L_20140603_000000V_000000A_R1_T2.ps +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1_cts.txt +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1_obj.nc +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1_obj.txt +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T1.ps +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2_cts.txt +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2_obj.nc +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2_obj.txt +# * 2014_06_02_000000/mode_000000L_20140604_000000V_000000A_R1_T2.ps +# +# For the netCDF file, 18 variable fields are present (not including the lat/lon fields). +# Those variables are:: +# +# * fcst_raw(lat, lon) +# * fcst_obj_raw(lat, lon) +# * fcst_obj_id(lat, lon) +# * fcst_clus_id(lat, lon) +# * obs_raw(lat, lon) +# * obs_obj_raw(lat, lon) +# * obs_obj_id(lat, lon) +# * obs_clus_id(lat, lon) +# * fcst_conv_radius +# * obs_conv_radius +# * fcst_conv_threshold(fcst_thresh_length) +# * obs_conv_threshold(obs_thresh_length) +# * fcst_variable(fcst_variable_length) +# * obs_variable(obs_variable_length) +# * fcst_level(fcst_level_length) +# * obs_level(obs_level_length) +# * fcst_units(fcst_units_length) +# * obs_units(obs_units_length) +# ############################################################################## # Keywords @@ -171,4 +220,4 @@ # # # sphinx_gallery_thumbnail_path = '_static/climate-MODE_fcstCESM_obsGPCP_AsianMonsoonPrecip.png' -# + diff --git a/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.py b/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.py index 854e15a7a9..915e32340d 100644 --- a/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.py +++ b/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.py @@ -5,6 +5,12 @@ model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- @@ -12,52 +18,79 @@ # This use case captures various statistical measures of two model comparisons # for low and total cloud fractions with different neighborhood # settings for internal model metrics and to aid in future model updates -# + +############################################################################## +# Version Added +# ------------- +# +# METplus version 5.1 ############################################################################## # Datasets # -------- # -# | **Forecast:** Global Forecast System (GFS) -# | **Observations:** ECMWF Reanalysis, Version 5 (ERA5) -# | **Grid:** GPP 17km masking region +# **Forecast:** Global Forecast System (GFS) +# +# **Observation:** ECMWF Reanalysis, Version 5 (ERA5) # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to 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 'Running METplus' section for more information. +# **Climatology:** None # +# **Grid:** GPP 17km masking region +# +# **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 # ------------------ # +# GridStat is the only MET tool called in this use case. # This use case utilizes Python Embedding, which is called using the PYTHON_NUMPY keyword -# in the observation input template settings. The same Python script can processes both forecast and -# observation datasets, but only the observation dataset is not -# set up for native ingest by MET. Two separate forecast fields are verified against two respective observation fields, -# with the Python script being passed the input file, the model name, the variable name being analyzed, -# the initialization and valid times, and a flag to indicate if the field passed is observation or forecast. -# This process is repeated with 3 instance names to GridStat, each with a different setting for regridding, -# neighborhood evaluation, thresholding, output line types, and output prefix names. +# in the observation input template settings. The Python script is passed an input file, +# model name, variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. +# After a successful call, a MET-readable gridded observation dataset is passed back to GridStat for evaluation. ############################################################################## # METplus Workflow # ---------------- # -# GridStat is the only MET tool called in this example. -# It processes the following run time: +# **Beginning time (INIT_BEG):** 2022070312 +# +# **End time (INIT_END):** 2022070312 # -# | **Init:** 2022-07-03 12Z -# | **Forecast lead:** 36 hour +# **Increment between beginning and end times (INIT_INCREMENT):** 12H # -# Because instance names are used, GridStat will run 3 times for this 1 initalization time. +# **Sequence of forecast leads to process (LEAD_SEQ):** 36 +# +# Because instance names are used, GridStat will run 3 times for this 1 initalization time. Each of the +# instance names correspond to different regridding, neighborhood evaluations, thresholding, output line types, and output +# prefix names. For the first GridStat instance, total cloud cover fraction and low cloud cover fraction are verified +# at 10 separate thresholds. The observation dataset is provided via Python Embedding. Various output line types are requested +# and placed in stat files, with a unique output prefix indicating which output are from which GridStat instance. All of the +# evaluation takes place within the masked region, read in via a poly line file. +# For the nbr GridStat instance, the same variables are verified, but the thresholds are expanded to include forecast +# and observation percentiles, ranging from 20 to 80. This instance also creates 4 neighborhoods of varying width using +# a circle definition. The related neighborhood line types are requested as output and a new ouput prefix is used. +# Finally, the prob GridStat instance updates the thresholds for the two variable fields to range from 0 to 1 and +# changes the forecast field to probabilistic space via the FCST_IS_PROB setting. Neighborhoods using the same definitions +# from the nbr instance are used, and the respective line types are requested with a new output prefix for output files +# from this instance. + ############################################################################## # METplus Configuration # --------------------- # # METplus first loads the default configuration file found in parm/metplus_config, -# then it loads any configuration files passed to METplus via the command line: -# parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.conf @@ -74,20 +107,41 @@ # 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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case utilizes 1 Python script to read and process the observation fields. -# parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac/read_input_data.py +# This use case utilizes one Python script to read and process the observation fields to become +# METplus usable. From the configuration file it collects an input file, model name, +# variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. Once the script runs, +# it uses the model name to extract the correct grid definition from the griddedDatasets dictionary, +# and the variable field name is used to extract the correct file variable field name (in combination +# with the name of the model) from the verifVariables dictionary. These are combined into a dictionary +# filled with values and keys used by the rest of the code, specifically set for the model and field +# being used. A Total cloud fraction call results in the field being extracted and set to a 0-100 range +# with a similar behavior for low cloud cover. The grid type associated with each model (determined by the +# griddedDatasets dictionary) helps the script create the grid's corresponding latitude and longitude arrays. +# Finally, the valid and initialization times that were passed at runtime are used to finalize the attrs dictionary +# and the dataset is passed back to METplus for evaluation. +# +# .. dropdown:: parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac/read_input_data.py +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac/read_input_data.py +# +# For more information on the basic requirements to utilize Python Embedding in METplus, +# please refer to the MET User’s Guide section on `Python embedding `_ + +############################################################################## +# User Scripting +# -------------- # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac/read_input_data.py +# User Scripting is not used in this use case. ############################################################################## # Running METplus @@ -109,17 +163,25 @@ # 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 model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac -# (relative to **OUTPUT_BASE**) -# and will contain the following files: +# Output for this use case will be found in {OUTPUT_BASE}/model_applications/clouds/GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac +# and will contain the following files:: # # * grid_stat_GFS_to_ERA5_F36_CloudFracs_360000L_20220705_000000V_pairs.nc # * grid_stat_GFS_to_ERA5_F36_CloudFracs_360000L_20220705_000000V.stat # * grid_stat_GFS_to_ERA5_F36_CloudFracs_NBR_360000L_20220705_000000V_pairs.nc # * grid_stat_GFS_to_ERA5_F36_CloudFracs_NBR_360000L_20220705_000000V.stat # * grid_stat_GFS_to_ERA5_F36_CloudFracs_PROB_360000L_20220705_000000V_pairs.nc -# * grid_stat_GFS_to_ERA5_F36_CloudFracs_PRB_360000L_20220705_000000V.stat - +# * grid_stat_GFS_to_ERA5_F36_CloudFracs_PROB_360000L_20220705_000000V.stat +# +# The netCDF files from the first GridStat instance and prob instance will contain +# the raw fields, difference fields, and gradient fields using the supplied masking area. +# For the nbr instance, there will be additional fields for the fractional coverage +# fields. Each of the instance's output can be identified by an additional tag in the file +# name (NBR for nbr, PROB for prob, and none for the first GridStat instance). For the +# accompanying stat files, the first GridStat instance contains FHO, CTC, CTS, CNT, SL1L2, and +# GRAD line types. The nbr instance will contain only the neighborhood-related line types +# (NBRCTC, NBRCTS, and NBRCNT). Finally, the prob GridStat instance will contain probabilistic +# line types only (PCT, PSTD, PJC, and PRC). ############################################################################## # Keywords @@ -135,4 +197,3 @@ # Navigate to the :ref:`quick-search` page to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/clouds-GridStat_fcstGFS_obsERA5_lowAndTotalCloudFrac.png' -# diff --git a/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.py b/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.py index b8ab2fc8ce..cd56108ef0 100644 --- a/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.py +++ b/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.py @@ -5,59 +5,91 @@ model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # # This use case captures various statistical measures of two model comparisons # for low and total cloud fraction with different neighborhood and probability -# settings for internal model metrics and to aid in future model updates -# +# settings for internal model metrics and to aid in future model updates. + +############################################################################## +# Version Added +# ------------- +# +# METplus version 5.1 ############################################################################## # Datasets # -------- # -# | **Forecast:** Global Forecast System (GFS) -# | **Observations:** Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA2) -# | **Grid:** GPP 17km masking region +# **Forecast:** Global Forecast System (GFS) +# +# **Observations:** Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA2) +# +# **Grid:** GPP 17km masking region # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to 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 'Running METplus' section for more information. +# **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 # ------------------ # +# GridStat is the only MET tool called in this use case. # This use case utilizes Python Embedding, which is called using the PYTHON_NUMPY keyword -# in the observation input template settings. The same Python script processes both forecast and -# observation datasets, but only the observation dataset is not set up for native ingest by MET. -# Two separate forecast fields are verified against two respective observation fields, -# with the Python script being passed the input file, the model name, the variable name being analyzed, -# the initialization and valid times, and a flag to indicate if the field passed is observation or forecast. -# This process is repeated with 3 instance names to GridStat, each with a different setting for regridding, -# neighborhood evaluation, thresholding, output line types, and output prefix names. +# in the observation input template settings. The Python script is passed an input file, +# model name, variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. +# After a successful call, a MET-readable gridded observation dataset is passed back to GridStat for evaluation. ############################################################################## # METplus Workflow # ---------------- # -# GridStat is the only MET tool called in this example. -# It processes the following run time: +# **Beginning time (INIT_BEG):** 2021070312 # -# | **Init:** 2021-07-03 12Z -# | **Forecast lead:** 36 hour -# -# Because instance names are used, GridStat will run 3 times for this 1 initalization time. +# **End time (INIT_END):** 2021070312 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 12H +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 36 +# +# Because instance names are used, GridStat will run 3 times for this 1 initalization time. Each of the +# instance names correspond to different regridding, neighborhood evaluations, thresholding, output line types, and output +# prefix names. For the first GridStat instance, total cloud cover fraction and low cloud cover fraction are verified +# at 10 separate thresholds. The observation dataset is provided via Python Embedding. Various output line types are requested +# and placed in stat files, with a unique output prefix indicating which output are from which GridStat instance. All of the +# evaluation takes place within the masked region, read in via a poly line file. +# For the nbr GridStat instance, the same variables are verified, but the thresholds are expanded to include forecast +# and observation percentiles, ranging from 20 to 80. This instance also creates 4 neighborhoods of varying width using +# a circle definition. The related neighborhood line types are requested as output and a new ouput prefix is used. +# Finally, the prob GridStat instance updates the thresholds for the two variable fields to range from 0 to 1 and +# changes the forecast field to probabilistic space via the FCST_IS_PROB setting. Neighborhoods using the same definitions +# from the nbr instance are used, and the respective line types are requested with a new output prefix for output files +# from this instance. ############################################################################## # METplus Configuration # --------------------- # # METplus first loads the default configuration file found in parm/metplus_config, -# then it loads any configuration files passed to METplus via the command line: -# parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.conf @@ -74,21 +106,39 @@ # 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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case utilizes 1 Python script to read and process both forecast and -# observation fields. -# parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py -# -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py +# This use case utilizes one Python script to read and process the observation fields to become +# METplus usable. From the configuration file it collects an input file, model name, +# variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. Once the script runs, +# it uses the model name to extract the correct grid definition from the griddedDatasets dictionary, +# and the variable field name is used to extract the correct file variable field name (in combination +# with the name of the model) from the verifVariables dictionary. These are combined into a dictionary +# filled with values and keys used by the rest of the code, specifically set for the model and field +# being used. A total cloud fraction call results in the field being extracted and set to a 0-100 range +# with a similar behavior for low cloud fraction. The grid type associated with each model (determined by the +# griddedDatasets dictionary) helps the script create the grid's corresponding latitude and longitude arrays. +# Finally, the valid and initialization times that were passed at runtime are used to finalize the attrs dictionary +# and the dataset is passed back to METplus for evaluation. +# +# .. dropdown:: parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py + +############################################################################## +# User Scripting +# -------------- +# +# User Scripting is not used in this use case. ############################################################################## # Running METplus @@ -110,16 +160,25 @@ # 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 model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac -# (relative to **OUTPUT_BASE**) -# and will contain the following files: -# -# * grid_stat_GFS_TO_MERRA2_F36_CloudFracs_360000L_20210705_000000V_pairs.nc -# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_360000L_20210705_000000V.stat -# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_NBR_360000L_20210705_000000V_pairs.nc -# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_NBR_360000L_20210705_000000V.stat -# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_PROB_360000L_20210705_000000V_pairs.nc -# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_PROB_360000L_20210705_000000V.stat +# Output for this use case will be found in {OUTPUT_BASE}/model_applications/clouds/GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac +# and will contain the following files:: +# +# * grid_stat_GFS_TO_MERRA2_F36_CloudFracs_360000L_20210705_000000V_pairs.nc +# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_360000L_20210705_000000V.stat +# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_NBR_360000L_20210705_000000V_pairs.nc +# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_NBR_360000L_20210705_000000V.stat +# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_PROB_360000L_20210705_000000V_pairs.nc +# * grid_stat_GFS_to_MERRA2_F36_CloudFracs_PROB_360000L_20210705_000000V.stat +# +# The netCDF files from the first GridStat instance and prob instance will contain +# the raw fields, difference fields, and gradient fields using the supplied masking area. +# For the nbr instance, there will be additional fields for the fractional coverage +# fields. Each of the instance's output can be identified by an additional tag in the file +# name (NBR for nbr, PROB for prob, and none for the first GridStat instance). For the +# accompanying stat files, the first GridStat instance contains FHO, CTC, CTS, CNT, SL1L2, and +# GRAD line types. The nbr instance will contain only the neighborhood-related line types +# (NBRCTC, NBRCTS, and NBRCNT). Finally, the prob GridStat instance will contain probabilistic +# line types only (PCT, PSTD, PJC, and PRC). ############################################################################## # Keywords @@ -135,4 +194,3 @@ # Navigate to the :ref:`quick-search` page to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/clouds-GridStat_fcstGFS_obsMERRA2_lowAndTotalCloudFrac.png' -# diff --git a/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.py b/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.py index b925405cb0..aad63b6cee 100644 --- a/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.py +++ b/docs/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.py @@ -5,59 +5,80 @@ model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # # This use case captures various statistical measures of two model comparisons # for cloud top pressures and temperatures with different neighborhood -# settings for internal model metrics and to aid in future model updates -# +# settings for internal model metrics and to aid in future model updates. + +############################################################################## +# Version Added +# ------------- +# +# METplus version 5.1 ############################################################################## # Datasets # -------- # -# | **Forecast:** Global Forecast System (GFS) -# | **Observations:** Satellite ClOud and Radiation Property retrieval System (SatCORPS) -# | **Grid:** GPP 17km masking region +# **Forecast:** Global Forecast System (GFS) # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to 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 'Running METplus' section for more information. +# **Observations:** Satellite ClOud and Radiation Property retrieval System (SatCORPS) # +# **Grid:** GPP 17km masking region +# +# **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. +# Click here to 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 'Running METplus' section for more information. ############################################################################## # METplus Components # ------------------ # +# GridStat is the only MET tool called in this use case. # This use case utilizes Python Embedding, which is called using the PYTHON_NUMPY keyword -# in the observation input template settings. The same Python script can processes both forecast and -# observation datasets, but only the observation dataset is not -# set up for native ingest by MET. Two separate forecast fields are verified against two respective observation fields, -# with the Python script being passed the input file, the model name, the variable name being analyzed, -# the initialization and valid times, and a flag to indicate if the field passed is observation or forecast. -# This process is repeated with 2 instance names to GridStat, each with a different setting for regridding, -# neighborhood evaluation, thresholding, output line types, and output prefix names. +# in the observation input template settings. The Python script is passed an input file, +# model name, variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. +# After a successful call, a MET-readable gridded observation dataset is passed back to GridStat for evaluation. ############################################################################## # METplus Workflow # ---------------- # -# GridStat is the only MET tool called in this example. -# It processes the following run time: +# **Beginning time (INIT_BEG):** 2022070312 +# +# **End time (INIT_END):** 2022070312 # -# | **Init:** 2022-07-03 12Z -# | **Forecast lead:** 36 hour +# **Increment between beginning and end times (INIT_INCREMENT):** 12H # -# Because instance names are used, GridStat will run 2 times for this 1 initalization time. +# **Sequence of forecast leads to process (LEAD_SEQ):** 36 +# +# Because instance names are used, GridStat will run 2 times for this 1 initalization time. Each of the +# instance names correspond to different regridding, neighborhood evaluations, thresholding, output line types, and output +# prefix names. For the first GridStat instance, high cloud temperature and pressure are verified at 12 and 10 separate thresholds, +# respectively. The observation dataset is provided via Python Embedding. Various output line types are requested +# and placed in stat files, with a unique output prefix indicating which output are from which GridStat instance. The CTC and CTS +# line types are also placed in text files. All of the evaluation takes place within the masked region, read in via a poly line file. +# For the nbr GridStat instance, the same variables are verified, but the thresholds are expanded to include forecast +# and observation percentiles, ranging from 20 to 80. This instance also creates 4 neighborhoods of varying width using +# a circle definition. The related neighborhood line types are requested as output and a new ouput prefix is used. ############################################################################## # METplus Configuration # --------------------- # # METplus first loads the default configuration file found in parm/metplus_config, -# then it loads any configuration files passed to METplus via the command line: -# parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.conf @@ -74,20 +95,41 @@ # 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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case utilizes 1 Python script to read and process the observation fields. -# parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp/read_input_data.py -# -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp/read_input_data.py +# This use case utilizes one Python script to read and process the observation fields to become +# METplus usable. From the configuration file it collects an input file, model name, +# variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. Once the script runs, +# it uses the model name to extract the correct grid definition from the griddedDatasets dictionary, +# and the variable field name is used to extract the correct file variable field name (in combination +# with the name of the model) from the verifVariables dictionary. These are combined into a dictionary +# filled with values and keys used by the rest of the code, specifically set for the model and field +# being used. The grid type associated with each model (determined by the griddedDatasets dictionary) +# helps the script create the grid's corresponding latitude and longitude arrays. +# Finally, the valid and initialization times that were passed at runtime are used to finalize the attrs dictionary +# and the dataset is passed back to METplus for evaluation. +# +# .. dropdown:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp/read_input_data.py +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp/read_input_data.py +# +# For more information on the basic requirements to utilize Python Embedding in METplus, +# please refer to the MET User’s Guide section on `Python embedding `_ + +############################################################################## +# User Scripting +# -------------- +# +# User Scripting is not used in this use case. ############################################################################## # Running METplus @@ -109,16 +151,25 @@ # 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 model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp -# (relative to **OUTPUT_BASE**) -# and will contain the following files: -# -# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V_pairs.nc -# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V_ctc.txt -# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V_cts.txt -# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V.stat -# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_NBR_360000L_20220705_000000V_pairs.nc -# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_NBR_360000L_20220705_000000V.stat +# Output for this use case will be found in {OUTPUT_BASE}/model_applications/clouds/GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp +# and will contain the following files:: +# +# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V_pairs.nc +# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V_ctc.txt +# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V_cts.txt +# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_360000L_20220705_000000V.stat +# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_NBR_360000L_20220705_000000V_pairs.nc +# * grid_stat_GFS_to_SATCORPS_F36_CloudHgts_NBR_360000L_20220705_000000V.stat +# +# The netCDF files from the first GridStat instance will contain +# the raw fields, difference fields, and gradient fields using the supplied masking area. +# For the nbr instance, there will be additional fields for the fractional coverage +# fields. Each of the instance's output can be identified by an additional tag in the file +# name (NBR for nbr and none for the first GridStat instance). For the +# accompanying stat files, the first GridStat instance contains FHO, CTC, CTS, CNT, SL1L2, and +# GRAD line types. The nbr instance will contain only the neighborhood-related line types +# (NBRCTC, NBRCTS, and NBRCNT). The first GridStat instance also creates separate text files +# for the CTC and CTS line type output. ############################################################################## # Keywords @@ -134,4 +185,3 @@ # Navigate to the :ref:`quick-search` page to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/clouds-GridStat_fcstGFS_obsSATCORPS_cloudTopPressAndTemp.png' -# diff --git a/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.py b/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.py index 515e0d9310..405e092a82 100644 --- a/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.py +++ b/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.py @@ -5,58 +5,88 @@ model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # # This use case captures various statistical measures of two model comparisons # for cloud base height with different neighborhood settings for internal -# model metrics and to aid in future model updates +# model metrics and to aid in future model updates. # +############################################################################## +# Version Added +# ------------- +# +# METplus version 5.1 + ############################################################################## # Datasets # -------- # -# | **Forecast:** Model for Prediction Across Scales (MPAS) -# | **Observations:** ECMWF Reanalysis, Version 5 (ERA5) -# | **Grid:** GPP 17km masking region +# **Forecast:** Model for Prediction Across Scales (MPAS) +# +# **Observation:** ECMWF Reanalysis, Version 5 (ERA5) # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to 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 'Running METplus' section for more information. +# **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. +# +# **Grid:** GPP 17km masking region ############################################################################## # METplus Components # ------------------ # +# GridStat is the only MET tool called in this use case. # This use case utilizes Python Embedding, which is called using the PYTHON_NUMPY keyword -# in the forecast and observation input template settings. The same Python script processes both forecast and -# observation datasets. The forecast field is verified against the respective observation field, -# with the Python script being passed the input file, the model name, the variable name being analyzed, -# the initialization and valid times, and a flag to indicate if the field passed is observation or forecast. -# This process is repeated with 2 instance names to GridStat, each with a different setting for regridding, -# neighborhood evaluation, thresholding, output line types, and output prefix names. +# in the observation and forecast input template settings. The Python script is passed an input file, +# model name, variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. +# After a successful call, a MET-readable gridded dataset is passed back to GridStat for evaluation. ############################################################################## # METplus Workflow # ---------------- # -# GridStat is the only MET tool called in this example. -# It processes the following run time: +# **Beginning time (INIT_BEG):** 2020072300 +# +# **End time (INIT_END):** 2020072300 # -# | **Init:** 2020-07-23 00Z -# | **Forecast lead:** 36 hour +# **Increment between beginning and end times (INIT_INCREMENT):** 12H # -# Because instance names are used, GridStat will run 2 times for this 1 initalization time. +# **Sequence of forecast leads to process (LEAD_SEQ):** 36 +# +# Because instance names are used, GridStat will run 2 times for this 1 initalization time. Each of the +# instance names correspond to different regridding, neighborhood evaluations, thresholding, output line types, and output +# prefix names. For the first GridStat instance, cloud base height is verified at 10 separate thresholds. +# The observation and forecast datasets are provided via Python Embedding. Various output line types are requested +# and placed in stat files, with a unique output prefix indicating which output are from which GridStat instance. +# All of the evaluation takes place within the masked region, read in via a poly line file. +# For the nbr GridStat instance, the same variable is verified, but the thresholds are expanded to include forecast +# and observation percentiles, ranging from 20 to 80. This instance also creates 4 neighborhoods of varying width using +# a circle definition. The related neighborhood line types are requested as output and a new ouput prefix is used. ############################################################################## # METplus Configuration # --------------------- # # METplus first loads the default configuration file found in parm/metplus_config, -# then it loads any configuration files passed to METplus via the command line: -# parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt.conf @@ -70,24 +100,46 @@ # # **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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case utilizes 1 Python script to read and process both forecast and -# observation fields. -# parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt/read_input_data.py +# This use case utilizes one Python script to read and process the observation and forecast fields to become +# METplus usable. From the configuration file it collects an input file, model name, +# variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. Once the script runs, +# it uses the model name to extract the correct grid definition from the griddedDatasets dictionary, +# and the variable field name is used to extract the correct observation file variable field name (in combination +# with the name of the model) from the verifVariables dictionary and the correct forecast +# file variable name from the verifVariablesModel dictionary. This information is combined into a dictionary +# filled with values and keys used by the rest of the code, specifically set for the model and field +# being used. The grid type associated with each model (determined by the griddedDatasets dictionary) +# helps the script create the grid's corresponding latitude and longitude arrays. +# Finally, the valid and initialization times that were passed at runtime are used to finalize the attrs dictionary +# and the dataset is passed back to METplus for evaluation. +# +# .. dropdown:: parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt/read_input_data.py +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt/read_input_data.py +# +# For more information on the basic requirements to utilize Python Embedding in METplus, +# please refer to the MET User’s Guide section on `Python embedding `_ + +############################################################################## +# User Scripting +# -------------- # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt/read_input_data.py +# User Scripting is not used in this use case. ############################################################################## # Running METplus @@ -109,14 +161,22 @@ # 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 model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt -# (relative to **OUTPUT_BASE**) -# and will contain the following files: +# Output for this use case will be found in {OUTPUT_BASE}/model_applications/clouds/GridStat_fcstMPAS_obsERA5_cloudBaseHgt +# and will contain the following files:: # # * grid_stat_MPAS_to_ERA5_F36_CloudBaseHgt_360000L_20200724_120000V_pairs.nc # * grid_stat_MPAS_to_ERA5_F36_CloudBaseHgt_360000L_20200724_120000V.stat # * grid_stat_MPAS_to_ERA5_F36_CloudBaseHgt_NBR_360000L_20200724_120000V_pairs.nc # * grid_stat_MPAS_to_ERA5_F36_CloudBaseHgt_NBR_360000L_20200724_120000V.stat +# +# The netCDF files from the first GridStat instance will contain +# the raw fields, difference fields, and gradient fields using the supplied masking area. +# For the nbr instance, there will be additional file variables for the fractional coverage +# fields. Each of the instance's output can be identified by an additional tag in the file +# name (NBR for nbr and none for the first GridStat instance). For the +# accompanying stat files, the first GridStat instance contains FHO, CTC, CTS, CNT, SL1L2, and +# GRAD line types. The nbr instance will contain only the neighborhood-related line types +# (NBRCTC, NBRCTS, and NBRCNT). ############################################################################## # Keywords @@ -132,4 +192,3 @@ # Navigate to the :ref:`quick-search` page to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/clouds-GridStat_fcstMPAS_obsERA5_cloudBaseHgt.png' -# diff --git a/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.py b/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.py index 139ed51c50..795d4fe564 100644 --- a/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.py +++ b/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.py @@ -5,58 +5,91 @@ model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # # This use case captures various statistical measures of two model comparisons # for low and total cloud fraction with different neighborhood and probability -# settings for internal model metrics and to aid in future model updates -# +# settings for internal model metrics and to aid in future model updates. + +############################################################################## +# Version Added +# ------------- +# +# METplus version 5.1 ############################################################################## # Datasets # -------- # -# | **Forecast:** Model for Prediction Across Scales (MPAS) -# | **Observations:** Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA2) -# | **Grid:** GPP 17km masking region +# **Forecast:** Model for Prediction Across Scales (MPAS) +# +# **Observation:** Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA2) +# +# **Climatology:** None # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to 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 'Running METplus' section for more information. +# **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. # +# **Grid:** GPP 17km masking region ############################################################################## # METplus Components # ------------------ # +# GridStat is the only MET tool called in this use case. # This use case utilizes Python Embedding, which is called using the PYTHON_NUMPY keyword -# in the forecast and observation input template settings. The same Python script processes both forecast and -# observation datasets. Two separate forecast fields are verified against two respective observation fields, -# with the Python script being passed the input file, the model name, the variable name being analyzed, -# the initialization and valid times, and a flag to indicate if the field passed is observation or forecast. -# This process is repeated with 3 instance names to GridStat, each with a different setting for regridding, -# neighborhood evaluation, thresholding, output line types, and output prefix names. +# in the observation and forecast input template settings. The Python script is passed an input file, +# model name, variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. +# After a successful call, a MET-readable gridded observation dataset is passed back to GridStat for evaluation. ############################################################################## # METplus Workflow # ---------------- # -# GridStat is the only MET tool called in this example. -# It processes the following run time: +# **Beginning time (INIT_BEG):** 2020072300 # -# | **Init:** 2020-07-23 00Z -# | **Forecast lead:** 36 hour +# **End time (INIT_END):** 2020072300 # -# Because instance names are used, GridStat will run 3 times for this 1 initalization time. +# **Increment between beginning and end times (INIT_INCREMENT):** 12H +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 36 +# +# Because instance names are used, GridStat will run 3 times for this 1 initalization time. Each of the +# instance names correspond to different regridding, neighborhood evaluations, thresholding, output line types, and output +# prefix names. For the first GridStat instance, low and total cloud fractions are verified at 10 separate thresholds. +# The observation and forecast datasets are provided via Python Embedding. Various output line types are requested +# and placed in stat files, with a unique output prefix indicating which output are from which GridStat instance. +# All of the evaluation takes place within the masked region, read in via a poly line file. +# For the nbr GridStat instance, the same variables are verified, but the thresholds are expanded to include forecast +# and observation percentiles, ranging from 20 to 80. This instance also creates 4 neighborhoods of varying width using +# a circle definition. The related neighborhood line types are requested as output and a new ouput prefix is used. +# Finally, the prob GridStat instance updates the forecast thresholds for the two variable fields to range from 0 to 1 and +# changes the forecast field to probabilistic space via the FCST_IS_PROB setting. Neighborhoods using the same definitions +# from the nbr instance are used, and the respective line types are requested with a new output prefix for output files +# from this instance. ############################################################################## # METplus Configuration # --------------------- # # METplus first loads the default configuration file found in parm/metplus_config, -# then it loads any configuration files passed to METplus via the command line: -# parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac.conf @@ -73,21 +106,42 @@ # 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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case utilizes 1 Python script to read and process both forecast and -# observation fields. -# parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py +# This use case utilizes one Python script to read and process the observation and forecast fields to become +# METplus usable. From the configuration file it collects an input file, model name, +# variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. Once the script runs, +# it uses the model name to extract the correct grid definition from the griddedDatasets dictionary, +# and the variable field name is used to extract the correct observation file variable field name (in combination +# with the name of the model) from the verifVariables dictionary and the correct forecast +# file variable name from the verifVariablesModel dictionary. This information is combined into a dictionary +# filled with values and keys used by the rest of the code, specifically set for the model and field +# being used. The grid type associated with each model (determined by the griddedDatasets dictionary) +# helps the script create the grid's corresponding latitude and longitude arrays. +# Finally, the valid and initialization times that were passed at runtime are used to finalize the attrs dictionary +# and the dataset is passed back to METplus for evaluation. +# +# .. dropdown:: parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py +# +# For more information on the basic requirements to utilize Python Embedding in METplus, +# please refer to the MET User’s Guide section on `Python embedding `_ + +############################################################################## +# User Scripting +# -------------- # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac/read_input_data.py +# User Scripting is not used in this use case. ############################################################################## # Running METplus @@ -109,9 +163,8 @@ # 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 model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac -# (relative to **OUTPUT_BASE**) -# and will contain the following files: +# Output for this use case will be found in {OUTPUT_BASE}/model_applications/clouds/GridStat_fcstMPAS_obsMERRA2_lowAndTotalCloudFrac +# and will contain the following files:: # # * grid_stat_MPAS_to_MERRA2_F36_CloudFracs_360000L_20200724_120000V_pairs.nc # * grid_stat_MPAS_to_MERRA2_F36_CloudFracs_360000L_20200724_120000V.stat @@ -119,6 +172,16 @@ # * grid_stat_MPAS_to_MERRA2_F36_CloudFracs_NBR_360000L_20200724_120000V.stat # * grid_stat_MPAS_to_MERRA2_F36_CloudFracs_PROB_360000L_20200724_120000V_pairs.nc # * grid_stat_MPAS_to_MERRA2_F36_CloudFracs_PROB_360000L_20200724_120000V.stat +# +# The netCDF files from the first GridStat instance and prob instance will contain +# the raw fields, difference fields, and gradient fields using the supplied masking area. +# For the nbr instance, there will be additional netCDF fields for the fractional coverage +# fields. Each of the instance's output can be identified by an additional tag in the file +# name (NBR for nbr, PROB for prob, and none for the first GridStat instance). For the +# accompanying stat files, the first GridStat instance contains FHO, CTC, CTS, CNT, SL1L2, and +# GRAD line types. The nbr instance will contain only the neighborhood-related line types +# (NBRCTC, NBRCTS, and NBRCNT). Finally, the prob GridStat instance will contain probabilistic +# line types only (PCT, PSTD, PJC, and PRC). ############################################################################## # Keywords diff --git a/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.py b/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.py index 37ffab119d..3b957c82e1 100644 --- a/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.py +++ b/docs/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.py @@ -5,58 +5,91 @@ model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- # # This use case captures various statistical measures of two model comparisons # for low and total cloud fraction with different neighborhood and probability -# settings for internal model metrics and to aid in future model updates -# +# settings for internal model metrics and to aid in future model updates. + +############################################################################## +# Version Added +# ------------- +# +# METplus version 6.0 ############################################################################## # Datasets # -------- # -# | **Forecast:** Model for Prediction Across Scales (MPAS) -# | **Observations:** Satellite ClOud and Radiation Property retrieval System (SatCORPS) -# | **Grid:** GPP 17km masking region +# **Forecast:** Model for Prediction Across Scales (MPAS) +# +# **Observation:** Satellite ClOud and Radiation Property retrieval System (SatCORPS) # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to 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 'Running METplus' section for more information. +# **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. +# +# **Grid:** GPP 17km masking region ############################################################################## # METplus Components # ------------------ # +# GridStat is the only MET tool called in this use case. # This use case utilizes Python Embedding, which is called using the PYTHON_NUMPY keyword -# in the forecast and observation input template settings. The same Python script processes both forecast and -# observation datasets. Two separate forecast fields are verified against two respective observation fields, -# with the Python script being passed the input file, the model name, the variable name being analyzed, -# the initialization and valid times, and a flag to indicate if the field passed is observation or forecast. -# This process is repeated with 3 instance names to GridStat, each with a different setting for regridding, -# neighborhood evaluation, thresholding, output line types, and output prefix names. +# in the observation and forecast input template settings. The Python script is passed an input file, +# model name, variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. +# After a successful call, a MET-readable gridded observation dataset is passed back to GridStat for evaluation. ############################################################################## # METplus Workflow # ---------------- # -# GridStat is the only MET tool called in this example. -# It processes the following run time: +# **Beginning time (INIT_BEG):** 2020072300 +# +# **End time (INIT_END):** 2020072300 # -# | **Init:** 2020-07-23 00Z -# | **Forecast lead:** 36 hour +# **Increment between beginning and end times (INIT_INCREMENT):** 12H # -# Because instance names are used, GridStat will run 3 times for this 1 initalization time. +# **Sequence of forecast leads to process (LEAD_SEQ):** 36 +# +# Because instance names are used, GridStat will run 3 times for this 1 initalization time. Each of the +# instance names correspond to different regridding, neighborhood evaluations, thresholding, output line types, and output +# prefix names. For the first GridStat instance, low and total cloud fractions are verified at 10 separate thresholds. +# The observation and forecast datasets are provided via Python Embedding. Various output line types are requested +# and placed in stat files, with a unique output prefix indicating which output are from which GridStat instance. +# All of the evaluation takes place within the masked region, read in via a poly line file. +# For the nbr GridStat instance, the same variables are verified, but the thresholds are expanded to include forecast +# and observation percentiles, ranging from 20 to 80. This instance also creates 4 neighborhoods of varying width using +# a circle definition. The related neighborhood line types are requested as output and a new ouput prefix is used. +# Finally, the prob GridStat instance updates the forecast thresholds for the two variable fields to range from 0 to 1 and +# changes the forecast field to probabilistic space via the FCST_IS_PROB setting. Neighborhoods using the same definitions +# from the nbr instance are used, and the respective line types are requested with a new output prefix for output files +# from this instance. ############################################################################## # METplus Configuration # --------------------- # # METplus first loads the default configuration file found in parm/metplus_config, -# then it loads any configuration files passed to METplus via the command line: -# parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.conf @@ -73,21 +106,39 @@ # 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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case utilizes 1 Python script to read and process both forecast and -# observation fields. -# parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac/read_input_data.py +# This use case utilizes one Python script to read and process the observation and forecast fields to become +# METplus usable. From the configuration file it collects an input file, model name, +# variable field name being analyzed, the initialization and valid times, +# and a flag to indicate if the field passed is observation or forecast. Once the script runs, +# it uses the model name to extract the correct grid definition from the griddedDatasets dictionary, +# and the variable field name is used to extract the correct observation file variable field name (in combination +# with the name of the model) from the verifVariables dictionary and the correct forecast +# file variable name from the verifVariablesModel dictionary. This information is combined into a dictionary +# filled with values and keys used by the rest of the code, specifically set for the model and field +# being used. The grid type associated with each model (determined by the griddedDatasets dictionary) +# helps the script create the grid's corresponding latitude and longitude arrays. +# Finally, the valid and initialization times that were passed at runtime are used to finalize the attrs dictionary +# and the dataset is passed back to METplus for evaluation. +# +# .. dropdown:: parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac/read_input_data.py +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac/read_input_data.py + +############################################################################## +# User Scripting +# -------------- # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/use_cases/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac/read_input_data.py +# User Scripting is not used in this use case. ############################################################################## # Running METplus @@ -109,9 +160,8 @@ # 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 model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac -# (relative to **OUTPUT_BASE**) -# and will contain the following files: +# Output for this use case will be found in {OUTPUT_BASE}/model_applications/clouds/GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac +# and will contain the following files:: # # * grid_stat_MPAS_F36_CloudFracs_360000L_20200724_120000V_pairs.nc # * grid_stat_MPAS_F36_CloudFracs_360000L_20200724_120000V.stat @@ -119,6 +169,16 @@ # * grid_stat_MPAS_F36_CloudFracs_NBR_360000L_20200724_120000V.stat # * grid_stat_MPAS_F36_CloudFracs_PROB_360000L_20200724_120000V_pairs.nc # * grid_stat_MPAS_F36_CloudFracs_PROB_360000L_20200724_120000V.stat +# +# The netCDF files from the first GridStat instance and prob instance will contain +# the raw fields, difference fields, and gradient fields using the supplied masking area. +# For the nbr instance, there will be additional netCDF fields for the fractional coverage +# fields. Each of the instance's output can be identified by an additional tag in the file +# name (NBR for nbr, PROB for prob, and none for the first GridStat instance). For the +# accompanying stat files, the first GridStat instance contains FHO, CTC, CTS, CNT, SL1L2, and +# GRAD line types. The nbr instance will contain only the neighborhood-related line types +# (NBRCTC, NBRCTS, and NBRCNT). Finally, the prob GridStat instance will contain probabilistic +# line types only (PCT, PSTD, PJC, and PRC). ############################################################################## # Keywords @@ -134,4 +194,3 @@ # Navigate to the :ref:`quick-search` page to discover other similar use cases. # # sphinx_gallery_thumbnail_path = '_static/clouds-GridStat_fcstMPAS_obsSATCORPS_lowAndTotalCloudFrac.png' -# diff --git a/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.py b/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.py index 66ca13a3bc..c44b50a57a 100644 --- a/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.py +++ b/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.py @@ -1,12 +1,17 @@ """ StatAnalysis: IODAv2 -=========================================================================== +==================== model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none -########################################### +############################################################################## # Scientific Objective # -------------------- # @@ -28,16 +33,32 @@ # This use case adopts the IODAv2 formatted NetCDF files, which replace the previous variable # formatting scheme to make use of NetCDF groups. +############################################################################## +# Version Added +# ------------- +# +# METplus version 5.0 + ############################################################################## # Datasets # -------- # +# **Forecast:** [UPDATE] +# +# **Observation:** [UPDATE] # -# | **Data source:** JEDI HofX output files in IODAv2 format +# **Climatology:** [UPDATE] # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to the METplus releases page and download sample data for the appropriate release: https://github.com/dtcenter/METplus/releases -# | The tarball should be unpacked into the directory that you will set the value of INPUT_BASE. See `Running METplus`_ section for more information. -# | +# **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. +# +# **Data source:** JEDI HofX output files in IODAv2 format ############################################################################## # METplus Components @@ -51,20 +72,27 @@ # METplus Workflow # ---------------- # +# **Beginning time (INIT_BEG):** 2018041500 +# +# **End time (INIT_END):** 2018041500 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 12H +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 +# # StatAnalysis is the only tool called in this example. It processes the following # run times: # # | **Valid:** 2018-04-15_00Z # | **Forecast lead:** 0 hour -# | ############################################################################## # 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/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.conf @@ -81,49 +109,38 @@ # 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` # -# .. note:: See the :ref:`StatAnalysis MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: STATAnalysisConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case uses a Python embedding script to read input data +# This use case uses a Python embedding script to read input data. # -# parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed/read_iodav2_mpr.py -# -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed/read_iodav2_mpr.py +# .. dropdown:: parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed/read_iodav2_mpr.py # +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed/read_iodav2_mpr.py ############################################################################## +# User Scripting +# -------------- +# +# This use case does not use additional scripts. + +############################################################################### # Running METplus # --------------- # -# It is recommended to run this use case by: -# -# Passing in StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.conf -c /path/to/user_system.conf -# -# The following METplus configuration variables must be set correctly to run this example.: +# Pass the use case configuration file to the run_metplus.py script along +# with any user-specific system configuration files if desired:: # -# * **INPUT_BASE** - Path to directory where sample data tarballs are unpacked (See Datasets section to obtain tarballs). -# * **OUTPUT_BASE** - Path where METplus output will be written. This must be in a location where you have write permissions -# * **MET_INSTALL_DIR** - Path to location where MET is installed locally -# -# Example User Configuration File:: -# -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y -# -# **NOTE:** All of these items must be found under the [dir] section. +# run_metplus.py /path/to/StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.conf /path/to/user_system.conf # - +# See :ref:`running-metplus` for more information. ############################################################################## # Expected Output @@ -134,8 +151,8 @@ # 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 StatAnalysis_IODAv2 (relative to **OUTPUT_BASE**) -# and will contain the following file: +# Output for this use case will be found in {OUTPUT_BASE}/StatAnalysis_IODAv2 +# and will contain the following file:: # # * dump.out @@ -153,4 +170,5 @@ # Navigate to the :ref:`quick-search` page to discover other similar use cases. # # +# # sphinx_gallery_thumbnail_path = '_static/data_assimilation-StatAnalysis_fcstGFS_HofX_obsIODAv2_PyEmbed.png' diff --git a/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.py b/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.py index 46b5eb8f08..a8e1db39f2 100644 --- a/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.py +++ b/docs/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.py @@ -5,6 +5,11 @@ model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none ########################################### # Scientific Objective @@ -34,16 +39,32 @@ # outputs the filtered MPR formatted columns in an ascii file. # +############################################################################## +# Version Added +# ------------- +# +# METplus version 4.0 + ############################################################################## # Datasets # -------- # +# **Forecast:** [UPDATE] +# +# **Observation:** [UPDATE] +# +# **Climatology:** None # -# | **Data source:** JEDI HofX output files in IODA format +# **Data source:** JEDI HofX output files in IODA format # -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to the METplus releases page and download sample data for the appropriate release: https://github.com/dtcenter/METplus/releases -# | The tarball should be unpacked into the directory that you will set the value of INPUT_BASE. See `Running METplus`_ section for more information. -# | +# **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 @@ -57,20 +78,27 @@ # METplus Workflow # ---------------- # +# **Beginning time (INIT_BEG):** 1982-01-01 +# +# **End time (INIT_END):** 2010-01-02 +# +# **Increment between beginning and end times (INIT_INCREMENT):** 12H +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 +# # StatAnalysis is the only tool called in this example. It processes the following # run times: # # | **Valid:** 2019-08-24_18Z # | **Forecast lead:** 6 hour -# | ############################################################################## # 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/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.conf @@ -87,49 +115,39 @@ # 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` # -# .. note:: See the :ref:`StatAnalysis MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: STATAnalysisConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/STATAnalysisConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case uses a Python embedding script to read input data +# This use case uses a Python embedding script to read input data. # -# parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface/read_ioda_mpr.py +# .. dropdown:: parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface/read_ioda_mpr.py # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface/read_ioda_mpr.py +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/data_assimilation/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface/read_ioda_mpr.py + +############################################################################## +# User Scripting +# -------------- +# +# This use case does not use additional scripts. # ############################################################################## # Running METplus # --------------- # -# It is recommended to run this use case by: -# -# Passing in StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.conf -c /path/to/user_system.conf -# -# The following METplus configuration variables must be set correctly to run this example.: +# Pass the use case configuration file to the run_metplus.py script along +# with any user-specific system configuration files if desired:: # -# * **INPUT_BASE** - Path to directory where sample data tarballs are unpacked (See Datasets section to obtain tarballs). -# * **OUTPUT_BASE** - Path where METplus output will be written. This must be in a location where you have write permissions -# * **MET_INSTALL_DIR** - Path to location where MET is installed locally -# -# Example User Configuration File:: -# -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y -# -# **NOTE:** All of these items must be found under the [dir] section. +# run_metplus.py /path/to/StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.conf /path/to/user_system.conf # - +# See :ref:`running-metplus` for more information. ############################################################################## # Expected Output @@ -140,10 +158,10 @@ # 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 model_applications/data_assimilation/StatAnalysis_HofX (relative to **OUTPUT_BASE**) -# and will contain the following file: +# Output for this use case will be found in {OUTPUT_BASE}/StatAnalysis_HofX +# and will contain the following file:: # -# * dump.out +# * dump.out ############################################################################## # Keywords @@ -160,4 +178,5 @@ # Navigate to the :ref:`quick-search` page to discover other similar use cases. # # +# # sphinx_gallery_thumbnail_path = '_static/data_assimilation-StatAnalysis_fcstHAFS_obsPrepBufr_JEDI_IODA_interface.png' diff --git a/docs/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.py b/docs/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.py index a7b11c5362..d2939eba41 100644 --- a/docs/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.py +++ b/docs/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.py @@ -21,35 +21,38 @@ # # The reference for the Terrestrial Coupling Index calculation is as follows: # -# Dirmeyer, P. A., 2011: The terrestrial segment of soil moisture-climate coupling. *Geophys. Res. Lett.*, **38**, L16702, doi: 10.1029/2011GL048268. +# Dirmeyer, P. A., 2011: The terrestrial segment of soil moisture-climate coupling. +# *Geophys. Res. Lett.*, **38**, L16702, `doi: 10.1029/2011GL048268 `_. + +############################################################################## +# Version Added +# ------------- # +# METplus version 5.1 ############################################################################## # Datasets -# --------------------- -# -# | **Forecast:** CESM 1979-1983 Simulations -# | * Community Land Model (CLM) file -# | * Community Atmosphere Model (CAM) file -# -# | **Observations:** Raw FLUXNET2015 observations -# -# | **Location:** All of the input data required for this use case can be found in the land_surface sample data tarball. Click here to 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 `Running METplus`_ section for more information. +# -------- # -# | **Data Source:** CESM - NSF NCAR Climate & Global Dynamics (CGD); FLUXNET2015 "SUBSET" Data Product: https://fluxnet.org/data/fluxnet2015-dataset/subset-data-product/ +# | **Forecast:** CESM 1979-1983 Simulations +# | +# | * Community Land Model (CLM) file +# | * Community Atmosphere Model (CAM) file # - -############################################################################## -# Python Dependencies -# --------------------- +# **Observation:** Raw FLUXNET2015 observations # -# This use case requires the following Python dependencies:: +# **Climatology:** None # -# * Xarray -# * Pandas -# * METcalcpy 3.0.0+ +# **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. # +# **Data Source:** CESM - NSF NCAR Climate & Global Dynamics (CGD); FLUXNET2015 "SUBSET" Data Product: https://fluxnet.org/data/fluxnet2015-dataset/subset-data-product/ ############################################################################## # METplus Components @@ -59,12 +62,19 @@ # The METplus PointStat processes the output of PyEmbedIngest and FLUXNET2015 dataset (using Python embedding), and outputs the requested line types. # Then the METplus PlotPointObs tool reads the output of PyEmbedIngest and FLUXNET2015 dataset and produce plots of TCI from CESM and point observations. # A custom loop runs through all the pre-defined seasons (DJF, MAM, JJA, SON) and runs PyEmbedIngest, PointStat, and PlotPointObs. -# ############################################################################## # METplus Workflow # ---------------- # +# **Beginning time (VALID_BEG):** 1979060100 +# +# **End time (VALID_END):** 1979060100 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 24H +# +# **Sequence of forecast leads to process (LEAD_SEQ):** 0 +# # The PyEmbedIngest tool reads 2 CESM files containing Soil Moisture (CLM file) and Sensible Heat Flux (CAM file), each composed of daily forecasts from # 1979 to 1983 and calculates TCI and generates a NETCDF file of the TCI. Raw CSV files containing FLUXNET station observations of latent heat flux (LE_F_MDS) # and soil water content at the shallowest level (SWC_F_MDS_1) are read using Python embedding, and TCI is computed. @@ -89,34 +99,47 @@ # --------------------- # # 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. -c parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.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. # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/PointStatConfig_wrapped +# **YOU SHOULD NOT SET ANY OF THESE ENVIRONMENT VARIABLES YOURSELF! THEY WILL BE OVERWRITTEN BY METPLUS WHEN IT CALLS THE MET TOOLS!** +# +# If there is a setting in the MET configuration file that is currently +# not supported by METplus you’d like to control, please refer to: +# :ref:`Overriding Unsupported MET config file settings` +# +# .. dropdown:: PointStatConfig_wrapped # +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/PointStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # +# This use case requires the following Python dependencies: +# +# * Xarray +# * Pandas +# * METcalcpy 3.0.0+ +# # This use case uses a Python embedding script to read both the forecast and observation data, in order to compute TCI, # which is the diagnostic that is being verified by MET using PointStat. The CESM forecast data is read using: # -# parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/cesm_tci.py +# .. dropdown:: parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/cesm_tci.py # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/cesm_tci.py +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/cesm_tci.py # # The user can control all arguments to this script via the METplus use case configuration file using the following config entries: # @@ -144,10 +167,10 @@ # # The raw FLUXNET2015 SUBSET data are read using: # -# parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/fluxnet2015_tci.py -# -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/fluxnet2015_tci.py +# .. dropdown:: parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/fluxnet2015_tci.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI/fluxnet2015_tci.py # # The user can control all command line arguments to this script via METplus config entries: # @@ -211,6 +234,15 @@ # Both of the above Python embedding scripts compute TCI using the ``calc_tci()`` function in METcalcpy. See the METcalcpy # documentation for more information: https://metcalcpy.readthedocs.io/en/latest/index.html. # +# For more information on the basic requirements to utilize Python Embedding in METplus, +# please refer to the MET User’s Guide section on `Python embedding `_ + +############################################################################## +# User Scripting +# -------------- +# +# This use case does not use additional scripts. + ############################################################################## # Running METplus @@ -222,7 +254,6 @@ # run_metplus.py /path/to/METplus/parm/use_cases/model_applications/land_surface/PointStat_fcstCESM_obsFLUXNET2015_TCI.conf /path/to/user_system.conf # # See :ref:`running-metplus` for more information. -# ############################################################################## # Expected Output @@ -233,48 +264,45 @@ # INFO: METplus has successfully finished running. # # Refer to the value set for **OUTPUT_BASE** to find where the output data was generated. -# Output for the use case will be found in 3 folders(relative to **OUTPUT_BASE**). -# Those folders are: -# -# * PyEmbedIngest -# -# The **OUTPUT_BASE** folder contains all of the TCI output calculated using CESM files in NETCDF format: -# -# * regrid_data_plane_DJF.nc -# * regrid_data_plane_JJA.nc -# * regrid_data_plane_MAM.nc -# * regrid_data_plane_SON.nc -# -# * PointStat -# -# The final folder, PointStat, contains all of the following output from the PointStat call: -# -# * point_stat_DJF_000000L_19790101_000000V_cnt.txt -# * point_stat_DJF_000000L_19790101_000000V_ctc.txt -# * point_stat_DJF_000000L_19790101_000000V_mpr.txt -# * point_stat_DJF_000000L_19790101_000000V.stat -# * point_stat_JJA_000000L_19790101_000000V_cnt.txt -# * point_stat_JJA_000000L_19790101_000000V_ctc.txt -# * point_stat_JJA_000000L_19790101_000000V_mpr.txt -# * point_stat_JJA_000000L_19790101_000000V.stat -# * point_stat_MAM_000000L_19790101_000000V_cnt.txt -# * point_stat_MAM_000000L_19790101_000000V_ctc.txt -# * point_stat_MAM_000000L_19790101_000000V_mpr.txt -# * point_stat_MAM_000000L_19790101_000000V.stat -# * point_stat_SON_000000L_19790101_000000V_cnt.txt -# * point_stat_SON_000000L_19790101_000000V_ctc.txt -# * point_stat_SON_000000L_19790101_000000V_mpr.txt -# * point_stat_SON_000000L_19790101_000000V.stat -# -# * PlotPointObs -# -# The final folder plot_point_obs, contains all of the plots from the PlotPointObs call: -# -# * cesm_fluxnet2015_DJF.ps -# * cesm_fluxnet2015_JJA.ps -# * cesm_fluxnet2015_MAM.ps -# * cesm_fluxnet2015_SON.ps -# +# Output for the use case will be found in 3 folders (relative to **OUTPUT_BASE**). +# Those folders are:: +# +# * PyEmbedIngest +# * PointStat +# * PlotPointObs +# +# The PyEmbedIngest folder contains all of the TCI output calculated using CESM files in NETCDF format:: +# +# * regrid_data_plane_DJF.nc +# * regrid_data_plane_JJA.nc +# * regrid_data_plane_MAM.nc +# * regrid_data_plane_SON.nc +# +# The PointStat folder contains all of the following output from the PointStat call:: +# +# * point_stat_DJF_000000L_19790101_000000V_cnt.txt +# * point_stat_DJF_000000L_19790101_000000V_ctc.txt +# * point_stat_DJF_000000L_19790101_000000V_mpr.txt +# * point_stat_DJF_000000L_19790101_000000V.stat +# * point_stat_JJA_000000L_19790101_000000V_cnt.txt +# * point_stat_JJA_000000L_19790101_000000V_ctc.txt +# * point_stat_JJA_000000L_19790101_000000V_mpr.txt +# * point_stat_JJA_000000L_19790101_000000V.stat +# * point_stat_MAM_000000L_19790101_000000V_cnt.txt +# * point_stat_MAM_000000L_19790101_000000V_ctc.txt +# * point_stat_MAM_000000L_19790101_000000V_mpr.txt +# * point_stat_MAM_000000L_19790101_000000V.stat +# * point_stat_SON_000000L_19790101_000000V_cnt.txt +# * point_stat_SON_000000L_19790101_000000V_ctc.txt +# * point_stat_SON_000000L_19790101_000000V_mpr.txt +# * point_stat_SON_000000L_19790101_000000V.stat +# +# The PlotPointObs folder contains all of the plots from the PlotPointObs call:: +# +# * cesm_fluxnet2015_DJF.ps +# * cesm_fluxnet2015_JJA.ps +# * cesm_fluxnet2015_MAM.ps +# * cesm_fluxnet2015_SON.ps ############################################################################## # Keywords diff --git a/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.py b/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.py index b01f741b64..efbb329c9d 100644 --- a/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.py +++ b/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.py @@ -1,12 +1,17 @@ """ Grid-Stat and MODE: Sea Ice Validation -==================================================================================================== +====================================== -model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS -_obsNCEP_sea_ice.conf +model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf """ -#################################################################################################### +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + +################################################################################ # Scientific Objective # -------------------- # @@ -14,62 +19,88 @@ # and Ice Mapping System (IMS) and the National Centers for Environmental Prediction (NCEP) # sea ice analysis. This is a validation and diagnostics use case because it is limited to a # comparison between IMS analysis to NCEP analysis. -# Written by Lindsay Blank, NCAR. January 2020 -#################################################################################################### +############################################################################## +# Version Added +# ------------- +# +# METplus version 3.0 + +################################################################################# # Datasets # -------- # # Both IMS and NCEP sea ice analyses are observation datasets. For the purposes # of MET, IMS is referred to as "forecast" and NCEP is referred to as "observation". # -# * Forecast dataset: IMS Sea Ice Concentration -# - Variable of interest: ICEC; ICEC is a binary field where "1" means a sea ice concentration of >=0.40 and "0" means a sea ice concentration of <0.40. -# - Level: Z0 (surface) -# - Dates: 20190201 - 20190228 -# - Valid time: 22 UTC -# - Format: Grib2 -# - Projection: 4-km Polar Stereographic -# -# * Observation dataset: NCEP Sea Ice Concentration -# - Variable of interest: ICEC; ICEC is the sea ice concentration with values from 0.0 - 1.0. Values >1.0 && <=1.28 indicate flagged data to be included and should be set to ==1.0 when running MET. Values >1.28 should be ignored as that indicates an invalid observation. -# - Level: Z0 (surface) -# - Dates: 20190201 - 20190228 -# - Valid time: 00 UTC -# - Format: Grib2 -# - Projection: 12.7-km Polar Stereographic +# | **Forecast:** IMS Sea Ice Concentration +# | * Variable of interest: ICEC; ICEC is a binary field where "1" means a sea ice concentration of >=0.40 and "0" means a sea ice concentration of <0.40. +# | * Level: Z0 (surface) +# | * Dates: 20190201 - 20190228 +# | * Valid time: 22 UTC +# | * Format: Grib2 +# | * Projection: 4-km Polar Stereographic +# +# | **Observation:** NCEP Sea Ice Concentration +# | * Variable of interest: ICEC; ICEC is the sea ice concentration with values from +# | 0.0 - 1.0. Values >1.0 && <=1.28 indicate flagged data to be included and should be set to ==1.0 when running MET. +# | Values >1.28 should be ignored as that indicates an invalid observation. +# | * Level: Z0 (surface) +# | * Dates: 20190201 - 20190228 +# | * Valid time: 00 UTC +# | * Format: Grib2 +# | * Projection: 12.7-km Polar Stereographic +# +# **Climatology:** None # -# * Data source: Received from Robert Grumbine at EMC. IMS data is originally from the NIC. NCEP data is originally from NCEP. +# **Data source:** Received from Robert Grumbine at EMC. IMS data is originally from the +# `NIC `_. NCEP data is originally from NCEP. # -# * Location: IMS: https://www.natice.noaa.gov/ims/index.html; IMS - (https://polar.ncep.noaa.gov/seaice/Analyses.shtml) +# **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 MET GridStat and MODE tools. -################################################################################################### +################################################################################### # METplus Workflow # ---------------- # +# **Beginning time (VALID_BEG):** 20190201 +# +# **End time (VALID_END):** 20190201 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 86400 +# +# **Sequence of forecast leads to process (LEAD_SEQ):** None +# # The workflow processes the data by valid time, meaning that each tool will be run for each time # before moving onto the next valid time. The GridStat tool is called first followed by the MODE # tool. It processes analysis times from 2019-02-01 to 2019-02-05. The valid times for each analysis # are different from one another (please see `Datasets`_ section for more information). -################################################################################################### +################################################################################## # METplus Configuration # --------------------- # -# METplus first loads all of the configuration files found in parm/metplus_config. Then, it loads -# any configuration files passed to METplus by the command line with the -c option. +# 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/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf # -################################################################################################### +################################################################################## # MET Configuration # ----------------- # @@ -81,49 +112,39 @@ # 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` # -# **GridStatConfig_wrapped** +# .. dropdown:: GridStatConfig_wrapped # -# .. note:: See the :ref:`GridStat 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/GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. dropdown:: MODEConfig_wrapped +# +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/MODEConfig_wrapped + +############################################################################## +# Python Embedding +# ---------------- # -# **MODEConfig_wrapped** +# This use case does not use Python embedding. + +############################################################################## +# User Scripting +# -------------- # -# .. note:: See the :ref:`MODE MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# This use case does not use additional scripts. # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/MODEConfig_wrapped -################################################################################################### +################################################################################ # Running METplus # --------------- # -# This use case can be run two ways: -# -# 1) Passing in GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf 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/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf -# -# The former method is recommended. Whether you add them to a user-specific configuration file or modify the metplus_config files, the following variables must be set correctly: -# -# * **INPUT_BASE** - Path to directory where sample data tarballs are unpacked (See Datasets section to obtain tarballs). -# * **OUTPUT_BASE** - Path where METplus output will be written. This must be in a location where you have write permissions -# * **MET_INSTALL_DIR** - PAth to location where MET is installed locally -# -# Example User Configuration File:: -# -# [dir] -# INPUT_BASE = /path/to/sample/input/data -# OUTPUT_BASE = /path/to/output/dir -# MET_INSTALL_DIR = /path/to/met-X.Y -# -# **NOTE** All of these items must be found under the [dir] section. +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/marine_and_cryosphere/GridStat_MODE_fcstIMS_obsNCEP_sea_ice.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. #################################################################################################### # Expected Output @@ -133,19 +154,20 @@ # # INFO: METplus has successfully finished running. # -# A successful run will have the following output files in the location defined by {OUTPUT_BASE}, which -# is located in the metplus_system.conf configuration file located in /path/to/METplus/parm/metplus_config. -# This list of files should be found for every time run through METplus. -# GridStat output will be in model_applications/marine_and_cryosphere/sea_ice/GridStat relative to the {OUTPUT_BASE}. -# MODE output will be in model_applications/marine_and_cryosphere/sea_ice/MODE relative to the {OUTPUT_BASE}. +# 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 two locations: +# +# * GridStat output will be in {OUTPUT_BASE}/model_applications/marine_and_cryosphere/sea_ice/GridStat. +# * MODE output will be in {OUTPUT_BASE}/model_applications/marine_and_cryosphere/sea_ice/MODE. +# # Using the output for 20190201 as an example: # -# **GridStat output**: +# **GridStat output**:: # # * grid_stat_IMS_ICEC_vs_NCEP_ICEC_Z0_000000L_20190201_220000V_pairs.nc # * grid_stat_IMS_ICEC_vs_NCEP_ICEC_Z0_000000L_20190201_220000V.stat # -# **MODE output**: +# **MODE output**:: # # * mode_IMS_ICEC_vs_NCEP_ICEC_000000L_20190201_220000V_000000A_R1_T1_cts.txt # * mode_IMS_ICEC_vs_NCEP_ICEC_000000L_20190201_220000V_000000A_R1_T1_obj.nc @@ -167,13 +189,11 @@ # * mode_IMS_ICEC_vs_NCEP_ICEC_000000L_20190201_220000V_000000A_R5_T1_obj.nc # * mode_IMS_ICEC_vs_NCEP_ICEC_000000L_20190201_220000V_000000A_R5_T1_obj.txt # * mode_IMS_ICEC_vs_NCEP_ICEC_000000L_20190201_220000V_000000A_R5_T1.ps -# ################################################################################################### # Keywords # -------- # -# # .. note:: # # * GridStatToolUseCase diff --git a/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.py b/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.py index 808040c6d8..d4b7a0e4e7 100644 --- a/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.py +++ b/docs/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.py @@ -5,6 +5,12 @@ model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf """ +############################################################################## +# .. contents:: +# :depth: 1 +# :local: +# :backlinks: none + ############################################################################## # Scientific Objective # -------------------- @@ -14,65 +20,66 @@ # provides standardization and reproducible results. ############################################################################## -# Datasets -# -------- -# -# | **Forecast:** RTOFS ssh file via Python Embedding script/file +# Version Added +# ------------- # -# | **Observations:** AVISO ssh file via Python Embedding script/file -# -# | **Sea Ice Masking:** RTOFS ice cover file via Python Embedding script/file -# -# | **Climatology:** HYCOM ssh file via Python Embedding script/file -# -# | **Location:** All of the input data required for this use case can be found in the met_test sample data tarball. Click here to 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 `Running METplus`_ section for more information. -# -# | **Data Source:** COPERNICUS GLOBAL OCEAN SSH NRT (LEVEL 4), HYCOM + NCODA Global 1/12 deg Reanalysis -# | +# METplus version 4.1 ############################################################################## -# External Dependencies -# --------------------- +# Datasets +# -------- # -# You will need to use a version of Python 3.6+ that has the following packages installed: +# **Forecast:** RTOFS ssh file via Python Embedding script/file # -# * scikit-learn -# * pyresample +# **Observations:** AVISO ssh file via Python Embedding script/file # -# 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. +# **Sea Ice Masking:** RTOFS ice cover file via Python Embedding script/file # -# 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.: +# **Climatology:** HYCOM ssh file via Python Embedding script/file # -# [user_env_vars] -# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python +# **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. +# +# **Data Source:** COPERNICUS GLOBAL OCEAN SSH NRT (LEVEL 4), HYCOM + NCODA Global 1/12 deg Reanalysis ############################################################################## # METplus Components # ------------------ # -# This use case utilizes the METplus GridStat wrapper to generate a -# command to run the MET tool GridStat with Python Embedding for the specified user hemispheres +# This use case only runs the Grid-Stat tool. It utilizes Python Embedding for the forecast, observation, +# and climatology datasets to be METplus-friendly. ############################################################################## # METplus Workflow # ---------------- # -# GridStat is the only tool called in this example. This use case will pass in both the observation, forecast, -# and climatology gridded data being pulled from the files via Python Embedding. All of the desired statistics -# reside in the CNT line type, so that is the only output requested. -# It processes the following run time: +# **Beginning time (VALID_BEG):** 20210811 +# +# **End time (VALID_END):** 20210811 +# +# **Increment between beginning and end times (VALID_INCREMENT):** 1M # -# | **Valid:** 2021-05-11 0Z -# | +# **Sequence of forecast leads to process (LEAD_SEQ):** 24 +# +# This use case will run 1 time to process the provided input files. In order to properly ingest the forecast, +# observation, and climatology datasets, Python Embedding is used. The configuration file passes the input forecast file, +# input observation file, ice cover masking file, directory path containing the climatology file, valid date string of %Y%m%d, +# and a file flag indicating which data dictionary should be passed back to METplus (forecast, observation, or climatology). +# All of the desired statistics reside in the CNT and SAL1L2 line types, so those are the only output requested. ############################################################################## # 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/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf +# then it loads any configuration files passed to METplus via the command line, +# i.e. parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf # # .. highlight:: bash # .. literalinclude:: ../../../../parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf @@ -89,52 +96,73 @@ # 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` # -# .. note:: See the :ref:`GridStat MET Configuration` section of the User's Guide for more information on the environment variables used in the file below: +# .. dropdown:: GridStatConfig_wrapped # -# .. highlight:: bash -# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped +# .. highlight:: bash +# .. literalinclude:: ../../../../parm/met_config/GridStatConfig_wrapped ############################################################################## # Python Embedding # ---------------- # -# This use case uses one Python script to read forecast and observation data +# This use case uses one Python script to read forecast, observation, and climatology data. +# At runtime, the Python script is passed the input forecast file, input observation file, +# ice cover masking file, directory path containing the climatology file, valid date string of %Y%m%d, +# and a file flag indicating which data dictionary should be passed back to METplus (forecast, observation, or climatology). +# The reasoning for needing all three files each time the script is run is due to the kd-tree calculations and masking +# which are all interrelated and cannot be currently performed within METplus. If any of the files are missing, an appropriate error +# message will be provided and the script will exit. If all files are present, then the script proceeds to pull out the requested +# forecast and observation fields, adjusting coordinate systems as necessary (not all of the inputs have the same +# coordinate system). For the climatology data, the script's action is dependant on the valid date: if it's prior to or after the 15th, +# the offset is calculated and used to extract a second climatology file's data that extends over the date in use. +# If the valid date is exactly the 15th, then a single file can be used. After that, the script processes the ice mask data, creates +# weights for the model data via kd-tree interpolation, creates a new interpolated model grid that matches the +# observation dataset (this is also done for the climatology data field), masks the various fields with the ice mask, +# and removes the bad data below a given latitude. Finally, the file flag is used to determine which of the three modified grids +# (forecast, observation, or climatology) needs to be returned to METplus. Note that these flags correspond to the +# respective configuration file field in METplus. +# +# .. dropdown:: parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh/read_rtofs_aviso_hycom.py +# +# .. highlight:: python +# .. literalinclude:: ../../../../parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh/read_rtofs_aviso_hycom.py +# +# For more information on the basic requirements to utilize Python Embedding in METplus, +# please refer to the MET User’s Guide section on `Python embedding `_ +# +# **External Dependencies** +# +# You will need to use a version of Python 3.6+ that has the following packages installed: +# +# * scikit-learn +# * pyresample # -# parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh/read_rtofs_aviso_hycom.py +# 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. # -# .. highlight:: python -# .. literalinclude:: ../../../../parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh/read_rtofs_aviso_hycom.py +# If this is the case, you will need to set the MET_PYTHON_EXE environment variable to the path of the version of Python +# you want to use. If you want this version of Python to only apply to this use case, set it in the [user_env_vars] +# section of a METplus configuration file.: # +# [user_env_vars] +# MET_PYTHON_EXE = /path/to/python/with/required/packages/bin/python ############################################################################## +# User Scripting +# -------------- +# +# This use case does not use additional scripts. + +############################################################################### # 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:: # -# 1) Passing in GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf then a user-specific system configuration file:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf -c /path/to/user_system.conf -# -# 2) Modifying the configurations in parm/metplus_config, then passing in GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf:: -# -# run_metplus.py -c /path/to/METplus/parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf -# -# The former method is recommended. Whether you add them to a user-specific configuration file or modify the metplus_config files, the following variables must be set correctly: -# -# * **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 -# -# **NOTE:** All of these items must be found under the [dir] section. +# run_metplus.py /path/to/METplus/parm/use_cases/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh.conf /path/to/user_system.conf # +# See :ref:`running-metplus` for more information. ############################################################################## # Expected Output @@ -145,13 +173,20 @@ # INFO: METplus has successfully finished running. # # Refer to the value set for **OUTPUT_BASE** to find where the output data was generated. -# Output for thisIce use case will be found in 20210503 (relative to **OUTPUT_BASE**) -# and will contain the following files: +# Output for this use case will be found in +# {OUTPUT_BASE}/model_applications/marine_and_cryosphere/GridStat_fcstRTOFS_obsAVISO_climHYCOM_ssh +# Output for this ice use case will be found in 20210503. +# and will contain the following files:: # # * grid_stat_SSH_000000L_20210811_000000V.stat # * grid_stat_SSH_000000L_20210811_000000V_sal1l2.txt # * grid_stat_SSH_000000L_20210811_000000V_cnt.txt # * grid_stat_SSH_000000L_20210811_000000V_pairs.nc +# +# The SAL1L2 and CNT line types were requested output with the BOTH configuration, +# so the .stat file will contain both line type outputs as well as each line type +# having its own text file. The netCDF file will only contain the raw fields as +# no NC_PAIRS_FLAG settings were utilized. ############################################################################## # Keywords