Per #392, update TC-Pairs documentation based on changes to the TCDIA…

…G line type.

data/config/TCPairsConfig_default

@@ -143,9 +143,8 @@ watch_warn = {
 diag_name = [];
 
 //
-// Unit conversions to be applied to diagnostic values
+// Unit conversions to be applied based on diagnostic names and units
 //
-
 diag_convert_map = [
    { source = "TCDIAG";
      key = [ "(10C)", "(10KT)", "(10M/S)" ];

docs/Users_Guide/tc-pairs.rst

@@ -34,11 +34,10 @@ The usage statement for tc_pairs is shown below:
 .. code-block:: none
 
   Usage: tc_pairs
-         -adeck source and/or -edeck source
-         -bdeck source
+         -adeck path and/or -edeck path
+         -bdeck path
          -config file
-         [-tcdiag source]
-         [-lsdiag source]
+         [-diag source path]
          [-out base]
          [-log file]
          [-v level]
@@ -48,28 +47,30 @@ tc_pairs has required arguments and can accept several optional arguments.
 Required arguments for tc_pairs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-1. The **-adeck source** argument indicates the adeck TC-Pairs acceptable format data source containing tropical cyclone model forecast (output from tracker) data to be verified. Acceptable data formats are limited to the standard ATCF format and the one column modified ATCF file, generated by running the tracker in genesis mode. It specifies the name of a TC-Pairs acceptable format file or top-level directory containing TC-Pairs acceptable format files ending in ".dat" to be processed. The **-adeck** or **-edeck** option must be used at least once.
+1. The **-adeck path** argument indicates the adeck TC-Pairs acceptable format data containing tropical cyclone model forecast (output from tracker) data to be verified. Acceptable data formats are limited to the standard ATCF format and the one column modified ATCF file, generated by running the tracker in genesis mode. It specifies the name of a TC-Pairs acceptable format file or top-level directory containing TC-Pairs acceptable format files ending in ".dat" to be processed. The **-adeck** or **-edeck** option must be used at least once.
 
-2. The **-edeck source** argument indicates the edeck ATCF format data source containing probabilistic track data to be verified. It specifies the name of an ATCF format file or top-level directory containing ATCF format files ending in ".dat" to be processed. The **-adeck** or **-edeck** option must be used at least once.
+2. The **-edeck path** argument indicates the edeck ATCF format data containing probabilistic track data to be verified. It specifies the name of an ATCF format file or top-level directory containing ATCF format files ending in ".dat" to be processed. The **-adeck** or **-edeck** option must be used at least once.
 
-3. The **-bdeck source** argument indicates the TC-Pairs acceptable format data source containing the tropical cyclone reference dataset to be used for verifying the adeck source. This source is typically the NHC Best Track Analysis, but could be any TC-Pairs acceptable formatted reference. The acceptable data formats for bdecks are the same as those for adecks. This argument specifies the name of a TC-Pairs acceptable format file or top-level directory containing TC-Pairs acceptable format files ending in ".dat" to be processed. 
+3. The **-bdeck path** argument indicates the TC-Pairs acceptable format data containing the tropical cyclone reference dataset to be used for verifying the adeck data. This data is typically the NHC Best Track Analysis, but could be any TC-Pairs acceptable formatted reference. The acceptable data formats for bdecks are the same as those for adecks. This argument specifies the name of a TC-Pairs acceptable format file or top-level directory containing TC-Pairs acceptable format files ending in ".dat" to be processed.
 
 4. The **-config file** argument indicates the name of the configuration file to be used. The contents of the configuration file are discussed below.
 
 Optional arguments for tc_pairs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-5. The **-tcdiag source** argument indicates the TC-Pairs acceptable format data source containing the tropical cyclone diagnostics dataset corresponding to the adeck tracks. This argument specifies the name of a TC-Pairs acceptable format file or top-level directory containing TC-Pairs acceptable format files ending in ".dat" to be processed.
+5. The **-diag source path** argument indicates the TC-Pairs acceptable format data containing the tropical cyclone diagnostics dataset corresponding to the adeck tracks. The **source** can be set to TCDIAG, LSDIAG_RT, or LSDIAG_DEV to indicate the input diagnostics data source. The **path** argument specifies the name of a TC-Pairs acceptable format file or top-level directory containing TC-Pairs acceptable format files ending in ".dat" to be processed.
 
-6. The **-lsdiag source** argument indicates the TC-Pairs acceptable format data source containing the large scale diagnostics dataset corresponding to the adeck tracks. This argument specifies the name of a TC-Pairs acceptable format file or top-level directory containing TC-Pairs acceptable format files ending in ".dat" to be processed.
+6. The -**out base** argument indicates the path of the output file base. This argument overrides the default output file base (**./out_tcmpr**).
 
-7. The -**out base** argument indicates the path of the output file base. This argument overrides the default output file base (**./out_tcmpr**).
+7. 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 log file.
 
-8. 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 log file.
+8. 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.
 
-9. 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.
+This tool currently only supports the rapid intensification (**RI**) edeck probability type but support for additional edeck probability types will be added in future releases.
 
-This tool currently only supports the rapid intensification (**RI**) edeck probability type but support for additional edeck probability types will be added in future releases. At least one **-adeck** or **-edeck** option must be specified. The **-adeck, -edeck**, and **-bdeck** options may optionally be followed with **suffix=string** to append that string to all model names found within that data source. This option may be useful when processing track data from two different sources which reuse the same model names. The **-tcdiag** and **-lsdiag** options may optionally be followed with **model=string** to override the model name of the tracks to which those diagnostics correspond. The **string** specifies a comma-separated list of one or more ATCF ID's to which these diagnostics should be paired (e.g. **model=OFCL,SHIP**).
+At least one **-adeck** or **-edeck** option must be specified. The **-adeck, -edeck**, and **-bdeck** options may optionally be followed with **suffix=string** to append that string to all model names found within that data source. This option may be useful when processing track data from two different sources which reuse the same model names.
+
+The **-diag** option may optionally be followed with **model=string** to override the model name of the tracks to which those diagnostics correspond. The **string** specifies a comma-separated list of one or more ATCF ID's to which these diagnostics should be paired (e.g. **model=OFCL,SHIP**).
 
 An example of the tc_pairs calling sequence is shown below:
 
@@ -83,6 +84,8 @@ The TC-Pairs tool implements the following logic:
 
 • Parse the adeck, edeck, and bdeck data files and store them as track objects.
 
+• Parse diagnostics data files and add the requested diagnostics to the existing adeck track objects.
+
 • Apply configuration file settings to filter the adeck, edeck, and bdeck track data down to a subset of interest.
 
 • Apply configuration file settings to derive additional adeck track data, such as interpolated tracks, consensus tracks, time-lagged tracks, and statistical track and intensity models.
@@ -265,14 +268,29 @@ ____________________
 
 .. code-block:: none
 
-  tcdiag_convert_map = [
-    { key = [ "(10C)", "(10KT)", "(10M/S)" ]; convert(x) = x / 10; }
+  diag_convert_map = [
+     { source = "TCDIAG";
+       key = [ "(10C)", "(10KT)", "(10M/S)" ];
+       convert(x) = x / 10; },
+
+     { source = "LSDIAG_RT";
+       key = [ "CSST", "RSST", "DSST", "DSTA", "XDST", "XNST", "NSST", "NSTA",
+               "NTMX", "NTFR", "U200", "U20C", "V20C", "E000", "EPOS", "ENEG", "EPSS", "ENSS",
+               "T000", "TLAT", "TLON", "TWAC", "TWXC", "G150", "G200", "G250", "V000", "V850",
+               "V500", "V300", "PENC", "SHDC", "SHGC", "T150", "T200", "T250", "SHRD", "SHRS",
+               "SHRG", "PENV", "HE07", "HE05", "PW01", "PW02", "PW03", "PW04", "PW05", "PW06",
+               "PW07", "PW08", "PW09", "PW10", "PW11", "PW12", "PW13", "PW14", "PW15", "PW16",
+               "PW17", "PW18", "PW20", "PW21" ];
+       convert(x) = x / 10; },
+
+     { source = "LSDIAG_RT";
+       key = [ "VVAV", "VMFX", "VVAC" ];
+       convert(x) = x / 100; }
   ];
-  lsdiag_convert_map = [];
 
-The **tcdiag_convert_map** and **lsdiag_convert_map** entries define conversion functions to be applied to diagnostics data read with the **-tcdiag** and **-lsdiag** command line options, respectively. Each array element is a dictionary consisting of a **key** and **convert(x)** entry.
+The **diag_convert_map** entries define conversion functions to be applied to diagnostics data read with the **-diag** command line option. Each array element is a dictionary consisting of a **source**, **key**, and **convert(x)** entry.
 
-The **key** is an array of strings. For **-tcdiag** inputs, the strings can specify diagnostic names or units. If both the name and units are specified, the conversion function for the name takes precedence. For **-lsdiag** inputs, the strings specify diagnostic names since no unit strings are provided. **convert(x)** is a function of one variable which defines how the diagnostic data should be converted. The defined function is applied to any diagnostic value who name or units appears in the **key**.
+The **source** is one of the supported diagnostics data sources. The **key** is an array of strings. The strings can specify diagnostic names or units, although units are only checked for **TCDIAG** sources. If both the name and units are specified, the conversion function for the name takes precedence. **convert(x)** is a function of one variable which defines how the diagnostic data should be converted. The defined function is applied to any diagnostic value who name or units appears in the **key**.
 
 ____________________
 
@@ -551,12 +569,15 @@ TC-Pairs produces output in TCST format. The default output file name can be ove
     - INDEX
     - Index of the current track pair
   * - 16
+    - SOURCE
+    - Diagnostics data source
+  * - 17
     - N_DIAG
     - Number of storm diagnostic name and value columns to follow
-  * - 17
+  * - 18
     - DIAG_i
     - Name of the of the ith storm diagnostic (repeated)
-  * - 18
+  * - 19
     - VALUE_i
     - Value of the ith storm diagnostic (repeated)
 

internal/test_unit/config/TCPairsConfig_DIAGNOSTICS

@@ -134,7 +134,7 @@ watch_warn = {
 diag_name = [ ${DIAG_NAME} ];
 
 //
-// Unit conversions to be applied to diagnostic values
+// Unit conversions to be applied based on diagnostic names and units
 // Commented out to use settings from the default config file
 //
 // diag_convert_map = [];