Feature #1371 series_analysis

docs/Users_Guide/series-analysis.rst

@@ -33,6 +33,7 @@ The usage statement for the Series-Analysis tool is shown below:
          -fcst  file_1 ... file_n | fcst_file_list
          -obs   file_1 ... file_n | obs_file_list
          [-both file_1 ... file_n | both_file_list]
+         [-aggr file]
          [-paired]
          -out file
          -config file
@@ -58,13 +59,17 @@ Optional Arguments for series_analysis
 
 5. To set both the forecast and observations to the same set of files, use the optional -both file_1 ... file_n | both_file_list option to the same set of files. This is useful when reading the NetCDF matched pair output of the Grid-Stat tool which contains both forecast and observation data.
 
-6. The -paired option indicates that the -fcst and -obs file lists are already paired, meaning there is a one-to-one correspondence between the files in those lists. This option affects how missing data is handled. When -paired is not used, missing or incomplete files result in a runtime error with no output file being created. When -paired is used, missing or incomplete files result in a warning with output being created using the available data.
+6. The -aggr option specifies the path to an existing Series-Analysis output file. When computing statistics for the input forecast and observation data, Series-Analysis aggregates the partial sums (SL1L2, SAL1L2 line types) and contingency table counts (CTC, MCTC, and PCT line types) with data provided in the aggregate file. This option enables Series-Analysis to run iteratively and update existing partial sums, counts, and statistics with new data.
 
-7. The -log file outputs log messages to the specified file.
+.. note:: When the -aggr option is used, only statistics that are derivable from partial sums and contingency table counts can be requested. Runtimes are generally much slower when aggregating data since it requires many additional NetCDF variables containing the scalar partial sums and contingency table counts to be read and written.
 
-8. The -v level overrides the default level of logging (2).
+7. The -paired option indicates that the -fcst and -obs file lists are already paired, meaning there is a one-to-one correspondence between the files in those lists. This option affects how missing data is handled. When -paired is not used, missing or incomplete files result in a runtime error with no output file being created. When -paired is used, missing or incomplete files result in a warning with output being created using the available data.
 
-9. The -compress level option indicates the desired level of compression (deflate level) for NetCDF variables. The valid level is between 0 and 9. The value of "level" will override the default setting of 0 from the configuration file or the environment variable MET_NC_COMPRESS. Setting the compression level to 0 will make no compression for the NetCDF output. Lower number is for fast compression and higher number is for better compression.
+8. The -log file outputs log messages to the specified file.
+
+9. The -v level overrides the default level of logging (2).
+
+10. The -compress level option indicates the desired level of compression (deflate level) for NetCDF variables. The valid level is between 0 and 9. The value of "level" will override the default setting of 0 from the configuration file or the environment variable MET_NC_COMPRESS. Setting the compression level to 0 will make no compression for the NetCDF output. Lower number is for fast compression and higher number is for better compression.
 
 An example of the series_analysis calling sequence is shown below:
 
@@ -179,3 +184,5 @@ The output_stats array controls the type of output that the Series-Analysis tool
 11. PJC for Joint and Conditional factorization for Probabilistic forecasts (See :numref:`table_PS_format_info_PJC`)
 
 12. PRC for Receiver Operating Characteristic for Probabilistic forecasts (See :numref:`table_PS_format_info_PRC`)
+
+.. note:: When the -input option is used, all partial sum and contingency table count columns are required to aggregate statistics across multiple runs. To facilitate this, the output_stats entries for the CTC, SL1L2, SAL1L2, and PCT line types can be set to "ALL" to indicate that all available columns for those line types should be written.

internal/test_unit/config/SeriesAnalysisConfig_climo

