\documentclass[psfig,12pt]{article}

\usepackage{graphicx}
\usepackage{amssymb}
\usepackage[T1]{fontenc}
\usepackage{times}
\usepackage{longtable}

\setlength{\topmargin}{0pt}
\setlength{\headheight}{0pt} % *** for xdvi and ps ***
\setlength{\headsep}{0pt}
\setlength{\textheight}{9.0truein}
\setlength{\textwidth}{6.5truein}
\setlength{\footskip}{24pt}
\setlength{\oddsidemargin}{0pt}
\setlength{\marginparsep}{2pt}
\setlength{\marginparwidth}{5pt}
\setlength{\parskip}{1em}
\hyphenpenalty=2000
\renewcommand{\baselinestretch}{1.0}

%%%%% Start document %%%%%
\begin{document}
\pagestyle{empty}

\centering
{\Large\bf NHC Ensemble-based Sensitivity Code Readme} \\
Ryan Torn, University at Albany, SUNY, rtorn@albany.edu \\
Updated: \today
\flushleft
\vspace{0.3in}

This document provides a description of the enclosed code that utilizes the ensemble-based
sensitivity technique to evaluate the sensitivity of various TC-related forecast outcomes, including
track, intensity, 2D maximum wind speed and precipitation, to forecast fields at an earlier lead time.
The enclosed code is written in conda python and is designed to work with any grib files that contain 
forecast data on a lat/lon grid.  The specific python packages that are needed to run this code 
are provided in the section below.  
The execution of the program is controlled by the numerous settings within a configuration/parameter file, 
while the date, storm, and parameter file itself are input as command-line arguments since they 
change based on storm and initialization time.  Furthermore,
the code is designed to work for a variety of models and computing systems.  Those differences related
to models and computing systems are isolated to the individual i/o module, which has common routine
names, but does all of the model/location specific differences inside of it and is transparent to 
the rest of the code.

The code itself consists of four distinct stages, all of which are controlled by run\_NHC\_sens.py

\begin{enumerate}
\item Data staging and preparation (model and platform specific)
\item Computing forecast metrics (fcst\_metrics\_tc.py)
\item Compute forecast fields to compute sensitivity to (compute\_tc\_fields.py)
\item Compute sensitivity and generate maps (nhc\_sens.py)
\end{enumerate}

In order to generate sensitivity output, the user should run the following command from the unix 
command line, which is the command for the Hurricane Laura forecast initialized 0000~UTC 22 August 2020:

\vspace{0.1in}
python run\_NHC\_sens.py --init 2020082200 --storm laura13l --param nhc\_ecmwf.py, 
\vspace{0.1in}

where the --init argument is the forecast initialization date in yyyymmddhh format, --storm is the 
TC name, including both the name, TC number, and the basin.  The TC number and basin are necessary 
as the code parses the storm text string to figure out the basin and TC number.  Finally, --param is
the path to the paramter/configuration file, that contains a number of configuration options that are
meant to be static from one initialization time/storm to another, but still gives the user the option
to change how the code executes, or how the plots look.  Most of the configuration options have 
default values, though some MUST be set within the file for the code to work (see parameter list).  
The tables below list 
the individual parameter/configuration options available and the default values, where appropriate.

The outcome of running this code is a set of graphics and gridded sensitivity output, which are 
organized using the following directory format:

\vspace{0.1in}
\{figure\_dir\}/\{yyyymmddhh\}\_\{storm\}/\{metric\}/sens/\{field\},
\vspace{0.1in}

where storm is the name of the TC (same as --storm line above), yyyymmddhh is the initialization date
(same as --init line above), metric is the name of each forecast metric, where each forecast metric has its own
directory.  For example, the integrated track metric (the default metric of the code) is named 
f120\_intmajtrack, with f120 meaning that the integrated track forecast window ends at 120 h, while 
intmajtrack is the name of the integrated track metric.  The user can specify additional metrics to compute 
sensitivity for using the metrics configuration option.  More information on the definition of each metric is 
located in the Metric section below.

Within each forecast metric directory are two sub-directories, one is called sens,
which are the sensitivity plots/grids on a fixed domain, while the sens\_sc provides storm-centered
graphics.  Within each of these directories is a set of subdirectories that represent individual
forecast fields that you are computing the sensitivity to.  The forecast hour in each file's name is the
forecast lead time that you are computing the sensitivity to (i.e., a file starting with 202008200\_f036 is 
the sensitivity of the metric to the 36~h forecast fields.).  The fields section contains information on
what each of the forecast fields represents, how it is calculated, and what metric(s) it is used for.

