Feature 1474 README (#1582)

* Changed name of README and README_TC, modified references to those, and cleaned up some formatting.

* Fixed formatting and language

* Update data_io.rst

* Update data_io.rst

* Update config_options_tc.rst

Co-authored-by: johnhg <johnhg@ucar.edu>

met/docs/Users_Guide/README.rst → met/docs/Users_Guide/config_options.rst

@@ -1,17 +1,17 @@
-.. _README:
+.. _config_options:
 
-======================================
- README - Configuration File Overview
-======================================
+
+Configuration File Overview
+===========================
 
 The configuration files that control many of the MET tools contain formatted
 ASCII text. This format has been updated for MET version |version| and
 continues to be used in subsequent releases.
 
-Settings common to multiple tools are described in the top part of this README
+Settings common to multiple tools are described in the top part of this
 file and settings specific to individual tools are described beneath the common
-settings. Please refer to the MET User's Guide in the "doc" directory for more
-details about the settings if necessary.
+settings. Please refer to the MET User's Guide for more details about the
+settings if necessary.
 
 A configuration file entry is an entry name, followed by an equal sign (=),
 followed by an entry value, and is terminated by a semicolon (;). The
@@ -288,12 +288,8 @@ References:
 |
 
 
-Configuration settings used by the MET tools
-============================================
-
-
 Settings common to multiple tools
----------------------------------
+_________________________________
 
 **exit_on_warning**
 
@@ -2174,7 +2170,7 @@ are empty. Note: grib_code 11 is equivalent to obs_var "TMP".
   }
 
 Settings specific to individual tools
--------------------------------------
+_____________________________________
 
 EnsembleStatConfig_default
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

met/docs/Users_Guide/README_TC.rst → met/docs/Users_Guide/config_options_tc.rst

@@ -1,9 +1,9 @@
-.. _README_TC:
+.. _config_options_tc:
 
-README_TC Configuration File Overview
-=====================================
+Tropical Cyclone Configuration Options
+======================================
 
-See :ref:`README`
+See :numref:`config_options` for a description of the configuration file syntax.
 
 Configuration settings common to multiple tools
 _______________________________________________

met/docs/Users_Guide/data_io.rst

@@ -251,26 +251,8 @@ The following is a summary of the input and output formats for each of the tools
 Configuration File Details
 __________________________
 
-Part of the strength of MET is the leveraging of capability across tools. There are several config options that are common to many of the tools. They are described in this section.
+Part of the strength of MET is the leveraging of capability across tools. There are several configuration options that are common to many of the tools.
 
 Many of the MET tools use a configuration file to set parameters. This prevents the command line from becoming too long and cumbersome and makes the output easier to duplicate.
 
-Settings common to multiple tools are described in the following sections while those specific to individual tools are explained in the sections for those tools. In addition, these configuration settings are described in the *README* file and the *README_TC* file for the MET-Tropical Cyclone tools.
-
-.. _Data IO MET Configuration File Options:
-
-MET Configuration File Options
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The information listed below may also be found in the *README* file.
-
-:ref:`README`
-
-.. _Data IO MET-TC Configuration File Options:
-
-MET-TC Configuration File Options
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The information listed below may also be found in the *README_TC* file.
-
-:ref:`README_TC`
+The configuration file details are described in :ref:`config_options` and :ref:`config_options_tc`.

met/docs/Users_Guide/ensemble-stat.rst

@@ -147,7 +147,7 @@ ____________________
   output_prefix  = "";
   version        = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`Data IO MET Configuration File Options`.
+The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
 
 _____________________
 
@@ -244,7 +244,7 @@ ____________________
   prob_cat_thresh    = [];
 
 
-Setting up the **fcst** and **obs** dictionaries of the configuration file is described in :numref:`Data IO MET Configuration File Options`. The following are some special considerations for the Ensemble-Stat tool.
+Setting up the **fcst** and **obs** dictionaries of the configuration file is described in :numref:`config_options`. The following are some special considerations for the Ensemble-Stat tool.
 
 
 The **ens** and **fcst** dictionaries do not need to include the same fields. Users may specify any number of ensemble fields to be summarized, but generally there are many fewer fields with verifying observations available. The **ens** dictionary specifies the fields to be summarized while the **fcst** dictionary specifies the fields to be verified.
