"""
UserScript: Calculate the Difficulty Index
==========================================

model_applications/medium_range/UserScript_fcstGEFS_Difficulty_Index.conf

"""
##############################################################################
# .. contents::
#   :depth: 1
#   :local:
#   :backlinks: none

##############################################################################
# Scientific Objective
# --------------------
#
# This use case calls the UserScript wrapper to run a user provided script that calculates 
# the difficulty index for wind speed. This use case allows for the user to change a variety 
# of variables needed to run the difficulty index (i.e. threshold start and units) so that the
# user can run the script at different thresholds without needing to alter the code. This 
# script run by the use case uses METcalcpy to provide the difficulty index calculation and
# METplotpy to provide the plotting capability. 
#
# The difficulty index was developed by the Naval Research Lab (NRL). The overall aim of the
# difficulty index is to graphically represent the expected difficulty of a decision based on 
# a set of forecasts (ensemble) of, e.g., wind speed as a function of space and 
# time. There are two basic factors that can make a decision difficult. The first factor is the 
# proximity of the ensemble mean forecast to a decision threshold, e.g. 34 knot winds. If the 
# ensemble mean is either much lower or much higher than the threshold, the decision is easier; 
# if it is closer to the threshold, the decision is harder. The second factor is the forecast 
# precision, or ensemble spread. The greater the spread around the ensemble mean, the more likely 
# it is that there will be ensemble members both above and below the decision threshold, making 
# the decision harder. (A third factor that we will not address here is undiagnosed systematic 
# error, which adds uncertainty in a similar way to ensemble spread.) The challenge is combining 
# these factors into a continuous function that allows the user to assess relative risk.
#
# Additional details on the computation of the Difficulty Index can be found in the `METcalcpy 
# documentation <https://metcalcpy.readthedocs.io/en/latest/Users_Guide/difficulty_index.html>`_ 
# and more information on plotting difficulty index can be found in the `METplotpy documentation
# <https://metplotpy.readthedocs.io/en/latest/Users_Guide/difficulty_index.html>`_.

##############################################################################
# Version Added
# -------------
#
# METplus version 4.1

##############################################################################
# Datasets
# --------
#
# **Forecast:** NOAA Global Ensemble Forecast System (GEFS)
#
# **Observation:** None
#
# **Climatology:** None
#
# **Location:** All of the input data required for this use case can be 
# found in a sample data tarball. Each use case category will have 
# one or more sample data tarballs. It is only necessary to download 
# the tarball with the use case’s dataset and not the entire collection 
# of sample data. Click here to access the METplus releases page and download sample data 
# for the appropriate release: https://github.com/dtcenter/METplus/releases
# This tarball should be unpacked into the directory that you will 
# set the value of INPUT_BASE. See :ref:`running-metplus` section for more information.

##############################################################################
# METplus Components
# ------------------
#
# This use case runs the UserScript wrapper tool to run a user provided script,
# in this case, wind_difficulty_index.py.

##############################################################################
# METplus Workflow
# ----------------
#
# **Beginning time (INIT_BEG):** 2020120812
#
# **End time (INIT_END):** 2020120812
#
# **Increment between beginning and end times (INIT_INCREMENT):** 12H
#
# **Sequence of forecast leads to process (LEAD_SEQ):** None
#
# This use case loops by process which means that each tool is run for all times before moving to the
# next tool. The tool order is as follows:
# 
# UserScript
#
# This example loops by initialization time (with begin, end, and increment as specified in the 
# METplus UserScript_fcstGEFS_Difficulty_Index.conf file). 
#
# 1 initialization time will be run over 1 lead time:
#
# **Init:** 20201208_12Z
#
# **Forecast lead:** 60
#
# Since the data file used only contains a single lead time, the lead time is implied and not configured
# anywhere in the use case configuration file.

##############################################################################
# METplus Configuration
# ---------------------
#
# METplus first loads all of the configuration files found in parm/metplus_config,
# then it loads any configuration files passed to METplus via the command line,
# i.e. parm/use_cases/model_applications/medium_range/UserScript_fcstGEFS_Difficulty_Index.conf
#
# .. highlight:: bash
# .. literalinclude:: ../../../../parm/use_cases/model_applications/medium_range/UserScript_fcstGEFS_Difficulty_Index.conf
#

#############################################################################
# MET Configuration
# ---------------------
#
# There are no MET tools used in this use case.
#

##############################################################################
# Python Embedding
# ----------------
#
# This use case uses a Python embedding script to read input data.
#
# .. dropdown:: parm/use_cases/model_applications/medium_range/UserScript_fcstGEFS_Difficulty_Index/wind_difficulty_index.py
#
#   .. highlight:: python
#   .. literalinclude:: ../../../../parm/use_cases/model_applications/medium_range/UserScript_fcstGEFS_Difficulty_Index/wind_difficulty_index.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 <https://met.readthedocs.io/en/latest/Users_Guide/appendixF.html#appendix-f-python-embedding>`_.

##############################################################################
# User Scripting
# --------------
#
# [UPDATE CONTENT]

##############################################################################
# Running METplus
# ---------------
#
# Pass the use case configuration file to the run_metplus.py script along 
# with any user-specific system configuration files if desired::
#
#   run_metplus.py /path/to/METplus/parm/use_cases/model_applications/medium_range/UserScript_fcstGEFS_Difficulty_Index.conf /path/to/user_system.conf
#
# See :ref:`running-metplus` for more information.

##############################################################################
# Expected Output
# ---------------
#
# A successful run will output the following both to the screen and to the logfile::
#
#   INFO: METplus has successfully finished running.
#
# Refer to the value set for **OUTPUT_BASE** to find where the output data was generated.
# Output for this use case will be found in a directory relative to **OUTPUT_BASE**. There
# should be a list of files that have the following format:
#
# wndspd_GEFS_NorthPac_5dy_30mem_difficulty_indexTHRESH_00_kn.png
# 
# Where THRESH is a number between DIFF_INDEX_SAVE_THRESH_START and 
# DIFF_INDEX_SAVE_THRESH_STOP which are defined in UserScript_fcstGEFS_Difficulty_Index.conf.
# 

##############################################################################
# Keywords
# --------
#
# .. note::
#
#   * UserScriptUseCase
#   * MediumRangeAppUseCase
#   * NRLOrgUseCase
#   * METcalcpyUseCase
#   * METplotpyUseCase
#
#   Navigate to the :ref:`quick-search` page to discover other similar use cases.
#
#
#

# sphinx_gallery_thumbnail_path = '_static/medium_range-UserScript_fcstGEFS_Difficulty_Index.png'
#