Gridded sensitivity output, in netCDF format, is stored in tar files in \{figure\_dir\}/awips/\{yyyymmddhh\}.tar.
Each tar file contains all of the storms for a particular initialization time using the following convention:
\{yyyymmddhh\}/\{storm\}/\{metshort\}, where \{metshort\} is the short name for each of the metric (track, inten,
wind, pcp).  These files can be ingested into the AWIPS system for discrimination by forecasters or for 
other purposes.

\section*{Forecast Metrics}

By default, the code will compute the sensitivity of TC track, intensity, wind speed, and precipitation independently.
The description below is the default behavior of the code that has been tested over many cases, though the user
has the option of modifying the timing and/or the domain of each.

\newpage

\begin{center}
\begin{longtable}{|p{1.0in}|p{5.25in}|}
\caption{Forecast Metric Descriptions} \\
\hline
Metric Name & Description \\  \hline\hline

intmajtrack &
Forecast metric that represents the track perturbation that explains the greatest amount of variability in the
ensemble forecast tracks for a time window in the forecast.  By default, the time window is 24-120 h, hence the 
graphics are in the f120\_intmajtrack directory and the grids are in the track directory in the tar file.
The calculation is done by taking the EOF decomposition of 
the ensemble latitude/longitude values as a function of time, where the metric is the principle component.  By convention,
positive values of the metric are indicative of a TC that will end up further along and/or
to the right of the ensemble-mean track.  The advantage of using this position metric is that it does not 
require specifying a particular lead time and takes into account the temporal correlation of forecast tracks 
(i.e., members that are further west early in the forecast will end up further west later on).  The user can 
modify how this metric is calculated via the track\_eof namelist options in the metric block of the parameter file.
\\ \hline

intmslp &
Forecast metric that represents the minimum SLP time series perturbation that explains the greatest amount of 
variability in the ensemble minimum SLP for a time window in the forecast.  By default, the time window is 48-96 h, hence the 
graphics are in the f096\_intmslp directory and the grids are in the inter directory in the tar file.
The calculation is done by taking the EOF decomposition of 
the ensemble minimum SLP values as a function of time, where the metric is the principle component.  By convention,
positive values of the metric are indicative of a TC that will have lower minimum SLP relative to the ensemble 
mean.  The user can modify how this metric is calculated via the intensity\_eof namelist options in the metric block 
of the parameter file.
\\ \hline

wndeof &
Forecast metric that represents the 2D pattern that explains the greatest amount of variability in the forecast
10~m maximum wind speed within the horizontal and time domain.  By default, the time window is 48-96 h, hence the 
graphics are in the f096\_wndeof directory and the grids are in the wind directory in the tar file.  The domain is 
automatically determined for each storm and initialization time by considering all of the grid points that are within 
300~km of any ensemble member's TC center.  The maximum wind speed is computed for each grid point and member by looping
over all times within the window and finding the highest wind speed.  The greater time frequency, the smoother this
field will appear.  The metric is then calculated by taking the EOF decomposition of 
the 2D maximum wind speed field, where the metric is the principle component.  By convention,
positive values of the metric are indicative of higher winds over the largest amount of the domain, though the metric is
often representative of across-track position shifts.  The user can modify how this metric is calculated via the
wind\_speed\_eof namelist options in the metric block of the parameter file.  Note the user can create a customized 
version of the metric by adding a text file (see namelist options).
\\ \hline

pcpeof &
Forecast metric that represents the 2D forecast precipitation pattern that explains the greatest amount of variability in the 
precipitation within the domain within a window of time.  By default, the time window is 48-120 h, hence the 
graphics are in the f120\_pcpeof directory and the grids are in the pcp directory in the tar file.  The domain is 
automatically determined for each storm and initialization time by considering all contiguous grid points where the 
precipitation exceeds 0.5~in~(24~h)$^{-1}$ during the window, is close to an ensemble member's track, and is over land.
The metric is then calculated by taking the EOF decomposition of the 2D precipitation field for the contiguous set of points, 
where the metric is the principle component.  By convention,
positive values of the metric are indicative of higher precipitation over the largest amount of the domain, though the metric is
often representative of across-track position shifts.  The user can modify how this metric is calculated via the
precip\_eof namelist options in the metric block of the parameter file.  Note the user can create a customized 
version of the metric by adding a text file (see namelist options).
\\ \hline

\end{longtable}
\end{center}

\section*{Forecast Fields}

The table below gives the list of fields for which the sensitivity is computed to for each of the TC metrics.  The ``Metric
Used'' column gives the metrics for which this field appears in the dashboard-style figure.