@@ -396,7 +396,7 @@ The **rng** group defines the random number generator **type** and **seed** to b
 The **seed** variable may be set to a specific value to make the assignment of ranks fully repeatable. When left empty, as shown above, the random number generator seed is chosen automatically which will lead to slightly different bootstrap confidence intervals being computed each time the data is run.
 
 
-Refer to the description of the **boot** entry in :numref:`Data IO MET Configuration File Options` for more details on the random number generator.
+Refer to the description of the **boot** entry in :numref:`config_options` for more details on the random number generator.
 
 
 ensemble_stat output

met/docs/Users_Guide/grid-diag.rst

@@ -66,7 +66,7 @@ _____________________
   mask          = { grid = ""; poly = ""; }
   version       = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`Data IO MET Configuration File Options`.
+The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
 
 _____________________
 

met/docs/Users_Guide/grid-stat.rst

@@ -60,7 +60,7 @@ The confidence intervals for the Grid-Stat tool are the same as those provided f
 Grid weighting
 ~~~~~~~~~~~~~~
 
-When computing continuous statistics on a regular large scale or global latitude-longitude grid, weighting may be applied in order to compensate for the meridian convergence toward higher latitudes. Grid square area weighting or weighting based on the cosine of the latitude are two configuration options in both point-stat and grid-stat. See :numref:`Data IO MET Configuration File Options` for more information.
+When computing continuous statistics on a regular large scale or global latitude-longitude grid, weighting may be applied in order to compensate for the meridian convergence toward higher latitudes. Grid square area weighting or weighting based on the cosine of the latitude are two configuration options in both point-stat and grid-stat. See :numref:`config_options` for more information.
 
 Neighborhood methods
 ~~~~~~~~~~~~~~~~~~~~
@@ -227,7 +227,7 @@ __________________________
   output_prefix  = "";
   version        = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`Data IO MET Configuration File Options`.
+The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
 
 ___________________________
 

met/docs/Users_Guide/index.rst

@@ -47,6 +47,8 @@ The National Center for Atmospheric Research (NCAR) is sponsored by NSF. The DTC
    overview
    installation
    data_io
+   config_options
+   config_options_tc
    reformat_point
    reformat_grid
    masking
@@ -69,8 +71,6 @@ The National Center for Atmospheric Research (NCAR) is sponsored by NSF. The DTC
    tc-rmw
    rmw-analysis
    plotting
-   README
-   README_TC
    refs
    appendixA
    appendixB

met/docs/Users_Guide/installation.rst

@@ -119,7 +119,7 @@ As described in the introduction to this section, two additional utilities are s
 MET directory structure
 _______________________
 
-The top-level MET directory consists of a README file, Makefiles, configuration files, and several subdirectories. The top-level Makefile and configuration files control how the entire toolkit is built. Instructions for using these files to build MET can be found in :numref:`Install_Building-the-MET`.
+The top-level MET directory consists of  Makefiles, configuration files, and several subdirectories. The top-level Makefile and configuration files control how the entire toolkit is built. Instructions for using these files to build MET can be found in :numref:`Install_Building-the-MET`.
 
 When MET has been successfully built and installed, the installation directory contains two subdirectories. The bin/ directory contains executables for each module of MET as well as several plotting utilities. The share/met/ directory contains many subdirectories with data required at runtime and a subdirectory of sample R scripts utilities. The colortables/, map/, and ps/ subdirectories contain data used in creating PostScript plots for several MET tools. The poly/ subdirectory contains predefined lat/lon polyline regions for use in selecting regions over which to verify. The polylines defined correspond to verification regions used by NCEP as described in :numref:`Appendix B, Section %s <appendixB>`. The config/ directory contains default configuration files for the MET tools. The python/ subdirectory contains sample scripts used in Python embedding (:numref:`Appendix F, Section %s <appendixF>`). The table_files/ and tc_data/ subdirectories contain GRIB table definitions and tropical cyclone data, respectively. The Rscripts/ subdirectory contains a handful of plotting graphic utilities for MET-TC. These are the same Rscripts that reside under the top-level MET scripts/Rscripts directory, other than it is the installed location. The wrappers/ subdirectory contains code used in Python embedding (:numref:`Appendix F, Section %s <appendixF>`).
 

