.. _rmw-analysis:

*****************
RMW-Analysis Tool
*****************

Introduction
============

The RMW-Analysis tool analyzes a set of output files generated by the TC-RMW tool. For each grid cell it aggregates variable statistics across the set and across the track points of the TC-RMW output files. The statistics are mean, standard deviation, minimum and maximum. Note that TC-RMW should be set to use the same scale factor of the radius of maximum winds (RMW) as the unit of range for its range-azimuth grid. The specified data variables on the range-azimuth-vertical grid then share a common range scale of RMW before aggregation by RMW-Analysis.

Practical Information
=====================

rmw_analysis Usage
------------------

The following sections describe the usage statement, required arguments, and optional arguments for **rmw_analysis**.

_______________________

.. code-block:: none

  Usage: rmw_analysis
         -data file_1 ... file_n | file_list
         -config file
         -out file
         [-log file]
         [-v level]

**rmw_analysis** has three required arguments and can accept several optional arguments.

Required Arguments for rmw_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. The **-data file_1 ... file_n | file_list** option specifies the NetCDF TC-RMW output files or ASCII file list of file names to be processed, as described in :numref:`ascii_file_lists`.

2. The **-config file** argument is the **RMWAnalysisConfig** to be used. The contents of the configuration file are discussed below.

3. The **-out** file argument is the NetCDF output file to be written.

Optional Arguments for rmw_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

4. The **-log file** option directs output and errors to the specified log file. All messages will be written to that file as well as standard out and error. Thus, users can save the messages without having to redirect the output on the command line. The default behavior is no logfile.

5. The **-v level** option indicates the desired level of verbosity. The contents of "level" will override the default setting of 2. Setting the verbosity to 0 will make the tool run with no log messages, while increasing the verbosity above 1 will increase the amount of logging.

rmw_analysis Configuration File
-------------------------------

The default configuration file for the RMW-Analysis tool named **RMWAnalysisConfig_default** can be found in the installed *share/met/config/* directory. It is encouraged for users to copy these default files before modifying their contents. The contents of the configuration file are described in the subsections below.

______________________

.. code-block:: none

  data = {
     level = [ "" ];
     field = [
        { name = "PRMSL"; },
        { name = "TMP";   }
     ];
  }

  version = "VN.N";

The :code:`data` dictionary specifies the name of the 2D and 3D gridded variables to be processed from the TC-RMW NetCDF output files. Its formatting is the same as the :code:`fcst` and :code:`obs` dictionaries, used in the MET statistics tools. However, while the :code:`level` string must be specified, it is not actually used and can remain as its default setting of an empty string. TC-RMW reads data for all variables requested and summarizes it through time for all tracks that meet the filtering criteria described below.

The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.

____________________

.. code-block:: none

  model      = [];
  storm_id   = [];
  basin      = [];
  cyclone    = [];
  storm_name = [];

  init_beg   = "";
  init_end   = "";
  init_inc   = [];
  init_exc   = [];

  valid_beg  = "";
  valid_end  = "";
  valid_inc  = [];
  valid_exc  = [];

  init_hour  = [];
  valid_hour = [];
  lead       = [];

  init_mask  = "";
  valid_mask = "";

  category   = [];

  column_thresh_name = [];
  column_thresh_val  = [];

  init_thresh_name = [];
  init_thresh_val  = [];

The NetCDF output from TC-RMW contains ATCF-formatted storm track information in the :code:`TrackLines` variable. The RMW-Analysis tool parses that track information and applies the filtering criteria listed above. Filtering is only applied for configuration entries that are non-empty lists or strings. The corresponding gridded data is only used for track points that meet all specified filtering criteria.

The :code:`column_thresh_name` and :code:`init_thresh_name` arrays specify the names of ATCF columns whose values should be checked. The former applies to each individual track point while the latter applies to the initial track point (i.e. lead time equals 0). If the filtering criteria is not satisfied for the initial time, the entire track is discarded. Only values from select ATCF columns (LAT, LON, VMAX, MSLP, POUTER, ROUTER, RMW, GUSTS, EYE, DIR, and SPEED) can be thresholded numerically with these options to filter the input data processed. 

These configuration options are described in :numref:`config_options_tc`.

rmw_analysis Output File
------------------------

The NetCDF output file will inherit the spatial grid from the first TC-RMW output file in the output file list. All TC-RMW files in this list must have the same grid dimension sizes, although their center (lat, lon) location can vary. A NetCDF output error will result if that is not the case. For each data variable specified in the config file, four corresponding NetCDF variables will be written. For example, for :code:`TMP` input, output variables named :code:`TMP_mean`, :code:`TMP_stdev`, :code:`TMP_min`, and :code:`TMP_max` will be written containing the mean, standard deviation, minimum, and maximum temperature values for each RMW grid location. No track point dimension is retained in the RMW-Analysis output, but the :code:`TrackLat_mean` and :code:`TrackLon_mean` output variables specify the average location of the track points processed.