\begin{center}
\begin{longtable}{|p{1.00in}|p{0.75in}|p{4.50in}|}
\caption{Forecast Field Descriptions} \\
\hline
Field Name & Metric Used & Description \\  \hline\hline

usteer & & Zonal component of the steering flow.  By default, this is designated as the average wind between
300-850~hPa (vortex removed), but this can be changed in the configuration file. \\ \hline

vsteer & & Meridional component of the steering flow.  By default, this is designated as the average wind between
300-850~hPa (vortex removed), but this can be changed in the configuration file. \\ \hline

masteer & intmajtrack, wndeof & Major axis winds are the wind component that is in the direction of greatest track variability for 
that particular case (positive values are either along and/or right of track).  In most situations, the 
sensitivity to the major axis wind is the most useful for sensitivity calculations because it most closely 
relates to variability in subsequent TC position, which is not often in the Cartesian directions.  \\ \hline

csteer & intmajtrack, intmslp, wndeof, pcpeof & 
Vorticity of the steering flow that is computed using the method described in usteer, vsteer.  This
field is most useful for looking at the sensitivity to the steering flow when the TC motion is more curved 
(i.e., rounding subtropical ridges). \\ \hline

q500-850hPa & intmslp, wndeof, pcpeof & Water vapor mixing ratio averaged between 500-850 hPa.  
Useful for looking at mid-tropospheric humidity \\ \hline

vor850hPa & intmslp & 850 hPa vorticity \\ \hline

ivt & pcpeof & Integrated vapor transport between surface and the top of the atmosphere.  \\ \hline

pv250hPa & & 250 hPa potential vorticity \\ \hline

h500 & & 500 hPa height \\ \hline

\end{longtable}
\end{center}

\section*{Interpretation}

The outcome of the sensitivity software is a series of graphics that show the sensitivity of the individual
metrics to the desired fields.  The figure below shows the sensitivity of Hurricane Helene's track forecast to the 
steering wind vorticity valid on 1200 UTC 25 September 2024.  The shading is the sensitivity where warm colors
indicate that increasing the vorticity at that point will result in a more eastern track, while cold colors indicate
that increasing the vorticity of that grid point will yield a more western track.  In this case, there is large
positive sensitivity over the eastern Gulf, meaning that increasing the vorticity in this location, which is at the 
southern end of a high pressure, is associated with a more eastern track.  In addition, there is a dipole of 
positive and negative sensitivity over the large upper trough over the Mississippi valley, such that increasing
the vorticity on the western side and decreasing on the eastern side, akin to shifting the trough to the southwest,
is associated with a more eastern position.  Regardless of sign, the locations of largest sensitivity magnitude
are where observation assets should be deployed (actual dropwindsondes denoted by +).  

An alternative method of visualizing the output is the paintball format, where the shaded region shows locations
where the magnitude of the sensitivity exceeds a minimum value (here 0.3) for a different field (fields vary
depending on metric).  Locations where the sensitivity overlap are locations where observations should be targeted.

\begin{figure}[h]
\centerline{\includegraphics[width=6.5in]{readme_plot.png}}
\caption{(a) Sensitivity of Hurricane Helene's track forecast to the steering wind vorticitiy field at 
1200 UTC 25 September initialized 0000 UTC 24 September 2024 (shading; units: dimensionless).  
The contours in denote the ensemble-mean steering wind vorticity ($\times$~10$^{5}$ s$^{-1}$). The + signs denote dropwindsonde 
deployment locations. (b) Locations where the sensitivity of Hurricane Helene's track forecast to the
major axis steering wind (green) and steering wind vorticity (magenta) exceeds a minimum value for the same
time.}
\end{figure}

\section*{Input Data}

This software requires two main sources of data: gridded ensemble forecast data and TC tracking data in ATCF format.
These files could be any format (i.e., one file per member and forecast hour, or all members in a single file) as long as
the individual python i/o module knows what file to look in for the requested member and forecast hour.  The table below
describes the I/O modules that are currently available and working.

\begin{center}
\begin{longtable}{|p{1.25in}|p{5.00in}|}
\caption{I/O Module characteristics} \\
\hline
I/O Module & Description \\  \hline\hline

ecmwf\_teton & ECMWF ensemble forecast data that is pushed to University at Albany by ECMWF on a daily basis.
These files contain all ensemble members for a single forecast lead time in one file.  User will need to point
to the directory where these files are located.  ATCF files are obtained from a directory on the local server, 
with each file containing the TC track information for all initialization times for a given storm.  These files
are created by downloading the ECMWF binary TC track files and converting to ATCF format. \\ \hline