met/docs/Users_Guide/masking.rst

@@ -164,4 +164,4 @@ In this example, the Gen-Vx-Mask tool will read the ASCII Lat/Lon file named **C
 Feature-Relative Methods
 ________________________
 
-This section contains a description of several methods that may be used to perform feature-relative (or event -based) evaluation. The methodology pertains to examining the environment surrounding a particular feature or event such as a tropical, extra-tropical cyclone, convective cell, snow-band, etc. Several approaches are available for these types of investigations including applying masking described above (e.g. circle or box) or using the “FORCE” interpolation method in the regrid configuration option (see :numref:`Data IO MET Configuration File Options`). These methods generally require additional scripting, including potentially storm-track identification, outside of MET to be paired with the features of the MET tools. METplus may be used to execute this type of analysis.  Please refer to the `METplus User's Guide <https://dtcenter.github.io/METplus/>`__.
+This section contains a description of several methods that may be used to perform feature-relative (or event -based) evaluation. The methodology pertains to examining the environment surrounding a particular feature or event such as a tropical, extra-tropical cyclone, convective cell, snow-band, etc. Several approaches are available for these types of investigations including applying masking described above (e.g. circle or box) or using the “FORCE” interpolation method in the regrid configuration option (see :numref:`config_options`). These methods generally require additional scripting, including potentially storm-track identification, outside of MET to be paired with the features of the MET tools. METplus may be used to execute this type of analysis.  Please refer to the `METplus User's Guide <https://dtcenter.github.io/METplus/>`__.

met/docs/Users_Guide/mode-td.rst

@@ -253,7 +253,7 @@ ______________________
   output_prefix  = "";
   version        = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`Data IO MET Configuration File Options`.
+The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
 
 ______________________
 

met/docs/Users_Guide/mode.rst

@@ -195,7 +195,7 @@ _____________________
   output_prefix  = "";
   version        = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`Data IO MET Configuration File Options`.
+The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
 
 
 _____________________
@@ -239,9 +239,9 @@ _____________________
   }
   obs = fcst; 
 
-The **field** entries in the forecast and observation dictionaries specify the model and observation variables and level to be compared. See a more complete description of them in :numref:`Data IO MET Configuration File Options`. In the above example, the forecast settings are copied into the observation dictionary using **obs = fcst;.**
+The **field** entries in the forecast and observation dictionaries specify the model and observation variables and level to be compared. See a more complete description of them in :numref:`config_options`. In the above example, the forecast settings are copied into the observation dictionary using **obs = fcst;.**
 
-The **censor_thresh** and **censor_val** entries are used to censor the raw data as described in :numref:`Data IO MET Configuration File Options`. Their functionality replaces the **raw_thresh** entry, which is deprecated in met-6.1. Prior to defining objects, it is recommended that the raw fields should be made to look similar to each other. For example, if the model only predicts values for a variable above some threshold, the observations should be thresholded at that same level. The censor thresholds can be specified using symbols. By default, no censor thresholding is applied.
+The **censor_thresh** and **censor_val** entries are used to censor the raw data as described in :numref:`config_options`. Their functionality replaces the **raw_thresh** entry, which is deprecated in met-6.1. Prior to defining objects, it is recommended that the raw fields should be made to look similar to each other. For example, if the model only predicts values for a variable above some threshold, the observations should be thresholded at that same level. The censor thresholds can be specified using symbols. By default, no censor thresholding is applied.
 
 The **conv_radius** entry defines the radius of the circular convolution applied to smooth the raw fields. The radii are specified in terms of grid units. The default convolution radii are defined in terms of the previously defined **grid_res** entry. Multiple convolution radii may be specified as an array (e.g. **conv_radius = [ 5, 10, 15 ];**).
 