@@ -132,13 +132,13 @@ vld_thresh = 0.5;
 //
 output_stats = {
    fho    = [ "TOTAL", "F_RATE", "H_RATE", "O_RATE" ];
-   ctc    = [ ];
+   ctc    = [ "ALL" ];
    cts    = [ ];
    mctc   = [ ];
-   mcts   = [ "ACC" ];
-   cnt    = [ "TOTAL", "RMSE", "ANOM_CORR" ];
-   sl1l2  = [ ];
-   sal1l2 = [ ];
+   mcts   = [ ];
+   cnt    = [ "TOTAL", "RMSE", "ANOM_CORR", "RMSFA", "RMSOA" ];
+   sl1l2  = [ "ALL" ];
+   sal1l2 = [ "ALL" ];
    pct    = [ ];
    pstd   = [ ];
    pjc    = [ ];

internal/test_unit/config/SeriesAnalysisConfig_climo_prob

@@ -148,7 +148,7 @@ output_stats = {
    cnt    = [ ];
    sl1l2  = [ ];
    sal1l2 = [ ];
-   pct    = [ ];
+   pct    = [ "ALL" ];
    pstd   = [ "TOTAL", "ROC_AUC", "BRIER", "BRIERCL", "BSS", "BSS_SMPL" ];
    pjc    = [ ];
    prc    = [ ];

internal/test_unit/xml/unit_climatology_1.0deg.xml

@@ -154,32 +154,28 @@
       <stat>&OUTPUT_DIR;/climatology_1.0deg/stat_analysis_MPR_to_PSTD.stat</stat>
     </output>
   </test>
-
+--!>
   <test name="climatology_SERIES_ANALYSIS_1.0DEG">
     <exec>&MET_BIN;/series_analysis</exec>
     <env>
       <pair><name>CLIMO_MEAN_FILE_LIST</name>
          <value>"&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590409",
-                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590410",
-                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590411"
+                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590410"
          </value>
       </pair>
       <pair><name>CLIMO_STDEV_FILE_LIST</name>
          <value>"&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590409",
-                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590410",
-                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590411"
+                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590410"
          </value>
       </pair>
     </env>
     <param> \
         -fcst &DATA_DIR_MODEL;/grib2/gfs/gfs_2012040900_F012.grib2 \
               &DATA_DIR_MODEL;/grib2/gfs/gfs_2012040900_F024.grib2 \
               &DATA_DIR_MODEL;/grib2/gfs/gfs_2012040900_F036.grib2 \
-              &DATA_DIR_MODEL;/grib2/gfs/gfs_2012040900_F048.grib2 \
         -obs  &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120409_1200_000.grb2 \
               &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120410_0000_000.grb2 \
               &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120410_1200_000.grb2 \
-              &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120411_0000_000.grb2 \
       -paired \
       -out    &OUTPUT_DIR;/climatology_1.0deg/series_analysis_GFS_CLIMO_1.0DEG.nc \
       -config &CONFIG_DIR;/SeriesAnalysisConfig_climo \
@@ -190,25 +186,84 @@
     </output>
   </test>
 
+  <test name="climatology_SERIES_ANALYSIS_1.0DEG_AGGR">
+    <exec>&MET_BIN;/series_analysis</exec>
+    <env>
+      <pair><name>CLIMO_MEAN_FILE_LIST</name>
+         <value>"&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590411"
+         </value>
+      </pair>
+      <pair><name>CLIMO_STDEV_FILE_LIST</name>
+         <value>"&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590411"
+         </value>
+      </pair>
+    </env>
+    <param> \
+        -fcst &DATA_DIR_MODEL;/grib2/gfs/gfs_2012040900_F048.grib2 \
+        -obs  &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120411_0000_000.grb2 \
+      -paired \
+      -aggr   &OUTPUT_DIR;/climatology_1.0deg/series_analysis_GFS_CLIMO_1.0DEG.nc \
+      -out    &OUTPUT_DIR;/climatology_1.0deg/series_analysis_GFS_CLIMO_1.0DEG_AGGR.nc \
+      -config &CONFIG_DIR;/SeriesAnalysisConfig_climo \
+      -v 2
+    </param>
+    <output>
+      <grid_nc>&OUTPUT_DIR;/climatology_1.0deg/series_analysis_GFS_CLIMO_1.0DEG_AGGR.nc</grid_nc>
+    </output>
+  </test>
+
   <test name="climatology_SERIES_ANALYSIS_PROB_1.0DEG">
     <exec>echo "&DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F003.grib2 \
                 &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F009.grib2 \
                 &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F015.grib2 \
-                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F021.grib2 \
-                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F027.grib2 \
-                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F033.grib2 \
-                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F039.grib2 \
-                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F045.grib2" \
-                > &OUTPUT_DIR;/climatology_1.0deg/input_fcst_file_list; \
+                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F021.grib2" \
+                > &OUTPUT_DIR;/climatology_1.0deg/20120409_fcst_file_list; \
           echo "&DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120409_0000_000.grb2 \
                 &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120409_0600_000.grb2 \
                 &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120409_1200_000.grb2 \
-                &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120409_1800_000.grb2 \
-                &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120410_0000_000.grb2 \
+                &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120409_1800_000.grb2" \
+                > &OUTPUT_DIR;/climatology_1.0deg/20120409_obs_file_list; \
+          &MET_BIN;/series_analysis</exec>
+    <env>
+      <pair><name>DAY_INTERVAL</name>  <value>1</value></pair>
+      <pair><name>HOUR_INTERVAL</name> <value>6</value></pair>
+      <pair><name>CLIMO_MEAN_FILE_LIST</name>
+         <value>"&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590409",
+                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590410",
+                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cmean_1d.19590411"
+         </value>
+      </pair>
+      <pair><name>CLIMO_STDEV_FILE_LIST</name>
+         <value>"&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590409",
+                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590410",
+                "&DATA_DIR_CLIMO;/NCEP_NCAR_40YR_1.0deg/cstdv_1d.19590411"
+         </value>
+      </pair>
+    </env>
+    <param> \
+      -fcst   &OUTPUT_DIR;/climatology_1.0deg/20120409_fcst_file_list \
+      -obs    &OUTPUT_DIR;/climatology_1.0deg/20120409_obs_file_list \
+      -paired \
+      -out    &OUTPUT_DIR;/climatology_1.0deg/series_analysis_PROB_CLIMO_1.0DEG.nc \
+      -config &CONFIG_DIR;/SeriesAnalysisConfig_climo_prob \
+      -v 2
+    </param>
+    <output>
+      <grid_nc>&OUTPUT_DIR;/climatology_1.0deg/series_analysis_PROB_CLIMO_1.0DEG.nc</grid_nc>
+    </output>
+  </test>
+
+  <test name="climatology_SERIES_ANALYSIS_PROB_1.0DEG_AGGR">
+    <exec>echo "&DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F027.grib2 \
+                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F033.grib2 \
+                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F039.grib2 \
+                &DATA_DIR_MODEL;/grib2/sref_pr/sref_prob_2012040821_F045.grib2" \
+                > &OUTPUT_DIR;/climatology_1.0deg/20120410_fcst_file_list; \
+          echo "&DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120410_0000_000.grb2 \
                 &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120410_0600_000.grb2 \
                 &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120410_1200_000.grb2 \
                 &DATA_DIR_MODEL;/grib2/gfsanl/gfsanl_4_20120410_1800_000.grb2" \
-                > &OUTPUT_DIR;/climatology_1.0deg/input_obs_file_list; \
+                > &OUTPUT_DIR;/climatology_1.0deg/20120410_obs_file_list; \
           &MET_BIN;/series_analysis</exec>
     <env>
       <pair><name>DAY_INTERVAL</name>  <value>1</value></pair>
@@ -227,15 +282,16 @@
       </pair>
     </env>
     <param> \
-      -fcst   &OUTPUT_DIR;/climatology_1.0deg/input_fcst_file_list \
-      -obs    &OUTPUT_DIR;/climatology_1.0deg/input_obs_file_list \
+      -fcst   &OUTPUT_DIR;/climatology_1.0deg/20120410_fcst_file_list \
+      -obs    &OUTPUT_DIR;/climatology_1.0deg/20120410_obs_file_list \
       -paired \
-      -out    &OUTPUT_DIR;/climatology_1.0deg/series_analysis_PROB_CLIMO_1.0DEG.nc \
+      -aggr   &OUTPUT_DIR;/climatology_1.0deg/series_analysis_PROB_CLIMO_1.0DEG.nc \
+      -out    &OUTPUT_DIR;/climatology_1.0deg/series_analysis_PROB_CLIMO_1.0DEG_AGGR.nc \
       -config &CONFIG_DIR;/SeriesAnalysisConfig_climo_prob \
       -v 2
     </param>
     <output>
-      <grid_nc>&OUTPUT_DIR;/climatology_1.0deg/series_analysis_PROB_CLIMO_1.0DEG.nc</grid_nc>
+      <grid_nc>&OUTPUT_DIR;/climatology_1.0deg/series_analysis_PROB_CLIMO_1.0DEG_AGGR.nc</grid_nc>
     </output>
   </test>