ecmwf\_aws\_down & ECMWF ensemble forecast data that is copied from a cloud computing platform, such as Amazon Web
Services or Microsoft.  The files are downloaded using the Herbie python package.  All ensemble members for a 
single forecast lead time are merged into one file.
ATCF files are obtained from a directory on the local server, 
with each file containing the TC track information for all initialization times for a given storm.  These files
are created by downloading the ECMWF binary TC track files and converting to ATCF format. \\ \hline

gefs\_aws\_down & GEFS ensemble forecast data that is copied from a cloud computing platform, such as Amazon Web
Services or Microsoft.  The files are downloaded using the Herbie python package.  All ensemble members for a 
single forecast lead time are merged into one file.
ATCF files are obtained by downloading the corresponding file from the NHC public data server. \\ \hline

\end{longtable}
\end{center}

\section*{Parameter File Information}

Below is a description of all potential namelist parameter values along with their default value if it is
not set.

\begin{center}
\begin{longtable}{|p{1.75in}|p{0.5in}|p{4.00in}|}
\caption{Configuration options for the ``model'' subset.} \\
\hline
Parameter Name & Type & Description \\  \hline\hline

model\_src & string & Name of the model being used in the sensitivity calculation.  This is mainly used in
plot titles, so the user can set to whatever they want.  No default value.  \\  \hline

io\_module & string & Name of the module to use for obtaining and reading the grib and ATCF file.  Each
platform and model will have its own module.  This value MUST be set by the user. \\  \hline

projection & string & Map projection for plots.  This is a placeholder for models that are not on
lat/lon grid.  Default:  PlateCarree \\ \hline

flip\_lon & boolean & Swap longitude from -180 to 180 to 0 to 360.  By default, the code uses the 
-180 to 180 longitude convention.  Default False \\ \hline

num\_ens & integer & Number of perturbation ensemble members (i.e., ECMWF has 50 perturbed members, 
GEFS has 30).  No default value, so it must be set. \\  \hline

fcst\_hour\_int & integer & Forecast hour interval for computing forecast fields for sensitivity 
calculations in hours.  Default:  12 h \\  \hline

input\_hour\_int & integer & Forecast hour internal of the input forecast fields.  Default:  6 h \\ \hline

fcst\_hour\_max & integer & Last forecast hour to compute forecast fields for sensitvity 
calculations in hours.  Default 120 h \\  \hline

tigge\_forecast\_time & string & List of forecast hours to read from ECMWF TIGGE archive. \\ \hline

tigge\_forecast\_grid\_space & string & Requested grid spacing for data pulled from the 
TIGGE respository.  Default: 1.0/1.0 (units: degrees) \\ \hline

tigge\_surface\_area & string & Latitude and Longitude grid boundaries to download surface
fields from TIGGE.  Default:  90/-180/-90/179 \\ \hline

tigge\_surface\_time & string & List of forecast hours to read surface fields from the TIGGE archive. \\ \hline

tigge\_surface\_grid\_space & string & Requested grid spacing for surface data pulled from the
TIGGE respository.  Default: 0.25/0.25 (units: degrees) \\ \hline

\end{longtable}
\end{center}

\begin{center}
\begin{longtable}{|p{1.60in}|p{0.5in}|p{4.15in}|}
\caption{Configuration options for the ``locations'' subset.} \\
\hline
Parameter Name & Type & Description \\ \hline\hline

atcf\_dir & string & Path to raw ATCF forecast data on local server.  Usage will depend on 
which io\_module that you use.  No default value \\ \hline

model\_dir & string & Path to raw model data on local server.  
Usage will depend on which io\_module that you use.  No default value \\ \hline

best\_dir & string & Path to best track data on local server.  
Usage will depend on which io\_module that you use.  No default value \\ \hline

work\_dir & string & Path to work directory where sensitivity calculations are carried out
No default value. \\ \hline

output\_dir & string & Path to directory to save certain output of the sensitivity 
calculations, if desired.  No default value.  \\ \hline

script\_dir & string & Path to python scripts and modules (i.e., where this code is located.)
No default value. \\ \hline

figure\_dir & string & Path to directory where output figures will be placed.
No default value.  \\ \hline

outgrid\_dir & string & Path to directory where gridded sensitivity output will be placed.
No default value.  \\ \hline

log\_dir & string & Path to directory where log file output from the python logging function
will be placed.  No default value. \\ \hline

log\_level & string & Logging level to output into the log file.  Default: INFO \\ \hline

archive\_metric & boolean & True to save metric netcdf files into the appropriate 
output\_dir location.  Default:  False \\ \hline

output\_dir & string & Path to directory where archived metric and field files will be 
placed.  Default: False \\ \hline

archive\_fields & boolean & True to save forecast field netcdf files into the appropriate
output\_dir.  Default: False \\ \hline