@@ -329,7 +329,7 @@ _____________________
      poly_flag = NONE; // Apply to NONE, FCST, OBS, or BOTH
   }
 
-Defining a **grid** and **poly** masking region is described in :numref:`Data IO MET Configuration File Options`. Applying a masking region when running MODE sets all grid points falling outside of that region to missing data, effectively limiting the area of which objects should be defined.
+Defining a **grid** and **poly** masking region is described in :numref:`config_options`. Applying a masking region when running MODE sets all grid points falling outside of that region to missing data, effectively limiting the area of which objects should be defined.
 
 The **grid_flag** and **poly_flag** entries specify how the grid and polyline masking should be applied:
 
@@ -425,7 +425,7 @@ _____________________
      color_table = "MET_BASE/colortables/mode_obj.ctable";
   }
 
-Specifying dictionaries to define the **color_table, plot_min**, and **plot_max** entries are described in :numref:`Data IO MET Configuration File Options`.
+Specifying dictionaries to define the **color_table, plot_min**, and **plot_max** entries are described in :numref:`config_options`.
 
 The MODE tool generates a color bar to represent the contents of the colortable that was used to plot a field of data. The number of entries in the color bar matches the number of entries in the color table. The values defined for each color in the color table are also plotted next to the color bar.
 

met/docs/Users_Guide/plotting.rst

@@ -91,7 +91,7 @@ ______________________
 
 The **grid_data** dictionary defines a gridded field of data to be plotted as a base image prior to plotting point locations on top of it. The data to be plotted is specified by the **field** array. If **field** is empty, no base image will be plotted. If **field** has length one, the requested data will be read from the input file specified by the **-plot_grid** command line argument.
 
-The **grid_plot_info** dictionary inside **grid_data** specifies the options for for plotting the gridded data. The options within **grid_plot_info** are described in :numref:`Data IO MET Configuration File Options`.
+The **grid_plot_info** dictionary inside **grid_data** specifies the options for for plotting the gridded data. The options within **grid_plot_info** are described in :numref:`config_options`.
 
 ______________________
 
@@ -153,7 +153,7 @@ ______________________
   censor_thresh = [];
   censor_val    = [];
   
-The **convert(x)** function, **censor_thresh** option, and **censor_val** option may be specified separately for each **point_data** array entry to transform the observation values prior to plotting. These options are further described in :numref:`Data IO MET Configuration File Options`.
+The **convert(x)** function, **censor_thresh** option, and **censor_val** option may be specified separately for each **point_data** array entry to transform the observation values prior to plotting. These options are further described in :numref:`config_options`.
 
 ______________________
 

met/docs/Users_Guide/point-stat.rst

@@ -345,11 +345,11 @@ ________________________
   output_prefix  = "";
   version        = "VN.N";
 
-The configuration options listed above are common to many MET tools and are described in :numref:`Data IO MET Configuration File Options`.
+The configuration options listed above are common to many MET tools and are described in :numref:`config_options`.
 
 _________________________
 
-Setting up the **fcst** and **obs** dictionaries of the configuration file is described in :numref:`Data IO MET Configuration File Options`. The following are some special considerations for the Point-Stat tool.
+Setting up the **fcst** and **obs** dictionaries of the configuration file is described in :numref:`config_options`. The following are some special considerations for the Point-Stat tool.
 
 The **obs** dictionary looks very similar to the **fcst** dictionary. When the forecast and observation variables follow the same naming convention, one can easily copy over the forecast settings to the observation dictionary using **obs = fcst;**. However when verifying forecast data in NetCDF format or verifying against not-standard observation variables, users will need to specify the **fcst** and **obs** dictionaries separately. The number of fields specified in the **fcst** and **obs** dictionaries must match.