save\_work\_dir & boolean & True to save work directory at the end of the execution.  Otherwise,
this directory will be deleted to save space.  Default:  False \\ \hline

\end{longtable}
\end{center}

\begin{center}
\begin{longtable}{|p{1.60in}|p{0.5in}|p{4.15in}|}
\caption{Configuration options for the ``vitals\_plot'' subset.  This controls diagnostic figures, 
such as the generic track, intensity and precipitation figures.} \\
\hline
Parameter Name & Type & Description \\ \hline \hline

trackfile & string & Name of figure that shows the TC track forecast.  Default:  track.png \\ \hline

track\_output\_dir & string & Name of directory to place the track plot.  Default: figure\_dir from above \\ \hline

intfile & string & Name of figure that shows the TC intensity forecast.  Default:  intensity.png \\ \hline

int\_output\_dir & string & Name of directory to place the intensity plot.  Default: figure\_dir from above \\ \hline

forecast\_hour\_int & float & Frequency of forecasts from model (hours).  Default: 6 \\ \hline

forecast\_hour\_max & string & Maximum forecast hour for track and intensity plots.  
Default:  120 hours \\ \hline

plot\_ellipse & boolean & True to plot TC position ellipses on plots.  Default:  True \\ \hline

ellipse\_frequency & float & Frequency to plot the position ellipses (hours).  Default: 24 \\ \hline

plot\_best & boolean & True to plot best track information, if available.  Default:  True \\ \hline

projection & string & Map projection to use for vitals plot.  Default:  PlateCarree \\ \hline

grid\_interval & float & Latitude and Longitude line grid interval (degrees).  Default:  5 \\ \hline

title\_string & string & customized string for TC track plots.  Overwrites the default string \\ \hline

precip\_hour\_1 & integer list & list of start forecast hours for precipitation plots.  No Default \\ \hline

precip\_hour\_2 & integer list & list of end forecast hours for precipitation plots.  No Default \\ \hline

min\_lat\_precip & float & Minimum latitude for precipitation forecast plots.  Default:  22.0 \\ \hline

max\_lat\_precip & float & Maximum latitude for precipitation forecast plots.  Default:  50.0 \\ \hline

min\_lon\_precip & float & Minimum longitude for precipitation forecast plots.  Default: -100.0 \\ \hline

max\_lon\_precip & float & Maximum longitude for precipitation forecast plots.  Default: -65.0 \\ \hline

\end{longtable}
\end{center}

\begin{center}
\begin{longtable}{|p{1.75in}|p{0.5in}|p{4.00in}|}
\caption{Configuration options for the ``metric'' subset.  This set of namelist values control the 
forecast metric definition and how it is calculated.} \\
\hline
Parameter Name & Type & Description \\ \hline \hline

metric\_hours & float & Vector list of forecast hours to compute individual time forecast metrics, such as 
position, intensity, etc.  This capability is old and not maintained at this point.  No default value \\ \hline

track\_eof\_metric & boolean & True to calculate the integrated track metric.  Default True \\ \hline

track\_eof\_hour\_init & float & Initial forecast hour to use for integrated track metric (hours).  Default: 24 \\ \hline

track\_eof\_hour\_int & float & Forecast hour interval to use for integrated track metric (hours).  Default:  6 \\ \hline

track\_eof\_hour\_final & float & Final forecast hour to use for integrated track metric (hours).  Default: 120 \\ \hline

track\_eof\_member\_frac & float & Fraction of members that need to be present during a forecast hour for track EOF.  Default:  0.5 \\ \hline

track\_eof\_esign & float & Factor to multiply EOF PC by.  Default 1.0 \\ \hline

title\_string & string & Title string that is placed at the top of the track EOF plot.  This overwrites the default
plot title if it exists.  Default:  None \\ \hline

intensity\_eof\_metric & boolean & True to calculate the time-integrated intensity metric based on min. SLP.
Default True \\ \hline

intensity\_eof\_hour\_init & float & Initial forecast hour to use for integrated intensity metric (hours).  Default: 24 \\ \hline

intensity\_eof\_hour\_int & float & Forecast hour interval to use for integrated intensity metric (hours).  Default:  6 \\ \hline

intensity\_eof\_hour\_final & float & Final forecast hour to use for integrated intensity metric (hours).  Default: 96 \\ \hline

\footnotesize{intensity\_eof\_member\_frac} & float & Fraction of members that need to be present during a forecast hour for intensity EOF.  Default:  0.3 \\ \hline

track\_inten\_eof\_metric & boolean & True to calculate the time-integrated combined track/intensity metric.
Default:  False \\ \hline 

track\_inten\_eof\_hour\_init & float & Initial forecast hour to use for integrated track/intensity metric (hours).  Default: 24 \\ \hline

track\_inten\_eof\_hour\_int & float & Forecast hour interval to use for integrated track/intensity metric (hours).  Default:  6 \\ \hline

track\_inten\_eof\_hour\_final & float & Final forecast hour to use for integrated track/intensity metric (hours).  Default: 120 \\ \hline

\footnotesize{track\_inten\_eof\_member\_frac} & float & Fraction of members that need to be present during a forecast hour for
integrated track/intensity EOF.  Default:  0.5 \\ \hline

track\_inten\_eof\_esign & float & Factor to multiply EOF PC by.  Default 1.0 \\ \hline

kinetic\_energy\_metric & boolean & True to calculate area-average kinetic energy metric.  Default:  False \\ \hline

kinetic\_energy\_radius & float & Radius over which to calculate the average kinetic energy (km).  Default:  200 \\ \hline

kinetic\_energy\_level & float & Pressure level to use for kinetic energy metric (hPa).  Default: 1000 \\ \hline

wind\_speed\_eof\_metric & boolean & True to calculate forecast metric that is EOF/PC of the
wind speed over the specified time window and area.  Default:  False \\ \hline

wind\_metric\_file & string & Path to file that contains precipitation EOF metric settings.
Assumes the file has the format \{yyyymmddhh\}\_\{storm\}\_wind.  No default value. \\ \hline

\footnotesize{wind\_speed\_eof\_forecast\_hour1} & integer & initial forecast hour for calculating the maximum wind speed metric (hour).
This value can be overwritten with a value in the wind\_metric\_file. Default: 48 \\ \hline

\footnotesize{wind\_speed\_eof\_forecast\_hour2} & integer & final forecast hour for calculating the maximum wind speed metric (hour).
This value can be overwritten with a value in the wind\_metric\_file. Default: 96 \\ \hline

wind\_speed\_eof\_adapt & boolean & True to use adaptive algorithm for identifying the wind speed EOF metric
domain based on the forecast times provided.  Default:  True \\ \hline

\footnotesize{wind\_speed\_eof\_dom\_buffer} & float & Distance from forecasted TC center over which the maximum wind speed
metric EOF is calculated.  Default:  300 \\ \hline

precipitation\_metric & boolean & True to calculate forecast metric that is the average
precipitation over the specified time window and area.  Currently experimental.  Default:  False \\ \hline

precipitation\_eof\_metric & boolean & True to calculate forecast metric that is EOF/PC of the 
precipitation over the specified time window and area.  Default:  False \\ \hline

precip\_metric\_file & string & Path to file that contains precipitation EOF metric settings.  
Assumes the file has the format \{yyyymmddhh\}\_\{storm\}\_precip.  No default value. \\ \hline

precip\_eof\_forecast\_hour1 & integer & initial forecast hour for calculating the precipitation metric (hour).
This value can be overwritten with a value in the precip\_metric\_file. Default: 48 \\ \hline

precip\_eof\_forecast\_hour2 & integer & final forecast hour for calculating the precipitation metric (hour).
This value can be overwritten with a value in the precip\_metric\_file.  Default: 120 \\ \hline

precip\_eof\_dom\_buffer & float & Distance from forecasted TC center over which the precipitation
metric EOF is calculated.  Can be overwritten by precip\_metric\_file.  Default:  300 \\ \hline

land\_mask\_minimum & float & Minimum value of the landmask value that is considered land.  1 = all land.
Can be overwritten by precip\_metric\_file.  Default: 0.2 \\ \hline

precip\_eof\_land\_mask & boolean & True to only consider grid points with a value above land\_mask\_minimum.
Can be overwritten by precip\_metric\_file.  Default: True \\ \hline

precip\_eof\_adapt & boolean & True to use adaptive algorithm for identifying the precipitation EOF metric
domain based on the forecast times provided.  Can be overwritten by precip\_metric\_file.  Default:  True \\ \hline

\footnotesize{precip\_eof\_time\_adapt} & boolean & True to use adaptive algorithm for identifying the time period for the 
precipitation EOF metric.  Can be overwritten by precip\_metric\_file.  Default:  True \\ \hline

\footnotesize{precip\_eof\_time\_adapt\_domain} & float & Distance in degrees from the min/max latitude and longitude to 
consider within the adaptive precipitation EOF metric metric.  Can be overwritten by precip\_metric\_file.  
Default:  2.0 \\ \hline

\footnotesize{precip\_eof\_time\_adapt\_freq} & integer & Forecast frequency to use for calculating time period for the
adaptive precipitation EOF metric.  Can be overwritten by precip\_metric\_file.  Default: 6 hours \\ \hline

precip\_eof\_adapt\_pcp\_min & float & Minimum precipitation threshold to consider for the adaptive 
precipitation EOF metric.  Can be overwritten by precip\_metric\_file.  Default:  12.7 (mm) \\ \hline

wind\_precip\_eof\_metric & boolean & True to calculate forecast metric that is EOF/PC of the 
maximum wind speed and precipitation over the specified time window and area.  Uses parameters from the
wind and precipitation EOF metrics.  Default False \\ \hline

fcst\_int & integer & Forecast frequency to use for calculating forecast metrics over time.
Default: 6 hours \\ \hline

static\_fields\_file & string & Path to a grib file that contains static fields, such as the landmask
for use in calculating metrics.  Default:  None \\ \hline

projection & string & Map projection to use for metric plot.  Default:  PlateCarree \\ \hline

grid\_interval & float & Latitude and Longitude line grid interval in metric plots (degrees).  Default:  5 \\ \hline

\end{longtable}
\end{center}

\begin{center}
\begin{longtable}{|p{1.60in}|p{0.5in}|p{4.15in}|}
\caption{Configuration options for the field subset.  This controls the forecast fields for which the sensitivity is computed
to.} \\
\hline
Parameter Name & Type & Description \\ \hline \hline

multiprocessor & boolean & True to calculate fields in serial using multiple processors.  Default:  False \\ \hline

processes & integer & Number of processes to use for computing fields.  Default:  None \\ \hline

calc\_uvsteer & boolean & True to compute the u/v component of the steering wind. Default: True \\ \hline

calc\_steer\_circ & boolean & True to compute the circulation/vorticity from the steering wind.  Default:  False \\ \hline

steer\_level1 & float & Lowest pressure level to use to compute the layer-average steering wind (hPa).  Default: 300 \\ \hline

steer\_level2 & float & Highest pressure level to use to compute the layer-average steering wind (hPa).  Default: 850 \\ \hline

steer\_radius & float & Radius to use for removing the TC from the model fields (km).  Default: 333 \\ \hline

calc\_height & boolean & True to compute gepotential height on specified pressure levels.  Default:  True \\ \hline

height\_levels & float & List of pressure levels to compute the geopotential height (hPa).
Default:  500 \\ \hline

calc\_pv\_pres & boolean & True to compute potential vorticity on specified pressure levels.
Default:  True \\ \hline

pv\_levels & float & List of pressure levels to compute the potential vorticity (hPa).  
Default:  250, 850 hPa \\ \hline  

calc\_theta-e & boolean & True to compute equivalent potential temperature at specified pressure levels.
Default:  False \\ \hline

theta-e\_levels & float & List of pressure levels to compute equivalent potential temperature (hPa).
Default:  700, 850 \\ \hline

calc\_q500-850hPa & boolean & True to compute the integrated water vapor between 500 and 
850~hPa.  Default:  False \\ \hline

calc\_ivt & boolean & True to compute the integrated vapor transport from the available pressure
levels.  Default:  True \\ \hline

calc\_winds & boolean & True to compute zonal and meridional wind at specified pressure levels.
Default:  False \\ \hline

wind\_levels & float & List of pressure levels to compute zonal and meridional wind (hPa).
Default:  850 \\ \hline

calc\_vorticity & boolean & True to compute relative vorticity at specified pressure levels.
Default:  False \\ \hline

vorticity\_levels & float & List of pressure levels to compute relative vorticity (hPa).
Default:  850 \\ \hline

vorticity\_radius & float & Radius to use for calculating the area-average of vorticity,
which is the effective scale of rotation (km).  Default: 115 km \\ \hline  

min\_lat & float & Minimum latitude to compute forecast fields over.  Default:  0.0 \\ \hline

max\_lat & float & Maximum latitude to compute forecast fields over.  Default:  65.0 \\ \hline

min\_lon & float & Minimum longitude to compute forecast fields over.  Default:  -180.0 \\ \hline

max\_lon & float & Maximum longitude to compute forecast fields over.  Default:  -10.0 \\ \hline

global & boolean & True to calculate fields based on a global forecast grid.  Default:  False \\ \hline

\end{longtable}
\end{center}

\begin{center}
\begin{longtable}{|p{1.60in}|p{0.5in}|p{4.15in}|}
\caption{Configuration options for the sens subset.  This set of parameters set the display options
for the sensitivity plots.} \\
\hline
Parameter Name & Type & Description \\  \hline \hline

multiprocessor & boolean & True to calculate sensitivity in serial using multiple processors.  Default:  False \\ \hline

processes & integer & Number of processes to use for computing sensitivity.  Default:  None \\ \hline

metrics & string & List of names of forecast metrics to compute the sensitivity to.  This 
parameter is not used anymore, but can be used.  Default:  none \\ \hline

min\_lat & float & Minimum latitude for sensitivity plots.  Default:  8.0, also set in
run\_NHC\_sens.py based on basin.  \\ \hline

max\_lat & float & Maximum latitude for sensitivity plots.  Default:  65.0, also set in
run\_NHC\_sens.py based on basin.  \\ \hline

min\_lon & float & Minimum longitude for sensitivity plots.  Default:  -140.0, also set in 
run\_NHC\_sens.py based on basin.  \\ \hline

max\_lon & float & Maximum longitude for sensitivity plots.  Default:  -20.0, also set in
run\_NHC\_sens.py based on basin.  \\ \hline

zero\_non\_sig\_sens & boolean & True to plot only the statistically significant 
sensitivity locations.  Default:  False   \\ \hline

grid\_interval & float & Latitude and Longitude line grid interval (degrees).  Default:  10$^{\circ}$.  \\ \hline

barb\_interval & integer & Number of grid points in between each wind barb in the plot.
Default:  6 grid points  \\ \hline

cbar\_shrink & float & width of colorbar within the figure.  Used to set shrink keyword in matplotlib.
Default: 1.0 \\ \hline

title\_string & string & String that will overwrite the basic title string used in the plots. \\ \hline

storm\_center\_radius & float & Radius from the TC center used in storm-center plots 
(degrees).  Default:  10 \\ \hline

dropsonde\_file & string & Full path to file of dropsonde locations.  Default:  none \\ \hline

drop\_file\_type & string & Type of dropsonde file to read. Default: nhc \\ \hline

drop\_mark\_size & integer &  Marker size of dropsonde locations in plot.  Default:  6 \\ \hline

drop\_mark\_color & string & Dropsonde marker color in plot.  Default: black \\ \hline

drop\_mark\_type & string & Dropsonde marker in plot.  Default: + \\ \hline

rawinsonde\_file & string & Full path to file of rawinsonde locations.  Default:  none \\ \hline

rawin\_mark\_size & integer & Marker size of rawinsonde locations in plot.  Default:  6 \\ \hline

rawin\_mark\_color & string & Rawinsonde marker color in plot.  Default: gray \\ \hline

turns\_file & string & Full path to file of aircraft turn locations.  Default:  none \\ \hline

turn\_line\_width & float & Line width of aircraft track.  Default: 2 \\ \hline

turn\_line\_color & string & Aircraft track line color in plot.  Default: black \\ \hline

turn\_file\_type & string & Type of aircraft turn file to read.  Default: nhc \\ \hline

range\_rings & boolean & True to plot range rings from the predicted TC center.  Default: True \\ \hline

ring\_values & floats & List of range ring radii for plot in km.  Default:  \\ \hline

range\_linewidth & float & Linewidth of the range rings.  Default: 1 \\ \hline

range\_colors & float & Color of the range rings.  Default: gray \\ \hline

plot\_summary & boolean & True to plot summary style figures used for the NHC 
dashboard format.  Default: False \\ \hline

output\_sens & boolean & True to create netCDF file that contains gridded sensitivity 
fields that can be used in AWIPS or traveling salesman.  Default:  True \\ \hline

nhc\_sens & boolean & True to create NHC version of the gridded netCDF file, which means that
it includes a variable that is the absolute value of sensitivity (for traveling salesman software)
and range rings.  Default:  False \\ \hline

wind\_levels & integer & List of pressure levels to plot wind sensitivity.  Default:  None \\ \hline

vorticity\_levels & integer & List of pressure levels to plot vorticity sensitivity.  Default:  None \\ \hline

\end{longtable}
\end{center}

\section*{Conda Information}

The code requires the minimum set of conda packages: ipython, numpy, cartopy, metpy, netcdf4, 
pandas, matplotlib, xarray, configparser, scipy, eofs, windspharm.  In addition, grib files are read using cfgrib 
for most of the I/O modules, though other possibilities exist.  All of these are fairly standard python packages, except
windspharm, which is frozen.  All of this packages can be downloaded from conda-forge stream.  Once all of the packages
are installed, you will need to compile the grid\_calc fortran code into a python object.  Computing spatial averages within
python can be very expensive, so this speeds up the calculation greatly.  In order to compile this code, go into the 
esens-util directory and type:  ``python -m numpy.f2py -c grid\_calc.f90 -m grid\_calc''.  The resulting object file will
need to be renamed grid\_calc.so.

\end{document}