From 3e6a5dafa847730ff5defdfea7acac0ce14c8784 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 11 Nov 2023 20:17:34 -0700 Subject: [PATCH] Update develop-ref after #2732 (#2734) Co-authored-by: jprestop Co-authored-by: Seth Linden Co-authored-by: John Halley Gotway Co-authored-by: Daniel Adriaansen Co-authored-by: John and Cindy Co-authored-by: rgbullock Co-authored-by: Randy Bullock Co-authored-by: Dave Albo Co-authored-by: Howard Soh Co-authored-by: George McCabe <23407799+georgemccabe@users.noreply.github.com> Co-authored-by: hsoh-u Co-authored-by: MET Tools Test Account Co-authored-by: Seth Linden Co-authored-by: lisagoodrich <33230218+lisagoodrich@users.noreply.github.com> Co-authored-by: davidalbo Co-authored-by: Lisa Goodrich Co-authored-by: metplus-bot <97135045+metplus-bot@users.noreply.github.com> Co-authored-by: j-opatz <59586397+j-opatz@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jonathan Vigh Co-authored-by: Tracy Hertneky <39317287+hertneky@users.noreply.github.com> Co-authored-by: David Albo Co-authored-by: Dan Adriaansen Co-authored-by: Julie Prestopnik fix 2518 dtypes appf docs (#2519) fix 2531 compilation errors (#2533) fix #2531 compilation_errors_configure (#2535) fix #2514 develop clang (#2563) fix #2575 develop python_convert (#2576) Fix Python environment issue (#2407) fix definitions of G172 and G220 based on comments in NOAA-EMC/NCEPLIBS-w3emc#157. (#2406) fix #2380 develop override (#2382) fix #2408 develop empty config (#2410) fix #2390 develop compile zlib (#2404) fix #2412 develop climo (#2422) fix #2437 develop convert (#2439) fix for develop, for #2437, forgot one reference to the search_parent for a dictionary lookup. fix #2452 develop airnow (#2454) fix #2449 develop pdf (#2464) fix #2402 develop sonarqube (#2468) fix #2426 develop buoy (#2475) fix 2596 main v11.1 rpath compilation (#2614) fix #2514 main_v11.1 clang (#2628) fix #2644 develop percentile (#2647) fix #2730 develop SI_BCU (#2732) --- data/config/MODEMultivarConfig_default | 7 + docs/Contributors_Guide/index.rst | 4 +- docs/Users_Guide/appendixA.rst | 18 +- docs/Users_Guide/appendixC.rst | 64 +- docs/Users_Guide/config_options.rst | 247 +++--- docs/Users_Guide/config_options_tc.rst | 4 +- docs/Users_Guide/data_io.rst | 10 +- docs/Users_Guide/ensemble-stat.rst | 20 +- docs/Users_Guide/gen-ens-prod.rst | 16 +- docs/Users_Guide/grid-diag.rst | 12 +- docs/Users_Guide/grid-stat.rst | 34 +- docs/Users_Guide/gsi-tools.rst | 20 +- docs/Users_Guide/installation.rst | 2 +- docs/Users_Guide/masking.rst | 10 +- docs/Users_Guide/met-tc_overview.rst | 6 +- docs/Users_Guide/mode-analysis.rst | 28 +- docs/Users_Guide/mode-td.rst | 16 +- docs/Users_Guide/mode.rst | 30 +- docs/Users_Guide/overview.rst | 10 +- docs/Users_Guide/plotting.rst | 28 +- docs/Users_Guide/point-stat.rst | 32 +- docs/Users_Guide/reformat_grid.rst | 58 +- docs/Users_Guide/reformat_point.rst | 70 +- docs/Users_Guide/release-notes.rst | 4 +- docs/Users_Guide/rmw-analysis.rst | 12 +- docs/Users_Guide/series-analysis.rst | 10 +- docs/Users_Guide/stat-analysis.rst | 22 +- docs/Users_Guide/tc-diag.rst | 28 +- docs/Users_Guide/tc-dland.rst | 10 +- docs/Users_Guide/tc-gen.rst | 14 +- docs/Users_Guide/tc-pairs.rst | 16 +- docs/Users_Guide/tc-rmw.rst | 12 +- docs/Users_Guide/tc-stat.rst | 18 +- docs/Users_Guide/wavelet-stat.rst | 20 +- docs/index.rst | 3 + internal/scripts/docker/build_met_docker.sh | 7 +- scripts/python/met/dataplane.py | 49 +- src/basic/vx_util/ascii_table.cc | 1 - src/basic/vx_util/data_plane.cc | 77 +- src/basic/vx_util/file_exists.cc | 2 - src/basic/vx_util/stat_column_defs.h | 2 +- src/basic/vx_util/vx_util.h | 1 + src/libcode/vx_nc_util/nc_utils.cc | 22 +- src/libcode/vx_shapedata/engine.cc | 731 +++++++----------- src/libcode/vx_shapedata/interest.cc | 67 +- src/libcode/vx_shapedata/interest.h | 8 +- src/libcode/vx_shapedata/mode_field_info.cc | 81 +- src/libcode/vx_shapedata/shapedata.cc | 486 +++++------- src/libcode/vx_statistics/compute_stats.cc | 77 +- src/libcode/vx_statistics/compute_stats.h | 5 +- src/tools/core/ensemble_stat/ensemble_stat.cc | 5 - src/tools/core/mode/mode.cc | 12 + src/tools/core/mode/mode_exec.cc | 11 +- src/tools/core/mode/mode_exec.h | 2 +- src/tools/core/mode/mode_frontend.cc | 3 +- src/tools/core/mode/multivar_frontend.cc | 14 +- src/tools/core/pcp_combine/pcp_combine.cc | 56 +- src/tools/other/mode_time_domain/3d_conv.cc | 113 +-- .../other/mode_time_domain/mtd_file_base.h | 4 +- .../other/mode_time_domain/mtd_file_float.cc | 40 +- src/tools/other/pb2nc/pb2nc.cc | 114 +-- 61 files changed, 1411 insertions(+), 1494 deletions(-) diff --git a/data/config/MODEMultivarConfig_default b/data/config/MODEMultivarConfig_default index 66ab5dfdf3..76207fd018 100644 --- a/data/config/MODEMultivarConfig_default +++ b/data/config/MODEMultivarConfig_default @@ -53,6 +53,11 @@ quilt = FALSE; // multivar_logic = "#1 && #2 && #3"; +// +// MODE Multivar intensity computation flag +// +multivar_intensity_flag = [FALSE, TRUE, TRUE]; + // // Forecast and observation fields to be verified // @@ -84,6 +89,8 @@ fcst = { filter_attr_thresh = []; merge_thresh = >=3.5; merge_flag = NONE; + multivar_name = "Super"; + multivar_level = "LO"; } obs = fcst; diff --git a/docs/Contributors_Guide/index.rst b/docs/Contributors_Guide/index.rst index 994ac22332..febe016321 100644 --- a/docs/Contributors_Guide/index.rst +++ b/docs/Contributors_Guide/index.rst @@ -1,6 +1,6 @@ -=================== +################### Contributor's Guide -=================== +################### Welcome to the Model Evaluation Tools (MET) Contributor's Guide. diff --git a/docs/Users_Guide/appendixA.rst b/docs/Users_Guide/appendixA.rst index 099498402c..7d6df54511 100644 --- a/docs/Users_Guide/appendixA.rst +++ b/docs/Users_Guide/appendixA.rst @@ -1816,7 +1816,7 @@ scripts available in the MET's *scripts/* directory show examples of how one might use these commands on example datasets. Here are suggestions on other things to check if you are having problems installing or running MET. -MET won't compile +MET Won't Compile ----------------- .. dropdown:: Troubleshooting Help @@ -1828,7 +1828,7 @@ MET won't compile * Have these libraries been compiled and installed using the same set of compilers used to build MET? -BUFRLIB Errors during MET installation +BUFRLIB Errors During MET Installation -------------------------------------- .. dropdown:: Troubleshooting Help @@ -1866,7 +1866,7 @@ BUFRLIB Errors during MET installation `METplus GitHub Discussions Forum `_. -Command line double quotes +Command Line Double Quotes -------------------------- .. dropdown:: Troubleshooting Help @@ -1882,7 +1882,7 @@ Command line double quotes 'G003', '/h/data/global/WXQC/data/met/nc_mdl/umm/1701150006', '- field', '\'name="HGT"; level="P500";\'', '-v', '6'] -Environment variable settings +Environment Variable Settings ----------------------------- .. dropdown:: Troubleshooting Help @@ -1916,7 +1916,7 @@ Environment variable settings value should be: https://met.readthedocs.io/en/latest/Users_Guide/installation.html -NetCDF install issues +NetCDF Install Issues --------------------- .. dropdown:: Troubleshooting Help @@ -1945,7 +1945,7 @@ NetCDF install issues MET_NETCDF environment variable, then run "make clean", reconfigure, and then run "make install" and "make test" again. -Error while loading shared libraries +Error While Loading Shared Libraries ------------------------------------ .. dropdown:: Troubleshooting Help @@ -1957,7 +1957,7 @@ Error while loading shared libraries gsl lib (for example, */home/user/MET/gsl-2.1/lib*) to your LD_LIBRARY_PATH. -General troubleshooting +General Troubleshooting ----------------------- .. dropdown:: Troubleshooting Help @@ -1971,7 +1971,7 @@ General troubleshooting * Try rerunning with a higher verbosity level. Increasing the verbosity level to 4 or 5 prints much more diagnostic information to the screen. -Where to get help +Where to Get Help ================= If none of the above suggestions have helped solve your problem, help @@ -1979,7 +1979,7 @@ is available through the `METplus GitHub Discussions Forum `_. -How to contribute code +How to Contribute Code ====================== If you have code you would like to contribute, we will gladly consider diff --git a/docs/Users_Guide/appendixC.rst b/docs/Users_Guide/appendixC.rst index 57e91bf090..7c5c618a43 100644 --- a/docs/Users_Guide/appendixC.rst +++ b/docs/Users_Guide/appendixC.rst @@ -52,7 +52,7 @@ Which statistics are the same, but with different names? .. _categorical variables: -MET verification measures for categorical (dichotomous) variables +MET Verification Measures for Categorical (Dichotomous) Variables ================================================================= @@ -99,7 +99,7 @@ TOTAL The total number of forecast-observation pairs, **T**. -Base rate +Base Rate --------- Called "O_RATE" in FHO output :numref:`table_PS_format_info_FHO` @@ -108,7 +108,7 @@ Called "BASER" in CTS output :numref:`table_PS_format_info_CTS` The base rate is defined as :math:`\bar{o} = \frac{n_{11} + n_{01}}{T} = \frac{n_{.1}}{T}.` This value is also known as the sample climatology, and is the relative frequency of occurrence of the event (i.e., o = 1). The base rate is equivalent to the "O" value produced by the NCEP Verification System. -Mean forecast +Mean Forecast ------------- Called "F_RATE" in FHO output :numref:`table_PS_format_info_FHO` @@ -182,7 +182,7 @@ POFD is defined as It is the proportion of non-events that were forecast to be events. POFD is also often called the False Alarm Rate. POFD ranges from 0 to 1; a perfect forecast would have POFD = 0. -Probability of Detection of the non-event (PODn) +Probability of Detection of the Non-Event (PODn) ------------------------------------------------ Called "PODN" in CTS output :numref:`table_PS_format_info_CTS` @@ -398,14 +398,14 @@ where the word expected refers to the mean value deduced from the climatology, r SEEPS scores are expected to lie between 0 and 1, with a perfect forecast having a value of 0. Individual values can be much larger than 1. Results can be presented as a skill score by using the value of 1 – SEEPS. -MET verification measures for continuous variables +MET Verification Measures for Continuous Variables ================================================== For continuous variables, many verification measures are based on the forecast error (i.e., **f - o**). However, it also is of interest to investigate characteristics of the forecasts, and the observations, as well as their relationship. These concepts are consistent with the general framework for verification outlined by :ref:`Murphy and Winkler, (1987) `. The statistics produced by MET for continuous forecasts represent this philosophy of verification, which focuses on a variety of aspects of performance rather than a single measure. The verification measures currently evaluated by the Point-Stat tool are defined and described in the subsections below. In these definitions, **f** represents the forecasts, **o** represents the observation, and **n** is the number of forecast-observation pairs. -Mean forecast +Mean Forecast ------------- Called "FBAR" in CNT output :numref:`table_PS_format_info_CNT` @@ -414,7 +414,7 @@ Called "FBAR" in SL1L2 output :numref:`table_PS_format_info_SL1L2` The sample mean forecast, FBAR, is defined as :math:`\bar{f} = \frac{1}{n} \sum_{i=1}^{n} f_i`. -Mean observation +Mean Observation ---------------- Called "OBAR" in CNT output :numref:`table_PS_format_info_CNT` @@ -423,7 +423,7 @@ Called "OBAR" in SL1L2 output :numref:`table_PS_format_info_SL1L2` The sample mean observation is defined as :math:`\bar{o} = \frac{1}{n} \sum_{i=1}^{n} o_i`. -Forecast standard deviation +Forecast Standard Deviation --------------------------- Called "FSTDEV" in CNT output :numref:`table_PS_format_info_CNT` @@ -434,7 +434,7 @@ The sample variance of the forecasts is defined as The forecast standard deviation is defined as :math:`s_f = \sqrt{s_f^2}`. -Observation standard deviation +Observation Standard Deviation ------------------------------ Called "OSTDEV" in CNT output :numref:`table_PS_format_info_CNT` @@ -456,7 +456,7 @@ The Pearson correlation coefficient, **r**, measures the strength of linear asso **r** can range between -1 and 1; a value of 1 indicates perfect correlation and a value of -1 indicates perfect negative correlation. A value of 0 indicates that the forecasts and observations are not correlated. -Spearman rank correlation coefficient :math:`(\rho_{s})` +Spearman Rank Correlation Coefficient :math:`(\rho_{s})` -------------------------------------------------------- Called "SP_CORR" in CNT :numref:`table_PS_format_info_CNT` @@ -469,7 +469,7 @@ A simpler formulation of the Spearman-rank correlation is based on differences b Like **r**, the Spearman rank correlation coefficient ranges between -1 and 1; a value of 1 indicates perfect correlation and a value of -1 indicates perfect negative correlation. A value of 0 indicates that the forecasts and observations are not correlated. -Kendall's Tau statistic ( :math:`\tau`) +Kendall's Tau Statistic ( :math:`\tau`) --------------------------------------- Called "KT_CORR" in CNT output :numref:`table_PS_format_info_CNT` @@ -510,14 +510,14 @@ Called "MBIAS" in CNT output :numref:`table_PS_format_info_CNT` Multiplicative bias is simply the ratio of the means of the forecasts and the observations: :math:`\text{MBIAS} = \bar{f} / \bar{o}` -Mean-squared error (MSE) +Mean-Squared Error (MSE) ------------------------ Called "MSE" in CNT output :numref:`table_PS_format_info_CNT` MSE measures the average squared error of the forecasts. Specifically, :math:`\text{MSE} = \frac{1}{n}\sum (f_{i} - o_{i})^{2}`. -Root-mean-squared error (RMSE) +Root-Mean-Squared Error (RMSE) ------------------------------ Called "RMSE" in CNT output :numref:`table_PS_format_info_CNT` @@ -535,7 +535,7 @@ SI is the ratio of the root mean squared error to the average observation value, Smaller values of SI indicate better agreement between the model and observations (less scatter on scatter plot). -Standard deviation of the error +Standard Deviation of the Error ------------------------------- Called "ESTDEV" in CNT output :numref:`table_PS_format_info_CNT` @@ -590,21 +590,21 @@ The Mean Squared Error Skill Score is one minus the ratio of the forecast MSE to .. math:: \text{MSESS} = 1 - \frac{\text{MSE}_f}{\text{MSE}_r} -Root-mean-squared Forecast Anomaly +Root-Mean-Squared Forecast Anomaly ---------------------------------- Called "RMSFA" in CNT output :numref:`table_PS_format_info_CNT` RMSFA is the square root of the average squared forecast anomaly. Specifically, :math:`\text{RMSFA} = \sqrt{\frac{1}{n} \sum(f_{i} - c_{i})^2}`. -Root-mean-squared Observation Anomaly +Root-Mean-Squared Observation Anomaly ------------------------------------- Called "RMSOA" in CNT output :numref:`table_PS_format_info_CNT` RMSOA is the square root of the average squared observation anomaly. Specifically, :math:`\text{RMSOA} = \sqrt{\frac{1}{n} \sum(o_{i} - c_{i})^2}`. -Percentiles of the errors +Percentiles of the Errors ------------------------- Called "E10", "E25", "E50", "E75", "E90" in CNT output :numref:`table_PS_format_info_CNT` @@ -636,7 +636,7 @@ The uncentered anomaly correlation coefficient (ANOM_CORR_UNCNTR) which does not Anomaly correlation can range between -1 and 1; a value of 1 indicates perfect correlation and a value of -1 indicates perfect negative correlation. A value of 0 indicates that the forecast and observed anomalies are not correlated. -Partial Sums lines (SL1L2, SAL1L2, VL1L2, VAL1L2) +Partial Sums Lines (SL1L2, SAL1L2, VL1L2, VAL1L2) ------------------------------------------------- :numref:`table_PS_format_info_SL1L2`, :numref:`table_PS_format_info_SAL1L2`, :numref:`table_PS_format_info_VL1L2`, and :numref:`table_PS_format_info_VAL1L2` @@ -647,7 +647,7 @@ The partial sums can be accumulated over individual cases to produce statistics *Minimally sufficient* statistics are those that condense the data most, with no loss of information. Statistics based on L1 and L2 norms allow for good compression of information. Statistics based on other norms, such as order statistics, do not result in good compression of information. For this reason, statistics such as RMSE are often preferred to statistics such as the median absolute deviation. The partial sums are not sufficient for order statistics, such as the median or quartiles. -Scalar L1 and L2 values +Scalar L1 and L2 Values ----------------------- Called "FBAR", "OBAR", "FOBAR", "FFBAR", and "OOBAR" in SL1L2 output :numref:`table_PS_format_info_SL1L2` @@ -667,7 +667,7 @@ These statistics are simply the 1st and 2nd moments of the forecasts, observatio Some of the other statistics for continuous forecasts (e.g., RMSE) can be derived from these moments. -Scalar anomaly L1 and L2 values +Scalar Anomaly L1 and L2 Values ------------------------------- Called "FABAR", "OABAR", "FOABAR", "FFABAR", "OOABAR" in SAL1L2 output :numref:`table_PS_format_info_SAL1L2` @@ -685,7 +685,7 @@ Computation of these statistics requires a climatological value, c. These statis \text{OOABAR} = \text{Mean}[(o - c)^2] = \bar{(o - c)}^2 = \frac{1}{n} \sum_{i=1}^n (o_i - c)^2 -Vector L1 and L2 values +Vector L1 and L2 Values ----------------------- Called "UFBAR", "VFBAR", "UOBAR", "VOBAR", "UVFOBAR", "UVFFBAR", "UVOOBAR" in VL1L2 output :numref:`table_PS_format_info_VL1L2` @@ -707,7 +707,7 @@ These statistics are the moments for wind vector values, where **u** is the E-W \text{UVOOBAR} = \text{Mean}(u_o^2 + v_o^2) = \frac{1}{n} \sum_{i=1}^n (u_{oi}^2 + v_{oi}^2) -Vector anomaly L1 and L2 values +Vector Anomaly L1 and L2 Values ------------------------------- Called "UFABAR", "VFABAR", "UOABAR", "VOABAR", "UVFOABAR", "UVFFABAR", "UVOOABAR" in VAL1L2 output :numref:`table_PS_format_info_VAL1L2` @@ -730,7 +730,7 @@ These statistics require climatological values for the wind vector components, : \text{UVOOABAR} = \text{Mean}[(u_o - u_c)^2 + (v_o - v_c)^2] = \frac{1}{n} \sum_{i=1}^n ((u_{oi} - u_c)^2 + (v_{oi} - v_c)^2) -Gradient values +Gradient Values --------------- Called "TOTAL", "FGBAR", "OGBAR", "MGBAR", "EGBAR", "S1", "S1_OG", and "FGOG_RATIO" in GRAD output :numref:`table_GS_format_info_GRAD` @@ -773,7 +773,7 @@ where the weights are applied at each grid location, with values assigned accord \text{FGOG_RATIO} = \frac{\text{FGBAR}}{\text{OGBAR}} -MET verification measures for probabilistic forecasts +MET Verification Measures for Probabilistic Forecasts ===================================================== The results of the probabilistic verification methods that are included in the Point-Stat, Grid-Stat, and Stat-Analysis tools are summarized using a variety of measures. MET treats probabilistic forecasts as categorical, divided into bins by user-defined thresholds between zero and one. For the categorical measures, if a forecast probability is specified in a formula, the midpoint value of the bin is used. These measures include the Brier Score (BS) with confidence bounds (:ref:`Bradley, 2008 `); the joint distribution, calibration-refinement, likelihood-base rate (:ref:`Wilks, 2011 `); and receiver operating characteristic information. Using these statistics, reliability and discrimination diagrams can be produced. @@ -843,7 +843,7 @@ A component of the Brier score. For probabilistic forecasts, uncertainty is a fu .. math:: \text{Uncertainty} = \frac{n_{.1}}{T}(1 - \frac{n_{.1}}{T}) -Brier score +Brier Score ----------- Called "BRIER" in PSTD output :numref:`table_PS_format_info_PSTD` @@ -927,7 +927,7 @@ This is the probability of an event for each forecast category :math:`p_i` (row) .. math:: \text{Base Rate}(i) = \frac{n_{i1}}{n_{i.}} = \text{probability}(o_{i1}) -Reliability diagram +Reliability Diagram ------------------- The reliability diagram is a plot of the observed frequency of events versus the forecast probability of those events, with the range of forecast probabilities divided into categories. @@ -940,7 +940,7 @@ The ideal forecast (i.e., one with perfect reliability) has conditional observed Example of Reliability Diagram -Receiver operating characteristic +Receiver Operating Characteristic --------------------------------- MET produces hit rate (POD) and false alarm rate (POFD) values for each user-specified threshold. This information can be used to create a scatter plot of POFD vs. POD. When the points are connected, the plot is generally referred to as the receiver operating characteristic (ROC) curve (also called the "relative operating characteristic" curve). See the area under the ROC curve (AUC) entry for related information. @@ -955,7 +955,7 @@ A ROC curve shows how well the forecast discriminates between two outcomes, so i Example of ROC Curve -Area Under the ROC curve (AUC) +Area Under the ROC Curve (AUC) ------------------------------ Called "ROC_AUC" in PSTD output :numref:`table_PS_format_info_PSTD` @@ -968,7 +968,7 @@ The area under the curve can be estimated in a variety of ways. In MET, the simp .. _App_C-ensemble: -MET verification measures for ensemble forecasts +MET Verification Measures for Ensemble Forecasts ================================================ RPS @@ -1125,7 +1125,7 @@ The ensemble spread for a single observation is the standard deviation of the en Note that prior to met-9.0.1, the ensemble spread of a spatial masking region was computed as the average of the spread values within that region. This algorithm was corrected in met-9.0.1 to average the ensemble variance values prior to computing the square root. -MET verification measures for neighborhood methods +MET Verification Measures for Neighborhood Methods ================================================== The results of the neighborhood verification approaches that are included in the Grid-Stat tool are summarized using a variety of measures. These measures include the Fractions Skill Score (FSS) and the Fractions Brier Score (FBS). MET also computes traditional contingency table statistics for each combination of threshold and neighborhood window size. @@ -1210,7 +1210,7 @@ The overall proportion of grid points with observed events to total grid points .. _App_C-distance_maps: -MET verification measures for distance map methods +MET Verification Measures for Distance Map Methods ================================================== The distance map statistics include Baddeley's :math:`\Delta` Metric, a statistic which is a true mathematical metric. The definition of a mathematical metric is included below. @@ -1245,7 +1245,7 @@ In terms of distance maps, Baddeley's :math:`\Delta` is the :math:`L_{p}` norm o The range for BADDELEY and HAUSDORFF is 0 to infinity, with a score of 0 indicating a perfect forecast. -Mean-error Distance +Mean-Error Distance ------------------- Called "MED_FO", "MED_OF", "MED_MIN", "MED_MAX", and "MED_MEAN" in the DMAP output :numref:`table_GS_format_info_DMAP` diff --git a/docs/Users_Guide/config_options.rst b/docs/Users_Guide/config_options.rst index 35805c71d3..521ff451a8 100644 --- a/docs/Users_Guide/config_options.rst +++ b/docs/Users_Guide/config_options.rst @@ -210,12 +210,12 @@ An error in the syntax of a configuration file will result in an error from the MET tool stating the location of the parsing error. Runtime Environment Variables ------------------------------ +============================= .. _config_env_vars: User-Specified Environment Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------ When editing configuration files, environment variables may be used for setting the configurable parameters if convenient. The configuration file parser expands @@ -243,7 +243,7 @@ files, the environment variables listed below have special meaning if set at run .. _met_airnow_stations: MET_AIRNOW_STATIONS -^^^^^^^^^^^^^^^^^^^ +------------------- The MET_AIRNOW_STATIONS environment variable can be used to specify a file that will override the default file. If set, it should be the full path to the file. @@ -263,7 +263,7 @@ envrionment variable to define its location. .. _met_ndbc_stations: MET_NDBC_STATIONS -^^^^^^^^^^^^^^^^^ +----------------- The MET_NDBC_STATIONS environment variable can be used to specify a file that will override the default file. If set it should be a full path to the file. @@ -303,7 +303,8 @@ NOTE: The downloaded files are written to a subdirectory ndbc_temp_data which can be deleted once the final output file is created. MET_BASE -^^^^^^^^ +-------- + The MET_BASE variable is defined in the code at compilation time as the path to the MET shared data. These are things like the default configuration files, common polygons and color scales. MET_BASE may be used in the MET configuration @@ -312,7 +313,7 @@ If MET_BASE is defined as an environment variable, its value will be used instead of the one defined at compilation time. MET_OBS_ERROR_TABLE -^^^^^^^^^^^^^^^^^^^ +------------------- The MET_OBS_ERROR_TABLE environment variable can be set to specify the location of an ASCII file defining observation error information. The default table can @@ -342,7 +343,7 @@ reset to the mimimum value and values greater than MAX are reset to the maximum value. A value of NA indicates that the variable is unbounded. MET_GRIB_TABLES -^^^^^^^^^^^^^^^ +--------------- The MET_GRIB_TABLES environment variable can be set to specify the location of custom GRIB tables. It can either be set to a specific file name or to a @@ -398,7 +399,7 @@ References: | OMP_NUM_THREADS -^^^^^^^^^^^^^^^ +--------------- **Introduction** @@ -459,12 +460,20 @@ Regions of parallelized code are: * :code:`fractional_coverage (data_plane_util.cc)` + * Called by `gen_ens_prod` to compute NMEP outputs. + * Called by `grid_stat` when applying neighborhood verification methods. + + * :code:`ShapeData::conv_filter_circ() (shapedata.cc)` + + * Called by `mode` to apply a convolution smoothing operation when + defining objects. + Only the following top-level executables can presently benefit from OpenMP parallelization: * :code:`grid_stat` - * :code:`ensemble_stat` * :code:`grid_ens_prod` + * :code:`mode` **Thread Binding** @@ -474,7 +483,7 @@ guarantees that threads remain evenly distributed across the available cores. Otherwise, the operating system may migrate threads between cores during a run. OpenMP provides some environment variables to handle this: :code:`OMP_PLACES` -and :code:`OMP_PROC_BIND`. We anticipate that the effect of setting only +and :code:`OMP_PROC_BIND`. We anticipate that the effect of setting only :code:`OMP_PROC_BIND=true` would be neutral-to-positive. However, there are sometimes compiler-specific environment variables. Instead, @@ -485,11 +494,11 @@ Where code is running in a production context, it is worth being familiar with the binding / affinitization method on the particular system and building it into any relevant scripting. -Settings common to multiple tools ---------------------------------- +Settings Common to Multiple Tools +================================= exit_on_warning -^^^^^^^^^^^^^^^ +--------------- The "exit_on_warning" entry in ConfigConstants may be set to true or false. If set to true and a MET tool encounters a warning, it will immediately exit @@ -500,7 +509,7 @@ with bad status after writing the warning message. exit_on_warning = FALSE; nc_compression -^^^^^^^^^^^^^^ +-------------- The "nc_compression" entry in ConfigConstants defines the compression level for the NetCDF variables. Setting this option in the config file of one of @@ -522,7 +531,7 @@ writing of NetCDF files within MET significantly. nc_compression = 0; output_precision -^^^^^^^^^^^^^^^^ +---------------- The "output_precision" entry in ConfigConstants defines the precision (number of significant decimal places) to be written to the ASCII output @@ -536,7 +545,7 @@ override the default value set in ConfigConstants. .. _config_tmp_dir: tmp_dir -^^^^^^^ +------- The "tmp_dir" entry in ConfigConstants defines the directory for the temporary files. The directory must exist and be writable. The environment @@ -552,8 +561,8 @@ A description of the use of temporary files in MET can be found in :numref:`Contributor's Guide Section %s `. message_type_group_map -^^^^^^^^^^^^^^^^^^^^^^ - +---------------------- + The "message_type_group_map" entry is an array of dictionaries, each containing a "key" string and "val" string. This defines a mapping of message type group names to a comma-separated list of values. This map is @@ -573,7 +582,7 @@ used. ]; message_type_map -^^^^^^^^^^^^^^^^ +---------------- The "message_type_map" entry is an array of dictionaries, each containing a "key" string and "val" string. This defines a mapping of input strings @@ -597,7 +606,7 @@ types. ]; model -^^^^^ +----- The "model" entry specifies a name for the model being verified. This name is written to the MODEL column of the ASCII output generated. If you're @@ -610,7 +619,7 @@ e.g. model = "GFS"; model = "FCST"; desc -^^^^ +---- The "desc" entry specifies a user-specified description for each verification task. This string is written to the DESC column of the ASCII output @@ -626,8 +635,8 @@ e.g. desc = "QC_9"; desc = "NA"; obtype -^^^^^^ - +------ + The "obtype" entry specifies a name to describe the type of verifying gridded observation used. This name is written to the OBTYPE column in the ASCII output generated. If you're using multiple types of verifying observations, @@ -643,7 +652,7 @@ the configuration file obtype value is written. .. _regrid: regrid -^^^^^^ +------ The "regrid" entry is a dictionary containing information about how to handle input gridded data files. The "regrid" entry specifies regridding logic @@ -754,7 +763,7 @@ using the following entries: } fcst -^^^^ +---- The "fcst" entry is a dictionary containing information about the field(s) to be verified. This dictionary may include the following entries: @@ -1198,7 +1207,7 @@ File-format specific settings for the "field" entry: } obs -^^^ +--- The "obs" entry specifies the same type of information as "fcst", but for the observation data. It will often be set to the same things as "fcst", @@ -1322,7 +1331,7 @@ or obs = fcst; climo_mean -^^^^^^^^^^ +---------- The "climo_mean" dictionary specifies climatology mean data to be read by the Grid-Stat, Point-Stat, Ensemble-Stat, and Series-Analysis tools. It consists @@ -1379,7 +1388,7 @@ of several entires defining the climatology file names and fields to be used. } climo_stdev -^^^^^^^^^^^ +----------- The "climo_stdev" dictionary specifies climatology standard deviation data to be read by the Grid-Stat, Point-Stat, Ensemble-Stat, and Series-Analysis @@ -1410,7 +1419,7 @@ over the "climo_mean" setting and then updating the "file_name" entry. } climo_cdf -^^^^^^^^^ +--------- The "climo_cdf" dictionary specifies how the the climatological mean ("climo_mean") and standard deviation ("climo_stdev") data are used to @@ -1477,7 +1486,7 @@ all pairs into a single climatological bin. } climate_data -^^^^^^^^^^^^ +------------ When specifying climatology data for probability forecasts, either supply a probabilistic "climo_mean" field or non-probabilistic "climo_mean" and @@ -1505,7 +1514,7 @@ probabilities. These derived probability values are used to compute the climatological Brier Score and Brier Skill Score. seeps_p1_thresh -^^^^^^^^^^^^^^^ +--------------- The "seeps_p1_thresh" option controls the threshold of p1 (probability of being dry) values. The default setting is >=0.1&&<=0.85. @@ -1515,7 +1524,7 @@ The default setting is >=0.1&&<=0.85. seeps_p1_thresh = >=0.1&&<=0.85; mask_missing_flag -^^^^^^^^^^^^^^^^^ +----------------- The "mask_missing_flag" entry specifies how missing data should be handled in the Wavelet-Stat and MODE tools: @@ -1534,7 +1543,7 @@ in the Wavelet-Stat and MODE tools: obs_window -^^^^^^^^^^ +---------- The "obs_window" entry is a dictionary specifying a beginning ("beg" entry) and ending ("end" entry) time offset values in seconds. It defines @@ -1553,7 +1562,7 @@ Point-Stat and Ensemble-Stat, the reference time is the forecast valid time. .. _config_options-mask: mask -^^^^ +--- The "mask" entry is a dictionary that specifies the verification masking regions to be used when computing statistics. Each mask defines a @@ -1677,7 +1686,7 @@ is included in the mask. ci_alpha -^^^^^^^^ +-------- The "ci_alpha" entry is an array of floats specifying the values for alpha to be used when computing confidence intervals. Values of alpha must be @@ -1692,7 +1701,7 @@ interval. .. _config_boot: boot -^^^^ +---- The "boot" entry defines the parameters to be used in calculation of bootstrap confidence intervals. The interval variable indicates what method @@ -1755,7 +1764,7 @@ should be used for computing bootstrap confidence intervals: } interp -^^^^^^ +------ The "interp" entry is a dictionary that specifies what interpolation or smoothing (for the Grid-Stat tool) methods should be applied. @@ -1865,7 +1874,7 @@ This dictionary may include the following entries: } land_mask -^^^^^^^^^ +--------- The "land_mask" dictionary defines the land/sea mask field used when verifying at the surface. The "flag" entry enables/disables this logic. @@ -1893,7 +1902,7 @@ The "land_mask.flag" entry may be set separately in each "obs.field" entry. } topo_mask -^^^^^^^^^ +--------- The "topo_mask" dictionary defines the model topography field used when verifying at the surface. The flag entry enables/disables this logic. @@ -1923,7 +1932,7 @@ The "topo_mask.flag" entry may be set separately in each "obs.field" entry. } hira -^^^^ +---- The "hira" entry is a dictionary that is very similar to the "interp" and "nbrhd" entries. It specifies information for applying the High Resolution @@ -1976,7 +1985,7 @@ This dictionary may include the following entries: } output_flag -^^^^^^^^^^^ +----------- The "output_flag" entry is a dictionary that specifies what verification methods should be applied to the input data. Options exist for each @@ -2027,7 +2036,7 @@ output line type from the MET tools. Each line type may be set to one of: } nc_pairs_flag -^^^^^^^^^^^^^ +------------- The "nc_pairs_flag" can be set either to a boolean value or a dictionary in either Grid-Stat, Wavelet-Stat or MODE. The dictionary (with slightly @@ -2058,7 +2067,7 @@ netcdf output will be generated. } nc_pairs_var_name -^^^^^^^^^^^^^^^^^ +----------------- The "nc_pairs_var_name" entry specifies a string for each verification task in Grid-Stat. This string is parsed from each "obs.field" dictionary entry @@ -2078,7 +2087,7 @@ For example: nc_pairs_var_name = ""; nc_pairs_var_suffix -^^^^^^^^^^^^^^^^^^^ +------------------- The "nc_pairs_var_suffix" entry is similar to the "nc_pairs_var_name" entry described above. It is also parsed from each "obs.field" dictionary entry. @@ -2101,7 +2110,7 @@ now deprecated. nc_pairs_var_suffix = ""; ps_plot_flag -^^^^^^^^^^^^ +------------ The "ps_plot_flag" entry is a boolean value for Wavelet-Stat and MODE indicating whether a PostScript plot should be generated summarizing @@ -2112,7 +2121,7 @@ the verification. ps_plot_flag = TRUE; grid_weight_flag -^^^^^^^^^^^^^^^^ +---------------- The "grid_weight_flag" specifies how grid weighting should be applied during the computation of continuous statistics and partial sums. It is @@ -2136,7 +2145,7 @@ by the sum of the weights for the current masking region. grid_weight_flag = NONE; hss_ec_value -^^^^^^^^^^^^ +------------ The "hss_ec_value" entry is a floating point number used in the computation of the HSS_EC statistic in the CTS and MCTS line types. It specifies the expected @@ -2154,7 +2163,7 @@ If set, it must greater than or equal to 0.0 and less than 1.0. A value of hss_ec_value = NA; rank_corr_flag -^^^^^^^^^^^^^^ +-------------- The "rank_corr_flag" entry is a boolean to indicate whether Kendall's Tau and Spearman's Rank Correlation Coefficients (in the CNT line type) should @@ -2166,7 +2175,7 @@ intensive and slows down the runtime significantly. rank_corr_flag = FALSE; duplicate_flag -^^^^^^^^^^^^^^ +-------------- The "duplicate_flag" entry specifies how to handle duplicate point observations in Point-Stat and Ensemble-Stat: @@ -2188,7 +2197,7 @@ in those cases. duplicate_flag = NONE; obs_summary -^^^^^^^^^^^ +----------- The "obs_summary" entry specifies how to compute statistics on observations that appear at a single location (lat,lon,level,elev) @@ -2224,7 +2233,7 @@ in those cases. obs_perc_value -^^^^^^^^^^^^^^ +-------------- Percentile value to use when obs_summary = PERC @@ -2234,7 +2243,7 @@ Percentile value to use when obs_summary = PERC obs_quality_inc -^^^^^^^^^^^^^^^ +--------------- The "obs_quality_inc" entry specifies the quality flag values that are to be retained and used for verification. An empty list signifies that all @@ -2250,7 +2259,7 @@ Note "obs_quality_inc" replaces the older option "obs_quality". obs_quality_exc -^^^^^^^^^^^^^^^ +--------------- The "obs_quality_exc" entry specifies the quality flag values that are to be ignored and not used for verification. An empty list signifies that all @@ -2265,7 +2274,7 @@ an array of strings, even if the values themselves are numeric. met_data_dir -^^^^^^^^^^^^ +------------ The "met_data_dir" entry specifies the location of the internal MET data sub-directory which contains data files used when generating plots. It @@ -2277,7 +2286,7 @@ locate the static data files they need at run time. met_data_dir = "MET_BASE"; many_plots -^^^^^^^^^^ +---------- The "fcst_raw_plot" entry is a dictionary used by Wavelet-Stat and MODE containing colortable plotting information for the plotting of the raw @@ -2309,7 +2318,7 @@ The "obs_raw_plot", "wvlt_plot", and "object_plot" entries are dictionaries similar to the "fcst_raw_plot" described above. output_prefix -^^^^^^^^^^^^^ +------------- The "output_prefix" entry specifies a string to be included in the output file name. The MET statistics tools construct output file names that @@ -2322,7 +2331,7 @@ of the same tool. output_prefix = ""; version -^^^^^^^ +------- The "version" entry specifies the version number of the configuration file. The configuration file version number should match the version number of @@ -2333,7 +2342,7 @@ the MET code being run. This value should generally not be modified. version = "VN.N"; time_summary -^^^^^^^^^^^^ +------------ This feature was implemented to allow additional processing of observations with high temporal resolution. The "flag" entry toggles the "time_summary" @@ -2414,14 +2423,14 @@ are empty. Note: grib_code 11 is equivalent to obs_var "TMP". vld_thresh = 0.0; } -Settings specific to individual tools -------------------------------------- +Settings Specific to Individual Tools +===================================== GenEnsProdConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ ens -""" +^^^ The "ens" entry is a dictionary that specifies the fields for which ensemble products should be generated. This is very similar to the "fcst" and "obs" @@ -2464,7 +2473,7 @@ entries. This dictionary may include the following entries: } nbrhd_prob -"""""""""" +^^^^^^^^^^ The nbrhd_prob dictionary defines the neighborhoods used to compute NEP and NMEP output. The neighborhood shape is a SQUARE or CIRCLE centered on @@ -2486,7 +2495,7 @@ specified. } nmep_smooth -""""""""""" +^^^^^^^^^^^ Similar to the interp dictionary, the nmep_smooth dictionary includes a type array of dictionaries to define one or more methods for smoothing the NMEP @@ -2513,7 +2522,7 @@ combination of the categorical threshold (cat_thresh), neighborhood width } ensemble_flag -""""""""""""" +^^^^^^^^^^^^^ The "ensemble_flag" entry is a dictionary of boolean value indicating which ensemble products should be generated: @@ -2568,10 +2577,10 @@ which ensemble products should be generated: } EnsembleStatConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- fcst, obs -""""""""" +^^^^^^^^^ The fcst and obs entries define the fields for which Ensemble-Stat should compute rank histograms, probability integral transform histograms, @@ -2610,7 +2619,7 @@ data is provided, the climo_cdf thresholds will be used instead. nc_var_str -"""""""""" +^^^^^^^^^^ The "nc_var_str" entry specifies a string for each ensemble field and verification task in Ensemble-Stat. This string is parsed from each @@ -2627,7 +2636,7 @@ e.g. nc_var_str = "MIN"; nc_var_str = ""; obs_thresh -"""""""""" +^^^^^^^^^^ The "obs_thresh" entry is an array of thresholds for filtering observation values prior to applying ensemble verification logic. They specify the values @@ -2641,7 +2650,7 @@ This option may be set separately for each obs.field entry. obs_thresh = [ NA ]; skip_const -"""""""""" +^^^^^^^^^^ Setting "skip_const" to true tells Ensemble-Stat to exclude pairs where all the ensemble members and the observation have a constant value. For example, @@ -2655,7 +2664,7 @@ random. skip_const = FALSE; obs_error -""""""""" +^^^^^^^^^ Observation error options @@ -2713,7 +2722,7 @@ levels, and range of values. } rng -""" +^^^ See: `Random Number Generator Performance `_ used for random assignment of ranks when they are tied. @@ -2726,7 +2735,7 @@ used for random assignment of ranks when they are tied. } MODEAnalysisConfig_default -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- MODE line options are used to create filters that determine which MODE output lines are read in and processed. The MODE line options are numerous. They @@ -3064,10 +3073,10 @@ MET User's Guide for a description of these attributes. MODEConfig_default -^^^^^^^^^^^^^^^^^^ +------------------ quilt -""""" +^^^^^ The "quilt" entry is a boolean to indicate whether all permutations of convolution radii and thresholds should be run. If set to false, the number @@ -3083,7 +3092,7 @@ MODE will be run. quilt = false; fcst, obs -""""""""" +^^^^^^^^^ The object definition settings for MODE are contained within the "fcst" and "obs" entries: @@ -3168,7 +3177,7 @@ The object definition settings for MODE are contained within the "fcst" and } grid_res -"""""""" +^^^^^^^^ The "grid_res" entry is the nominal spacing for each grid square in kilometers. The variable is not used directly in the code, but subsequent @@ -3181,7 +3190,7 @@ are used for these variables. grid_res = 4; match_flag -"""""""""" +^^^^^^^^^^ The "match_flag" entry specifies the matching method to be applied: @@ -3200,7 +3209,7 @@ The "match_flag" entry specifies the matching method to be applied: match_flag = MERGE_BOTH; max_centroid_dist -""""""""""""""""" +^^^^^^^^^^^^^^^^^ The "max_centroid_dist" entry specifies the maximum allowable distance in grid squares between the centroids of objects for them to be compared. @@ -3212,7 +3221,7 @@ skip unreasonable object comparisons. max_centroid_dist = 800.0/grid_res; weight -"""""" +^^^^^^ The weight variables control how much weight is assigned to each pairwise attribute when computing a total interest value for object pairs. The weights @@ -3235,7 +3244,7 @@ sum of the weights listed. } interest_function -""""""""""""""""" +^^^^^^^^^^^^^^^^^ The set of interest function variables listed define which values are of interest for each pairwise attribute measured. The interest functions may be @@ -3292,7 +3301,7 @@ mathematical functions. } total_interest_thresh -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ The total_interest_thresh variable should be set between 0 and 1. This threshold is applied to the total interest values computed for each pair of @@ -3303,7 +3312,7 @@ objects and is used in determining matches. total_interest_thresh = 0.7; print_interest_thresh -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ The print_interest_thresh variable determines which pairs of object attributes will be written to the output object attribute ASCII file. The @@ -3318,7 +3327,7 @@ the max_centroid_dist variable. print_interest_thresh = 0.0; plot_valid_flag -""""""""""""""" +^^^^^^^^^^^^^^^ When applied, the plot_valid_flag variable indicates that only the region containing valid data after masking is applied should be plotted. TRUE @@ -3330,7 +3339,7 @@ region containing valid data after masking should be plotted. plot_valid_flag = FALSE; plot_gcarc_flag -""""""""""""""" +^^^^^^^^^^^^^^^ When applied, the plot_gcarc_flag variable indicates that the edges of polylines should be plotted using great circle arcs as opposed to straight @@ -3341,7 +3350,7 @@ lines in the grid. plot_gcarc_flag = FALSE; ct_stats_flag -""""""""""""" +^^^^^^^^^^^^^ The ct_stats_flag can be set to TRUE or FALSE to produce additional output, in the form of contingency table counts and statistics. @@ -3351,7 +3360,7 @@ in the form of contingency table counts and statistics. ct_stats_flag = TRUE; shift_right -""""""""""" +^^^^^^^^^^^ When MODE is run on global grids, this parameter specifies how many grid squares to shift the grid to the right. MODE does not currently connect @@ -3366,7 +3375,7 @@ much more flexible "regrid" option may be used instead. shift_right = 0; PB2NCConfig_default -^^^^^^^^^^^^^^^^^^^ +------------------- The PB2NC tool filters out observations from PREPBUFR or BUFR files using the following criteria: @@ -3427,7 +3436,7 @@ following criteria: (upper-air profile reports) message_type -"""""""""""" +^^^^^^^^^^^^ In the PB2NC tool, the "message_type" entry is an array of message types to be retained. An empty list indicates that all should be retained. @@ -3449,7 +3458,7 @@ For example: message_type = []; station_id -"""""""""" +^^^^^^^^^^ The "station_id" entry is an array of station ids to be retained or the filename which contains station ids. An array of station ids @@ -3463,7 +3472,7 @@ For example: station_id = [ "KDEN" ]; station_id = []; elevation_range -""""""""""""""" +^^^^^^^^^^^^^^^ The "elevation_range" entry is a dictionary which contains "beg" and "end" entries specifying the range of observing locations elevations to be @@ -3477,7 +3486,7 @@ retained. } pb_report_type -"""""""""""""" +^^^^^^^^^^^^^^ The "pb_report_type" entry is an array of PREPBUFR report types to be retained. The numeric "pb_report_type" entry allows for further @@ -3498,7 +3507,7 @@ For example: pb_report_type = []; in_report_type -"""""""""""""" +^^^^^^^^^^^^^^ The "in_report_type" entry is an array of input report type values to be retained. The numeric "in_report_type" entry provides additional @@ -3518,7 +3527,7 @@ For example: in_report_type = []; instrument_type -""""""""""""""" +^^^^^^^^^^^^^^^ The "instrument_type" entry is an array of instrument types to be retained. An empty list indicates that all should be retained. @@ -3528,7 +3537,7 @@ An empty list indicates that all should be retained. instrument_type = []; level_range -""""""""""" +^^^^^^^^^^^ The "level_range" entry is a dictionary which contains "beg" and "end" entries specifying the range of vertical levels (1 to 255) to be retained. @@ -3541,7 +3550,7 @@ entries specifying the range of vertical levels (1 to 255) to be retained. } level_category -"""""""""""""" +^^^^^^^^^^^^^^ The "level_category" entry is an array of integers specifying which level categories should be retained: @@ -3578,7 +3587,7 @@ See: `Current Table A Entries in PREPBUFR mnemonic table `, which replaces and extends that functionality. Ensemble product generation was removed from Ensemble-Stat in version 11.0.0. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== .. _ES_HiRA_framework: -HiRA framework +HiRA Framework -------------- The HiRA framework described in :numref:`PS_HiRA_framework` is also supported in the Ensemble-Stat tool. That support is provided as an interpolation option via the **interp** dictionary. The interpolation dictionary defines how gridded model data is matched to each observation value. Most interpolation methods, such as **UW_MEAN** for the unweighted mean or **BILIN** for bilinear, compute a single value for each ensemble member. When the High Resolution Assessment (HiRA) interpolation method is chosen, as shown below, all of the nearby neighborhood points surrounding each observation from each member are used. Therefore, processing an N-member ensemble using a HiRA neighborhood of size M produces ensemble output with size N*M. This approach fully leverages information from all nearby grid points to evaluate the ensemble quality. @@ -39,7 +39,7 @@ The HiRA framework described in :numref:`PS_HiRA_framework` is also supported in In this example, all four grid points of the 2x2 square surrounding each observation point are used to define the ensemble. Therefore, an N-member ensemble is evaluated as an ensemble of size Nx4. -Ensemble statistics +Ensemble Statistics ------------------- Rank histograms and probability integral transform (PIT) histograms are used to determine if the distribution of ensemble values is the same as the distribution of observed values for any forecast field (:ref:`Hamill, 2001 `). The rank histogram is a tally of the rank of the observed value when placed in order with each of the ensemble values from the same location. If the distributions are identical, then the rank of the observation will be uniformly distributed. In other words, it will fall among the ensemble members randomly in equal likelihood. The PIT histogram applies this same concept, but transforms the actual rank into a probability to facilitate ensembles of differing sizes or with missing members. @@ -54,7 +54,7 @@ The Ensemble-Stat tool can derive ensemble relative frequencies and verify them Note that if no probability category thresholds (prob_cat_thresh) are defined, but climatological mean and standard deviation data is provided along with climatological bins, climatological distribution percentile thresholds are automatically derived and used to compute probabilistic outputs. -Climatology data +Climatology Data ---------------- The Ensemble-Stat output includes at least three statistics computed relative to external climatology data. The climatology is defined by mean and standard deviation fields, and typically both are required in the computation of ensemble skill score statistics. MET assumes that the climatology follows a normal distribution, defined by the mean and standard deviation at each point. @@ -63,7 +63,7 @@ When computing the CRPS skill score for (:ref:`Gneiting et al., 2004 `. can be replicated using the appropriate options. The user selects a distribution for the observation error, along with parameters for that distribution. Rescaling and bias correction can also be specified prior to the perturbation. Random draws from the distribution can then be added to either, or both, of the forecast and observed fields, including ensemble members. Details about the effects of the choices on verification statistics should be considered, with many details provided in the literature (*e.g.* :ref:`Candille and Talagrand, 2008 `; :ref:`Saetra et al., 2004 `; :ref:`Santos and Ghelli, 2012 `). Generally, perturbation makes verification statistics better when applied to ensemble members, and worse when applied to the observations themselves. @@ -77,7 +77,7 @@ Practical Information This section contains information about configuring and running the Ensemble-Stat tool. The Ensemble-Stat tool creates or verifies gridded model data. For verification, this tool can accept either gridded or point observations. If provided, the climatology data files must be gridded. The input gridded model, observation, and climatology datasets must be on the same grid prior to calculation of any statistics, and in one of the MET supported gridded file formats. If gridded files are not on the same grid, MET will do the regridding for you if you specify the desired output grid. The point observations must be formatted as the NetCDF output of the point reformatting tools described in :numref:`reformat_point`. -ensemble_stat usage +ensemble_stat Usage ------------------- The usage statement for the Ensemble Stat tool is shown below: @@ -100,7 +100,7 @@ The usage statement for the Ensemble Stat tool is shown below: ensemble_stat has three required arguments and accepts several optional ones. -Required arguments ensemble_stat +Required Arguments ensemble_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **n_ens ens_file_1 ... ens_file_n** is the number of ensemble members followed by a list of ensemble member file names. This argument is not required when ensemble files are specified in the **ens_file_list**, detailed below. @@ -109,7 +109,7 @@ Required arguments ensemble_stat 3. The **config_file** is an **EnsembleStatConfig** file containing the desired configuration settings. -Optional arguments for ensemble_stat +Optional Arguments for ensemble_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. To produce ensemble statistics using gridded observations, use the **-grid_obs file** option to specify a gridded observation file. This option may be used multiple times if your observations are in several files. @@ -145,7 +145,7 @@ An example of the ensemble_stat calling sequence is shown below: In this example, the Ensemble-Stat tool will process six forecast files specified in the file list into an ensemble forecast. Observations in both point and grid format will be included, and be used to compute ensemble statistics separately. Ensemble Stat will create a NetCDF file containing requested ensemble fields and an output STAT file. -ensemble_stat configuration file +ensemble_stat Configuration File -------------------------------- The default configuration file for the Ensemble-Stat tool named **EnsembleStatConfig_default** can be found in the installed *share/met/config* directory. Another version is located in *scripts/config*. We encourage users to make a copy of these files prior to modifying their contents. Each configuration file (both the default and sample) contains many comments describing its contents. The contents of the configuration file are also described in the subsections below. @@ -426,7 +426,7 @@ The **seed** variable may be set to a specific value to make the assignment of r Refer to the description of the **boot** entry in :numref:`config_options` for more details on the random number generator. -ensemble_stat output +ensemble_stat Output -------------------- ensemble_stat can produce output in STAT, ASCII, and NetCDF formats. The ASCII output duplicates the STAT output but has the data organized by line type. The output files are written to the default output directory or the directory specified by the -outdir command line option. diff --git a/docs/Users_Guide/gen-ens-prod.rst b/docs/Users_Guide/gen-ens-prod.rst index 7c581d2baf..57da0849cb 100644 --- a/docs/Users_Guide/gen-ens-prod.rst +++ b/docs/Users_Guide/gen-ens-prod.rst @@ -11,10 +11,10 @@ The Gen-Ens-Prod tool generates simple ensemble products (mean, spread, probabil .. note:: This ensemble product generation step was provided by the Ensemble-Stat tool in earlier versions of MET. The Gen-Ens-Prod tool replaces and extends that functionality. Users are strongly encouraged to migrate ensemble product generation from Ensemble-Stat to Gen-Ens-Prod, as new features will only be added to Gen-Ens-Prod and the existing Ensemble-Stat functionality will be deprecated in a future version. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== -Ensemble forecasts derived from a set of deterministic ensemble members +Ensemble Forecasts Derived from a Set of Deterministic Ensemble Members ----------------------------------------------------------------------- Ensemble forecasts are often created as a set of deterministic forecasts. The ensemble members are rarely used separately. Instead, they can be combined in various ways to produce a forecast. MET can combine the ensemble members into some type of summary forecast according to user specifications. Ensemble means are the most common, and can be paired with the ensemble variance or spread. Maximum, minimum and other summary values are also available, with details in the practical information section. @@ -27,7 +27,7 @@ The neighborhood ensemble probability (NEP) and neighborhood maximum ensemble pr The Gen-Ens-Prod tool writes the gridded relative frequencies, NEP, and NMEP fields to a NetCDF output file. Probabilistic verification methods can then be applied to those fields by evaluating them with the Grid-Stat and/or Point-Stat tools. -Climatology data +Climatology Data ---------------- The ensemble relative frequencies derived by Gen-Ens-Prod are computed by applying threshold(s) to the input ensemble member data. Those thresholds can be simple and remain constant over the entire domain (e.g. >0) or can be defined relative to the climatological distribution at each grid point (e.g. >CDP90, for exceeding the 90-th percentile of climatology). When using climatological distribution percentile (CDP) thresholds, the climatological mean and standard deviation must be provided in the configuration file. @@ -37,7 +37,7 @@ Practical Information This section contains information about configuring and running the Gen-Ens-Prod tool. The Gen-Ens-Prod tool writes a NetCDF output file containing the requested ensemble product fields for each input field specified. If provided, the climatology data files must be gridded. All input gridded model and climatology datasets must be on the same grid. However, users may leverage the automated regridding feature in MET if the desired output grid is specified in the configuration file. -gen_ens_prod usage +gen_ens_prod Usage ------------------ The usage statement for the Ensemble Stat tool is shown below: @@ -54,7 +54,7 @@ The usage statement for the Ensemble Stat tool is shown below: gen_ens_prod has three required arguments and accepts several optional ones. -Required arguments gen_ens_prod +Required Arguments gen_ens_prod ------------------------------- 1. The **-ens file_1 ... file_n** option specifies the ensemble member file names. This argument is not required when ensemble files are specified in the **ens_file_list**, detailed below. @@ -65,7 +65,7 @@ Required arguments gen_ens_prod 4. The **-config file** option is a **GenEnsProdConfig** file containing the desired configuration settings. -Optional arguments for gen_ens_prod +Optional Arguments for gen_ens_prod ----------------------------------- 4. The **-ctrl file** option specifies the input file for the ensemble control member. Data for this member is included in the computation of the ensemble mean, but excluded from the spread. The control file should not appear in the **-ens** list of ensemble member files (unless processing a single file that contains all ensemble members). @@ -85,7 +85,7 @@ An example of the gen_ens_prod calling sequence is shown below: In this example, the Gen-Ens-Prod tool derives products from the input ensemble members listed on the command line. -gen_ens_prod configuration file +gen_ens_prod Configuration File ------------------------------- The default configuration file for the Gen-Ens-Prod tool named **GenEnsProdConfig_default** can be found in the installed *share/met/config* directory. Another version is located in *scripts/config*. We encourage users to make a copy of these files prior to modifying their contents. The contents of the configuration file are described in the subsections below. @@ -297,7 +297,7 @@ The **ensemble_flag** specifies which derived ensemble fields should be calculat 14. Climatological Distribution Percentile field for each CDP threshold specified -gen_ens_prod output +gen_ens_prod Output ------------------- The Gen-Ens-Prod tools writes a gridded NetCDF output file whose file name is specified using the -out command line option. The contents of that file depend on the contents of the **ens.field** array, the **ensemble_flag** options selected, and the presence of climatology data. The NetCDF variable names are self-describing and include the name/level of the field being processed, the type of ensemble product, and any relevant threshold information. If **nc_var_str** is defined for an **ens.field** array entry, that string is included in the corresponding NetCDF output variable names. diff --git a/docs/Users_Guide/grid-diag.rst b/docs/Users_Guide/grid-diag.rst index 96ec66375a..f2fd55e78c 100644 --- a/docs/Users_Guide/grid-diag.rst +++ b/docs/Users_Guide/grid-diag.rst @@ -9,10 +9,10 @@ Introduction The Grid-Diag tool creates histograms (probability distributions when normalized) for an arbitrary collection of data fields and levels. Joint histograms will be created for all possible pairs of variables. Masks can be used to subset the data fields spatially. The histograms are accumulated over a time series of input data files, similar to Series-Analysis. -Practical information +Practical Information ===================== -grid_diag usage +grid_diag Usage --------------- The following sections describe the usage statement, required arguments, and optional arguments for **grid_diag**. @@ -31,7 +31,7 @@ The following sections describe the usage statement, required arguments, and opt grid_diag has required arguments and can accept several optional arguments. -Required arguments for grid_diag +Required Arguments for grid_diag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-data file_1 ... file_n | data_file_list** options specify the gridded data files or an ASCII file containing a list of file names to be used. @@ -44,7 +44,7 @@ A typical use case for this option is for the first **-data** to specify forecas 3. The **-config file** is the configuration file to be used. The contents of the configuration file are discussed below. -Optional arguments for grid_diag +Optional Arguments for grid_diag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 log file. @@ -53,7 +53,7 @@ Optional arguments for grid_diag 6. 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. -grid_diag configuration file +grid_diag Configuration File ---------------------------- The default configuration file for the Grid-Diag tool named **GridDiagConfig_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. @@ -96,7 +96,7 @@ The **name** and **level** entries in the **data** dictionary define the data to Grid-Diag prints a warning message if the actual range of data values falls outside the range defined for that variable in the configuration file. Any data values less than the configured range are counted in the first bin, while values greater than the configured range are counted in the last bin. -grid_diag output file +grid_diag Output File --------------------- The NetCDF file has a dimension for each of the specified data variable and level combinations, e.g. APCP_L0 and PWAT_L0. The bin minimum, midpoint, and maximum values are indicated with an _min, _mid, or _max appended to the variable/level. diff --git a/docs/Users_Guide/grid-stat.rst b/docs/Users_Guide/grid-stat.rst index 61c6ccb5db..22fe740a55 100644 --- a/docs/Users_Guide/grid-stat.rst +++ b/docs/Users_Guide/grid-stat.rst @@ -11,29 +11,29 @@ The Grid-Stat tool functions in much the same way as the Point-Stat tool, except Scientific and statistical aspects of the Grid-Stat tool are briefly described in this section, followed by practical details regarding usage and output from the tool. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== -Statistical measures +Statistical Measures -------------------- The Grid-Stat tool computes a wide variety of verification statistics. Broadly speaking, these statistics can be subdivided into three types of statistics: measures for categorical variables, measures for continuous variables, and measures for probabilistic forecasts. Further, when a climatology file is included, reference statistics for the forecasts compared to the climatology can be calculated. These categories of measures are briefly described here; specific descriptions of all measures are provided in :numref:`Appendix C, Section %s `. Additional information can be found in :ref:`Wilks (2011) ` and :ref:`Jolliffe and Stephenson (2012) `, and on the Collaboration for Australian Weather and Climate Research Forecast Verification - `Issues, Methods and FAQ web page `_. In addition to these verification measures, the Grid-Stat tool also computes partial sums and other FHO statistics that are produced by the NCEP verification system. These statistics are also described in :numref:`Appendix C, Section %s `. -Measures for categorical variables +Measures for Categorical Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Categorical verification statistics are used to evaluate forecasts that are in the form of a discrete set of categories rather than on a continuous scale. Grid-Stat computes both 2x2 and multi-category contingency tables and their associated statistics, similar to Point-Stat. See :numref:`Appendix C, Section %s ` for more information. -Measures for continuous variables +Measures for Continuous Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For continuous variables, many verification measures are based on the forecast error (i.e., f - o). However, it also is of interest to investigate characteristics of the forecasts, and the observations, as well as their relationship. These concepts are consistent with the general framework for verification outlined by :ref:`Murphy and Winkler (1987) `. The statistics produced by MET for continuous forecasts represent this philosophy of verification, which focuses on a variety of aspects of performance rather than a single measure. See :numref:`Appendix C, Section %s ` for specific information. A user may wish to eliminate certain values of the forecasts from the calculation of statistics, a process referred to here as "conditional verification". For example, a user may eliminate all temperatures above freezing and then calculate the error statistics only for those forecasts of below freezing temperatures. Another common example involves verification of wind forecasts. Since wind direction is indeterminate at very low wind speeds, the user may wish to set a minimum wind speed threshold prior to calculating error statistics for wind direction. The user may specify these thresholds in the configuration file to specify the conditional verification. Thresholds can be specified using the usual Fortran conventions (<, <=, ==, !-, >=, or >) followed by a numeric value. The threshold type may also be specified using two letter abbreviations (lt, le, eq, ne, ge, gt). Further, more complex thresholds can be achieved by defining multiple thresholds and using && or || to string together event definition logic. The forecast and observation threshold can be used together according to user preference by specifying one of: UNION, INTERSECTION, or SYMDIFF (symmetric difference). -Measures for probabilistic forecasts and dichotomous outcomes +Measures for Probabilistic Forecasts and Dichotomous Outcomes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For probabilistic forecasts, many verification measures are based on reliability, accuracy and bias. However, it also is of interest to investigate joint and conditional distributions of the forecasts and the observations, as in :ref:`Wilks (2011) `. See :numref:`Appendix C, Section %s ` for specific information. @@ -42,27 +42,27 @@ Probabilistic forecast values are assumed to have a range of either 0 to 1 or 0 Since METv6.0, when the "prob" entry is set as a dictionary to define the field of interest, setting "prob_as_scalar = TRUE" indicates that this data should be processed as regular scalars rather than probabilities.For example, this option can be used to compute traditional 2x2 contingency tables and neighborhood verification statistics for probability data. It can also be used to compare two probability fields directly. -Use of a climatology field for comparative verification +Use of a Climatology Field for Comparative Verification ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Grid-Stat tool allows evaluation of model forecasts compared with a user-supplied climatology. Prior to calculation of statistics, the climatology must be put on the same grid as the forecasts and observations. In particular, the anomaly correlation and mean squared error skill score provide a measure of the forecast skill versus the climatology. For more details about climatological comparisons and reference forecasts, see the relevant section in the Point-Stat Chapter: :numref:`Climatology`. -Use of analysis fields for verification +Use of Analysis Fields for Verification ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Grid-Stat tool allows evaluation of model forecasts using model analysis fields. However, users are cautioned that an analysis field is not independent of its parent model; for this reason verification of model output using an analysis field from the same model is generally not recommended and is not likely to yield meaningful information about model performance. -Statistical confidence intervals +Statistical Confidence Intervals -------------------------------- The confidence intervals for the Grid-Stat tool are the same as those provided for the Point-Stat tool except that the scores are based on pairing grid points with grid points so that there are likely more values for each field making any assumptions based on the central limit theorem more likely to be valid. However, it should be noted that spatial (and temporal) correlations are not presently taken into account in the confidence interval calculations. Therefore, confidence intervals reported may be somewhat too narrow (e.g., :ref:`Efron, 2007 `). See :numref:`Appendix D, Section %s ` for details regarding confidence intervals provided by MET. -Grid weighting +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:`config_options` for more information. -Neighborhood methods +Neighborhood Methods -------------------- MET also incorporates several neighborhood methods to give credit to forecasts that are close to the observations, but not necessarily exactly matched up in space. Also referred to as "fuzzy" verification methods, these methods do not just compare a single forecast at each grid point to a single observation at each grid point; they compare the forecasts and observations in a neighborhood surrounding the point of interest. With the neighborhood method, the user chooses a distance within which the forecast event can fall from the observed event and still be considered a hit. In MET this is implemented by defining a square search window around each grid point. Within the search window, the number of observed events is compared to the number of forecast events. In this way, credit is given to forecasts that are close to the observations without requiring a strict match between forecasted events and observed events at any particular grid point. The neighborhood methods allow the user to see how forecast skill varies with neighborhood size and can help determine the smallest neighborhood size that can be used to give sufficiently accurate forecasts. @@ -73,7 +73,7 @@ The user must specify several parameters in the grid_stat configuration file to .. _grid-stat_seeps: -SEEPS scores +SEEPS Scores ------------ The Stable Equitable Error in Probability Space (SEEPS) was devised for monitoring global deterministic forecasts of precipitation against the WMO gauge network (:ref:`Rodwell et al., 2010 `; :ref:`Haiden et al., 2012 `) and is a multi-category score which uses a climatology to account for local variations in behavior. Please see Point-Stat documentation :numref:`PS_seeps` for more details. @@ -154,14 +154,14 @@ In some cases, a user may be interested in a much higher threshold than :math:`2 Since :math:`G_\beta` is so sensitive to the choice of :math:`\beta`, which is defined relative to the number of points in the verification domain, :math:`G_\beta` is only computed for the full verification domain. :math:`G_\beta` is reported as a bad data value for any masking region subsets of the full verification domain. -Practical information +Practical Information ===================== This section contains information about configuring and running the Grid-Stat tool. The Grid-Stat tool verifies gridded model data using gridded observations. The input gridded model and observation datasets must be in one of the MET supported file formats. The requirement of having all gridded fields using the same grid specification was removed in METv5.1. There is a regrid option in the configuration file that allows the user to define the grid upon which the scores will be computed. The gridded observation data may be a gridded analysis based on observations such as Stage II or Stage IV data for verifying accumulated precipitation, or a model analysis field may be used. The Grid-Stat tool provides the capability of verifying one or more model variables/levels using multiple thresholds for each model variable/level. The Grid-Stat tool performs no interpolation when the input model, observation, and climatology datasets must be on a common grid. MET will interpolate these files to a common grid if one is specified. The interpolation parameters may be used to perform a smoothing operation on the forecast field prior to verifying it to investigate how the scale of the forecast affects the verification statistics. The Grid-Stat tool computes a number of continuous statistics for the forecast minus observation differences, discrete statistics once the data have been thresholded, or statistics for probabilistic forecasts. All types of statistics can incorporate a climatological reference. -grid_stat usage +grid_stat Usage --------------- The usage statement for the Grid-Stat tool is listed below: @@ -179,7 +179,7 @@ The usage statement for the Grid-Stat tool is listed below: grid_stat has three required arguments and accepts several optional ones. -Required arguments for grid_stat +Required Arguments for grid_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **fcst_file** argument indicates the gridded file containing the model data to be verified. @@ -188,7 +188,7 @@ Required arguments for grid_stat 3. 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 grid_stat +Optional Arguments for grid_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-outdir path** indicates the directory where output files should be written. @@ -225,7 +225,7 @@ In the second example, the Grid-Stat tool will verify the model data in the samp .. _grid_stat-configuration-file: -grid_stat configuration file +grid_stat Configuration File ---------------------------- The default configuration file for the Grid-Stat tool, named **GridStatConfig_default**, can be found in the installed *share/met/config* directory. Other versions of the configuration file are included in *scripts/config*. We recommend that users make a copy of the default (or other) configuration file prior to modifying it. The contents are described in more detail below. @@ -471,7 +471,7 @@ The **nc_pairs_var_suffix** entry is similar to the **nc_pairs_var_name** entry. .. _grid_stat-output: -grid_stat output +grid_stat Output ---------------- grid_stat produces output in STAT and, optionally, ASCII and NetCDF formats. The ASCII output duplicates the STAT output but has the data organized by line type. The output files are written to the default output directory or the directory specified by the -outdir command line option. diff --git a/docs/Users_Guide/gsi-tools.rst b/docs/Users_Guide/gsi-tools.rst index b5bde4f9a7..a6e80a448e 100644 --- a/docs/Users_Guide/gsi-tools.rst +++ b/docs/Users_Guide/gsi-tools.rst @@ -12,12 +12,12 @@ When MET reads GSI diagnostic files, the innovation (O-B; generated prior to the MET includes two tools for processing GSI diagnostic files. The GSID2MPR tool reformats individual GSI diagnostic files into the MET matched pair (MPR) format, similar to the output of the Point-Stat tool. The GSIDENS2ORANK tool processes an ensemble of GSI diagnostic files and reformats them into the MET observation rank (ORANK) line type, similar to the output of the Ensemble-Stat tool. The output of both tools may be passed to the Stat-Analysis tool to compute a wide variety of continuous, categorical, and ensemble statistics. -GSID2MPR tool +GSID2MPR Tool ============= This section describes how to run the GSID2MPR tool. The GSID2MPR tool reformats one or more GSI diagnostic files into an ASCII matched pair (MPR) format, similar to the MPR output of the Point-Stat tool. The output MPR data may be passed to the Stat-Analysis tool to compute a wide variety of continuous or categorical statistics. -gsid2mpr usage +gsid2mpr Usage -------------- The usage statement for the GSID2MPR tool is shown below: @@ -37,12 +37,12 @@ The usage statement for the GSID2MPR tool is shown below: gsid2mpr has one required argument and accepts several optional ones. -Required arguments for gsid2mpr +Required Arguments for gsid2mpr ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **gsi_file_1 [gsi_file2 ... gsi_file_n]** argument indicates the GSI diagnostic files (conventional or radiance) to be reformatted. -Optional arguments for gsid2mpr +Optional Arguments for gsid2mpr ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2. The **-swap** option switches the endianness when reading the input binary files. @@ -71,7 +71,7 @@ An example of the gsid2mpr calling sequence is shown below: In this example, the GSID2MPR tool will process a single input file named **diag_conv_ges.mem001** file, set the output **MODEL** header column to **GSI_MEM001**, and write output to the **out** directory. The output file is named the same as the input file but a **.stat** suffix is added to indicate its format. -gsid2mpr output +gsid2mpr Output --------------- The GSID2MPR tool performs a simple reformatting step and thus requires no configuration file. It can read both conventional and radiance binary GSI diagnostic files. Support for additional GSI diagnostic file type may be added in future releases. Conventional files are determined by the presence of the string **conv** in the filename. Files that are not conventional are assumed to contain radiance data. Multiple files of either type may be passed in a single call to the GSID2MPR tool. For each input file, an output file will be generated containing the corresponding matched pair data. @@ -243,12 +243,12 @@ An example of the Stat-Analysis calling sequence is shown below: In this example, the Stat-Analysis tool will read MPR lines from the input file named **diag_conv_ges.mem001.stat**, retain only those lines where the **FCST_VAR** column indicates temperature (**t**) and where the **ANLY_USE** column has a value of 1.0, and derive continuous statistics. -GSIDENS2ORANK tool +GSIDENS2ORANK Tool ================== This section describes how to run the GSIDENS2ORANK tool. The GSIDENS2ORANK tool processes an ensemble of GSI diagnostic files and reformats them into the MET observation rank (ORANK) line type, similar to the output of the Ensemble-Stat tool. The ORANK line type contains ensemble matched pair information and is analogous to the MPR line type for a deterministic model. The output ORANK data may be passed to the Stat-Analysis tool to compute ensemble statistics. -gsidens2orank usage +gsidens2orank Usage ------------------- The usage statement for the GSIDENS2ORANK tool is shown below: @@ -268,7 +268,7 @@ The usage statement for the GSIDENS2ORANK tool is shown below: gsidens2orank has three required arguments and accepts several optional ones. -Required arguments for gsidens2orank +Required Arguments for gsidens2orank ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **ens_file_1 ... ens_file_n** argument is a list of ensemble binary GSI diagnostic files to be reformatted. @@ -277,7 +277,7 @@ Required arguments for gsidens2orank 3. The **-out path** argument specifies the name of the output **.stat** file. -Optional arguments for gsidens2orank +Optional Arguments for gsidens2orank ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-ens_mean path** option is the ensemble mean binary GSI diagnostic file. @@ -306,7 +306,7 @@ An example of the gsidens2orank calling sequence is shown below: In this example, the GSIDENS2ORANK tool will process all of the ensemble members whose file name **matches diag_conv_ges.mem\*,** write output to the file named **diag_conv_ges_ens_mean_orank.txt**, and populate the output **ENS_MEAN** column with the values found in the **diag_conv_ges.ensmean** file rather than computing the ensemble mean values from the ensemble members on the fly. -gsidens2orank output +gsidens2orank Output -------------------- The GSIDENS2ORANK tool performs a simple reformatting step and thus requires no configuration file. The multiple files passed to it are interpreted as members of the same ensemble. Therefore, each call to the tool processes exactly one ensemble. All input ensemble GSI diagnostic files must be of the same type. Mixing conventional and radiance files together will result in a runtime error. The GSIDENS2ORANK tool processes each ensemble member and keeps track of the observations it encounters. It constructs a list of the ensemble values corresponding to each observation and writes an output ORANK line listing the observation value, its rank, and all the ensemble values. The random number generator is used by the GSIDENS2ORANK tool to randomly assign a rank value in the case of ties. diff --git a/docs/Users_Guide/installation.rst b/docs/Users_Guide/installation.rst index 5e4318b349..a8c743f9e6 100644 --- a/docs/Users_Guide/installation.rst +++ b/docs/Users_Guide/installation.rst @@ -145,7 +145,7 @@ Building the MET Package Building the MET package consists of three main steps: (1) install the required libraries, (2) configure the environment variables, and (3) configure and execute the build. Users can follow the instructions below or use a sample installation script. Users can find the script and its instructions under on the `Downloads `_ page of the MET website. -Get the MET source code +Get the MET Source Code ----------------------- The MET source code is available for download from the public `MET GitHub repository `_. diff --git a/docs/Users_Guide/masking.rst b/docs/Users_Guide/masking.rst index a4e7345643..0d705ac06e 100644 --- a/docs/Users_Guide/masking.rst +++ b/docs/Users_Guide/masking.rst @@ -6,12 +6,12 @@ Regional Verification using Spatial Masking Verification over a particular region or area of interest may be performed using "masking". Defining a masking region is simply selecting the desired set of grid points to be used. The Gen-Vx-Mask tool automates this process and replaces the Gen-Poly-Mask and Gen-Circle-Mask tools from previous releases. It may be run to create a bitmap verification masking region to be used by many of the statistical tools. This tool enables the user to generate a masking region once for a domain and apply it to many cases. It has been enhanced to support additional types of masking region definition (e.g. tropical-cyclone track over water only). An iterative approach may be used to define complex areas by combining multiple masking regions together. -Gen-Vx-Mask tool +Gen-Vx-Mask Tool ================ The Gen-Vx-Mask tool may be run to create a bitmap verification masking region to be used by the MET statistics tools. This tool enables the user to generate a masking region once for a domain and apply it to many cases. While the MET statistics tools can define some masking regions on the fly using polylines, doing so can be slow, especially for complex polylines containing hundreds of vertices. Using the Gen-Vx-Mask tool to create a bitmap masking region before running the other MET tools will make them run more efficiently. -gen_vx_mask usage +gen_vx_mask Usage ----------------- The usage statement for the Gen-Vx-Mask tool is shown below: @@ -40,7 +40,7 @@ The usage statement for the Gen-Vx-Mask tool is shown below: gen_vx_mask has four required arguments and can take optional ones. Note that **-type string** (masking type) was previously optional but is now required. -Required arguments for gen_vx_mask +Required Arguments for gen_vx_mask ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **input_grid** argument is a named grid, the path to a gridded data file, or an explicit grid specification string (see :numref:`App_B-grid_specification_strings`) which defines the grid for which a mask is to be defined. If set to a gen_vx_mask output file, automatically read mask data as the **input_field**. @@ -61,7 +61,7 @@ Required arguments for gen_vx_mask 4. The **-type string** is required to set the masking type. The application will give an error message and exit if "-type string" is not specified on the command line. See the description of supported types below. -Optional arguments for gen_vx_mask +Optional Arguments for gen_vx_mask ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. The **-input_field string** option can be used to read existing mask data from "input_file". @@ -100,7 +100,7 @@ Optional arguments for gen_vx_mask .. _Types_of_masking_gen_vx_mask: -Types of masking available in gen_vx_mask +Types of Masking Available in gen_vx_mask ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Gen-Vx-Mask tool supports the following types of masking region definition selected using the **-type** command line option: diff --git a/docs/Users_Guide/met-tc_overview.rst b/docs/Users_Guide/met-tc_overview.rst index d7930b6a75..75df964106 100644 --- a/docs/Users_Guide/met-tc_overview.rst +++ b/docs/Users_Guide/met-tc_overview.rst @@ -11,14 +11,14 @@ The purpose of this User's Guide is to provide basic information to the users of The following sections provide an overview of MET-TC and its components, as well as basic information on the software build. The required input, including file format and the MET-TC are discussed followed by a description of the TC-DLand, TC-Diag, TC-Pairs, TC-Stat, TC-RMW, and RMW-Analysis tools. Each section covers the input, output and practical usage including a description of the configuration files. This is followed by a short overview of graphical utilities available within the MET-TC release. -MET-TC components +MET-TC Components ================= The MET tools used in the verification of Tropical Cyclones are referred to as MET-TC. These tools are shown across the bottom of the flowchart in :numref:`overview-figure`. The MET-TC tools are described in more detail in later sections. Tropical cyclone forecasts and observations are quite different than numerical model forecasts, and thus they have their own set of tools. These consist of TC-DLand, TC-Diag, TC-Pairs, TC-Stat, TC-Gen, TC-RMW, and RMW-Analysis. The TC-DLand module calculates the distance to land from all locations on a specified grid. This information can be used in later modules to eliminate tropical cyclones that are over land from being included in the statistics. TC-Diag converts gridded model output into cylindrical coordinates for each storm location, calls Python scripts to compute storm-relative diagnostics, and writes ASCII output to be read by TC-Pairs. TC-Pairs matches up tropical cyclone forecasts and observations and writes all output to a file. In TC-Stat, these forecast / observation pairs are analyzed according to user preference to produce statistics. TC-Gen evaluates the performance of Tropical Cyclone genesis forecast using contingency table counts and statistics. TC-RMW performs a coordinate transformation for gridded model or analysis fields centered on the current storm location. RMW-Analysis filters and aggregates the output of TC-RMW across multiple cases. -Input data format +Input Data Format ================= This section discusses the input and output file formats expected and produced by MET-TC. When discussing the input data, it is expected that users have run model output through vortex tracking software in order to obtain position and intensity information in Automated Tropical Cyclone Forecasting System (ATCF) file format. Best track and aids files in Automated Tropical Cyclone Forecasting System (ATCF) format (hereafter referred to as ATCF format) are necessary for model data input into the TC-Pairs tool. The ATCF format was first developed at the Naval Oceanographic and Atmospheric Research Laboratory (NRL), and is currently used for the National Hurricane Center (NHC) operations. ATCF format must be adhered to in order for the MET-TC tools to properly parse the input data. @@ -109,7 +109,7 @@ All operational model aids and the BEST can be obtained from the `NHC ftp server If a user has gridded model output, the model data must be run through a vortex tracking algorithm in order to obtain the ATCF-formatted input that MET-TC requires. Many vortex tracking algorithms have been developed in order to obtain basic position, maximum wind, and minimum sea level pressure information from model forecasts. One vortex tracking algorithm that is supported and freely available is the `GFDL vortex tracker package. `_ -Output data format +Output Data Format ================== The MET package produces output in four basic file formats: STAT files, ASCII files, NetCDF files, and PostScript plots. The MET-TC tool produces output in TCSTAT, which stands for Tropical Cyclone - STAT. This output format consists of tabular ASCII data that can be easily read by many analysis tools and software packages, making the output from MET-TC very versatile. Like STAT, TCSTAT is a specialized ASCII format containing one record on each line. Currently, the only line type available in MET-TC is TCMPR (Tropical Cyclone Matched Pairs). As more line types are included in future releases, all line types will be included in a single TCSTAT file. The TC-DLand, TC-Diag, TC-RMW, and RMW-Analysis tools also write NetCDF files containing a variety of output data types. diff --git a/docs/Users_Guide/mode-analysis.rst b/docs/Users_Guide/mode-analysis.rst index c37db8ac8b..aa82392555 100644 --- a/docs/Users_Guide/mode-analysis.rst +++ b/docs/Users_Guide/mode-analysis.rst @@ -11,21 +11,21 @@ Users may wish to summarize multiple ASCII files produced by MODE across many ca .. _MODE_A-Scientific-and-statistical: -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== The MODE-Analysis tool operates in two modes, called "summary" and "bycase". In summary mode, the user specifies on the command line the MODE output columns of interest as well as filtering criteria that determine which input lines should be used. For example, a user may be interested in forecast object areas, but only if the object was matched, and only if the object centroid is inside a particular region. The summary statistics generated for each specified column of data are the minimum, maximum, mean, standard deviation, and the 10th, 25th, 50th, 75th and 90th percentiles. In addition, the user may specify a "dump'" file: the individual MODE lines used to produce the statistics will be written to this file. This option provides the user with a filtering capability. The dump file will consist only of lines that match the specified criteria. The other option for operating the analysis tool is "bycase". Given initial and final values for forecast lead time, the tool will output, for each valid time in the interval, the matched area, unmatched area, and the number of forecast and observed objects that were matched or unmatched. For the areas, the user can specify forecast or observed objects, and also simple or cluster objects. A dump file may also be specified in this mode. -Practical information +Practical Information ===================== The MODE-Analysis tool reads lines from MODE ASCII output files and applies filtering and computes basic statistics on the object attribute values. For each job type, filter parameters can be set to determine which MODE output lines are used. The following sections describe the mode_analysis usage statement, required arguments, and optional arguments. .. _mode_analysis-usage: -mode_analysis usage +mode_analysis Usage ------------------- The usage statement for the MODE-Analysis tool is shown below: @@ -46,7 +46,7 @@ The usage statement for the MODE-Analysis tool is shown below: The MODE-Analysis tool has two required arguments and can accept several optional arguments. -Required arguments for mode_analysis: +Required Arguments for mode_analysis: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-lookin path** specifies the name of a specific STAT file (any file ending in .stat) or the name of a directory where the Stat-Analysis tool will search for STAT files. This option may be used multiple times to specify multiple locations. @@ -57,12 +57,12 @@ Specifying **-summary** will produce summary statistics for the MODE output colu Specifying **-bycase** will produce a table of metrics for each case undergoing analysis. Any columns specified are ignored for this option. -Optional arguments for mode_analysis +Optional Arguments for mode_analysis ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. The mode_analysis options are described in the following section. These are divided into sub-sections describing the analysis options and mode line options. -Analysis options +Analysis Options ^^^^^^^^^^^^^^^^ The general analysis options described below provide a way for the user to indicate configuration files to be used, where to write lines used to perform the analysis, and over which fields to generate statistics. @@ -137,7 +137,7 @@ This toggle indicates whether matched or unmatched object lines should be used. -Multiple-set string options +Multiple-Set String Options ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following options set various string attributes. They can be set multiple times on the command line but must be separated by spaces. Each of these options must be indicated as a string. String values that include spaces may be used by enclosing the string in quotation marks. @@ -189,7 +189,7 @@ These options indicate vertical levels for forecast and observed fields to be us ____________________ -Multiple-set integer options +Multiple-Set Integer Options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following options set various integer attributes. They can be set multiple times on the command line but must be separated by spaces. Each of the following options may only be indicated as an integer. @@ -225,7 +225,7 @@ These options indicate the convolution radius used for forecast or observed obje _____________________ -Integer max/min options +Integer Max/Min Options ^^^^^^^^^^^^^^^^^^^^^^^ These options set limits on various integer attributes. Leaving a maximum value unset means no upper limit is imposed on the value of the attribute. The option works similarly for minimum values. @@ -288,7 +288,7 @@ ____________________ These options refer to the minimum/maximum values for symmetric difference for objects to be used in the analysis. -Date/time max/min options +Date/Time Max/Min Options ^^^^^^^^^^^^^^^^^^^^^^^^^ These options set limits on various date/time attributes. The values can be specified in one of three ways: @@ -324,7 +324,7 @@ These two options indicate minimum/maximum values for forecast and observation i _____________________ -Floating-point max/min options +Floating-Point Max/Min Options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Setting limits on various floating-point attributes. One may specify these as integers (i.e., without a decimal point), if desired. The following pairs of options indicate minimum and maximum values for each MODE attribute that can be described as a floating-point number. Please refer to :numref:`MODE-output` for a description of these attributes as needed. @@ -562,7 +562,7 @@ ____________________ -interest_max value -Miscellaneous options +Miscellaneous Options ^^^^^^^^^^^^^^^^^^^^^ These options are used to indicate parameters that did not fall into any of the previous categories. @@ -587,14 +587,14 @@ This option prints the usage message. .. _mode_analysis-configuration-file: -mode_analysis configuration file +mode_analysis Configuration File -------------------------------- To use the MODE-Analysis tool, the user must un-comment the options in the configuration file to apply them and comment out unwanted options. The options in the configuration file for the MODE-Analysis tools are the same as the MODE command line options described in :numref:`mode_analysis-usage`. The parameters that are set in the configuration file either add to or override parameters that are set on the command line. For the "set string" and "set integer type" options enclosed in brackets, the values specified in the configuration file are added to any values set on the command line. For the "toggle" and "min/max type" options, the values specified in the configuration file override those set on the command line. -mode_analysis output +mode_analysis Output -------------------- The output of the MODE-Analysis tool is a self-describing tabular format written to standard output. The length and contents of the table vary depending on whether **-summary** or **-bycase** is selected. The contents also change for **-summary** depending on the number of columns specified by the user. diff --git a/docs/Users_Guide/mode-td.rst b/docs/Users_Guide/mode-td.rst index e205ccba36..c8c07c1117 100644 --- a/docs/Users_Guide/mode-td.rst +++ b/docs/Users_Guide/mode-td.rst @@ -28,7 +28,7 @@ At first glance, the addition of a third dimension would seem to entail no diffi In this section, we will assume that the reader has a basic familiarity with traditional MODE, its internal operation, (convolution thresholding, fuzzy logic matching and merging) and its output. We will not review these things here. Instead, we will point out differences in MTD from the way traditional MODE does things when they come up. This release is a beta version of MTD, intended mostly to encourage users to experiment with it and give us feedback and suggestions to be used in a more robust MTD release in the future. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== Attributes @@ -177,17 +177,17 @@ To summarize: Any forecast simple objects that find themselves in the same equiv Match & Merge Example -Practical information +Practical Information ===================== -MTD input +MTD Input --------- The formats for two-dimensional data files used as input to MTD are the same ones supported by most of the MET tools. Generally speaking, if MODE can use a forecast or observation data file as input, then that file can also be used by MTD. The only difference is that while MODE takes only one forecast and one observed data file as input, MTD takes a series of files. As shown in the next section, filenames for each time used must be given. Thus, for example, if MTD is being used for verification over a period of 24 hours, and the data file valid times are separated by one hour, then a total of 48 filenames must be specified on the MTD command line - 24 filenames for the forecast files, and 24 for the observation files. Further, the filenames must be given in order of increasing valid time. Many users will prefer to write scripts to automate this, rather than type in a lengthy command line by hand. -MTD usage +MTD Usage --------- The usage statement for the MODE-TD tool is listed below: The command line switches may be given in any order. @@ -205,7 +205,7 @@ The usage statement for the MODE-TD tool is listed below: The command line switc The MODE-TD tool has three required arguments and can accept several optional arguments. -Required arguments for mtd +Required Arguments for mtd ^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. **-fcst file\_list** gives a list of forecast 2D data files to be processed by MTD. The files should have equally-spaced intervals of valid time. @@ -214,7 +214,7 @@ Required arguments for mtd 3. **-config config\_file** gives the path to a local configuration file that is specific to this particular run of MTD. The default MTD configuration file will be read first, followed by this one. Thus, only configuration options that are different from the default settings need be specified. Options set in this file will override any corresponding options set in the default configuration file. -Optional arguments for mtd +Optional Arguments for mtd ^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. **-single file\_list** may be used instead of **-fcst** and **-obs** to define objects in a single field. @@ -237,7 +237,7 @@ An example of the mtd calling sequence is listed below: In this example, the MODE-TD tool will read in a list of forecast GRIB files in the fcst_files directory and similarly spaced observation GRIB files in the obs_files directory. It uses a configuration file called **MTDConfig_default** and writes the output to the *out_dir/mtd* directory. -MTD configuration file +MTD Configuration File ---------------------- The default configuration file for the MODE tool, **MODEConfig_default**, can be found in the installed *share/met/config* directory. Another version of the configuration file is provided in *scripts/config*. We encourage users to make a copy of the configuration files prior to modifying their contents.Most of the entries in the MTD configuration file should be familiar from the corresponding file for MODE. This initial beta release of MTD does not offer all the tunable options that MODE has accumulated over the years, however. In this section, we will not bother to repeat explanations of config file details that are exactly the same as those in MODE; we will only explain those elements that are different from MODE, and those that are unique to MTD. @@ -351,7 +351,7 @@ ______________________ The **txt_output** dictionary also contains a collection of boolean flags, in this case controlling the output of ASCII attribute files. The **attributes_2d** flag controls the output of the 2D object attributes for constant-time slices of 3D objects, while the **attributes_3d** flag controls the output of single and pair 3D spacetime object attributes. -mtd output +mtd Output ---------- MTD creates several output files after each run in ASCII and NetCDF formats. There are text files giving 2D and 3D attributes of spacetime objects and information on matches and merges, as well as a NetCDF file giving the objects themselves, in case any further or specialized analysis of the objects needs to be done. diff --git a/docs/Users_Guide/mode.rst b/docs/Users_Guide/mode.rst index 98ab658ea4..9da477d24f 100644 --- a/docs/Users_Guide/mode.rst +++ b/docs/Users_Guide/mode.rst @@ -17,12 +17,12 @@ MODE may be used in a generalized way to compare any two fields. For simplicity, .. _MODE_Scientific-and-statistical: -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== The methods used by the MODE tool to identify and match forecast and observed objects are briefly described in this section. -Resolving objects +Resolving Objects ----------------- The process used for resolving objects in a raw data field is called *convolution thresholding*. The raw data field is first convolved with a simple filter function as follows: @@ -81,7 +81,7 @@ All the attributes discussed so far are defined for single objects. Once these a Several area measures are also used for pair attributes. **Union Area** is the total area that is in either one (or both) of the two objects. **Intersection Area** is the area that is inside both objects simultaneously. **Symmetric Difference** is the area inside at least one object, but not inside both. -Fuzzy logic +Fuzzy Logic ----------- Once object attributes :math:`\alpha_1,\alpha_2,\ldots,\alpha_n` are estimated, some of them are used as input to a fuzzy logic engine that performs the matching and merging steps. **Merging** refers to grouping together objects in a single field, while **matching** refers to grouping together objects in different fields, typically the forecast and observed fields. Interest maps :math:`I_i` are applied to the individual attributes :math:`\alpha_i` to convert them into interest values, which range from zero (representing no interest) to one (high interest). For example, the default interest map for centroid difference is one for small distances, and falls to zero as the distance increases. For other attributes (*e.g.*, intersection area), low values indicate low interest, and high values indicate more interest. @@ -98,7 +98,7 @@ This total interest value is then thresholded, and pairs of objects that have to Another merging method is available in MODE, which can be used instead of, or along with, the fuzzy logic based merging just described. Recall that the convolved field is thresholded to produce the mask field. A second (lower) threshold can be specified so that objects that are separated at the higher threshold but joined at the lower threshold are merged. -Summary statistics +Summary Statistics ------------------ Once MODE has been run, summary statistics are written to an output file. These files contain information about all single and cluster objects and their attributes. Total interest for object pairs is also output, as are percentiles of intensity inside the objects. The output file is in a simple flat ASCII tabular format (with one header line) and thus should be easily readable by just about any programming language, scripting language, or statistics package. Refer to :numref:`MODE-output` for lists of the statistics included in the MODE output files. Example scripts will be posted on the MET website in the future. @@ -118,14 +118,14 @@ match. If a particular **multivar_intensity_flag** value is TRUE the correspond If all **multivar_intensity_flag** values are FALSE, the forecast and observation *super* objects are written to NetCDF, text, and postscript output files in the standard mode output format, but with no intensity information. -Practical information +Practical Information ===================== This section contains a description of how MODE can be configured and run. The MODE tool is used to perform a features-based verification of gridded model data using gridded observations. The input gridded model and observation datasets must be in one of the MET supported gridded file formats. If the input datasets are not already on a common grid, MODE can interpolate them to a common grid. The regrid option in the configuration file enables the user to specify the grid upon which the scores will be computed. The gridded analysis data may be based on observations, such as Stage II or Stage IV data for verifying accumulated precipitation, or a model analysis field may be used. However, users are cautioned that it is generally unwise to verify model output using an analysis field produced by the same model. MODE provides the capability to select a single model variable/level from which to derive objects to be analyzed. MODE was developed and tested using accumulated precipitation. However, the code has been generalized to allow the use of any gridded model and observation field. Based on the options specified in the configuration file, MODE will define a set of simple objects in the model and observation fields. It will then compute an interest value for each pair of objects across the fields using a fuzzy engine approach. Those interest values are thresholded, and any pairs of objects above the threshold will be matched/merged. Through the configuration file, MODE offers a wide range of flexibility in how the objects are defined, processed, matched, and merged. -mode usage +mode Usage ---------- The usage statement for the MODE tool is listed below: @@ -144,7 +144,7 @@ The usage statement for the MODE tool is listed below: The MODE tool has three required arguments and can accept several optional arguments. -Required arguments for mode +Required Arguments for mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **fcst_file** argument indicates the gridded file containing the model field to be verified. @@ -153,7 +153,7 @@ Required arguments for mode 3. 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 mode +Optional Arguments for mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-config_merge merge_config_file** option indicates the name of a second configuration file to be used when performing fuzzy engine merging by comparing the model or observation field to itself. The MODE tool provides the capability of performing merging within a single field by comparing the field to itself. Interest values are computed for each object and all of its neighbors. If an object and its neighbor have an interest value above some threshold, they are merged. The **merge_config_file** controls the settings of the fuzzy engine used to perform this merging step. If a **merge_config_file** is not provided, the configuration specified by the config_file in the previous argument will be used. @@ -192,11 +192,13 @@ In Example 2, the MODE tool will verify the model data in the sample_fcst.nc Net .. _MODE-configuration-file: -mode configuration file +mode Configuration File ----------------------- The default configuration file for the MODE tool, **MODEConfig_default**, can be found in the installed *share/met/config* directory. Another version of the configuration file is provided in *scripts/config*. We encourage users to make a copy of the configuration files prior to modifying their contents. Descriptions of **MODEConfig_default** and the required variables for any MODE configuration file are also provided below. While the configuration file contains many entries, most users will only need to change a few for their use. Specific options are described in the following subsections. +A second default configuration file for the multivar MODE option, **MODEMultivarConfig_default**, is also found in the installed *share/met/config* directory. We encourage users to make a copy of this default configuration file when setting up a multivar configuration prior to modifying content. The two default config files **MODEConfig_default** and **MODEMultivarConfig_default** are similar, with **MODEMultivarConfig_default** having example multivar specific content. + Note that environment variables may be used when editing configuration files, as described in the :numref:`config_env_vars`. _____________________ @@ -251,15 +253,13 @@ _____________________ The **multivar_intensity_flag** entry appears only in the **MODEMultivarConfig_default** file. This option is paired with the **multivar_logic** entry, and can take on a value of TRUE or FALSE for each **field**. In the multivar case, super objects are created using the **multivar_logic** settings. For each input for which **multivar_intensity_flag** is TRUE, the input is masked to be non-missing only within the super objects, and traditional mode is run on that masked input. For each input for which **multivar_intensity_flag** is FALSE, the input is skipped over. If all the multivar_intensity_flag values are FALSE, traditional mode output is created for the super objects, but with no intensity information. - _____________________ .. code-block:: none - multivar_name = "Precip"; - -The **multivar_name** entry appears only in the **MODEMultivarConfig_default** file. This option is used only when the multivar option is enabled, and only when all **multivar_intensity_flag** values are FALSE. It can be thought of as an identifier for the multivariate super object. It shows up in output files names and content. If not set the default value is "Super". It can be set separately for forecasts and observations, or as a common value for both. + multivar_name = "Super"; +The **multivar_name** entry appears only in the **MODEMultivarConfig_default** file. This option is used only when the multivar option is enabled, and only when all **multivar_intensity_flag** values are FALSE. It can be thought of as an identifier for the multivariate super object. It shows up in output files names and content. It can be set separately for forecasts and observations or as a common value for both. _____________________ @@ -324,7 +324,7 @@ The **merge_flag** entry controls what type of merging techniques will be applie • **BOTH** indicates that both techniques should be used. -By default, the double thresholding merging technique is applied. +By default, the double thresholding **THRESH** merging technique is applied in single variable mode. The merging defaults to **NONE** with multivariate mode. _____________________ @@ -545,7 +545,7 @@ When MODE is run on global grids, this parameter specifies how many grid squares .. _MODE-output: -mode output +mode Output ----------- MODE produces output in ASCII, NetCDF, and PostScript formats. diff --git a/docs/Users_Guide/overview.rst b/docs/Users_Guide/overview.rst index dff4c81fc1..37cf16b404 100644 --- a/docs/Users_Guide/overview.rst +++ b/docs/Users_Guide/overview.rst @@ -4,7 +4,7 @@ Overview of MET *************** -Purpose and organization of the User's Guide +Purpose and Organization of the User's Guide ============================================ The goal of this User's Guide is to provide basic information for users of the Model Evaluation Tools (MET) to enable them to apply MET to their datasets and evaluation studies. MET was originally designed for application to the post-processed output of the `Weather Research and Forecasting (WRF) `_ model. However, MET may also be used for the evaluation of forecasts from other models or applications, including the `Unified Forecast System (UFS) `_, and the `System for Integrated Modeling of the Atmosphere (SIMA) `_ if certain file format definitions (described in this document) are followed. @@ -22,7 +22,7 @@ The MET package is available to DTC staff, visitors, and collaborators, as well .. _MET-goals: -MET goals and design philosophy +MET Goals and Design Philosophy =============================== The primary goal of MET development is to provide a state-of-the-art verification package to the NWP community. By "state-of-the-art" we mean that MET will incorporate newly developed and advanced verification methodologies, including new methods for diagnostic and spatial verification and new techniques provided by the verification and modeling communities. MET also utilizes and replicates the capabilities of existing systems for verification of NWP forecasts. For example, the MET package replicates existing National Center for Environmental Prediction (NCEP) operational verification capabilities (e.g., I/O, methods, statistics, data types). MET development will take into account the needs of the NWP community - including operational centers and the research and development community. Some of the MET capabilities include traditional verification approaches for standard surface and upper air variables (e.g., Equitable Threat Score, Mean Squared Error), confidence intervals for verification measures, and spatial forecast verification methods. In the future, MET will include additional state-of-the-art and new methodologies. @@ -31,7 +31,7 @@ The MET package has been designed to be modular and adaptable. For example, indi The MET code and documentation is maintained by the DTC in Boulder, Colorado. The MET package is freely available to the modeling, verification, and operational communities, including universities, governments, the private sector, and operational modeling and prediction centers. -MET components +MET Components ============== The major components of the MET package are represented in :numref:`overview-figure`. The main stages represented are input, reformatting, plotting, intermediate output, statistical analyses, and output and aggregation/analysis. Each of these stages is described further in later sections. For example, the input and output formats are discussed in :numref:`data_io` as well as in the sections associated with each of the statistics modules. MET input files are represented on the far left. @@ -70,12 +70,12 @@ Tropical cyclone forecasts and observations are quite different than numerical m The following sections of this MET User's Guide contain usage statements for each tool, which may be viewed if you type the name of the tool. Alternatively, the user can also type the name of the tool followed by **-help** to obtain the usage statement. Each tool also has a **-version** command line option associated with it so that the user can determine what version of the tool they are using. -Future development plans +Future Development Plans ======================== MET is an evolving verification software package. New capabilities are planned in controlled, successive version releases. Bug fixes and user-identified problems will be addressed as they are found and posted to the known issues section of the `MET User Support web page `_. Plans are also in place to incorporate many new capabilities and options in future releases of MET. Please refer to the issues listed in the `MET GitHub repository `_ to see our development priorities for upcoming releases. -Code support +Code Support ============ MET support is provided through the `METplus GitHub Discussions Forum `_. We will endeavor to respond to requests for help in a timely fashion. In addition, information about MET and tools that can be used with MET are provided on the `MET web page `_. diff --git a/docs/Users_Guide/plotting.rst b/docs/Users_Guide/plotting.rst index 3c03278114..b1f9880146 100644 --- a/docs/Users_Guide/plotting.rst +++ b/docs/Users_Guide/plotting.rst @@ -9,7 +9,7 @@ Plotting Utilities This section describes how to check your data files using plotting utilities. Point observations can be plotted using the Plot-Point-Obs utility. A single model level can be plotted using the plot_data_plane utility. For object based evaluations, the MODE objects can be plotted using plot_mode_field. Occasionally, a post-processing or timing error can lead to errors in MET. These tools can assist the user by showing the data to be verified to ensure that times and locations match up as expected. -plot_point_obs usage +plot_point_obs Usage -------------------- The usage statement for the Plot-Point-Obs utility is shown below: @@ -31,14 +31,14 @@ The usage statement for the Plot-Point-Obs utility is shown below: plot_point_obs has two required arguments and can take optional ones. -Required arguments for plot_point_obs +Required Arguments for plot_point_obs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **nc_file** argument indicates the name of the point observation file to be plotted. This file is the output from one of the point pre-processing tools, such as pb2nc. Python embedding for point observations is also supported, as described in :numref:`pyembed-point-obs-data`. 2. The **ps_file** argument indicates the name given to the output file containing the plot. -Optional arguments for plot_point_obs +Optional Arguments for plot_point_obs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. The **-config config_file** option specifies the configuration file to be used. The contents of the optional configuration file are discussed below. @@ -75,7 +75,7 @@ An equivalent command using python embedding for point observations is shown bel Please see section :numref:`pyembed-point-obs-data` for more details about Python embedding in MET. -plot_point_obs configuration file +plot_point_obs Configuration File --------------------------------- The default configuration file for the Plot-Point-Obs tool named **PlotPointObsConfig_default** can be found in the installed *share/met/config* directory. The contents of the configuration file are described in the subsections below. @@ -220,7 +220,7 @@ For each observation, this tool stores the observation latitude, longitude, and .. _plot_data_plane-usage: -plot_data_plane usage +plot_data_plane Usage --------------------- The usage statement for the plot_data_plane utility is shown below: @@ -239,7 +239,7 @@ The usage statement for the plot_data_plane utility is shown below: plot_data_plane has two required arguments and can take optional ones. -Required arguments for plot_data_plane +Required Arguments for plot_data_plane ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **input_filename** argument indicates the name of the gridded data file to be plotted. @@ -248,7 +248,7 @@ Required arguments for plot_data_plane 3. The **field_string** argument contains information about the field and level to be plotted. -Optional arguments for plot_data_plane +Optional Arguments for plot_data_plane ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-color_table color_table_name** overrides the default color table (*MET_BASE/colortables/met_default.ctable*) @@ -275,7 +275,7 @@ A second example of the plot_data_plane calling sequence is shown below: In the first example, the Plot-Data-Plane tool will process the input test.grb file and write a PostScript image to a file named test.ps showing temperature at 2 meters. The second example plots downward shortwave radiation flux at the surface. The second example is run at verbosity level 4 so that the user can inspect the output and make sure its plotting the intended record. -plot_mode_field usage +plot_mode_field Usage --------------------- The usage statement for the plot_mode_field utility is shown below: @@ -292,7 +292,7 @@ The usage statement for the plot_mode_field utility is shown below: plot_mode_field has four required arguments and can take optional ones. -Required arguments for plot_mode_field +Required Arguments for plot_mode_field ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **mode_nc_file_list** specifies the MODE output files to be used for plotting. @@ -303,7 +303,7 @@ Required arguments for plot_mode_field 4. The **-config file** specifies the configuration file to use for specification of plotting options. -Optional arguments for plot_mode_field +Optional Arguments for plot_mode_field ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. 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. @@ -327,10 +327,10 @@ In this example, the plot_mode_field tool will plot simple objects from an obser Once MET has been applied to forecast and observed fields (or observing locations), and the output has been sorted through the Analysis Tool, numerous graphical and summary analyses can be performed depending on a specific user's needs. Here we give some examples of graphics and summary scores that one might wish to compute with the given output of MET and MET-TC. Any computing language could be used for this stage; some scripts will be provided on the `MET users web page `_ as examples to assist users. -Examples of plotting MET output +Examples of Plotting MET Output =============================== -Grid-Stat tool examples +Grid-Stat Tool Examples ----------------------- The plots in :numref:`plotting_Gilbert_skill_score` show time series of frequency bias and Gilbert Skill Score, stratified according to time of day. This type of figure is particularly useful for diagnosing problems that are tied to the diurnal cycle. In this case, two of the models (green dash-dotted and black dotted lines) show an especially high Bias (near 3) during the afternoon (15-21 UTC; left panel), while the skill (GSS; right panel) appears to be best for the models represented by the solid black line and green dashed lines in the morning (09-15 UTC). Note that any judgment of skill based on GSS should be restricted to times when the Bias is close to one. @@ -341,7 +341,7 @@ The plots in :numref:`plotting_Gilbert_skill_score` show time series of frequenc Time series of forecast area bias and Gilbert Skill Score for four model configurations (different lines) stratified by time-of-day. -MODE tool examples +MODE Tool Examples ------------------ When using the MODE tool, it is possible to think of matched objects as hits and unmatched objects as false alarms or misses depending on whether the unmatched object is from the forecast or observed field, respectively. Because the objects can have greatly differing sizes, it is useful to weight the statistics by the areas, which are given in the output as numbers of grid squares. When doing this, it is possible to have different matched observed object areas from matched forecast object areas so that the number of hits will be different depending on which is chosen to be a hit. When comparing multiple forecasts to the same observed field, it is perhaps wise to always use the observed field for the hits so that there is consistency for subsequent comparisons. Defining hits, misses and false alarms in this way allows one to compute many traditional verification scores without the problem of small-scale discrepancies; the matched objects are defined as being matched because they are "close" by the fuzzy logic criteria. Note that scores involving the number of correct negatives may be more difficult to interpret as it is not clear how to define a correct negative in this context. It is also important to evaluate the number and area attributes for these objects in order to provide a more complete picture of how the forecast is performing. @@ -364,7 +364,7 @@ In addition to the traditional scores, MODE output allows more information to be .. _TC-Stat-tool-example: -TC-Stat tool example +TC-Stat Tool Example -------------------- There is a basic R script located in the MET installation, *share/met/Rscripts/plot_tcmpr.R*. The usage statement with a short description of the options for *plot_tcmpr.R* can be obtained by typing: Rscript *plot_tcmpr.R* with no additional arguments. The only required argument is the **-lookin** source, which is the path to the TC-Pairs TCST output files. The R script reads directly from the TC-Pairs output, and calls TC-Stat directly for filter jobs specified in the *"-filter options"* argument. diff --git a/docs/Users_Guide/point-stat.rst b/docs/Users_Guide/point-stat.rst index 1572209a7a..4258e8057f 100644 --- a/docs/Users_Guide/point-stat.rst +++ b/docs/Users_Guide/point-stat.rst @@ -11,14 +11,14 @@ The Point-Stat tool provides verification statistics for forecasts at observatio Scientific and statistical aspects of the Point-Stat tool are discussed in the following section. Practical aspects of the Point-Stat tool are described in :numref:`tc-stat_practical-information`. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== The statistical methods and measures computed by the Point-Stat tool are described briefly in this section. In addition, :numref:`matching-methods` discusses the various interpolation options available for matching the forecast grid point values to the observation points. The statistical measures computed by the Point-Stat tool are described briefly in :numref:`PS_Statistical-measures` and in more detail in :numref:`Appendix C, Section %s `. :numref:`PS_Statistical-confidence-intervals` describes the methods for computing confidence intervals that are applied to some of the measures computed by the Point-Stat tool; more detail on confidence intervals is provided in :numref:`Appendix D, Section %s `. .. _matching-methods: -Interpolation/matching methods +Interpolation/Matching Methods ------------------------------ This section provides information about the various methods available in MET to match gridded model output to point observations. Matching in the vertical and horizontal are completed separately using different methods. @@ -119,7 +119,7 @@ The forecast value at P is chosen as the grid point inside the interpolation are .. _PS_HiRA_framework: -HiRA framework +HiRA Framework -------------- The Point-Stat tool has been enhanced to include the High Resolution Assessment (HiRA) verification logic (:ref:`Mittermaier, 2014 `). HiRA is analogous to neighborhood verification but for point observations. The HiRA logic interprets the forecast values surrounding each point observation as an ensemble forecast. These ensemble values are processed in three ways. First, the ensemble continuous statistics (ECNT), the observation rank statistics (ORANK) and the ranked probability score (RPS) line types are computed directly from the ensemble values. Second, for each categorical threshold specified, a fractional coverage value is computed as the ratio of the nearby forecast values that meet the threshold criteria. Point-Stat evaluates those fractional coverage values as if they were a probability forecast. When applying HiRA, users should enable the matched pair (MPR), probabilistic (PCT, PSTD, PJC, or PRC), continuous ensemble statistics (ECNT), observation rank statistics (ORANK) or ranked probability score (RPS) line types in the **output_flag** dictionary. The number of probabilistic HiRA output lines is determined by the number of categorical forecast thresholds and HiRA neighborhood widths chosen. @@ -138,7 +138,7 @@ Often, the neighborhood size is chosen so that multiple models to be compared ha .. _PS_seeps: -SEEPS scores +SEEPS Scores ------------ The Stable Equitable Error in Probability Space (SEEPS) was devised for monitoring global deterministic forecasts of precipitation against the WMO gauge network (:ref:`Rodwell et al., 2010 `; :ref:`Haiden et al., 2012 `) and is a multi-category score which uses a climatology to account for local variations in behavior. Since the score uses probability space to define categories using the climatology, it can be aggregated over heterogeneous climate regions. Even though it was developed for use with precipitation forecasts, in principle it could be applied to any forecast parameter for which a sufficiently long time period of observations exists to create a suitable climatology. The computation of SEEPS for precipitation is only supported for now. @@ -149,26 +149,26 @@ When calculating a single SEEPS value over observing stations for a particular r .. _PS_Statistical-measures: -Statistical measures +Statistical Measures -------------------- The Point-Stat tool computes a wide variety of verification statistics. Broadly speaking, these statistics can be subdivided into statistics for categorical variables and statistics for continuous variables. The categories of measures are briefly described here; specific descriptions of the measures are provided in :numref:`Appendix C, Section %s `. Additional information can be found in :ref:`Wilks (2011) ` and :ref:`Jolliffe and Stephenson (2012) `, and at Collaboration for Australian Weather and Climate Research. Forecast Verification - `Issues, Methods and FAQ web page. `_ In addition to these verification measures, the Point-Stat tool also computes partial sums and other FHO statistics that are produced by the NCEP verification system. These statistics are also described in :numref:`Appendix C, Section %s `. -Measures for categorical variables +Measures for Categorical Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Categorical verification statistics are used to evaluate forecasts that are in the form of a discrete set of categories rather than on a continuous scale. If the original forecast is continuous, the user may specify one or more thresholds in the configuration file to divide the continuous measure into categories. Currently, Point-Stat computes categorical statistics for variables in two or more categories. The special case of dichotomous (i.e., 2-category) variables has several types of statistics calculated from the resulting contingency table and are available in the CTS output line type. For multi-category variables, fewer statistics can be calculated so these are available separately, in line type MCTS. Categorical variables can be intrinsic (e.g., rain/no-rain) or they may be formed by applying one or more thresholds to a continuous variable (e.g., temperature < 273.15 K or cloud coverage percentages in 10% bins). See :numref:`Appendix C, Section %s ` for more information. -Measures for continuous variables +Measures for Continuous Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For continuous variables, many verification measures are based on the forecast error (i.e., f - o). However, it also is of interest to investigate characteristics of the forecasts, and the observations, as well as their relationship. These concepts are consistent with the general framework for verification outlined by :ref:`Murphy and Winkler (1987) `. The statistics produced by MET for continuous forecasts represent this philosophy of verification, which focuses on a variety of aspects of performance rather than a single measure. See :numref:`Appendix C, Section %s ` for specific information. A user may wish to eliminate certain values of the forecasts from the calculation of statistics, a process referred to here as``'conditional verification''. For example, a user may eliminate all temperatures above freezing and then calculate the error statistics only for those forecasts of below freezing temperatures. Another common example involves verification of wind forecasts. Since wind direction is indeterminate at very low wind speeds, the user may wish to set a minimum wind speed threshold prior to calculating error statistics for wind direction. The user may specify these thresholds in the configuration file to specify the conditional verification. Thresholds can be specified using the usual Fortran conventions (<, <=, ==, !-, >=, or >) followed by a numeric value. The threshold type may also be specified using two letter abbreviations (lt, le, eq, ne, ge, gt). Further, more complex thresholds can be achieved by defining multiple thresholds and using && or || to string together event definition logic. The forecast and observation threshold can be used together according to user preference by specifying one of: UNION, INTERSECTION, or SYMDIFF (symmetric difference). -Measures for probabilistic forecasts and dichotomous outcomes +Measures for Probabilistic Forecasts and Dichotomous Outcomes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For probabilistic forecasts, many verification measures are based on reliability, accuracy and bias. However, it also is of interest to investigate joint and conditional distributions of the forecasts and the observations, as in :ref:`Wilks (2011) `. See :numref:`Appendix C, Section %s ` for specific information. @@ -179,7 +179,7 @@ When the "prob" entry is set as a dictionary to define the field of interest, se .. _Climatology: -Measures for comparison against climatology +Measures for Comparison Against Climatology ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For each of the types of statistics mentioned above (categorical, continuous, and probabilistic), it is possible to calculate measures of skill relative to climatology. MET will accept a climatology file provided by the user, and will evaluate it as a reference forecast. Further, anomalies, i.e. departures from average conditions, can be calculated. As with all other statistics, the available measures will depend on the nature of the forecast. Common statistics that use a climatological reference include: the mean squared error skill score (MSESS), the Anomaly Correlation (ANOM_CORR and ANOM_CORR_UNCNTR), scalar and vector anomalies (SAL1L2 and VAL1L2), continuous ranked probability skill score (CRPSS and CRPSS_EMP), Brier Skill Score (BSS) (:ref:`Wilks, 2011 `; :ref:`Mason, 2004 `). @@ -188,7 +188,7 @@ Often, the sample climatology is used as a reference by a skill score. The sampl .. _PS_Statistical-confidence-intervals: -Statistical confidence intervals +Statistical Confidence Intervals -------------------------------- A single summary score gives an indication of the forecast performance, but it is a single realization from a random process that neglects uncertainty in the score's estimate. That is, it is possible to obtain a good score, but it may be that the "good" score was achieved by chance and does not reflect the "true" score. Therefore, when interpreting results from a verification analysis, it is imperative to analyze the uncertainty in the realized scores. One good way to do this is to utilize confidence intervals. A confidence interval indicates that if the process were repeated many times, say 100, then the true score would fall within the interval :math:`100(1-\alpha)\%` of the time. Typical values of :math:`\alpha` are 0.01, 0.05, and 0.10. The Point-Stat tool allows the user to select one or more specific :math:`\alpha`-values to use. @@ -259,14 +259,14 @@ For more information on confidence intervals pertaining to verification measures .. _tc-stat_practical-information: -Practical information +Practical Information ===================== The Point-Stat tool is used to perform verification of a gridded model field using point observations. The gridded model field to be verified must be in one of the supported file formats. The point observations must be formatted as the NetCDF output of the point reformatting tools described in :numref:`reformat_point`. The Point-Stat tool provides the capability of interpolating the gridded forecast data to the observation points using a variety of methods as described in :numref:`matching-methods`. The Point-Stat tool computes a number of continuous statistics on the matched pair data as well as discrete statistics once the matched pair data have been thresholded. If no matched pairs are found for a particular verification task, a report listing counts for reasons why the observations were not used is written to the log output at the default verbosity level of 2. If matched pairs are found, this report is written at verbosity level 3. Inspecting these rejection reason counts is the first step in determining why Point-Stat found no matched pairs. The order of the log messages matches the order in which the processing logic is applied. Start from the last log message and work your way up, considering each of the non-zero rejection reason counts. -point_stat usage +point_stat Usage ---------------- The usage statement for the Point-Stat tool is shown below: @@ -286,7 +286,7 @@ The usage statement for the Point-Stat tool is shown below: point_stat has three required arguments and can take many optional ones. -Required arguments for point_stat +Required Arguments for point_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **fcst_file** argument names the gridded file in either GRIB or NetCDF containing the model data to be verified. @@ -295,7 +295,7 @@ Required arguments for point_stat 3. 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 point_stat +Optional Arguments for point_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-point_obs** file may be used to pass additional NetCDF point observation files to be used in the verification. Python embedding for point observations is also supported, as described in :numref:`pyembed-point-obs-data`. @@ -320,7 +320,7 @@ An example of the point_stat calling sequence is shown below: In this example, the Point-Stat tool evaluates the model data in the sample_fcst.grb GRIB file using the observations in the NetCDF output of PB2NC, sample_pb.nc, applying the configuration options specified in the **PointStatConfig file**. -point_stat configuration file +point_stat Configuration File ----------------------------- The default configuration file for the Point-Stat tool named **PointStatConfig_default** can be found in the installed *share/met/config* directory. Another version is located in *scripts/config*. We encourage users to make a copy of these files prior to modifying their contents. The contents of the configuration file are described in the subsections below. @@ -502,7 +502,7 @@ The default SEEPS climo file exists at MET_BASE/climo/seeps/PPT24_seepsweights.n .. _point_stat-output: -point_stat output +point_stat Output ----------------- point_stat produces output in STAT and, optionally, ASCII format. The ASCII output duplicates the STAT output but has the data organized by line type. The output files will be written to the default output directory or the directory specified using the "-outdir" command line option. diff --git a/docs/Users_Guide/reformat_grid.rst b/docs/Users_Guide/reformat_grid.rst index aadb73eb6f..3ef6897c54 100644 --- a/docs/Users_Guide/reformat_grid.rst +++ b/docs/Users_Guide/reformat_grid.rst @@ -6,7 +6,7 @@ Re-Formatting of Gridded Fields Several MET tools exist for the purpose of reformatting gridded fields, and they are described in this section. These tools are represented by the reformatting column of MET flowchart depicted in :numref:`overview-figure`. -Pcp-Combine tool +Pcp-Combine Tool ================ This section describes the Pcp-Combine tool which summarizes data across multiple input gridded data files and writes the results to a single NetCDF output file. It is often used to modify precipitation accumulation intervals in the forecast and/or observation datasets to make them comparable. However it can also be used to derive summary fields, such as daily min/max temperature or average precipitation rate. @@ -23,7 +23,7 @@ The Pcp-Combine tool supports four types of commands ("sum", "add", "subtract", By default, the Pcp-Combine tool processes data for **APCP**, the GRIB string for accumulated precipitation. When requesting data using time strings (i.e. [HH]MMSS), Pcp-Combine searches for accumulated precipitation for that accumulation interval. Alternatively, use the "-field" option to process fields other than **APCP** or for non-GRIB files. The "-field" option may be used multiple times to process multiple fields in a single run. Since the Pcp-Combine tool does not support automated regridding, all input data must be on the same grid. In general the input files should have the same initialization time unless the user has indicated that it should ignore the initialization time for the "sum" command. The "subtract" command produces a warning when the input initialization times differ or the subtraction results in a negative accumulation interval. -pcp_combine usage +pcp_combine Usage ----------------- The usage statement for the Pcp-Combine tool is shown below: @@ -65,14 +65,14 @@ The add, subtract, and derive commands all require that the input files be expli file_1 ... file_n | input_file_list -Required arguments for the pcp_combine +Required Arguments for the pcp_combine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The Pcp-Combine tool must be run with exactly one run command (-sum, -add, -subtract, or -derive) with the corresponding additional arguments. 2. The **out_file** argument indicates the name for the NetCDF file to be written. -Optional arguments for pcp_combine +Optional Arguments for pcp_combine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. The **-field string** option defines the data to be extracted from the input files. Use this option when processing fields other than **APCP** or non-GRIB files. It can be used multiple times and output will be created for each. In general, the field string should include the **name** and **level** of the requested data and be enclosed in single quotes. It is processed as an inline configuration file and may also include data filtering, censoring, and conversion options. For example, use **-field ‘name=”ACPCP”; level=”A6”; convert(x)=x/25.4;’** to read 6-hourly accumulated convective precipitation from a GRIB file and convert from millimeters to inches. @@ -87,7 +87,7 @@ Optional arguments for pcp_combine 8. 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. -Required arguments for the pcp_combine sum command +Required Arguments for the pcp_combine Sum Command ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **init_time** argument, provided in YYYYMMDD[_HH[MMSS]] format, indicates the initialization time for model data to be summed. Only files found with this initialization time will be processed. If combining observation files, Stage II or Stage IV data for example, the initialization time is not applicable. Providing a string of all zeros (00000000_000000) indicates that all files, regardless of initialization time should be processed. @@ -98,19 +98,19 @@ Required arguments for the pcp_combine sum command 4. The **out_accum** argument, in HH[MMSS] format, indicates the desired total accumulation period to be summed. -Optional arguments for pcp_combine sum command +Optional Arguments for pcp_combine Sum Command ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. The **-pcpdir path** option indicates the directories in which the input files reside. The contents of "**path**" will override the default setting. This option may be used multiple times and can accept multiple arguments, supporting the use of wildcards. 6. The **-pcprx reg_exp** option indicates the regular expression to be used in matching files in the search directories specified. The contents of "reg_exp" will override the default setting that matches all file names. If the search directories contain a large number of files, the user may specify that only a subset of those files be processed using a regular expression which will speed up the run time. -Required arguments for the pcp_combine derive command +Required Arguments for the pcp_combine Derive Command ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The "derive" run command must be followed by **stat_list** which is a comma-separated list of summary fields to be computed. The **stat_list** may be set to sum, min, max, range, mean, stdev, and vld_count for the sum, minimum, maximum, range (max-min), average, standard deviation, and valid data count fields, respectively. -Input files for pcp_combine add, subtract, and derive commands +Input Files for pcp_combine Add, Subtract, and Derive Commands ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The input files for the add, subtract, and derive command can be specified in one of 3 ways: @@ -169,7 +169,7 @@ This command would grab the first level of the TT variable from a pinterp NetCDF The Pcp-Combine tool will subtract the 36 hour precipitation accumulations in the file 2022043018_36.grib2 (a 36hr forecast initialized at 2022-04-30 18Z) from the 48 hour accumulations in the file 2022043018_48.grib2 (a 48hr forecast from the same model cycle). This will produce the 12 hour accumulation amounts for the period in between the 36 and 48 hour forecasts. It will write out a single NetCDF file containing that 12 hours of accumulation. -pcp_combine output +pcp_combine Output ------------------ The output NetCDF files contain the requested accumulation intervals as well as information about the grid on which the data lie. That grid projection information will be parsed out and used by the MET statistics tools in subsequent steps. One may use NetCDF utilities such as ncdump or ncview to view the contents of the output file. Alternatively, the MET Plot-Data-Plane tool described in :numref:`plot_data_plane-usage` may be run to create a PostScript image of the data. @@ -212,12 +212,12 @@ Each NetCDF file generated by the Pcp-Combine tool contains the dimensions and v .. _regrid-data-plane: -Regrid-Data-Plane tool +Regrid-Data-Plane Tool ====================== This section contains a description of running the Regrid-Data-Plane tool. This tool may be run to read data from any gridded file MET supports, interpolate to a user-specified grid, and writes the field(s) out in NetCDF format. The user may specify the method of interpolation used for regridding as well as which fields to regrid. This tool is particularly useful when dealing with GRIB2 and NetCDF input files that need to be regridded. For GRIB1 files, it has also been tested for compatibility with the copygb regridding utility mentioned in :numref:`Installation-of-optional`. -regrid_data_plane usage +regrid_data_plane Usage ----------------------- The usage statement for the regrid_data_plane utility is shown below: @@ -240,7 +240,7 @@ The usage statement for the regrid_data_plane utility is shown below: [-v level] [-compress level] -Required arguments for regrid_data_plane +Required Arguments for regrid_data_plane ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **input_filename** is the gridded data file to be read. @@ -251,7 +251,7 @@ Required arguments for regrid_data_plane 4. The **-field string** may be used multiple times to define the field(s) to be regridded. -Optional arguments for regrid_data_plane +Optional Arguments for regrid_data_plane ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. The **-method type** option overrides the default regridding method. Default is NEAREST. @@ -291,17 +291,17 @@ For more details on setting the **to_grid, -method, -width,** and **-vld_thresh* In this example, the Regrid-Data-Plane tool will regrid data from the **input.grb** file to the grid on which the first record of the **togrid.grb** file resides using Bilinear Interpolation with a width of 2 and write the output in NetCDF format to a file named **regridded.nc**. The variables in **regridded.nc** will include 6-hour accumulated precipitation, 2m temperature, 10m U and V components of the wind, and the 500mb geopotential height. -Automated regridding within tools +Automated Regridding within Tools --------------------------------- While the Regrid-Data-Plane tool is useful as a stand-alone tool, the capability is also included to automatically **regrid** one or both fields in most of the MET tools that handle gridded data. See the regrid entry in :numref:`Configuration File Details` for a description of the configuration file entries that control automated regridding. -Shift-Data-Plane tool +Shift-Data-Plane Tool ===================== The Shift-Data-Plane tool performs a rigid shift of the entire grid based on user-defined specifications and writes the field(s) out in NetCDF format. This tool was originally designed to account for track error when comparing fields associated with tropical cyclones. The user specifies the latitude and longitude of the source and destination points to define the shift. Both points must fall within the domain and are used to define the X and Y direction grid unit shift. The shift is then applied to all grid points. The user may specify the method of interpolation and the field to be shifted. The effects of topography and land/water masks are ignored. -shift_data_plane usage +shift_data_plane Usage ---------------------- The usage statement for the shift_data_plane utility is shown below: @@ -323,7 +323,7 @@ The usage statement for the shift_data_plane utility is shown below: shift_data_plane has five required arguments and can also take optional ones. -Required arguments for shift_data_plane +Required Arguments for shift_data_plane ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **input_filename** is the gridded data file to be read. @@ -336,7 +336,7 @@ Required arguments for shift_data_plane 5. The **-to lat lon** specifies the ending location within the domain to define the shift. Lat is deg N, Lon is deg E. -Optional arguments for shift_data_plane +Optional Arguments for shift_data_plane ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6. The **-method type** overrides the default regridding method. Default is NEAREST. @@ -365,12 +365,12 @@ For more details on setting the **-method** and **-width** options, see the **re In this example, the Shift-Data-Plane tool reads 12-hour accumulated precipitation from the **nam.grb** file, applies a rigid shift defined by (38.6272, -90.1978) to (40.1717, -105.1092) and writes the output in NetCDF format to a file named **nam_shift_APCP_12.nc**. These **-from** and **-to** locations result in a grid shift of -108.30 units in the x-direction and 16.67 units in the y-direction. -MODIS regrid tool +MODIS regrid Tool ================= This section contains a description of running the MODIS regrid tool. This tool may be run to create a NetCDF file for use in other MET tools from `MODIS level 2 cloud product from NASA. `_ -modis_regrid usage +modis_regrid Usage ------------------ The usage statement for the modis_regrid utility is shown below: @@ -390,7 +390,7 @@ The usage statement for the modis_regrid utility is shown below: modis_regrid has some required arguments and can also take optional ones. -Required arguments for modis_regrid +Required Arguments for modis_regrid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-data_file path** argument specifies the data files used to get the grid information. @@ -407,7 +407,7 @@ Required arguments for modis_regrid 7. The **modis_file** argument is the name of the MODIS input file. -Optional arguments for modis_regrid +Optional Arguments for modis_regrid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 8. The **-units text** option specifies the units string in the global attributes section of the output file. @@ -442,7 +442,7 @@ There are two WWMCA tools available. The WWMCA-Plot tool makes a PostScript plot The WWMCA tools attempt to parse timing and hemisphere information from the file names. They tokenize the filename using underscores (_) and dots (.) and examine each element which need be in no particular order. A string of 10 or more numbers is interpreted as the valid time in YYYYMMDDHH[MMSS] format. The string NH indicates the northern hemisphere while SH indicates the southern hemisphere. While WWMCA data is an analysis and has no forecast lead time, other datasets following this format may. Therefore, a string of 1 to 4 numbers is interpreted as the forecast lead time in hours. While parsing the filename provides default values for this timing information, they can be overridden by explicitly setting their values in the WWMCA-Regrid configuration file. -wwmca_plot usage +wwmca_plot Usage ---------------- The usage statement for the WWMCA-Plot tool is shown below: @@ -458,12 +458,12 @@ The usage statement for the WWMCA-Plot tool is shown below: wmmca_plot has some required arguments and can also take optional ones. -Required arguments for wwmca_plot +Required Arguments for wwmca_plot ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **wwmca_cloud_pct_file_list** argument represents one or more WWMCA cloud percent files given on the command line. As with any command given to a UNIX shell, the user can use meta-characters as a shorthand way to specify many filenames. For each input file specified, one output PostScript plot will be created. -Optional arguments for wwmca_plot +Optional Arguments for wwmca_plot ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2. The **-outdir path** option specifies the directory where the output PostScript plots will be placed. If not specified, then the plots will be put in the current (working) directory. @@ -478,7 +478,7 @@ Optional arguments for wwmca_plot Example output of WWMCA-Plot tool. -wwmca_regrid usage +wwmca_regrid Usage ------------------ The usage statement for the WWMCA-Regrid tool is shown below: @@ -496,7 +496,7 @@ The usage statement for the WWMCA-Regrid tool is shown below: wmmca_regrid has some required arguments and can also take optional ones. -Required arguments for wwmca_regrid +Required Arguments for wwmca_regrid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-out filename** argument specifies the name of the output netCDF file. @@ -507,7 +507,7 @@ Required arguments for wwmca_regrid 4. The **-sh filename [pt_filename]** argument specifies the southern hemisphere WWMCA binary file and, optionally, may be followed by a binary pixel age file. This switch is required if the output grid includes any portion of the southern hemisphere. -Optional arguments for wwmca_regrid +Optional Arguments for wwmca_regrid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. 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. @@ -518,7 +518,7 @@ Optional arguments for wwmca_regrid In any regridding problem, there are two grids involved: the "From" grid, which is the grid the input data are on, and the "To" grid, which is the grid the data are to be moved onto. In **WWMCA-Regrid** the "From" grid is pre-defined by the hemisphere of the WWMCA binary files being processed. The "To" grid and corresponding regridding logic are specified using the **regrid** section of the configuration file. If the "To" grid is entirely confined to one hemisphere, then only the WWMCA data file for that hemisphere needs to be given. If the "To" grid or the interpolation box used straddles the equator, the data files for both hemispheres need to be given. Once the "To" grid is specified in the config file, the WWMCA-Regrid tool will know which input data files it needs and will complain if it is not given the right ones. -wwmca_regrid configuration file +wwmca_regrid Configuration File ------------------------------- The default configuration file for the WWMCA-Regrid tool named **WWMCARegridConfig_default** can be found in the installed *share/met/config* directory. We encourage users to make a copy of this file prior to modifying its contents. The contents of the configuration file are described in the subsections below. diff --git a/docs/Users_Guide/reformat_point.rst b/docs/Users_Guide/reformat_point.rst index 161a10805f..d21586ebed 100644 --- a/docs/Users_Guide/reformat_point.rst +++ b/docs/Users_Guide/reformat_point.rst @@ -8,14 +8,14 @@ There are several formats of point observations that may be preprocessed using t .. _PB2NC tool: -PB2NC tool +PB2NC Tool ========== This section describes how to configure and run the PB2NC tool. The PB2NC tool is used to stratify the contents of an input PrepBUFR point observation file and reformat it into NetCDF format for use by other MET tools. The PB2NC tool must be run on the input PrepBUFR point observation file prior to performing verification with the MET statistics tools. .. _pb2nc usage: -pb2nc usage +pb2nc Usage ----------- The usage statement for the PB2NC tool is shown below: @@ -38,7 +38,7 @@ The usage statement for the PB2NC tool is shown below: pb2nc has both required and optional arguments. -Required arguments for pb2nc +Required Arguments for pb2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. @@ -50,7 +50,7 @@ The **netcdf_file** argument is the output NetCDF file to be written. 3. The **config_file** argument is the configuration file to be used. The contents of the configuration file are discussed below. -Optional arguments for pb2nc +Optional Arguments for pb2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-pbfile prepbufr_file** option is used to pass additional input PrepBUFR files. @@ -91,7 +91,7 @@ In this example, the PB2NC tool will process the input **sample_pb.blk** file ap .. _pb2nc configuration file: -pb2nc configuration file +pb2nc Configuration File ------------------------ The default configuration file for the PB2NC tool named **PB2NCConfig_default** can be found in the installed *share/met/config* directory. The version used for the example run in :numref:`Sample test cases` is available in *scripts/config*. It is recommended that users make a copy of configuration files prior to modifying their contents. @@ -332,7 +332,7 @@ The quality mark for time summaries is always reported by PB2NC as bad data. Tim .. _pb2nc output: -pb2nc output +pb2nc Output ------------ Each NetCDF file generated by the PB2NC tool contains the dimensions and variables shown in :numref:`table_reformat-point_pb2nc_output_dim` and :numref:`table_reformat-point_pb2nc_output_vars`. @@ -437,7 +437,7 @@ Each NetCDF file generated by the PB2NC tool contains the dimensions and variabl - Lookup table containing a description string for the unique observation variable names in obs_var. -ASCII2NC tool +ASCII2NC Tool ============= This section describes how to run the ASCII2NC tool. The ASCII2NC tool is used to reformat ASCII point observations into the NetCDF format expected by the Point-Stat tool. For those users wishing to verify against point observations that are not available in PrepBUFR format, the ASCII2NC tool provides a way of incorporating those observations into MET. If the ASCII2NC tool is used to perform a reformatting step, no configuration file is needed. However, for more complex processing, such as summarizing time series observations, a configuration file may be specified. For details on the configuration file options, see :numref:`config_options` and example configuration files distributed with the MET code. @@ -508,7 +508,7 @@ The default ASCII point observation format consists of one row of data per obser - Observation_Value - Observation value in units consistent with the GRIB code definition. -ascii2nc usage +ascii2nc Usage -------------- Once the ASCII point observations have been formatted as expected, the ASCII file is ready to be processed by the ASCII2NC tool. The usage statement for ASCII2NC tool is shown below: @@ -529,14 +529,14 @@ Once the ASCII point observations have been formatted as expected, the ASCII fil ascii2nc has two required arguments and can take several optional ones. -Required arguments for ascii2nc +Required Arguments for ascii2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **ascii_file** argument is the ASCII point observation file(s) to be processed. If using Python embedding with "-format python" provides a quoted string containing the Python script to be run followed by any command line arguments that script takes. 2. The **netcdf_file** argument is the NetCDF output file to be written. -Optional arguments for ascii2nc +Optional Arguments for ascii2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. The **-format ASCII_format** option may be set to "met_point", "little_r", "surfrad", "wwsis", "airnowhourlyaqobs", "airnowhourly", "airnowdaily_v2", "ndbc_standard", "aeronet", "aeronetv2", "aeronetv3", or "python". If passing in ISIS data, use the "surfrad" format flag. @@ -566,7 +566,7 @@ In this example, the ASCII2NC tool will reformat the input **sample_ascii_obs.tx .. _ascii2nc-pyembed: -ascii2nc configuration file +ascii2nc Configuration File --------------------------- The default configuration file for the ASCII2NC tool named **Ascii2NcConfig_default** can be found in the installed *share/met/config* directory. It is recommended that users make a copy of this file prior to modifying its contents. @@ -610,7 +610,7 @@ _____________________ This entry is an array of dictionaries, each containing a **key** string and **val** string which define a mapping of input strings to output message types. This mapping is currently only applied when converting input little_r report types to output message types. -ascii2nc output +ascii2nc Output --------------- The NetCDF output of the ASCII2NC tool is structured in the same way as the output of the PB2NC tool described in :numref:`pb2nc output`. @@ -618,14 +618,14 @@ The NetCDF output of the ASCII2NC tool is structured in the same way as the outp "obs_vid" variable is replaced with "obs_gc" when the GRIB code is given instead of the variable names. In this case, the global variable "use_var_id" does not exist or set to false (use_var_id = "false" ;). Three variables (obs_var, obs_units, and obs_desc) related with variable names are not added. -MADIS2NC tool +MADIS2NC Tool ============= This section describes how to run the MADIS2NC tool. The MADIS2NC tool is used to reformat `Meteorological Assimilation Data Ingest System (MADIS) `_ point observations into the NetCDF format expected by the MET statistics tools. An optional configuration file controls the processing of the point observations. The MADIS2NC tool supports many of the MADIS data types, as listed in the usage statement below. Support for additional MADIS data types may be added in the future based on user feedback. -madis2nc usage +madis2nc Usage -------------- The usage statement for the MADIS2NC tool is shown below: @@ -652,7 +652,7 @@ The usage statement for the MADIS2NC tool is shown below: madis2nc has required arguments and can also take optional ones. -Required arguments for madis2nc +Required Arguments for madis2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **madis_file** argument is one or more input MADIS point observation files to be processed. @@ -664,7 +664,7 @@ Required arguments for madis2nc 3. The argument **-type str** is a type of MADIS observations (metar, raob, profiler, maritime, mesonet or acarsProfiles). -Optional arguments for madis2nc +Optional Arguments for madis2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-config file** option specifies the configuration file to generate summaries of the fields in the ASCII files. @@ -708,7 +708,7 @@ An example of the madis2nc calling sequence is shown below: In this example, the MADIS2NC tool will reformat the input sample_madis_obs.nc file into NetCDF format and write the output to a file named sample_madis_obs_met.nc. Warnings and error messages will be written to the madis.log file, and the verbosity level of logging is three. -madis2nc configuration file +madis2nc Configuration File --------------------------- @@ -736,7 +736,7 @@ _____________________ The **time_summary** dictionary is described in :numref:`pb2nc configuration file`. -madis2nc output +madis2nc Output --------------- The NetCDF output of the MADIS2NC tool is structured in the same way as the output of the PB2NC tool described in :numref:`pb2nc output`. @@ -744,14 +744,14 @@ The NetCDF output of the MADIS2NC tool is structured in the same way as the outp "obs_vid" variable is replaced with "obs_gc" when the GRIB code is given instead of the variable names. In this case, the global variable "use_var_id" does not exist or set to false (use_var_id = "false" ;). Three variables (obs_var, obs_units, and obs_desc) related with variable names are not added. -LIDAR2NC tool +LIDAR2NC Tool ============= The LIDAR2NC tool creates a NetCDF point observation file from a CALIPSO HDF data file. Not all of the data present in the CALIPSO file is reproduced in the output, however. Instead, the output focuses mostly on information about clouds (as opposed to aerosols) as seen by the satellite along its ground track. -lidar2nc usage +lidar2nc Usage -------------- The usage statement for LIDAR2NC tool is shown below: @@ -769,7 +769,7 @@ The usage statement for LIDAR2NC tool is shown below: Unlike most of the MET tools, lidar2nc does not use a config file. Currently, the options needed to run lidar2nc are not complex enough to require one. -Required arguments for lidar2nc +Required Arguments for lidar2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **lidar_file** argument is the input HDF lidar data file to be processed. Currently, CALIPSO files are supported but support for additional file types will be added in future releases. @@ -778,7 +778,7 @@ Required arguments for lidar2nc 2. The **out_file** argument is the NetCDF output file to be written. -Optional arguments for lidar2nc +Optional Arguments for lidar2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. 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. @@ -787,7 +787,7 @@ Optional arguments for lidar2nc 5. 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. -lidar2nc output +lidar2nc Output --------------- Each observation type in the lidar2nc output is assigned a GRIB code. These are outlined in :numref:`lidar2nc_grib_code_table`. GRIB codes were assigned to these fields arbitrarily, with GRIB codes in the 600s denoting individual bit fields taken from the feature classification flag field in the CALIPSO file. @@ -859,14 +859,14 @@ We will not give a detailed description of each CALIPSO data product that lidar2 - Horizontal_Averaging -IODA2NC tool +IODA2NC Tool ============ This section describes the IODA2NC tool which is used to reformat IODA (Interface for Observation Data Access) point observations from the `Joint Center for Satellite Data Assimilation (JCSDA) `_ into the NetCDF format expected by the MET statistics tools. An optional configuration file controls the processing of the point observations. The IODA2NC tool reads NetCDF point observation files created by the `IODA Converters `_. Support for interfacing with data from IODA may be added in the future based on user feedback. -ioda2nc usage +ioda2nc Usage ------------- The usage statement for the IODA2NC tool is shown below: @@ -888,14 +888,14 @@ The usage statement for the IODA2NC tool is shown below: ioda2nc has required arguments and can also take optional ones. -Required arguments for ioda2nc +Required Arguments for ioda2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **ioda_file** argument is an input IODA NetCDF point observation file to be processed. 2. The **netcdf_file** argument is the NetCDF output file to be written. -Optional arguments for ioda2nc +Optional Arguments for ioda2nc ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. The **-config config_file** is a IODA2NCConfig file to filter the point observations and define time summaries. @@ -925,7 +925,7 @@ An example of the ioda2nc calling sequence is shown below: In this example, the IODA2NC tool will reformat the data in the input ioda.NC001007.2020031012.nc file and write the output to a file named ioda2nc.2020031012.nc. The data to be processed is specified by IODA2NCConfig, log messages will be written to the ioda2nc.log file, and the verbosity level is three. -ioda2nc configuration file +ioda2nc Configuration File -------------------------- The default configuration file for the IODA2NC tool named **IODA2NcConfig_default** can be found in the installed *share/met/config* directory. It is recommended that users make a copy of this file prior to modifying its contents. @@ -1003,18 +1003,18 @@ _____________________ The **missing_thresh** option is an array of thresholds. Any data values which meet any of these thresholds are interpreted as being bad, or missing, data. -ioda2nc output +ioda2nc Output -------------- The NetCDF output of the IODA2NC tool is structured in the same way as the output of the PB2NC tool described in :numref:`pb2nc output`. -Point2Grid tool +Point2Grid Tool =============== The Point2Grid tool reads point observations from a MET NetCDF point obseravtion file, via python embedding, or from GOES-16/17 input files in NetCDF format (especially, Aerosol Optical Depth) and creates a gridded NetCDF file. Future development may add support for additional input types. -point2grid usage +point2grid Usage ---------------- The usage statement for the Point2Grid tool is shown below: @@ -1040,7 +1040,7 @@ The usage statement for the Point2Grid tool is shown below: [-compress level] -Required arguments for point2grid +Required Arguments for point2grid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **input_filename** argument indicates the name of the input file to be processed. The input can be a MET NetCDF point observation file generated by other MET tools or a NetCDF AOD dataset from GOES16/17. Python embedding for point observations is also supported, as described in :numref:`pyembed-point-obs-data`. @@ -1054,7 +1054,7 @@ The MET point observation NetCDF file name as **input_filename** argument is equ 4. The **-field** string argument is a string that defines the data to be regridded. It may be used multiple times. If **-adp** option is given (for AOD data from GOES16/17), the name consists with the variable name from the input data file and the variable name from ADP data file (for example, "AOD_Smoke" or "AOD_Dust": getting AOD variable from the input data and applying smoke or dust variable from ADP data file). -Optional arguments for point2grid +Optional Arguments for point2grid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. The **-config** file option is the configuration file to be used. @@ -1109,7 +1109,7 @@ Listed below is an example of processing the same set of observations but using Please refer to :numref:`Appendix F, Section %s ` for more details about Python embedding in MET. -point2grid output +point2grid Output ----------------- The point2grid tool will output a gridded NetCDF file containing the following: @@ -1137,7 +1137,7 @@ The point2grid tool will output a gridded NetCDF file containing the following: For MET observation input and CF complaint NetCDF input with 2D time variable: The latest observation time within the target grid is saved as the observation time. If the "valid_time" is configured at the configuration file, the valid_time from the configuration file is saved into the output file. -point2grid configuration file +point2grid Configuration File ----------------------------- diff --git a/docs/Users_Guide/release-notes.rst b/docs/Users_Guide/release-notes.rst index 2f8cc777a6..a8542a39bc 100644 --- a/docs/Users_Guide/release-notes.rst +++ b/docs/Users_Guide/release-notes.rst @@ -9,7 +9,7 @@ When applicable, release notes are followed by the GitHub issue number which des enhancement, or new feature (`MET GitHub issues `_). Important issues are listed **in bold** for emphasis. -MET Version 12.0.0-beta1 release notes (20230915) +MET Version 12.0.0-beta1 Release Notes (20230915) ------------------------------------------------- .. dropdown:: Repository, build, and test @@ -37,7 +37,7 @@ MET Version 12.0.0-beta1 release notes (20230915) MET Upgrade Instructions ======================== -MET Version 12.0.0 upgrade instructions +MET Version 12.0.0 Upgrade Instructions --------------------------------------- * MET Version 12.0.0 introduces three new required dependencies: diff --git a/docs/Users_Guide/rmw-analysis.rst b/docs/Users_Guide/rmw-analysis.rst index 6b0a849de9..f287bbfd54 100644 --- a/docs/Users_Guide/rmw-analysis.rst +++ b/docs/Users_Guide/rmw-analysis.rst @@ -9,10 +9,10 @@ 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 +Practical Information ===================== -rmw_analysis usage +rmw_analysis Usage ------------------ The following sections describe the usage statement, required arguments, and optional arguments for **rmw_analysis**. @@ -30,7 +30,7 @@ _______________________ **rmw_analysis** has required arguments and can accept several optional arguments. -Required arguments for rmw_analysis +Required Arguments for rmw_analysis ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-data file_1 ... file_n | data_file_list** argument is the NetCDF output of TC-RMW to be processed or an ASCII file containing a list of files. @@ -39,14 +39,14 @@ Required arguments for rmw_analysis 3. The **-out** file argument is the NetCDF output file to be written. -Optional arguments for rmw_analysis +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 +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. @@ -86,7 +86,7 @@ The track filter options available in rmw_analysis and listed above are describe -rmw_analysis output file +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. 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, e.g. TMP_mean, TMP_stdev, TMP_min, TMP_max. No track point dimension is retained in the rmw_analysis output. diff --git a/docs/Users_Guide/series-analysis.rst b/docs/Users_Guide/series-analysis.rst index 1dd568fcda..0be681585f 100644 --- a/docs/Users_Guide/series-analysis.rst +++ b/docs/Users_Guide/series-analysis.rst @@ -22,7 +22,7 @@ To define a time series of forecasts that all have the same valid time, set the To define a series of vertical levels all contained in a single input file, set the forecast and observation fields to a list of the vertical levels to be used. Pass the tool single forecast and observation files containing the vertical level data. The tool will loop over the forecast field entries, extract that field from the input forecast file, and then search the observation file for a matching record. -series_analysis usage +series_analysis Usage --------------------- The usage statement for the Series-Analysis tool is shown below: @@ -42,7 +42,7 @@ The usage statement for the Series-Analysis tool is shown below: series_analysis has four required arguments and accepts several optional ones. -Required arguments series_stat +Required Arguments series_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-fcst file_1 ... file_n | fcst_file_list** options specify the gridded forecast files or ASCII files containing lists of file names to be used. @@ -53,7 +53,7 @@ Required arguments series_stat 4. The **-config file** is a Series-Analysis Configuration file containing the desired settings. -Optional arguments for series_analysis +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. @@ -78,7 +78,7 @@ An example of the series_analysis calling sequence is shown below: In this example, the Series-Analysis tool will process the list of forecast and observation files specified in the text file lists into statistics for each grid location using settings specified in the configuration file. Series-Analysis will create an output NetCDF file containing requested statistics. -series_analysis output +series_analysis Output ---------------------- The Series-Analysis tool produces NetCDF files containing output statistics for each grid location from the input files. The details about the output statistics available from each output line type are detailed in Chapter 5 since they are also produced by the Grid-Stat Tool. A subset of these can be produced by this tool, with the most notable exceptions being the wind vector and neighborhood statistics. Users can inventory the contents of the Series-Analysis output files using the ncdump -h command to view header information. Additionally, ncview or the Plot-Data-Plane tool can be used to visualize the output. An example of Series-Analysis output is shown in :numref:`series-analysis_Glibert_precip` below. @@ -89,7 +89,7 @@ The Series-Analysis tool produces NetCDF files containing output statistics for An example of the Gilbert Skill Score for precipitation forecasts at each grid location for a month of files. -series_analysis configuration file +series_analysis Configuration File ---------------------------------- The default configuration file for the Series-Analysis tool named **SeriesAnalysisConfig_default** can be found in the installed *share/met/config* directory. The contents of the configuration file are described in the subsections below. diff --git a/docs/Users_Guide/stat-analysis.rst b/docs/Users_Guide/stat-analysis.rst index eb23b9ad77..0a5c7ec842 100644 --- a/docs/Users_Guide/stat-analysis.rst +++ b/docs/Users_Guide/stat-analysis.rst @@ -11,18 +11,18 @@ The Stat-Analysis tool ties together results from the Point-Stat, Grid-Stat, Ens MET version 9.0 adds support for the passing matched pair data (MPR) into Stat-Analysis using a Python script with the "-lookin python ..." option. An example of running Stat-Analysis with Python embedding can be found in :numref:`Appendix F, Section %s `. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== The Stat-Analysis tool can perform a variety of analyses, and each type of analysis is called a "job". The job types include the ability to (i) aggregate results over a user-specified time; (ii) stratify statistics based on time of day, model initialization time, lead-time, model run identifier, output filename, or wavelet decomposition scale; and (iii) compute specific verification indices such as the GO Index [1]_ and wind direction statistics. Future functionality may include information about time-trends and/or calculations based on climatology (e.g., anomaly correlation). This section summarizes the capabilities of the supported Stat-Analysis jobs. -Filter STAT lines +Filter STAT Lines ----------------- The Stat-Analysis "filter" job simply filters out specific STAT lines based on user-specified search criteria. All of the STAT lines that are retained from one or many files are written to a single output file. The output file for filtered STAT lines must be specified using the **-dump_row** job command option. -Summary statistics for columns +Summary Statistics for Columns ------------------------------ The Stat-Analysis "summary" job produces summary information for columns of data. After the user specifies the column(s) of interest and any other relevant search criteria, summary information is produced from values in those column(s) of data. The summary statistics produced are: mean, standard deviation, minimum, maximum, the 10th, 25th, 50th, 75th, and 90th percentiles, the interquartile range, the range, and both weighted and unweighted means using the logic prescribed by the World Meteorological Organization (WMO). @@ -37,12 +37,12 @@ The **-derive** job command option can be used to perform the derivation of stat .. _StA_Aggregated-values-from: -Aggregated values from multiple STAT lines +Aggregated Values from Multiple STAT Lines ------------------------------------------ The Stat-Analysis "aggregate" job aggregates values from multiple STAT lines of the same type. The user may specify the specific line type of interest and any other relevant search criteria. The Stat-Analysis tool then creates sums of each of the values in all lines matching the search criteria. The aggregated data are output as the same line type as the user specified. The STAT line types which may be aggregated in this way are the contingency table (FHO, CTC, PCT, MCTC, NBRCTC), partial sums (SL1L2, SAL1L2, VL1L2, and VAL1L2), and other (ISC, ECNT, RPS, RHIST, PHIST, RELP, NBRCNT, SSVAR, GRAD, and SEEPS) line types. -Aggregate STAT lines and produce aggregated statistics +Aggregate STAT Lines and Produce Aggregated Statistics ------------------------------------------------------ The Stat-Analysis "aggregate-stat" job aggregates multiple STAT lines of the same type together and produces relevant statistics from the aggregated line. This may be done in the same manner listed above in :numref:`StA_Aggregated-values-from`. However, rather than writing out the aggregated STAT line itself, the relevant statistics generated from that aggregated line are provided in the output. Specifically, if a contingency table line type (FHO, CTC, PCT, MCTC, or NBRCTC) has been aggregated, contingency table statistics (CTS, ECLV, PSTD, MCTS, or NBRCTS) line types can be computed. If a partial sums line type (SL1L2 or SAL1L2) has been aggregated, the continuous statistics (CNT) line type can be computed. If a vector partial sums line type (VL1L2 or VAL1L2) has been aggregated, the vector continuous statistics (VCNT) line type can be computed. For ensembles, the ORANK line type can be accumulated into ECNT, RPS, RHIST, PHIST, RELP, or SSVAR output. If a SEEPS matched pair line type (SEEPS_MPR) has been aggregated, the aggregated SEEPS line type (SEEPS) can be computed. If the matched pair line type (MPR) has been aggregated, may output line types (FHO, CTC, CTS, CNT, MCTC, MCTS, SL1L2, SAL1L2, VL1L2, VCNT, WDIR, PCT, PSTD, PJC, PRC, or ECLV) can be computed. Multiple output line types may be specified for each "aggregate-stat" job, as long as each output is derivable from the input. @@ -258,14 +258,14 @@ Once the appropriate lines have been generated for each verification time of int 2. For the "AGGR_WDIR" line, the input VL1L2 lines are first aggregated into a single line of partial sums where the weight for each line is determined by the number of points it represents. From this aggregated line, the mean forecast wind direction, observation wind direction, and the associated error are computed and written out. -Practical information +Practical Information ===================== The following sections describe the usage statement, required arguments and optional arguments for the Stat-Analysis tool. .. _stat_analysis-usage: -stat_analysis usage +stat_analysis Usage ------------------- The usage statement for the Stat-Analysis tool is shown below: @@ -284,14 +284,14 @@ stat_analysis has two required arguments and accepts several optional ones. In the usage statement for the Stat-Analysis tool, some additional terminology is introduced. In the Stat-Analysis tool, the term "job" refers to a set of tasks to be performed after applying user-specified options (i.e., "filters"). The filters are used to pare down a collection of output from the MET statistics tools to only those lines that are desired for the analysis. The job and its filters together comprise the "job command line". The "job command line" may be specified either on the command line to run a single analysis job or within the configuration file to run multiple analysis jobs at the same time. If jobs are specified in both the configuration file and the command line, only the jobs indicated in the configuration file will be run. The various jobs types are described in :numref:`Des_components_STAT_analysis_tool` and the filtering options are described in :numref:`stat_analysis-configuration-file`. -Required arguments for stat_analysis +Required Arguments for stat_analysis ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-lookin path** specifies the name of a directory to be searched recursively for STAT files (ending in ".stat") or any explicit file name with any suffix (such as "_ctc.txt") to be read. This option may be used multiple times to specify multiple directories and/or files to be read. If "-lookin python" is used, it must be followed by a Python embedding script and any command line arguments it takes. Python embedding can be used to pass **only** matched pair (MPR) lines as input to Stat-Analysis. 2. Either a configuration file must be specified with the **-config** option, or a **JOB COMMAND LINE** must be denoted. The **JOB COMMAND LINE** is described in :numref:`stat_analysis-configuration-file` -Optional arguments for stat_analysis +Optional Arguments for stat_analysis ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. The **-config config_file** specifies the configuration file to be used. The contents of the configuration file are discussed below. @@ -315,7 +315,7 @@ In this example, the Stat-Analysis tool will search for valid STAT lines located .. _stat_analysis-configuration-file: -stat_analysis configuration file +stat_analysis Configuration File -------------------------------- The default configuration file for the Stat-Analysis tool named **STATAnalysisConfig_default** can be found in the installed *share/met/config* directory. The version used for the example run in :numref:`installation` is also available in *scripts/config*. Like the other configuration files described in this document, it is recommended that users make a copy of these files prior to modifying their contents. @@ -676,7 +676,7 @@ These job command options are analogous to the options listed above but apply wh When processing input ORANK lines and writing output RHIST or PHIST lines, this option defines the output histogram bin width to be used. -stat-analysis tool output +stat-analysis Tool Output ------------------------- The output generated by the Stat-Analysis tool contains statistics produced by the analysis. It also records information about the analysis job that produced the output for each line. Generally, the output is printed to the screen. However, it can be redirected to an output file using the "**-out**" option. The format of output from each STAT job command is described below. diff --git a/docs/Users_Guide/tc-diag.rst b/docs/Users_Guide/tc-diag.rst index d7296aa65b..7c46b85448 100644 --- a/docs/Users_Guide/tc-diag.rst +++ b/docs/Users_Guide/tc-diag.rst @@ -36,10 +36,10 @@ The default Python diagnostics scripts included with the MET release provide the .. _tc-diag_practical_info: -Practical information +Practical Information ===================== -tc_diag usage +tc_diag Usage ------------- The following sections describe the usage statement, required arguments, and optional arguments for tc_diag. @@ -56,7 +56,7 @@ The following sections describe the usage statement, required arguments, and opt tc_diag has required arguments and can accept several optional arguments. -Required arguments for tc_diag +Required Arguments for tc_diag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-data domain tech_id_list [ file_1 ... file_n | data_file_list ]** option specifies a domain name, a comma-separated list of ATCF tech ID's, and a list of gridded data files or an ASCII file containing a list of files to be used. Specify **-data** one for each gridded data source. @@ -65,7 +65,7 @@ Required arguments for tc_diag 3. The **-config file** option is the TCDiagConfig file to be used. The contents of the configuration file are discussed below. -Optional arguments for tc_diag +Optional Arguments for tc_diag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-outdir path** option overrides the default output directory (current working directory) with the output directory path provided. @@ -74,12 +74,12 @@ Optional arguments for tc_diag 6. 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. -tc_diag configuration file +tc_diag Configuration File -------------------------- The default configuration file for the TC-Diag tool named **TCDiagConfig_default** can be found in the installed *share/met/config/* directory. Users are encouraged to copy these default files before modifying their contents. The contents of the configuration file are described in the subsections below. -Configuring input tracks and time +Configuring Input Tracks and Time ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -109,7 +109,7 @@ The configuration options listed above are used to filter the input track data d The **lead** entry is an array of strings specifying lead times in HH[MMSS] format. By default, diagnostics are computed every 6 hours out to 126 hours. Lead times for which no track point or gridded model data exist produce a warning message and diagnostics set to a missing data value. -Configuring domain information +Configuring Domain Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -143,7 +143,7 @@ The **diag_script** entry is an array of strings. Each string specifies the path .. note:: As of MET version 11.1.0, no tropical cyclone diagnostics are actually computed or written to the output. -Configuring data censoring and conversion options +Configuring Data Censoring and Conversion Options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -154,7 +154,7 @@ Configuring data censoring and conversion options These data censoring and conversion options are common to multiple MET tools and are described in :numref:`config_options`. They can be specified separately in each **data.field** array entry, described below. If provided, those operations are performed after reading the gridded data but prior to converting to the cylindrical coordinate range-azimuth grid. -Configuring fields, levels, and domains +Configuring Fields, Levels, and Domains ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -191,7 +191,7 @@ The **name** and **level** entries are common to multiple MET tools and are desc The **domain** entry is an array of strings. Each string specifies a domain name. If the **domain_info** domain name appears in this **domain** list, then this field will be read from that **domain_info** data source. If **domain** is set to an empty list, then this field will be read from all domain data sources. -Configuring regridding options +Configuring Regridding Options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -202,7 +202,7 @@ These **regrid** dictionary is common to multiple MET tools and is described in .. note:: As of MET version 11.1.0, the nearest neighbor regridding method is used rather than this configuration file option. -Configuring vortex removal option +Configuring Vortex Removal Option ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -213,7 +213,7 @@ The **vortex_removal** flag entry is a boolean specifying whether or not vortex .. note:: As of MET version 11.1.0, vortex removal logic is not yet supported. -Configuring data input and output options +Configuring Data Input and Output Options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -234,7 +234,7 @@ These three flag entries are booleans specifying what output data types should b .. note:: As of MET version 11.1.0, **nc_rng_azi_flag** is the only supported output type. These configuration options will automatically be reset at runtime to the settings listed above. -Configuring MET version, output prefix, and temp directory +Configuring MET Version, Output Prefix, and Temp Directory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none @@ -245,7 +245,7 @@ Configuring MET version, output prefix, and temp directory These options are common to multiple MET tools and are described in :numref:`config_options`. -tc_diag output +tc_diag Output -------------- The TC-Diag tool writes up to three output data types, as specified by flags in the configuration file. Each time TC-Diag is run it processes track data for a single initialization time. The actual number of output files varies depending on the number of model tracks provided. diff --git a/docs/Users_Guide/tc-dland.rst b/docs/Users_Guide/tc-dland.rst index c88ea33e0b..aa631ed7de 100644 --- a/docs/Users_Guide/tc-dland.rst +++ b/docs/Users_Guide/tc-dland.rst @@ -11,7 +11,7 @@ Many filtering criteria within the MET-TC tools depend on the distinction betwee While the TC-dland tool is available to be run, most users will find the precomputed distance to land files distributed with the release sufficient. Therefore, the typical user will not actually need to run this tool. -Input/output format +Input/Output Format =================== The input for the TC-dland tool is a file containing the longitude (degrees east) and latitude (degrees north) of all the coastlines and islands considered to be a significant landmass. The default input is to use all three land data files (**aland.dat, shland.dat, wland.dat**) found in the installed *share/met/tc_data/* directory. The use of all three files produces a global land data file. The **aland.dat** file contains the longitude and latitude distinctions used by NHC for the Atlantic and eastern North Pacific basins, the **shland.dat** contains longitude and latitude distinctions for the Southern Hemisphere (south Pacific and South Indian Ocean), and the **wland.dat** contains the remainder of the Northern Hemisphere (western North Pacific and North Indian Ocean). Users may supply their own input file in order to refine the definition of coastlines and a significant landmass. @@ -22,12 +22,12 @@ The output file from TC-dland is a NetCDF format file containing a gridded field **dland_global_tenth_degree.nc:** TC-dland output from all three land data files (global coverage) using a 1/10th degree grid. -Practical information +Practical Information ===================== This section briefly describes how to run tc_dland. The default grid is set to 1/10th degree Northwest (NW) hemispheric quadrant (over North America) grid. -tc_dland usage +tc_dland Usage -------------- .. code-block:: none @@ -43,12 +43,12 @@ tc_dland usage **tc_dland** has one required argument and accepts several optional ones. -Required arguments for tc_dland +Required Arguments for tc_dland ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **out_file** argument indicates the NetCDF output file containing the computed distances to land. -Optional arguments for tc_dland +Optional Arguments for tc_dland ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2. The **-grid spec** argument overrides the default grid (1/10th NH grid). Spec = **lat_ll lon_ll delta_lat delta_lon n_lat n_lon** diff --git a/docs/Users_Guide/tc-gen.rst b/docs/Users_Guide/tc-gen.rst index 1f690a1477..762fc0069f 100644 --- a/docs/Users_Guide/tc-gen.rst +++ b/docs/Users_Guide/tc-gen.rst @@ -11,7 +11,7 @@ The TC-Gen tool provides verification of deterministic and probabilistic tropica .. _tc-gen_stat_aspects: -Statistical aspects +Statistical Aspects =================== The TC-Gen tool processes both deterministic and probabilistic forecasts. @@ -32,12 +32,12 @@ Care should be taken when interpreting the statistics for filtered data. In some .. _tc-gen_practical_info: -Practical information +Practical Information ===================== This section describes how to configure and run the TC-Gen tool. The following sections describe the usage statement, required arguments, and optional arguments for tc_gen. -tc_gen usage +tc_gen Usage ------------ The usage statement for tc_gen is shown below: @@ -56,7 +56,7 @@ The usage statement for tc_gen is shown below: TC-Gen has three required arguments and accepts optional ones. -Required arguments for tc_gen +Required Arguments for tc_gen ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-genesis source** argument is the path to one or more ATCF or fort.66 (see documentation listed below) files generated by the Geophysical Fluid Dynamics Laboratory (GFDL) Vortex Tracker when run in tcgen mode or an ASCII file list or a top-level directory containing them. The required file format is described in the "Output formats" section of the `GFDL Vortex Tracker users guide. `_ @@ -71,7 +71,7 @@ Note: At least one of the **-genesis**, **-edeck**, or **-shape** command line o 5. 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_gen +Optional Arguments for tc_gen ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6. The **-out base** argument indicates the path of the output file base. This argument overrides the default output file base (./tc_gen) @@ -157,7 +157,7 @@ The TC-Gen tool implements the following logic: * Report the Nx2 probabilistic contingency table counts and statistics for each lead time. These counts and statistics are identified in the output files as *GENESIS_SHAPE*. -tc_gen configuration file +tc_gen Configuration File ------------------------- The default configuration file for the **TC-Gen** tool named **TCGenConfig_default** can be found in the installed *share/met/config* directory. Like the other configuration files described in this document, it is recommended that users make a copy of these files prior to modifying their contents. @@ -481,7 +481,7 @@ ______________________ The configuration options listed above are common to many MET tools and are described in :numref:`config_options`. TC-Gen writes output for 2x2 contingency tables to the **FHO**, **CTC**, and **CTS** line types when verifying deterministic genesis forecasts specified using the **-track** command line option. TC-Gen writes output for Nx2 probabilistic contingency tables to the **PCT**, **PSTD**, **PJC**, and **PRC** line types when verifying the probability of genesis forecasts specified using the **-edeck** command line option and probabilistic shapefiles using the **-shape** command line option. Note that the **genmpr** line type is specific to TC-Gen and describes individual genesis matched pairs. -tc_gen output +tc_gen Output ------------- TC-Gen produces output in STAT and, optionally, ASCII and NetCDF formats. The ASCII output duplicates the STAT output but has the data organized by line type. The output files are created based on the **-out** command line argument. The default output base name, **./tc_gen** writes output files in the current working directory named **tc_gen.stat** and, optionally, **tc_gen_pairs.nc** and **tc_gen_{TYPE}.txt** for each of the supported output line types. These output files can easily be redirected to another location using the **-out** command line option. The format of the STAT and ASCII output of the TC-Gen tool matches the output of other MET tools with the exception of the genesis matched pair line type. Please refer to the tables in :numref:`point_stat-output` for a description of the common output line types. The genesis matched pair line type and NetCDF output file are described below. diff --git a/docs/Users_Guide/tc-pairs.rst b/docs/Users_Guide/tc-pairs.rst index d8f7a79b5f..36b7d86ab5 100644 --- a/docs/Users_Guide/tc-pairs.rst +++ b/docs/Users_Guide/tc-pairs.rst @@ -9,13 +9,13 @@ Introduction The TC-Pairs tool provides verification for tropical cyclone forecasts in ATCF file format. It matches an ATCF format tropical cyclone (TC) forecast with a second ATCF format reference TC dataset (most commonly the Best Track analysis). The TC-Pairs tool processes both track and intensity adeck data and probabilistic edeck data. The adeck matched pairs contain position errors, as well as wind, sea level pressure, and distance to land values for each TC dataset. The edeck matched pairs contain probabilistic forecast values and the verifying observation values. The pair generation can be subset based on user-defined filtering criteria. Practical aspects of the TC-Pairs tool are described in :numref:`TC-Pairs_Practical-information`. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== .. _TC-Pairs_Diagnostics: TC Diagnostics ------------------ +-------------- TC diagnostics provide information about a TC's structure or its environment. Each TC diagnostic is a single-valued measure that corresponds to some aspect of the storm itself or the surrounding large-scale environment. TC diagnostics can be derived from observational analyses, model fields, or even satellite observations. Examples include: @@ -50,12 +50,12 @@ A future version of MET will also allow the CIRA model diagnostics to be compute .. _TC-Pairs_Practical-information: -Practical information +Practical Information ===================== This section describes how to configure and run the TC-Pairs tool. The TC-Pairs tool is used to match a tropical cyclone model forecast to a corresponding reference dataset. Both tropical cyclone forecast/reference data must be in ATCF format. Output from the TC-dland tool (NetCDF gridded distance file) is also a required input for the TC-Pairs tool. It is recommended to run tc_pairs on a storm-by-storm basis, rather than over multiple storms or seasons to avoid memory issues. -tc_pairs usage +tc_pairs Usage -------------- The usage statement for tc_pairs is shown below: @@ -73,7 +73,7 @@ The usage statement for tc_pairs is shown below: tc_pairs has required arguments and can accept several optional arguments. -Required arguments for tc_pairs +Required Arguments for tc_pairs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. @@ -84,7 +84,7 @@ Required arguments for tc_pairs 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 +Optional Arguments for tc_pairs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 CIRA_DIAG_RT or SHIPS_DIAG_RT 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. Support for additional diagnostic sources will be added in future releases. @@ -125,7 +125,7 @@ The TC-Pairs tool implements the following logic: • For each edeck/bdeck pair, write paired edeck probabilities and matching bdeck values to output PROBRIRW lines. -tc_pairs configuration file +tc_pairs Configuration File --------------------------- The default configuration file for the TC-Pairs tool named **TCPairsConfig_default** can be found in the installed *share/met/config/* directory. Users are encouraged to copy these default files before modifying their contents. The contents of the configuration file are described in the subsections below. @@ -398,7 +398,7 @@ parameter will result in missed matches. .. _tc_pairs-output: -tc_pairs output +tc_pairs Output --------------- TC-Pairs produces output in TCST format. The default output file name can be overwritten using the -out file argument in the usage statement. The TCST file output from TC-Pairs may be used as input into the TC-Stat tool. The header column in the TC-Pairs output is described in :numref:`TCST Header`. diff --git a/docs/Users_Guide/tc-rmw.rst b/docs/Users_Guide/tc-rmw.rst index 29e0e3be07..a9e67ffbc1 100644 --- a/docs/Users_Guide/tc-rmw.rst +++ b/docs/Users_Guide/tc-rmw.rst @@ -9,10 +9,10 @@ Introduction The TC-RMW tool regrids tropical cyclone model data onto a moving range-azimuth grid centered on points along the storm track provided in ATCF format, most likely the adeck generated from the file. The radial grid spacing may be set as a factor of the radius of maximum winds (RMW). If wind fields are specified in the configuration file the radial and tangential wind components will be computed. Any regridding method available in MET can be used to interpolate data on the model output grid to the specified range-azimuth grid. The regridding will be done separately on each vertical level. The model data files must coincide with track points in a user provided ATCF formatted track file. -Practical information +Practical Information ===================== -tc_rmw usage +tc_rmw Usage ------------ The following sections describe the usage statement, required arguments, and optional arguments for tc_rmw. @@ -29,7 +29,7 @@ The following sections describe the usage statement, required arguments, and opt tc_rmw has required arguments and can accept several optional arguments. -Required arguments for tc_rmw +Required Arguments for tc_rmw ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-data file_1 ... file_n | data_file_list** options specify the gridded data files or an ASCII file containing a list of files to be used. @@ -40,14 +40,14 @@ Required arguments for tc_rmw 4. The **-out** argument is the NetCDF output file to be written. -Optional arguments for tc_rmw +Optional Arguments for tc_rmw ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. 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. 6. 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. -tc_rmw configuration file +tc_rmw Configuration File ------------------------- The default configuration file for the TC-RMW tool named **TCRMWConfig_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. @@ -161,7 +161,7 @@ _______________________ The **radial_velocity_field_name** and **radial_velocity_long_field_name** parameters define the field names to give the output radial velocity grid in the netCDF output file. The parameters are used only if **compute_radial_and_radial_winds** is set to TRUE. -tc_rmw output file +tc_rmw Output File ------------------ The NetCDF output file contains the following dimensions: diff --git a/docs/Users_Guide/tc-stat.rst b/docs/Users_Guide/tc-stat.rst index 0d9e824837..b9770fe816 100644 --- a/docs/Users_Guide/tc-stat.rst +++ b/docs/Users_Guide/tc-stat.rst @@ -11,17 +11,17 @@ The TC-Stat tool ties together results from the TC-Pairs tool by providing summa .. _Statistical-aspects: -Statistical aspects +Statistical Aspects =================== -Filter TCST lines +Filter TCST Lines ----------------- The TC-Stat tool can be used to simply filter specific lines of the TCST file based on user-defined filtering criteria. All of the TCST lines that are retained from one or more files are written out to a single output file. The output file is also in TCST format. Filtering options are outlined below in :numref:`tc_stat-configuration-file` (configuration file). If multiple filtering options are listed, the job will be performed on their intersection. -Summary statistics for columns +Summary Statistics for Columns ------------------------------ The TC-Stat tool can be used to produce summary information for a single column of data. After the user specifies the specific column of interest, and any other relevant search criteria, summary information is produced from values in that column of data. The summary statistics produced are listed in :numref:`table_columnar_output_summary_tc_stat`. @@ -70,12 +70,12 @@ Users may specify several job command options to configure the behavior of this .. _Practical-information-1: -Practical information +Practical Information ===================== The following sections describe the usage statement, required arguments, and optional arguments for tc_stat. -tc_stat usage +tc_stat Usage ------------- The usage statement for tc_stat is shown below: @@ -93,14 +93,14 @@ TC-Stat has one required argument and accepts optional ones. The usage statement for the TC-Stat tool includes the "job" term, which refers to the set of tasks to be performed after applying user-specified filtering options. The filtering options are used to pare down the TC-Pairs output to only those lines that are desired for the analysis. The job and its filters together comprise a "job command line". The "job command line" may be specified either on the command line to run a single analysis job or within the configuration file to run multiple analysis jobs at the same time. If jobs are specified in both the configuration file and the command line, only the jobs indicated in the configuration file will be run. The various jobs are described in :numref:`table_columnar_output_summary_tc_stat` and the filtering options are described in :numref:`tc_stat-configuration-file`. -Required arguments for tc_stat +Required Arguments for tc_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **-lookin source** argument indicates the location of the input TCST files generated from tc_pairs. This argument can be used one or more times to specify the name of a TCST file or top-level directory containing TCST files to be processed. Multiple tcst files may be specified by using a wild card (\*). 2. Either a configuration file must be specified with the **-config** option, or a **JOB COMMAND LINE** must be denoted. The **JOB COMMAND LINE** options are described in :numref:`tc_stat-configuration-file`. -Optional arguments for tc_stat +Optional Arguments for tc_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3. The **-out file** argument indicates the desired name of the TCST format output file. @@ -121,7 +121,7 @@ In this example, the TC-Stat tool uses any TCST file (output from tc_pairs) in t .. _tc_stat-configuration-file: -tc_stat configuration file +tc_stat Configuration File ^^^^^^^^^^^^^^^^^^^^^^^^^^ The default configuration file for the **TC-Stat** tool named **TCStatConfig_default** can be found in the installed *share/met/config* directory. Like the other configuration files described in this document, it is recommended that users make a copy of these files prior to modifying their contents. @@ -391,7 +391,7 @@ _________________________ .. _tc_stat-output: -tc_stat output +tc_stat Output -------------- The output generated from the TC-Stat tool contains statistics produced by the analysis. Additionally, it includes information about the analysis job that produced the output for each line. The output can be redirected to an output file using the **-out** option. The format of output from each tc_stat job command is listed below. diff --git a/docs/Users_Guide/wavelet-stat.rst b/docs/Users_Guide/wavelet-stat.rst index b9a1aa7a76..1cab8c2ddb 100644 --- a/docs/Users_Guide/wavelet-stat.rst +++ b/docs/Users_Guide/wavelet-stat.rst @@ -21,10 +21,10 @@ The spatial scale components are obtained usually by applying a single band spat The Intensity-Scale technique evaluates the forecast skill as a function of the intensity values and of the spatial scale of the error. The scale components are obtained by applying a two dimensional Haar wavelet filter. Note that wavelets, because of their locality, are suitable for representing discontinuous fields characterized by few sparse non-zero features, such as precipitation. Moreover, the technique is based on a categorical approach, which is a robust and resistant approach, suitable for non-normally distributed variables, such as precipitation. The intensity-scale technique was specifically designed to cope with the difficult characteristics of precipitation fields, and for the verification of spatial precipitation forecasts. However, the intensity-scale technique can also be applied to verify other variables, such as cloud fraction. -Scientific and statistical aspects +Scientific and Statistical Aspects ================================== -The method +The Method ---------- :ref:`Casati et al. (2004) ` applied the Intensity-Scale verification to preprocessed and re-calibrated (unbiased) data. The preprocessing was aimed to mainly normalize the data, and defined categorical thresholds so that each categorical bin had a similar sample size. The recalibration was performed to eliminate the forecast bias. Preprocessing and recalibration are not strictly necessary for the application of the Intensity-Scale technique. The MET Intensity-Scale Tool does not perform either, and applies the Intensity-Scale approach to biased forecasts, for categorical thresholds defined by the user. @@ -126,7 +126,7 @@ Note that the energy squared of the observation binary field is identical to the -The spatial domain constraints +The Spatial Domain Constraints ------------------------------ The Intensity-Scale technique is constrained by the fact that orthogonal wavelets (discrete wavelet transforms) are usually performed dyadic domains, square domains of :math:`\mathbf{2^n} **x** :math:`\mathbf{2^n} grid-points. The Wavelet-Stat tool handles this issue based on settings in the configuration file by defining tiles of dimensions :math:`\mathbf{2^n} **x** :math:`\mathbf{2^n} over the input domain in the following ways: @@ -137,19 +137,19 @@ The Intensity-Scale technique is constrained by the fact that orthogonal wavelet 3. Padding: If the domain size is only slightly smaller than :math:`\mathbf{2^n} **x** :math:`\mathbf{2^n}, for certain variables (e.g. precipitation), it is advisable to expand the domain out to :math:`\mathbf{2^n} **x** :math:`\mathbf{2^n} grid-points by adding extra rows and/or columns of fill data. For precipitation variables, a fill value of zero is used. For continuous variables, such as temperature, the fill value is defined as the mean of the valid data in the rest of the field. A drawback to the padding method is the introduction of artificial data into the original field. Padding should only be used when a very small number of rows and/or columns need to be added. -Aggregation of statistics on multiple cases +Aggregation of Statistics on Multiple Cases ------------------------------------------- The Stat-Analysis tool aggregates the intensity scale technique results. Since the results are scale-dependent, it is sensible to aggregate results from multiple model runs (e.g. daily runs for a season) on the same spatial domain, so that the scale components for each singular case will be the same number, and the domain, if not a square domain of :math:`\mathbf{2^n} **x** :math:`\mathbf{2^n} grid-points, will be treated in the same fashion. Similarly, the intensity thresholds for each run should all be the same. The MSE and forecast and observation squared energy for each scale and thresholds are aggregated simply with a weighted average, where weights are proportional to the number of grid-points used in each single run to evaluate the statistics. If the same domain is always used (and it should) the weights result all the same, and the weighted averaging is a simple mean. For each threshold, the aggregated Br is equal to the aggregated squared energy of the binary observation field, and the aggregated FBI is obtained as the ratio of the aggregated squared energies of the forecast and observation binary fields. From aggregated Br and FBI, the MSErandom for the aggregated runs can be evaluated using the same formula as for the single run. Finally, the Intensity-Scale Skill Score is evaluated by using the aggregated statistics within the same formula used for the single case. -Practical information +Practical Information ===================== The following sections describe the usage statement, required arguments and optional arguments for the Stat-Analysis tool. -wavelet_stat usage +wavelet_stat Usage ------------------ The usage statement for the Wavelet-Stat tool is shown below: @@ -167,7 +167,7 @@ The usage statement for the Wavelet-Stat tool is shown below: wavelet_stat has three required arguments and accepts several optional ones. -Required arguments for wavelet_stat +Required Arguments for wavelet_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. The **fcst_file** argument is the gridded file containing the model data to be verified. @@ -176,7 +176,7 @@ Required arguments for wavelet_stat 3. The **config_file** argument is the configuration file to be used. The contents of the configuration file are discussed below. -Optional arguments for wavelet_stat +Optional Arguments for wavelet_stat ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. The **-outdir path** indicates the directory where output files should be written. @@ -200,7 +200,7 @@ In the example, the Wavelet-Stat tool will verify the model data in the **sample .. _wavelet_stat-configuration-file: -wavelet_stat configuration file +wavelet_stat Configuration File ------------------------------- The default configuration file for the Wavelet-Stat tool, **WaveletStatConfig_default**, can be found in the installed *share/met/config* directory. Another version of the configuration file is provided in *scripts/config*. We recommend that users make a copy of the default (or other) configuration file prior to modifying it. The contents are described in more detail below. @@ -313,7 +313,7 @@ The nc_pairs_flag is described in :numref:`grid_stat-configuration-file` .. _wavelet_stat-output: -wavelet_stat output +wavelet_stat Output ------------------- wavelet_stat produces output in STAT and, optionally, ASCII and NetCDF and PostScript formats. The ASCII output duplicates the STAT output but has the data organized by line type. While the Wavelet-Stat tool currently only outputs one STAT line type, additional line types may be added in future releases. The output files are written to the default output directory or the directory specified by the -outdir command line option. diff --git a/docs/index.rst b/docs/index.rst index 42c2882bae..2c81368bf2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,7 @@ ===================== MET version |version| ===================== + Developed by the `Developmental Testbed Center `_, Boulder, CO @@ -8,6 +9,7 @@ Boulder, CO History ------- + The Model Evaluation Tools (MET) were developed by the Developmental Testbed Center (DTC) and released in January 2008. The goal of the tools was to provide the community with a platform-independent and extensible framework @@ -37,6 +39,7 @@ and is open to community contributions. METplus Concept --------------- + METplus is the overarching, or umbrella, repository and hence framework for the Unified Forecast System verification capability. It is intended to be extensible through adding additional capability developed by the community. diff --git a/internal/scripts/docker/build_met_docker.sh b/internal/scripts/docker/build_met_docker.sh index e7cfb2dcde..c8bc1ce47b 100755 --- a/internal/scripts/docker/build_met_docker.sh +++ b/internal/scripts/docker/build_met_docker.sh @@ -7,9 +7,10 @@ source internal/scripts/environment/development.docker mkdir -p /met/logs LOG_FILE=/met/logs/MET-${MET_GIT_NAME}_configure.log -echo "Configuring MET ${MET_GIT_NAME} and writing log file ${LOG_FILE}" -./bootstrap -./configure --enable-grib2 --enable-mode_graphics --enable-modis --enable-lidar2nc --enable-python CPPFLAGS="-I/usr/local/include -I/usr/local/include/freetype2 -I/usr/local/include/cairo" LIBS="-ltirpc" > ${LOG_FILE} 2>&1 +echo "Running bootstrap for MET ${MET_GIT_NAME} and writing log file ${LOG_FILE}" +./bootstrap > ${LOG_FILE} 2>&1 +echo "Configuring MET ${MET_GIT_NAME} and appending to log file ${LOG_FILE}" +./configure --enable-grib2 --enable-mode_graphics --enable-modis --enable-lidar2nc --enable-python CPPFLAGS="-I/usr/local/include -I/usr/local/include/freetype2 -I/usr/local/include/cairo" LIBS="-ltirpc" >> ${LOG_FILE} 2>&1 if [ $? != 0 ]; then cat ${LOG_FILE} exit 1 diff --git a/scripts/python/met/dataplane.py b/scripts/python/met/dataplane.py index e11fc31d50..57c9ac367b 100644 --- a/scripts/python/met/dataplane.py +++ b/scripts/python/met/dataplane.py @@ -180,32 +180,33 @@ def validate_met_data(met_data, fill_value=None): from_ndarray = False if met_data is None: logger.quit(f"{method_name} The met_data is None") - - nx, ny = met_data.shape - met_fill_value = dataplane.MET_FILL_VALUE - if dataplane.is_xarray_dataarray(met_data): - from_xarray = True - attrs = met_data.attrs - met_data = met_data.data - modified_met_data = True - if isinstance(met_data, np.ndarray): - from_ndarray = True - met_data = np.ma.array(met_data) - - if isinstance(met_data, np.ma.MaskedArray): - is_int_data = dataplane.is_integer(met_data[0,0]) or dataplane.is_integer(met_data[int(nx/2),int(ny/2)]) - met_data = np.ma.masked_equal(met_data, float('nan')) - met_data = np.ma.masked_equal(met_data, float('inf')) - if fill_value is not None: - met_data = np.ma.masked_equal(met_data, fill_value) - met_data = met_data.filled(int(met_fill_value) if is_int_data else met_fill_value) else: - logger.log_msg(f"{method_name} unknown datatype {type(met_data)}") + nx, ny = met_data.shape + + met_fill_value = dataplane.MET_FILL_VALUE + if dataplane.is_xarray_dataarray(met_data): + from_xarray = True + attrs = met_data.attrs + met_data = met_data.data + modified_met_data = True + if isinstance(met_data, np.ndarray): + from_ndarray = True + met_data = np.ma.array(met_data) + + if isinstance(met_data, np.ma.MaskedArray): + is_int_data = dataplane.is_integer(met_data[0,0]) or dataplane.is_integer(met_data[int(nx/2),int(ny/2)]) + met_data = np.ma.masked_equal(met_data, float('nan')) + met_data = np.ma.masked_equal(met_data, float('inf')) + if fill_value is not None: + met_data = np.ma.masked_equal(met_data, fill_value) + met_data = met_data.filled(int(met_fill_value) if is_int_data else met_fill_value) + else: + logger.log_msg(f"{method_name} unknown datatype {type(met_data)}") - if dataplane.KEEP_XARRAY: - return xr.DataArray(met_data,attrs=attrs) if from_xarray else met_data - else: - return met_data + if dataplane.KEEP_XARRAY: + return xr.DataArray(met_data,attrs=attrs) if from_xarray else met_data + else: + return met_data def main(argv): diff --git a/src/basic/vx_util/ascii_table.cc b/src/basic/vx_util/ascii_table.cc index 9d1911f1de..326d53b978 100644 --- a/src/basic/vx_util/ascii_table.cc +++ b/src/basic/vx_util/ascii_table.cc @@ -1567,7 +1567,6 @@ switch ( just ) { default: mlog << Error << "\njustified_item() -> bad justification value\n\n"; exit ( 1 ); - break; } // switch diff --git a/src/basic/vx_util/data_plane.cc b/src/basic/vx_util/data_plane.cc index 2dd2dcaf38..52d2b72f9e 100644 --- a/src/basic/vx_util/data_plane.cc +++ b/src/basic/vx_util/data_plane.cc @@ -23,6 +23,7 @@ using namespace std; #include +#include #include "data_plane.h" @@ -230,57 +231,57 @@ void DataPlane::dump(ostream & out, int depth) const { void DataPlane::debug_examine(bool show_all_values) const { - vector values; - vector count; + // Nothing to print if verbosity level is below 4 + if(mlog.verbosity_level() < 4) return; + + map value_count_map; int total_count = 0; - - for (int x=0; x::iterator vi; - vi = find(values.begin(), values.end(), v); - if (vi == values.end()) { - values.push_back(v); - count.push_back(1); - } else { - int ii = vi - values.begin(); - count[ii] = count[ii] + 1; - } + + for(int i=0; i 0) total_count++; + + if (show_all_values) { + + // Add a new map entry + if(value_count_map.count(Data[i]) == 0) { + value_count_map[Data[i]] = 0; } + + // Increment count + value_count_map[Data[i]] += 1; } } - if (show_all_values) { - for (size_t i=0; i 0 = " << total_count + << " of " << Data.size() << "\n"; + + return; } /////////////////////////////////////////////////////////////////////////////// string DataPlane::sdebug_examine() const{ + ConcatString cs; + int n = 0; - int total_count = 0; - - for (int x=0; x 0) n++; } - char buf[1000]; - sprintf(buf, "Total count = %d", total_count); - string retval = buf; - return retval; + + cs << "Total count > 0 = " << n << " of " << (int) Data.size(); + + return cs; } /////////////////////////////////////////////////////////////////////////////// diff --git a/src/basic/vx_util/file_exists.cc b/src/basic/vx_util/file_exists.cc index 6d007303a4..a51db6f164 100644 --- a/src/basic/vx_util/file_exists.cc +++ b/src/basic/vx_util/file_exists.cc @@ -1,5 +1,3 @@ - - // *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* // ** Copyright UCAR (c) 1992 - 2023 // ** University Corporation for Atmospheric Research (UCAR) diff --git a/src/basic/vx_util/stat_column_defs.h b/src/basic/vx_util/stat_column_defs.h index e02e160d8b..2b59bd8dbe 100644 --- a/src/basic/vx_util/stat_column_defs.h +++ b/src/basic/vx_util/stat_column_defs.h @@ -105,7 +105,7 @@ static const char * cnt_columns [] = { "RMSFA", "RMSFA_BCL", "RMSFA_BCU", "RMSOA", "RMSOA_BCL", "RMSOA_BCU", "ANOM_CORR_UNCNTR", "ANOM_CORR_UNCNTR_BCL", "ANOM_CORR_UNCNTR_BCU", - "SI", "SI_BCL", "SI_BCL" + "SI", "SI_BCL", "SI_BCU" }; static const char * sl1l2_columns [] = { diff --git a/src/basic/vx_util/vx_util.h b/src/basic/vx_util/vx_util.h index 84638028ff..c50e7d16fc 100644 --- a/src/basic/vx_util/vx_util.h +++ b/src/basic/vx_util/vx_util.h @@ -37,6 +37,7 @@ #include "fix_float.h" #include "get_filenames.h" #include "grib_constants.h" +#include "GridTemplate.h" #include "int_array.h" #include "interp_mthd.h" #include "interp_util.h" diff --git a/src/libcode/vx_nc_util/nc_utils.cc b/src/libcode/vx_nc_util/nc_utils.cc index 6350b6576a..9ea240f666 100644 --- a/src/libcode/vx_nc_util/nc_utils.cc +++ b/src/libcode/vx_nc_util/nc_utils.cc @@ -8,21 +8,21 @@ //////////////////////////////////////////////////////////////////////// -using namespace std; - #include #include #include #include -using namespace netCDF; -using namespace netCDF::exceptions; #include "vx_log.h" #include "nc_utils.h" #include "util_constants.h" #include "vx_cal.h" +using namespace std; +using namespace netCDF; +using namespace netCDF::exceptions; + //////////////////////////////////////////////////////////////////////// void patch_nc_name(string *var_name) { @@ -172,7 +172,7 @@ bool get_att_value_chars(const NcAtt *att, ConcatString &value) { att->getValues(att_value); value = att_value; } - catch (exceptions::NcChar ex) { + catch (exceptions::NcChar &ex) { value = ""; // Handle netCDF::exceptions::NcChar: NetCDF: Attempt to convert between text & numbers mlog << Warning << "\n" << method_name @@ -188,7 +188,7 @@ bool get_att_value_chars(const NcAtt *att, ConcatString &value) { att->getValues(att_value); value = att_value; } - catch (exceptions::NcChar ex) { + catch (exceptions::NcChar &ex) { int num_elements_sub = 8096; int num_elements = att->getAttLength();; char *att_value[num_elements]; @@ -199,7 +199,7 @@ bool get_att_value_chars(const NcAtt *att, ConcatString &value) { att->getValues(att_value); value = att_value[0]; } - catch (exceptions::NcException ex) { + catch (exceptions::NcException &ex) { mlog << Warning << "\n" << method_name << "Exception: " << ex.what() << "\n" << "Fail to read " << GET_NC_NAME_P(att) << " attribute (" @@ -1373,15 +1373,18 @@ bool get_nc_data(NcVar *var, float *data) { case NcType::nc_DOUBLE: { double *packed_data = new double[cell_count]; + for (int idx=0; idxgetVar(packed_data); copy_nc_data_(var, data, packed_data, cell_count, diff --git a/src/libcode/vx_shapedata/engine.cc b/src/libcode/vx_shapedata/engine.cc index d16ba7de6c..0bfab73929 100644 --- a/src/libcode/vx_shapedata/engine.cc +++ b/src/libcode/vx_shapedata/engine.cc @@ -6,7 +6,6 @@ // ** P.O.Box 3000, Boulder, Colorado, 80307-3000, USA // *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* - /////////////////////////////////////////////////////////////////////// using namespace std; @@ -17,6 +16,8 @@ using namespace std; #include #include #include +#include +#include #include "engine.h" #include "mode_columns.h" @@ -591,12 +592,17 @@ void ModeFuzzyEngine::do_fcst_convolution() { // Apply a circular convolution to the raw field // - mlog << Debug(4) << " Before fcst convolution: " << fcst_conv->sdebug_examine() << "\n"; - + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " Before fcst convolution: " + << fcst_conv->sdebug_examine() << "\n"; + } if(r > 0) fcst_conv->conv_filter_circ(2*r + 1, conf_info.Fcst->vld_thresh); - mlog << Debug(4) << " After fcst convolution: " << fcst_conv->sdebug_examine() << "\n"; + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After fcst convolution: " + << fcst_conv->sdebug_examine() << "\n"; + } need_fcst_conv = false; need_fcst_thresh = true; @@ -625,14 +631,20 @@ void ModeFuzzyEngine::do_obs_convolution() { mlog << Debug(3) << "Applying circular convolution of radius " << r << " to the observation field.\n"; - mlog << Debug(4) << " Before obs convolution: " << obs_conv->sdebug_examine() << "\n"; + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " Before obs convolution: " + << obs_conv->sdebug_examine() << "\n"; + } // // Apply a circular convolution to the raw field // if(r > 0) obs_conv->conv_filter_circ(2*r + 1, conf_info.Obs->vld_thresh); - mlog << Debug(4) << " After obs convolution: " << obs_conv->sdebug_examine() << "\n"; + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After obs convolution: " + << obs_conv->sdebug_examine() << "\n"; + } need_obs_conv = false; need_obs_thresh = true; @@ -657,13 +669,21 @@ void ModeFuzzyEngine::do_fcst_thresholding() { *fcst_thresh = *fcst_raw; fcst_thresh->threshold(conf_info.Fcst->conv_thresh); - mlog << Debug(4) << " After thresholding raw fcst field: " << fcst_thresh->sdebug_examine() << "\n"; + + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After thresholding raw fcst field: " + << fcst_thresh->sdebug_examine() << "\n"; + } // // Threshold the convolved field // fcst_mask->threshold(conf_info.Fcst->conv_thresh); - mlog << Debug(4) << " After thresholding convolved fcst field: " << fcst_mask->sdebug_examine() << "\n"; + + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After thresholding convolved fcst field: " + << fcst_mask->sdebug_examine() << "\n"; + } mlog << Debug(3) << "Applying convolution threshold " << conf_info.Fcst->conv_thresh.get_str() @@ -692,13 +712,21 @@ void ModeFuzzyEngine::do_obs_thresholding() { *obs_thresh = *obs_raw; obs_thresh->threshold(conf_info.Obs->conv_thresh); - mlog << Debug(4) << " After thresholding raw obs field: " << obs_thresh->sdebug_examine() << "\n"; + + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After thresholding raw obs field: " + << obs_thresh->sdebug_examine() << "\n"; + } // // Threshold the convolved field // obs_mask->threshold(conf_info.Obs->conv_thresh); - mlog << Debug(4) << " After thresholding convolved obs field: " << obs_mask->sdebug_examine() << "\n"; + + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After thresholding convolved obs field: " + << obs_mask->sdebug_examine() << "\n"; + } mlog << Debug(3) << "Applying convolution threshold " << conf_info.Obs->conv_thresh.get_str() @@ -733,7 +761,11 @@ void ModeFuzzyEngine::do_fcst_filtering() { fcst_raw, conf_info.Fcst->conv_thresh, grid, conf_info.Fcst->var_info->is_precipitation()); - mlog << Debug(4) << " After attribute filtering of fcst field: " << fcst_mask->sdebug_examine() << "\n"; + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After attribute filtering of fcst field: " + << fcst_mask->sdebug_examine() << "\n"; + } + mlog << Debug(3) << "Applying object attribute filtering" << " resulted in " << fcst_mask->n_objects() << " simple forecast objects.\n"; @@ -769,7 +801,11 @@ void ModeFuzzyEngine::do_obs_filtering() { obs_raw, conf_info.Obs->conv_thresh, grid, conf_info.Obs->var_info->is_precipitation()); - mlog << Debug(4) << " After attribute filtering of obs field: " << obs_mask->sdebug_examine() << "\n"; + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After attribute filtering of obs field: " + << obs_mask->sdebug_examine() << "\n"; + } + mlog << Debug(3) << "Applying object attribute filtering" << " resulted in " << obs_mask->n_objects() << " simple observation objects.\n"; @@ -797,7 +833,11 @@ void ModeFuzzyEngine::do_fcst_splitting() { if(!need_fcst_split) return; *fcst_split = split(*fcst_mask, n_fcst); - mlog << Debug(4) << " After splitting of fcst field: " << fcst_split->sdebug_examine() << "\n"; + + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After splitting of fcst field: " + << fcst_split->sdebug_examine() << "\n"; + } need_fcst_split = false; need_fcst_merge = true; @@ -816,7 +856,11 @@ void ModeFuzzyEngine::do_obs_splitting() { if(!need_obs_split) return; *obs_split = split(*obs_mask, n_obs); - mlog << Debug(4) << " After splitting of obs field: " << obs_split->sdebug_examine() << "\n"; + + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After splitting of obs field: " + << obs_split->sdebug_examine() << "\n"; + } need_obs_split = false; need_obs_merge = true; @@ -1033,32 +1077,22 @@ void ModeFuzzyEngine::do_matching() { void ModeFuzzyEngine::do_no_match() { int j, k, n; - ShapeData * fcst_shape = (ShapeData *) 0; - ShapeData * obs_shape = (ShapeData *) 0; + ShapeData cur_shape; do_fcst_splitting(); do_obs_splitting(); clear_colors(); - fcst_shape = new ShapeData [n_fcst]; - obs_shape = new ShapeData [n_obs]; - - if(!fcst_shape || !obs_shape) { - - mlog << Error << "\nModeFuzzyEngine::do_no_match() -> " - << "memory allocation error\n\n"; - exit(1); - } - // // Do the single features // fcst_single.set_size(n_fcst); for(j=0; jvar_info->is_precipitation()); fcst_single[j].object_number = j+1; @@ -1067,8 +1101,9 @@ void ModeFuzzyEngine::do_no_match() { obs_single.set_size(n_obs); for(j=0; jvar_info->is_precipitation()); obs_single[j].object_number = j+1; @@ -1112,9 +1147,6 @@ void ModeFuzzyEngine::do_no_match() { // Done // - delete [] fcst_shape; fcst_shape = (ShapeData *) 0; - delete [] obs_shape; obs_shape = (ShapeData *) 0; - return; } @@ -1123,32 +1155,22 @@ void ModeFuzzyEngine::do_no_match() { void ModeFuzzyEngine::do_match_merge() { int j, k, n; InterestInfo junkinfo; - ShapeData * fcst_shape = (ShapeData *) 0; - ShapeData * obs_shape = (ShapeData *) 0; + ShapeData cur_shape; do_fcst_splitting(); do_obs_splitting(); clear_colors(); - fcst_shape = new ShapeData [n_fcst]; - obs_shape = new ShapeData [n_obs]; - - if(!fcst_shape || !obs_shape) { - - mlog << Error << "\nModeFuzzyEngine::do_match_merge() -> " - << "memory allocation error\n\n"; - exit(1); - } - // // Do the single features // fcst_single.set_size(n_fcst); for(j=0; jvar_info->is_precipitation()); fcst_single[j].object_number = j+1; @@ -1157,8 +1179,9 @@ void ModeFuzzyEngine::do_match_merge() { obs_single.set_size(n_obs); for(j=0; jvar_info->is_precipitation()); obs_single[j].object_number = j+1; @@ -1277,9 +1300,6 @@ void ModeFuzzyEngine::do_match_merge() { // Done // - delete [] fcst_shape; fcst_shape = (ShapeData *) 0; - delete [] obs_shape; obs_shape = (ShapeData *) 0; - return; } @@ -1292,12 +1312,10 @@ void ModeFuzzyEngine::do_match_merge() { /////////////////////////////////////////////////////////////////////// void ModeFuzzyEngine::do_fcst_merge_thresh() { - int j, k, x, y; - int n_fcst_merge, intersection; - int count, first_k; + const char *method_name = "ModeFuzzyEngine::do_fcst_merge_thresh() -> "; + int j, mid, oid; + int n_fcst_merge; ShapeData fcst_merge_mask, fcst_merge_split; - ShapeData * fcst_shape = (ShapeData *) 0; - ShapeData * fcst_merge_shape = (ShapeData *) 0; do_fcst_splitting(); @@ -1318,90 +1336,60 @@ void ModeFuzzyEngine::do_fcst_merge_thresh() { fcst_merge_split = split(fcst_merge_mask, n_fcst_merge); // - // Allocate space for all of the simple forecast shapes and - // forecast merge shapes + // Mapping of simple object id to merge object id values and vice-versa // - fcst_shape = new ShapeData [n_fcst]; - fcst_merge_shape = new ShapeData [n_fcst_merge]; + map > obj_to_mrg_map; + map > mrg_to_obj_map; + std::set empty_set; - if(!fcst_shape || !fcst_merge_shape) { + // Add map entries for each object + for(j=1; j<=n_fcst; j++) obj_to_mrg_map[j] = empty_set; + for(j=1; j<=n_fcst_merge; j++) mrg_to_obj_map[j] = empty_set; - mlog << Error << "\nModeFuzzyEngine::do_fcst_merge_thresh() -> " - << "memory allocation error\n\n"; - exit(1); - } + // Loop over all the data points + for(j=0; jdata.nxy(); j++) { + + oid = fcst_split->data.buf()[j]; + mid = fcst_merge_split.data.buf()[j]; + + // Update object id maps + if(oid > 0) obj_to_mrg_map[oid].insert(mid); + if(oid > 0 && mid > 0) mrg_to_obj_map[mid].insert(oid); + + } // end for j // - // Select all of the simple forecast shapes and - // forecast merge shapes + // Each simple object should be fully contained in a merge object // - for(j=0; j= fcst area - // - - if(intersection >= fcst_shape[k].area()) { - - collection.make_room(); - - // - // Keep track of the first embedded shape. You only want to - // create a composite if there are more than 1 shapes in it. - // - if(count == 0) first_k = k+1; + // Ignore merge objects containing a single simple object + if(mrg_to_obj_map[mid].size() <= 1) continue; - else if(count == 1) { - collection.set[collection.n_sets].add_pair(first_k, -1); - collection.set[collection.n_sets].add_pair(k+1, -1); - } - else { - collection.set[collection.n_sets].add_pair(k+1, -1); - } + // Add all simple objects into one new set + collection.make_room(); + for(auto it = mrg_to_obj_map[mid].begin(); + it != mrg_to_obj_map[mid].end(); it++) { + collection.set[collection.n_sets].add_pair(*it, -1); + } - count++; - } - } // end for k + // Increment set counter + collection.n_sets++; - if(count > 0) collection.n_sets++; - } // end for j - - // - // Done - // - - delete [] fcst_shape; fcst_shape = (ShapeData *) 0; - delete [] fcst_merge_shape; fcst_merge_shape = (ShapeData *) 0; + } // end for mid return; } @@ -1415,12 +1403,10 @@ void ModeFuzzyEngine::do_fcst_merge_thresh() { /////////////////////////////////////////////////////////////////////// void ModeFuzzyEngine::do_obs_merge_thresh() { - int j, k, x, y; - int n_obs_merge, intersection; - int count, first_k; + const char *method_name = "ModeFuzzyEngine::do_obs_merge_thresh() -> "; + int j, mid, oid; + int n_obs_merge; ShapeData obs_merge_mask, obs_merge_split; - ShapeData * obs_shape = (ShapeData *) 0; - ShapeData * obs_merge_shape = (ShapeData *) 0; do_obs_splitting(); @@ -1441,328 +1427,243 @@ void ModeFuzzyEngine::do_obs_merge_thresh() { obs_merge_split = split(obs_merge_mask, n_obs_merge); // - // Allocate space for all of the simple observation shapes and - // observation merge shapes + // Mapping of simple object id to merge object id values and vice-versa // - obs_shape = new ShapeData [n_obs]; - obs_merge_shape = new ShapeData [n_obs_merge]; + map > obj_to_mrg_map; + map > mrg_to_obj_map; + std::set empty_set; - if(!obs_shape || !obs_merge_shape) { + // Add map entries for each object + for(j=1; j<=n_obs; j++) obj_to_mrg_map[j] = empty_set; + for(j=1; j<=n_obs_merge; j++) mrg_to_obj_map[j] = empty_set; - mlog << Error << "\nModeFuzzyEngine::do_obs_merge_thresh() -> " - << "memory allocation error\n\n"; - exit(1); - } + // Loop over all the data points + for(j=0; jdata.nxy(); j++) { + + oid = obs_split->data.buf()[j]; + mid = obs_merge_split.data.buf()[j]; + + // Update object id maps + if(oid > 0) obj_to_mrg_map[oid].insert(mid); + if(oid > 0 && mid > 0) mrg_to_obj_map[mid].insert(oid); + + } // end for j // - // Select all of the simple observation shapes and - // simple merge shapes + // Each simple object should be fully contained in a merge object // - for(j=0; j= obs area - // - if(intersection >= obs_shape[k].area()) { - - collection.make_room(); + for(mid=1; mid<=n_obs_merge; mid++) { - // - // Keep track of the first embedded shape. You only want to - // create a composite if there are more than 1 shapes in it. - // - if(count == 0) first_k = k+1; + // Ignore merge objects containing a single simple object + if(mrg_to_obj_map[mid].size() <= 1) continue; - else if(count == 1) { - collection.set[collection.n_sets].add_pair(-1, first_k); - collection.set[collection.n_sets].add_pair(-1, k+1); - } - else { - collection.set[collection.n_sets].add_pair(-1, k+1); - } - - count++; - } - } // end for k - - if(count > 0) collection.n_sets++; - } // end for j + // Add all simple objects into one new set + collection.make_room(); + for(auto it = mrg_to_obj_map[mid].begin(); + it != mrg_to_obj_map[mid].end(); it++) { + collection.set[collection.n_sets].add_pair(-1, *it); + } - // - // Done - // + // Increment set counter + collection.n_sets++; - delete [] obs_shape; obs_shape = (ShapeData *) 0; - delete [] obs_merge_shape; obs_merge_shape = (ShapeData *) 0; + } // end for mid return; } +/////////////////////////////////////////////////////////////////////// void ModeFuzzyEngine::do_fcst_merge_thresh(const ShapeData &merge_data) { - int j, k, x, y; - int n_fcst_merge, intersection; - int count, first_k; - //ShapeData fcst_merge_mask; + const char *method_name = "ModeFuzzyEngine::do_fcst_merge_thresh() -> "; + int j, mid, oid; + int n_fcst_merge; ShapeData fcst_merge_split; - ShapeData * fcst_shape = (ShapeData *) 0; - ShapeData * fcst_merge_shape = (ShapeData *) 0; do_fcst_splitting(); // - // Define the forecast merge field by applying the specified threshold - // to the convolved field - // - fcst_merge_split = merge_data; - n_fcst_merge = fcst_merge_split.n_objects(); - - // fcst_merge_mask = *fcst_conv; - - // // - // // Threshold the forecast merge field - // // - // fcst_merge_mask.threshold(conf_info.Fcst->merge_thresh); - - // // - // // Split up the forecast merge field - // // - // fcst_merge_split = split(fcst_merge_mask, n_fcst_merge); - - // - // Allocate space for all of the simple forecast shapes and - // forecast merge shapes + // Check dimensions // - fcst_shape = new ShapeData [n_fcst]; - fcst_merge_shape = new ShapeData [n_fcst_merge]; - - if(!fcst_shape || !fcst_merge_shape) { - - mlog << Error << "\nModeFuzzyEngine::do_fcst_merge_thresh() -> " - << "memory allocation error\n\n"; + if(fcst_split->data.nx() != merge_data.data.nx() || + fcst_split->data.ny() != merge_data.data.ny()) { + mlog << Error << "\n" << method_name + << "grid dimensions do not match (" << fcst_split->data.nx() << ", " + << fcst_split->data.ny() << ") != (" << merge_data.data.nx() << ", " + << merge_data.data.ny() << ")!\n\n"; exit(1); } // - // Select all of the simple forecast shapes and - // forecast merge shapes + // Assume that the input merge data has already been split // - for(j=0; j > obj_to_mrg_map; + map > mrg_to_obj_map; + std::set empty_set; - // - // Calculate intersection area - // - intersection = 0; + // Add map entries for each object + for(j=1; j<=n_fcst; j++) obj_to_mrg_map[j] = empty_set; + for(j=1; j<=n_fcst_merge; j++) mrg_to_obj_map[j] = empty_set; - for(x=0; xdata.nxy(); j++) { - if(fcst_merge_shape[j].s_is_on(x, y) && - fcst_shape[k].s_is_on(x, y)) intersection++; - } - } + oid = fcst_split->data.buf()[j]; + mid = fcst_merge_split.data.buf()[j]; - // - // Add to set collection only if the fcst object is - // completely contained in the merge object. Meaning, - // intersection area >= fcst area - // + // Update object id maps + if(oid > 0) obj_to_mrg_map[oid].insert(mid); + if(oid > 0 && mid > 0) mrg_to_obj_map[mid].insert(oid); - if(intersection >= fcst_shape[k].area()) { + } // end for j - collection.make_room(); + // + // Each simple object should be fully contained in a merge object + // + for(oid=1; oid<=n_fcst; oid++) { + if(obj_to_mrg_map[oid].size() != 1) { + mlog << Warning << "\n" << method_name + << "No forecast threshold merging done because simple object " + << oid << " is not fully contained within one merge object!\n\n"; + return; + } + } - // - // Keep track of the first embedded shape. You only want to - // create a composite if there are more than 1 shapes in it. - // - if(count == 0) first_k = k+1; + // + // Calculate the composite object sets + // + for(mid=1; mid<=n_fcst_merge; mid++) { - else if(count == 1) { - collection.set[collection.n_sets].add_pair(first_k, -1); - collection.set[collection.n_sets].add_pair(k+1, -1); - } - else { - collection.set[collection.n_sets].add_pair(k+1, -1); - } + // Ignore merge objects containing a single simple object + if(mrg_to_obj_map[mid].size() <= 1) continue; - count++; - } - } // end for k + // Add all simple objects into one new set + collection.make_room(); + for(auto it = mrg_to_obj_map[mid].begin(); + it != mrg_to_obj_map[mid].end(); it++) { + collection.set[collection.n_sets].add_pair(*it, -1); + } - if(count > 0) collection.n_sets++; - } // end for j + // Increment set counter + collection.n_sets++; - // - // Done - // + } // end for mid - delete [] fcst_shape; fcst_shape = (ShapeData *) 0; - delete [] fcst_merge_shape; fcst_merge_shape = (ShapeData *) 0; + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After merging of fcst field: " + << fcst_split->sdebug_examine() << "\n"; + } - mlog << Debug(4) << " After merging of fcst field: " << fcst_split->sdebug_examine() << "\n"; return; } +/////////////////////////////////////////////////////////////////////// + void ModeFuzzyEngine::do_obs_merge_thresh(const ShapeData &merge_data) { - int j, k, x, y; - int n_obs_merge, intersection; - int count, first_k; - //ShapeData obs_merge_mask; + const char *method_name = "ModeFuzzyEngine::do_fcst_merge_thresh() -> "; + int j, mid, oid; + int n_obs_merge; ShapeData obs_merge_split; - ShapeData * obs_shape = (ShapeData *) 0; - ShapeData * obs_merge_shape = (ShapeData *) 0; do_obs_splitting(); // - // Define the forecast merge field by applying the specified threshold - // to the convolved field - // - // obs_merge_mask = *obs_conv; - - // - // Threshold the forecast merge field + // Check dimensions // - // obs_merge_mask.threshold(conf_info.Obs->merge_thresh); + if(obs_split->data.nx() != merge_data.data.nx() || + obs_split->data.ny() != merge_data.data.ny()) { + mlog << Error << "\n" << method_name + << "grid dimensions do not match (" << obs_split->data.nx() << ", " + << obs_split->data.ny() << ") != (" << merge_data.data.nx() << ", " + << merge_data.data.ny() << ")!\n\n"; + exit(1); + } // - // Split up the forecast merge field + // Assume that the input merge data has already been split // - obs_merge_split = merge_data; //split(obs_merge_mask, n_obs_merge); + obs_merge_split = merge_data; n_obs_merge = obs_merge_split.n_objects(); // - // Allocate space for all of the simple observation shapes and - // observation merge shapes + // Mapping of simple object id to merge object id values and vice-versa // - obs_shape = new ShapeData [n_obs]; - obs_merge_shape = new ShapeData [n_obs_merge]; + map > obj_to_mrg_map; + map > mrg_to_obj_map; + std::set empty_set; - if(!obs_shape || !obs_merge_shape) { + // Add map entries for each object + for(j=1; j<=n_obs; j++) obj_to_mrg_map[j] = empty_set; + for(j=1; j<=n_obs_merge; j++) mrg_to_obj_map[j] = empty_set; - mlog << Error << "\nModeFuzzyEngine::do_obs_merge_thresh() -> " - << "memory allocation error\n\n"; - exit(1); - } + // Loop over all the data points + for(j=0; jdata.nxy(); j++) { + + oid = obs_split->data.buf()[j]; + mid = obs_merge_split.data.buf()[j]; + + // Update object id maps + if(oid > 0) obj_to_mrg_map[oid].insert(mid); + if(oid > 0 && mid > 0) mrg_to_obj_map[mid].insert(oid); + + } // end for j // - // Select all of the simple observation shapes and - // simple merge shapes + // Each simple object should be fully contained in a merge object // - for(j=0; j= obs area - // - if(intersection >= obs_shape[k].area()) { - - collection.make_room(); - - // - // Keep track of the first embedded shape. You only want to - // create a composite if there are more than 1 shapes in it. - // - if(count == 0) first_k = k+1; - - else if(count == 1) { - collection.set[collection.n_sets].add_pair(-1, first_k); - collection.set[collection.n_sets].add_pair(-1, k+1); - } - else { - collection.set[collection.n_sets].add_pair(-1, k+1); - } + // Add all simple objects into one new set + collection.make_room(); + for(auto it = mrg_to_obj_map[mid].begin(); + it != mrg_to_obj_map[mid].end(); it++) { + collection.set[collection.n_sets].add_pair(-1, *it); + } - count++; - } - } // end for k + // Increment set counter + collection.n_sets++; - if(count > 0) collection.n_sets++; - } // end for j + } // end for mid - // - // Done - // - - delete [] obs_shape; obs_shape = (ShapeData *) 0; - delete [] obs_merge_shape; obs_merge_shape = (ShapeData *) 0; + if(mlog.verbosity_level() >= 4) { + mlog << Debug(4) << " After merging of obs field: " + << obs_split->sdebug_examine() << "\n"; + } - mlog << Debug(4) << " After merging of obs field: " << obs_split->sdebug_examine() << "\n"; return; } @@ -2114,31 +2015,22 @@ void ModeFuzzyEngine::do_obs_merge_engine(const char *default_config, void ModeFuzzyEngine::do_match_fcst_merge() { int j, k, n; InterestInfo junkinfo; - ShapeData * fcst_shape = (ShapeData *) 0; - ShapeData * obs_shape = (ShapeData *) 0; + ShapeData cur_shape; do_fcst_splitting(); do_obs_splitting(); clear_colors(); - fcst_shape = new ShapeData [n_fcst]; - obs_shape = new ShapeData [n_obs]; - - if(!fcst_shape || !obs_shape) { - mlog << Error << "\nModeFuzzyEngine::do_match_fcst_merge() -> " - << "memory allocation error\n\n"; - exit(1); - } - // // Do the single features // fcst_single.set_size(n_fcst); for(j=0; jvar_info->is_precipitation()); fcst_single[j].object_number = j+1; @@ -2147,8 +2039,9 @@ void ModeFuzzyEngine::do_match_fcst_merge() { obs_single.set_size(n_obs); for(j=0; jvar_info->is_precipitation()); obs_single[j].object_number = j+1; @@ -2275,9 +2168,6 @@ void ModeFuzzyEngine::do_match_fcst_merge() { // Done // - delete [] fcst_shape; fcst_shape = (ShapeData *) 0; - delete [] obs_shape; obs_shape = (ShapeData *) 0; - return; } @@ -2291,31 +2181,22 @@ void ModeFuzzyEngine::do_match_fcst_merge() { void ModeFuzzyEngine::do_match_only() { int j, k, n; InterestInfo junkinfo; - ShapeData * fcst_shape = (ShapeData *) 0; - ShapeData * obs_shape = (ShapeData *) 0; + ShapeData cur_shape; do_fcst_splitting(); do_obs_splitting(); clear_colors(); - fcst_shape = new ShapeData [n_fcst]; - obs_shape = new ShapeData [n_obs]; - - if(!fcst_shape || !obs_shape) { - mlog << Error << "\nModeFuzzyEngine::do_match_only() -> " - << "memory allocation error\n\n"; - exit(1); - } - // // Do the single features // fcst_single.set_size(n_fcst); for(j=0; jvar_info->is_precipitation()); fcst_single[j].object_number = j+1; @@ -2324,8 +2205,9 @@ void ModeFuzzyEngine::do_match_only() { obs_single.set_size(n_obs); for(j=0; jvar_info->is_precipitation()); obs_single[j].object_number = j+1; @@ -2446,9 +2328,6 @@ void ModeFuzzyEngine::do_match_only() { // Done // - delete [] fcst_shape; fcst_shape = (ShapeData *) 0; - delete [] obs_shape; obs_shape = (ShapeData *) 0; - return; } @@ -2537,8 +2416,7 @@ void ModeFuzzyEngine::do_obs_clus_splitting() { void ModeFuzzyEngine::do_cluster_features() { int j; - ShapeData * fcst_clus_shape = (ShapeData *) 0; - ShapeData * obs_clus_shape = (ShapeData *) 0; + ShapeData cur_shape; if(need_fcst_clus_split) do_fcst_clus_splitting(); if(need_obs_clus_split) do_obs_clus_splitting(); @@ -2548,16 +2426,6 @@ void ModeFuzzyEngine::do_cluster_features() { // n_clus = collection.n_sets; - fcst_clus_shape = new ShapeData [n_clus]; - obs_clus_shape = new ShapeData [n_clus]; - - if(!fcst_clus_shape || !obs_clus_shape) { - - mlog << Error << "\nModeFuzzyEngine::do_cluster_features() -> " - << "memory allocation error\n\n"; - exit(1); - } - // // Do the single features for clusters // @@ -2565,16 +2433,18 @@ void ModeFuzzyEngine::do_cluster_features() { obs_cluster.set_size(n_clus); for(j=0; jvar_info->is_precipitation()); + cur_shape = select(*fcst_clus_split, j+1); + fcst_cluster[j].set(*fcst_raw, *fcst_thresh, + *fcst_clus_split, cur_shape, + conf_info.inten_perc_value, + conf_info.Fcst->var_info->is_precipitation()); fcst_cluster[j].object_number = j+1; - obs_clus_shape[j] = select(*obs_clus_split, j+1); - obs_cluster[j].set(*obs_raw, *obs_thresh, obs_clus_shape[j], - conf_info.inten_perc_value, - conf_info.Obs->var_info->is_precipitation()); + cur_shape = select(*obs_clus_split, j+1); + obs_cluster[j].set(*obs_raw, *obs_thresh, + *obs_clus_split, cur_shape, + conf_info.inten_perc_value, + conf_info.Obs->var_info->is_precipitation()); obs_cluster[j].object_number = j+1; } @@ -2585,7 +2455,7 @@ void ModeFuzzyEngine::do_cluster_features() { for(j=0; jcentroid(centroid_x, centroid_y); + mask_sd.centroid(centroid_x, centroid_y); // // Axis angle // - axis_ang = Mask->angle_degrees(); + axis_ang = mask_sd.angle_degrees(); // // Length and Width // - Mask->calc_length_width(length, width); + mask_sd.calc_length_width(length, width); // // Aspect ratio @@ -228,28 +228,28 @@ void SingleFeature::set(const ShapeData &raw, const ShapeData &thresh, // // Object area // - area = Mask->area(); + area = mask_sd.area(); // // Object threshold area: the area of the raw field inside the mask // area that meets the threshold criteria // - area_thresh = (double) ShapeData_intersection(*Thresh, *Mask); + area_thresh = (double) ShapeData_intersection(*Thresh, mask_sd); // // Curvature, Curvature_x, Curvature_y // - curvature = Mask->curvature(curvature_x, curvature_y); + curvature = mask_sd.curvature(curvature_x, curvature_y); // // Complexity // - complexity = Mask->complexity(); + complexity = mask_sd.complexity(); // // Compute the Intensity Percentiles // - get_percentiles(intensity_ptile, raw, mask, perc, precip_flag); + get_percentiles(intensity_ptile, raw_sd, mask_sd, perc, precip_flag); // // User Percentile @@ -259,17 +259,17 @@ void SingleFeature::set(const ShapeData &raw, const ShapeData &thresh, // // Convex hull // - convex_hull = Mask->convex_hull(); + convex_hull = mask_sd.convex_hull(); // // Boundary: // Split the mask field and store the boundary for each object. // - split_wd = split(mask, n_bdy); + cur_split_sd = split(mask_sd, n_bdy); boundary = new Polyline [n_bdy]; for(i=0; iarea)/(Fcst->area), (Fcst->area)/(Obs->area) ); - // // Intersection, union, and symmetric diff areas // intersection_area = union_area = 0.0; symmetric_diff = 0.0; - for(x=0; x<(Fcst->Mask->data.nx()); ++x) { - for(y=0; y<(Fcst->Mask->data.ny()); ++y) { + int nxy = Fcst->Split->data.nxy(); + for(i=0; iMask->s_is_on(x, y); - obs_on = Obs->Mask->s_is_on(x, y); + fcst_on = (nint(Fcst->Split->data.data()[i]) == Fcst->object_number ? 1 : 0); + obs_on = (nint( Obs->Split->data.data()[i]) == Obs->object_number ? 1 : 0); - if(fcst_on && obs_on) intersection_area++; - if(fcst_on || obs_on) union_area++; - if((fcst_on && !obs_on) || - (!fcst_on && obs_on)) symmetric_diff++; - } + if( fcst_on && obs_on) intersection_area++; + if( fcst_on || obs_on) union_area++; + if( ( fcst_on && !obs_on) || + (!fcst_on && obs_on) ) symmetric_diff++; } // diff --git a/src/libcode/vx_shapedata/interest.h b/src/libcode/vx_shapedata/interest.h index de8832ed2b..6fd6f9cc2d 100644 --- a/src/libcode/vx_shapedata/interest.h +++ b/src/libcode/vx_shapedata/interest.h @@ -49,13 +49,13 @@ class SingleFeature { void clear(); - void set(const ShapeData &raw, const ShapeData &thresh, - const ShapeData &mask, const int perc, - const bool precip_flag); + void set(const ShapeData &raw, const ShapeData &thresh, + const ShapeData &split, const ShapeData &mask, + const int perc, const bool precip_flag); const ShapeData * Raw; // NOT allocated, so DON'T delete! const ShapeData * Thresh; // NOT allocated, so DON'T delete! - const ShapeData * Mask; // NOT allocated, so DON'T delete! + const ShapeData * Split; // NOT allocated, so DON'T delete! int object_number; diff --git a/src/libcode/vx_shapedata/mode_field_info.cc b/src/libcode/vx_shapedata/mode_field_info.cc index 6cecb55d07..06311f5d47 100644 --- a/src/libcode/vx_shapedata/mode_field_info.cc +++ b/src/libcode/vx_shapedata/mode_field_info.cc @@ -9,6 +9,7 @@ //////////////////////////////////////////////////////////////////////// +#include #include "vx_config.h" #include "vx_data2d.h" @@ -20,6 +21,7 @@ #include "mode_field_info.h" +using std::string; //////////////////////////////////////////////////////////////////////// @@ -219,32 +221,87 @@ if ( dict->lookup(conf_key_conv_thresh) ) { } -if ( dict->lookup(conf_key_merge_thresh) ) { - - merge_thresh_array = dict->lookup_thresh_array(conf_key_merge_thresh); - -} - if ( dict->lookup(conf_key_vld_thresh) ) { vld_thresh = dict->lookup_double(conf_key_vld_thresh); } -// for the multivar case, go without parent, and error out if merge flag is -// not set for the individual field +// For the multivar case, more complex logic regarding merge_flag and merge_thresh +// If individual entry has a merge_flag, it must have a merge_thresh (unless merge_flag=NONE) +// If individual entry has no merge_flag, check the parent and go with that flag and thresh +// If individual entry has no merge_flag, but individual entry has a merge_thresh, it's an error + if ( _multivar ) { + // set defaults to no merging + merge_thresh.clear(); + merge_flag = MergeType_None; + + // pull out the name + string name = var_info->name(); + if ( dict->lookup(conf_key_merge_flag, false)) { - merge_flag = int_to_mergetype(dict->lookup_int(conf_key_merge_flag)); + // this individual entry has merge_flag + merge_flag = int_to_mergetype(dict->lookup_int(conf_key_merge_flag, + default_dictionary_error_out, + default_dictionary_print_warning, + false)); + string merge_name = mergetype_to_string(merge_flag); + if (dict->lookup(conf_key_merge_thresh, false)) { + // the individual entry also has a merge_thresh, this is good + merge_thresh_array = dict->lookup_thresh_array(conf_key_merge_thresh, + default_dictionary_error_out, + default_dictionary_print_warning, + false); + } else { + // get the parent's merge_thresh, just to have something. Error out if the merge_flag is not none + // because that is inconsistent + merge_thresh_array = dict->lookup_thresh_array(conf_key_merge_thresh); + + if (merge_flag != MergeType_None) { + mlog << Error << "\nMode_Field_Info::set() -> " + << "Field:" << name << ". " + << " When 'merge_flag' is explicitly set, 'merge_thresh' must be explicitly set for multivariate mode\n\n"; + exit ( 1 ); + } + + } } else { - mlog << Error << "\nMode_Field_Info::set() -> " - << "'merge_flag' must be explicitly set for all fields with multivariate mode\n\n"; - exit ( 1 ); + // individual entry does not have a merge_flag, try parent + if ( dict->lookup(conf_key_merge_flag, true)) { + // the parent does have a merge flag + merge_flag = int_to_mergetype(dict->lookup_int(conf_key_merge_flag)); + string merge_name = mergetype_to_string(merge_flag); + if (dict->lookup(conf_key_merge_thresh, false)) { + // individual entry has a merge_thresh but no merge_flag, this is not good + mlog << Error << "\nMode_Field_Info::set() -> " + << "Field:" << name << ". " + << "When 'merge_flag' is not explicitly set, 'merge_thresh' cannot explicitly set for multivariate mode\n\n"; + exit ( 1 ); + } else { + // individual entry doesn't have a merge_thresh, parent has a merge_flag + // expect parent to have a merge_thresh + merge_thresh_array = dict->lookup_thresh_array(conf_key_merge_thresh); + if (merge_thresh_array.n() == 0 && merge_flag != MergeType_None) { + // parent has a merge_flag but no merge_thresh + mlog << Error << "\nMode_Field_Info::set() -> " + << "Field:" << name << ". using parent merge_flag: " << merge_name + << " Parent has no 'merge_thresh', not allowed in multivariate mode\n\n"; + exit ( 1 ); + } else { + string thresh_str = merge_thresh_array.thresh()->get_str(); + mlog << Debug(2) << "Field:" << name << ". Using parent merge_flag: " + << merge_name << " and parent merge_thresh:" << thresh_str + << "\n"; + } + } + } } } else { if ( dict->lookup(conf_key_merge_flag, true)) { merge_flag = int_to_mergetype(dict->lookup_int(conf_key_merge_flag)); } + merge_thresh_array = dict->lookup_thresh_array(conf_key_merge_thresh); } filter_attr_map = parse_conf_filter_attr_map(dict); diff --git a/src/libcode/vx_shapedata/shapedata.cc b/src/libcode/vx_shapedata/shapedata.cc index 9051d00819..909eaf5598 100644 --- a/src/libcode/vx_shapedata/shapedata.cc +++ b/src/libcode/vx_shapedata/shapedata.cc @@ -15,8 +15,9 @@ // // Mod# Date Name Description // ---- ---- ---- ----------- -// 000 11-05-31 Halley Gotway Adapated from wrfdata.cc. -// 001 14-05-29 Halley Gotway Add ShapeData::n_objects() +// 000 05/31/11 Halley Gotway Adapated from wrfdata.cc +// 001 05/29/14 Halley Gotway Add ShapeData::n_objects() +// 002 11/02/23 Halley Gotway MET #2724 add OpenMP to convolution // /////////////////////////////////////////////////////////////////////////////// @@ -93,11 +94,11 @@ ShapeData::ShapeData(const ShapeData &f) { ShapeData & ShapeData::operator=(const ShapeData &f) { - if ( this == &f ) return ( *this ); + if ( this == &f ) return *this; assign(f); - return(*this); + return *this; } /////////////////////////////////////////////////////////////////////////////// @@ -132,13 +133,11 @@ int ShapeData::x_left(int y) const { exit(1); } - int x; - - for(x=0; x=0; x--) { - if(f_is_on(x, y)) return(x); + for(int x=(data.nx() - 1); x>=0; x--) { + if(f_is_on(x, y)) return x; } - return(-1); + return -1; } /////////////////////////////////////////////////////////////////////////////// @@ -169,12 +166,12 @@ bool ShapeData::s_is_on(int x, int y, bool error_out) const // Unless error out is true, return bad status for being off the grid if(!error_out) { - if(x < 0 || x >= data.nx() || y < 0 || y >= data.ny()) return ( false ); + if(x < 0 || x >= data.nx() || y < 0 || y >= data.ny()) return false; } // Check if the current point is non-zero - return ( data(x, y) > 0.0 ); + return data(x, y) > 0.0; } @@ -187,12 +184,12 @@ bool ShapeData::f_is_on(int x, int y) const // Check if the current point or any of of it's neighbors are non-zero - if(s_is_on(x, y)) return ( true ); - if((x > 0) && s_is_on(x-1, y)) return ( true ); - if((x > 0) && (y > 0) && s_is_on(x-1, y-1)) return ( true ); - if((y > 0) && s_is_on(x, y-1)) return ( true ); + if(s_is_on(x, y)) return true; + if((x > 0) && s_is_on(x-1, y)) return true; + if((x > 0) && (y > 0) && s_is_on(x-1, y-1)) return true; + if((y > 0) && s_is_on(x, y-1)) return true; - return(false); + return false; } /////////////////////////////////////////////////////////////////////////////// @@ -201,16 +198,15 @@ void ShapeData::calc_moments() { - int x, y; double xx, yy; mom.clear(); - for(x=0; x 0 && obj_thresh.check(raw_ptr->data.data()[i])) cur_area++; } - return(cur_area); + return cur_area; } /////////////////////////////////////////////////////////////////////////////// void ShapeData::calc_length_width(double &l, double &w) const { - int x, y; double xx, yy; double u, v, u_max, u_min, v_max, v_min; double u_extent, v_extent; @@ -308,8 +303,8 @@ void ShapeData::calc_length_width(double &l, double &w) const { u_max = v_max = -1.0e30; u_min = v_min = 1.0e30; - for (x=0; x 102) { @@ -406,7 +402,7 @@ double ShapeData::intensity_percentile(const ShapeData *raw_ptr, int perc, val = new double [Nxy]; // Compute the requested percentile of intensity - for(i=0, n=0, val_sum=0.0; i 0) { @@ -438,9 +434,9 @@ double ShapeData::intensity_percentile(const ShapeData *raw_ptr, int perc, } // Clean up - if(val) { delete [] val; val = (double *) 0; }; + if(val) { delete [] val; val = (double *) nullptr; }; - return(v); + return v; } //////////////////////////////////////////////////////////////////////// @@ -508,165 +504,122 @@ double ShapeData::get_attr(const ConcatString &attr_name, attr_val = bad_data_double; } - return(attr_val); + return attr_val; } /////////////////////////////////////////////////////////////////////////////// +void ShapeData::conv_filter_circ(int diameter, double vld_thresh) { + const char *method_name = "ShapeData::conv_filter_circ() -> "; + GridPoint *gp = nullptr; + int x, y, count, n_vld; + double v, v_sum; + DataPlane conv_dp; -void ShapeData::conv_filter_circ(int diameter, double vld_thresh) - -{ - -int x, y, xx, yy, u, v; -int dn, fn, nn; -int vpr, upr; -int count, bd_count; -double center, cur, sum; -double dx, dy, dist; -double vld_ratio; -const int nx = data.nx(); -const int ny = data.ny(); -bool * f = (bool *) 0; -bool center_bad = false; -DataPlane in_data = data; -const bool vld_thresh_one = is_eq(vld_thresh, 1.0); - - -if ( (diameter%2 == 0) || (diameter < 3) ) { - - mlog << Error << "\nShapeData::conv_filter_circ() -> " - << "diameter must be odd and >= 3 ... diameter = " - << diameter << "\n\n"; - - exit(1); - -} - -const int radius = (diameter - 1)/2; - -const vector * in = &(in_data.Data); - vector * out = &(data.Data); - -f = new bool [diameter*diameter]; - - // - // set up the filter - // - -for (y=0; y= 3 ... diameter = " + << diameter << "\n\n"; + exit(1); } -} - - // - // do the convolution - // - -dn = -1; - -for(y=0; y= ny) ) continue; - - vpr = v + radius; - - for(u=-radius; u<=radius; ++u) { - - xx = x + u; - - if ( (xx < 0) || (xx >= nx) ) continue; - - upr = u + radius; - - fn = STANDARD_XY_YO_N(diameter, upr, vpr); - - if ( !(f[fn]) ) continue; - - nn = STANDARD_XY_YO_N(nx, xx, yy) ; - - cur = (*in)[nn]; - - if( ::is_bad_data(cur) ) { bd_count++; continue; } - - sum += cur; - - count++; - - } // for v - - } // for u - - // - // If the center of the convolution contains bad data and the ratio - // of bad data in the convolution area is too high, set the convoled - // value to bad data. - // - - if ( count == 0 ) sum = bad_data_double; - else { - - vld_ratio = ((double) count)/(bd_count + count); +#pragma omp parallel default(none) \ + shared(mlog, data, conv_dp, diameter, vld_thresh) \ + private(x, y, count, n_vld, v, v_sum, gp) + { + + // Build the grid template with shape circle and wrap_lon false + GridTemplateFactory gtf; + GridTemplate* gt = gtf.buildGT(GridTemplateFactory::GridTemplate_Circle, + diameter, false); + +#pragma omp single + { + // Initialize the convolved field to bad data + conv_dp = data; + conv_dp.set_constant(bad_data_double); + } - if ( center_bad && (vld_ratio < vld_thresh) ) sum = bad_data_double; - else sum /= count; + // Compute the convolved values +#pragma omp for schedule (static) + for(int x=0; xgetFirstInGrid(x, y, data.nx(), data.ny()); + gp != nullptr; + gp = gt->getNextInGrid()) { + v = data.get(gp->x, gp->y); + count += 1; + if(::is_bad_data(v)) continue; + n_vld += 1; + v_sum += v; + } + } + // Subtract off the bottom edge, shift up, and add the top + else { + + // Subtract points from the the bottom edge + for(gp = gt->getFirstInBotEdge(); + gp != nullptr; + gp = gt->getNextInBotEdge()) { + v = data.get(gp->x, gp->y); + count -= 1; + if(::is_bad_data(v)) continue; + n_vld -= 1; + v_sum -= v; + } + + // Increment Y + gt->incBaseY(1); + + // Add points from the the top edge + for(gp = gt->getFirstInTopEdge(); + gp != nullptr; + gp = gt->getNextInTopEdge()) { + v = data.get(gp->x, gp->y); + count += 1; + if(::is_bad_data(v)) continue; + n_vld += 1; + v_sum += v; + } + } - } + // If the center of the convolution contains bad data and the ratio + // of bad data in the convolution area is too high, set the convoled + // value to bad data. + if(count == 0 || n_vld == 0) v = bad_data_double; + else if(::is_bad_data(data.get(x, y)) && + (double)(n_vld)/count < vld_thresh) v = bad_data_double; + else v = (double) v_sum/n_vld; + conv_dp.set(v, x, y); - (*out)[dn] = sum; + } // end for y - } // for y + // Increment X + if(x < (data.nx() - 1)) gt->incBaseX(1); -} // for x + } // end for x - // - // done - // + delete gt; -if ( f ) { delete [] f; f = (bool *) 0; } + } // End of omp parallel -return; + // Save the result + data = conv_dp; + return; } - //////////////////////////////////////////////////////////////////////// @@ -674,7 +627,7 @@ Polyline ShapeData::convex_hull_new() const { -int j, k, y; +int j, k; int n_in, n_out; Polyline hull_poly; IntPoint * in = new IntPoint [2*(data.ny() + 1)]; @@ -682,7 +635,7 @@ IntPoint * in = new IntPoint [2*(data.ny() + 1)]; n_in = 0; -for (y=0; y<(data.ny()); ++y) { +for (int y=0; y<(data.ny()); ++y) { j = x_left(y); @@ -727,10 +680,10 @@ for (j=0; j " << "no points found in object\n\n"; - return(boundary); + return boundary; } // @@ -1095,7 +1048,7 @@ Polyline ShapeData::single_boundary_offset(bool all_points, int clockwise, } } - return(boundary); + return boundary; } /////////////////////////////////////////////////////////////////////////////// @@ -1196,15 +1149,15 @@ if ( (nx_new <= 0) || (ny_new <= 0) ) { } -int x_old, y_old, x_new, y_new; +int x_old, y_old; DataPlane old = data; -for (x_new=0; x_newhas(k) ) return ( true ); + if ( c[j]->has(k) ) return true; } -return ( false ); +return false; } @@ -1601,15 +1539,13 @@ int Partition::which_cell(int k) const { -int j; - -for (j=0; jhas(k) ) return ( j ); + if ( c[j]->has(k) ) return j; } -return ( -1 ); +return -1; } @@ -1619,7 +1555,7 @@ void Partition::merge_cells(int j_1, int j_2) { -int k, nn; +int nn; int j_min, j_max; @@ -1651,7 +1587,7 @@ if ( j_1 < j_2 ) { nn = c[j_max]->n; -for (k=0; kadd(c[j_max]->e[k]); @@ -1745,7 +1681,7 @@ double d; d = x_1*x_2 + y_1*y_2; -return ( d ); +return d; } @@ -1849,31 +1785,31 @@ int get_step_case(bool lr, bool ur, bool ul, bool ll) { // // Lower Left - if(!lr && !ur && !ul && ll) return(ll_case); + if(!lr && !ur && !ul && ll) return ll_case; // Lower Right - else if(lr && !ur && !ul && !ll) return(lr_case); + else if(lr && !ur && !ul && !ll) return lr_case; // // Valid cases with exactly two cells on // // Upper Left, Lower Left - else if(!lr && !ur && ul && ll) return(ul_ll_case); + else if(!lr && !ur && ul && ll) return ul_ll_case; // Lower Right, Upper Right - else if(lr && ur && !ul && !ll) return(lr_ur_case); + else if(lr && ur && !ul && !ll) return lr_ur_case; // Lower Right, Upper Left - else if(lr && !ur && ul && !ll) return(lr_ul_case); + else if(lr && !ur && ul && !ll) return lr_ul_case; // Upper Right, Lower Left - else if(!lr && ur && !ul && ll) return(ur_ll_case); + else if(!lr && ur && !ul && ll) return ur_ll_case; // // Valid cases with exactly three cells on // // Upper Right, Upper Left, Lower Left - else if(!lr && ur && ul && ll) return(ur_ul_ll_case); + else if(!lr && ur && ul && ll) return ur_ul_ll_case; // Lower Right, Upper Right, Upper Left - else if(lr && ur && ul && !ll) return(lr_ur_ul_case); + else if(lr && ur && ul && !ll) return lr_ur_ul_case; // // Otherwise, combination is invalid @@ -1892,7 +1828,6 @@ int get_step_case(bool lr, bool ur, bool ul, bool ll) { void apply_mask(ShapeData &f, ShapeData &mask) { - int x, y; if(f.data.nx() != mask.data.nx() || f.data.ny() != mask.data.ny() ) { @@ -1902,8 +1837,8 @@ void apply_mask(ShapeData &f, ShapeData &mask) exit(1); } - for(x=0; x &attr_map, // Select the current object sd_object = select(sd_split, i); + keep_object[i] = true; // Loop over attribute filter map for(it=attr_map.begin(); it!= attr_map.end(); it++) { @@ -2042,7 +1978,7 @@ void ShapeData::threshold_attr(const map &attr_map, } // Clean up - if(keep_object) { delete [] keep_object; keep_object = (bool *) 0; } + if(keep_object) { delete [] keep_object; keep_object = (bool *) nullptr; } return; } @@ -2091,7 +2027,7 @@ void ShapeData::threshold_area(SingleThresh t) } // end for y } // end for x - if ( area_object ) { delete [] area_object; area_object = (double *) 0; } + if ( area_object ) { delete [] area_object; area_object = (double *) nullptr; } return; } @@ -2105,7 +2041,8 @@ void ShapeData::threshold_intensity(const ShapeData *sd_ptr, int perc, SingleThr { int i, n, x, y, v_int, n_obj_inten; ShapeData s; - double * obj_inten = (double *) 0, obj_inten_sum; + double *obj_inten = (double *) nullptr; + double obj_inten_sum; const int nx = data.nx(); const int ny = data.ny(); @@ -2184,9 +2121,9 @@ void ShapeData::threshold_intensity(const ShapeData *sd_ptr, int perc, SingleThr } // end for y } // end for x - if(obj_inten) { delete [] obj_inten; obj_inten = (double *) 0; } + if(obj_inten) { delete [] obj_inten; obj_inten = (double *) nullptr; } -if ( inten_object ) { delete [] inten_object; inten_object = (double *) 0; } + if ( inten_object ) { delete [] inten_object; inten_object = (double *) nullptr; } return; } @@ -2380,7 +2317,7 @@ out.calc_moments(); // done // -return ( out ); +return out; } @@ -2390,7 +2327,7 @@ return ( out ); ShapeData select(const ShapeData &id, int n) { - int k, x, y; + int k; int nx, ny; int count; ShapeData d = id; @@ -2400,8 +2337,8 @@ ShapeData select(const ShapeData &id, int n) count = 0; - for(x=0; x 0) { - double *density_vector; + vector density_vector; double pvf[SEEPS_MATRIX_SIZE]; double weighted_score, weight_sum, weight[count]; @@ -1457,41 +1457,48 @@ void compute_aggregated_seeps(const PairDataPoint *pd, SeepsAggScore *seeps) { seeps->mean_fcst = fcst_sum / count; seeps->mean_obs = obs_sum / count; seeps->score = score_sum / count; - density_vector = compute_seeps_density_vector(pd, seeps); weighted_score = 0.; for (int i=0; i count) density_cnt = count; + + //IDL: w = 1/d + weight_sum = 0.; + for (int i=0; iscore * weight[i]; - //IDL: svf(cat{i)) = svf(cat{i)) + c(4+cat(i) * w{i) - //IDL: pvf(cat{i)) = pvf(cat{i)) + w{i) - pvf[seeps_mpr->s_idx] += weight[i]; - } - else mlog << Debug(1) << method_name - << "the length of density vector (" << count << ") is less than MPR.\n"; + } + if (!is_eq(weight_sum, 0)) { + //IDL: w = w/sum(w) + for (int i=0; iscore * weight[i]; + //IDL: svf(cat{i)) = svf(cat{i)) + c(4+cat(i) * w{i) + //IDL: pvf(cat{i)) = pvf(cat{i)) + w{i) + pvf[seeps_mpr->s_idx] += weight[i]; + } + else { + mlog << Debug(1) << method_name + << "the length of density vector (" << density_cnt + << ") is less than SEEPS MPR (" << seeps_mprs.size() << ").\n"; + break; } } - - if (density_vector != nullptr) delete [] density_vector; } + + density_vector.clear(); + seeps_mprs.clear(); // The weight for s12 to s32 should come from climo file, but not available yet @@ -1707,7 +1714,7 @@ void compute_aggregated_seeps_grid(const DataPlane &fcst_dp, const DataPlane &ob // ; PV-WAVE prints: 2.00000 4.00000 //////////////////////////////////////////////////////////////////////// -double *compute_seeps_density_vector(const PairDataPoint *pd, SeepsAggScore *seeps) { +void compute_seeps_density_vector(const PairDataPoint *pd, SeepsAggScore *seeps, vector &density_vector) { int seeps_idx; SeepsScore *seeps_mpr; int seeps_cnt = seeps->n_obs; @@ -1725,12 +1732,11 @@ double *compute_seeps_density_vector(const PairDataPoint *pd, SeepsAggScore *see if (seeps_cnt == 0) { mlog << Debug(1) << method_name << "no SEEPS_MPR available.\n"; - return nullptr; + return; } // Get lat/lon & convert them to radian and get sin/cos values seeps_idx = 0; - double *density_vector = new double[seeps_cnt]; for(int i=0; in_obs; i++) { if (i >= pd->seeps_mpr.size()) break; seeps_mpr = pd->seeps_mpr[i]; @@ -1752,10 +1758,9 @@ double *compute_seeps_density_vector(const PairDataPoint *pd, SeepsAggScore *see // Initialize v_count = 0; if (seeps_idx < seeps_cnt) seeps_cnt = seeps_idx; - for(int i=0; i &density_vector); //////////////////////////////////////////////////////////////////////// // diff --git a/src/tools/core/ensemble_stat/ensemble_stat.cc b/src/tools/core/ensemble_stat/ensemble_stat.cc index 62885a5f5e..b778e97f2f 100644 --- a/src/tools/core/ensemble_stat/ensemble_stat.cc +++ b/src/tools/core/ensemble_stat/ensemble_stat.cc @@ -99,8 +99,6 @@ using namespace netCDF; #include "nc_obs_util.h" #include "nc_point_obs_in.h" -#include "handle_openmp.h" - #ifdef WITH_PYTHON #include "data2d_nc_met.h" #include "pointdata_python.h" @@ -177,9 +175,6 @@ static void set_compress(const StringArray &); int met_main(int argc, char *argv[]) { - // Set up OpenMP (if enabled) - init_openmp(); - // Process the command line arguments process_command_line(argc, argv); diff --git a/src/tools/core/mode/mode.cc b/src/tools/core/mode/mode.cc index 079a5db734..a9277a0884 100644 --- a/src/tools/core/mode/mode.cc +++ b/src/tools/core/mode/mode.cc @@ -56,6 +56,7 @@ // 019 04/01/19 Fillmore Add FCST and OBS units. // 020 07/06/22 Howard Soh METplus-Internal #19 Rename main to met_main // 021 06/09/23 Albo Major changes for multivariate mode +// 022 11/02/23 Halley Gotway MET #2724 add OpenMP to convolution // //////////////////////////////////////////////////////////////////////// @@ -73,6 +74,7 @@ using namespace std; #include #include "main.h" +#include "handle_openmp.h" #include "string_array.h" #include "mode_usage.h" #include "mode_frontend.h" @@ -115,6 +117,7 @@ const char * const program_name = "mode"; static const char default_config_filename [] = "MET_BASE/config/MODEConfig_default"; +static const char default_multivar_config_filename [] = "MET_BASE/config/MODEMultivarConfig_default"; /////////////////////////////////////////////////////////////////////// @@ -130,6 +133,9 @@ int met_main(int argc, char * argv []) string s; const char * user_config_filename = 0; + // Set up OpenMP (if enabled) + init_openmp(); + for (j=0,n=0; jinit(n_files); + mode_exec->init(n_files, ptype != SINGLE_VAR); ModeConfInfo & conf = mode_exec->engine.conf_info; if ( field_index >= 0 ) conf.set_field_index(field_index); diff --git a/src/tools/core/mode/multivar_frontend.cc b/src/tools/core/mode/multivar_frontend.cc index 087311dd67..c19a3ad0b0 100644 --- a/src/tools/core/mode/multivar_frontend.cc +++ b/src/tools/core/mode/multivar_frontend.cc @@ -10,7 +10,8 @@ //////////////////////////////////////////////////////////////////////// -static const char mode_default_config [] = "MET_BASE/config/MODEConfig_default"; +// for multivar mode, this is the default file +static const char mode_default_config [] = "MET_BASE/config/MODEMultivarConfig_default"; static const int dir_creation_mode = 0755; @@ -68,6 +69,8 @@ static const char tab [] = " "; static const bool do_clusters = false; +static string default_out_dir = "."; + static ModeConfInfo config; static string mode_path; @@ -394,6 +397,12 @@ void process_command_line(const StringArray & argv) CommandLine cline; + // + // Set the default output directory + // + + outdir = replace_path(default_out_dir); + mode_path = argv[0]; cline.set(argv); @@ -671,9 +680,6 @@ void process_superobjects(ShapeData &f_result, ShapeData &o_result, mode_argv.add(junk); mode_argv.add("-outdir"); mode_argv.add(dir); - // mode_argv.add("-field_index"); - // snprintf(junk, sizeof(junk), "%d", j); - // mode_argv.add(junk); mlog << Debug(1) << "Running superobject mode \n\n"; diff --git a/src/tools/core/pcp_combine/pcp_combine.cc b/src/tools/core/pcp_combine/pcp_combine.cc index 0efcb42ac9..afc7e9a09b 100644 --- a/src/tools/core/pcp_combine/pcp_combine.cc +++ b/src/tools/core/pcp_combine/pcp_combine.cc @@ -80,8 +80,6 @@ // //////////////////////////////////////////////////////////////////////// -using namespace std; - #include #include #include @@ -94,7 +92,6 @@ using namespace std; #include #include -using namespace netCDF; #include "main.h" #include "vx_log.h" @@ -107,6 +104,9 @@ using namespace netCDF; #include "vx_cal.h" #include "vx_math.h" +using namespace std; +using namespace netCDF; + //////////////////////////////////////////////////////////////////////// static ConcatString program_name; @@ -133,7 +133,7 @@ static StringArray req_out_var_name; static int i_out_var = 0; static int n_out_var; static MetConfig config; -static VarInfo * var_info = (VarInfo *) 0; +static VarInfo * var_info = (VarInfo *) nullptr; static double vld_thresh = 1.0; static int compress_level = -1; @@ -151,7 +151,7 @@ static StringArray field_list; static StringArray derive_list; // Output NetCDF file -NcFile *nc_out = (NcFile *) 0; +NcFile *nc_out = (NcFile *) nullptr; NcDim lat_dim; NcDim lon_dim; @@ -217,7 +217,7 @@ int met_main(int argc, char *argv[]) { // Reinitialize for the current loop. // field_string = req_field_list[i]; - if(var_info) { delete var_info; var_info = (VarInfo *) 0; } + if(var_info) { delete var_info; var_info = (VarInfo *) nullptr; } // // Reset when reading multiple fields from the same input files. @@ -241,7 +241,7 @@ int met_main(int argc, char *argv[]) { // close_nc(); - return(0); + return 0; } //////////////////////////////////////////////////////////////////////// @@ -561,9 +561,9 @@ void sum_data_files(Grid & grid, DataPlane & plane) { DataPlane part; double v_sum, v_part; Grid cur_grid; - unixtime * pcp_times = (unixtime *) 0; - int * pcp_recs = (int *) 0; - ConcatString * pcp_files = (ConcatString *) 0; + unixtime * pcp_times = (unixtime *) nullptr; + int * pcp_recs = (int *) nullptr; + ConcatString * pcp_files = (ConcatString *) nullptr; // // Compute the number of forecast precipitation files to be found, @@ -586,6 +586,8 @@ void sum_data_files(Grid & grid, DataPlane & plane) { // for(i=0; id_name; Met2dDataFileFactory factory; - Met2dDataFile * mtddf = (Met2dDataFile *) 0; + Met2dDataFile * mtddf = (Met2dDataFile *) nullptr; VarInfoFactory var_fac; - VarInfo * cur_var = (VarInfo *) 0; + VarInfo * cur_var = (VarInfo *) nullptr; // // Create a data file object. @@ -767,7 +769,7 @@ int search_pcp_dir(const char *cur_dir, const unixtime cur_ut, // cur_var = var_fac.new_var_info(mtddf->file_type()); if(!cur_var) { - delete mtddf; mtddf = 0; + delete mtddf; mtddf = nullptr; mlog << Warning << "search_pcp_dir() -> " << "unable to determine filetype of \"" << cur_file << "\"\n"; @@ -796,8 +798,8 @@ int search_pcp_dir(const char *cur_dir, const unixtime cur_ut, // // Cleanup. // - if(mtddf) { delete mtddf; mtddf = (Met2dDataFile *) 0; } - if(cur_var) { delete cur_var; cur_var = (VarInfo *) 0; } + if(mtddf) { delete mtddf; mtddf = (Met2dDataFile *) nullptr; } + if(cur_var) { delete cur_var; cur_var = (VarInfo *) nullptr; } // check for a valid match if( -1 != i_rec ) { met_closedir(dp); break; } @@ -1168,7 +1170,7 @@ void get_field(const char *filename, const char *cur_field, const unixtime get_init_ut, const unixtime get_valid_ut, Grid & grid, DataPlane & plane) { Met2dDataFileFactory factory; - Met2dDataFile *mtddf = (Met2dDataFile *) 0; + Met2dDataFile *mtddf = (Met2dDataFile *) nullptr; GrdFileType ftype; VarInfoFactory var_fac; VarInfo *cur_var; @@ -1244,10 +1246,10 @@ void get_field(const char *filename, const char *cur_field, // // Cleanup. // - if(mtddf) { delete mtddf; mtddf = (Met2dDataFile *) 0; } - if(cur_var) { delete cur_var; cur_var = (VarInfo *) 0; } + if(mtddf) { delete mtddf; mtddf = (Met2dDataFile *) nullptr; } + if(cur_var) { delete cur_var; cur_var = (VarInfo *) nullptr; } - // if ( var ) { delete var; var = 0; } + // if ( var ) { delete var; var = nullptr; } return; @@ -1270,7 +1272,7 @@ void open_nc(const Grid &grid) { << "trouble opening output file " << out_filename << "\n\n"; delete nc_out; - nc_out = (NcFile *) 0; + nc_out = (NcFile *) nullptr; exit(1); } @@ -1452,8 +1454,8 @@ void close_nc() { // // Clean up. // - if(nc_out) { delete nc_out; nc_out = (NcFile *) 0; } - if(var_info ) { delete var_info; var_info = (VarInfo *) 0; } + if(nc_out) { delete nc_out; nc_out = (NcFile *) nullptr; } + if(var_info ) { delete var_info; var_info = (VarInfo *) nullptr; } return; } diff --git a/src/tools/other/mode_time_domain/3d_conv.cc b/src/tools/other/mode_time_domain/3d_conv.cc index 0dd0172f22..5baec68a82 100644 --- a/src/tools/other/mode_time_domain/3d_conv.cc +++ b/src/tools/other/mode_time_domain/3d_conv.cc @@ -18,8 +18,6 @@ static const bool do_ppms = false; //////////////////////////////////////////////////////////////////////// -using namespace std; - #include #include #include @@ -29,7 +27,6 @@ using namespace std; #include #include -using namespace netCDF; #include "vx_cal.h" #include "vx_util.h" @@ -38,14 +35,17 @@ using namespace netCDF; #include "mtd_file.h" #include "mtd_nc_defs.h" +using namespace std; +using namespace netCDF; + //////////////////////////////////////////////////////////////////////// static int spatial_conv_radius = -1; -static double * sum_plane_buf = 0; -static bool * ok_sum_plane_buf = 0; +static double * sum_plane_buf = nullptr; +static bool * ok_sum_plane_buf = nullptr; //////////////////////////////////////////////////////////////////////// @@ -66,11 +66,11 @@ struct DataHandle { { - int j, k; + int k; k = 0; - for (j=0; j0) { + value /= n_good; - value *= scale; + value *= scale; - if ( value < min_conv_value ) min_conv_value = value; - if ( value > max_conv_value ) max_conv_value = value; + if ( value < min_conv_value ) min_conv_value = value; + if ( value > max_conv_value ) max_conv_value = value; + } } @@ -429,10 +434,10 @@ for (x=0; x ActualValidTimes; // useful for uneven time increments + std::vector ActualValidTimes; // useful for uneven time increments IntArray Lead_Times; @@ -117,7 +117,7 @@ class MtdFileBase { void set_delta_t (int); // seconds - void init_actual_valid_times(const vector &validTimes); + void init_actual_valid_times(const std::vector &validTimes); void set_lead_time(int index, int value); diff --git a/src/tools/other/mode_time_domain/mtd_file_float.cc b/src/tools/other/mode_time_domain/mtd_file_float.cc index f0c70f509f..3ac18561df 100644 --- a/src/tools/other/mode_time_domain/mtd_file_float.cc +++ b/src/tools/other/mode_time_domain/mtd_file_float.cc @@ -101,7 +101,7 @@ void MtdFloatFile::float_init_from_scratch() { -Data = 0; +Data = nullptr; clear(); @@ -119,7 +119,7 @@ void MtdFloatFile::clear() MtdFileBase::clear(); -if ( Data ) { delete [] Data; Data = 0; } +if ( Data ) { delete [] Data; Data = nullptr; } DataMin = DataMax = 0; @@ -218,7 +218,7 @@ void MtdFloatFile::set_size(int _nx, int _ny, int _nt) { -if ( Data ) { delete [] Data; Data = 0; } +if ( Data ) { delete [] Data; Data = nullptr; } int j; const int n3 = _nx*_ny*_nt; @@ -939,14 +939,14 @@ out.set_accum(0); int x, y, n; double value; +const int data_cnt = Nx*Ny*Nt; for (x=0; x= 0 && n = Nt) ) { - mlog << Error << "\n\n MtdFloatFile::put_data_plane() -> range check error on t\n\n"; + mlog << Error << "\n\n " << method_name << "range check error on t\n\n"; exit ( 1 ); @@ -985,7 +985,7 @@ if ( (t < 0) || (t >= Nt) ) { if ( (d.nx() != Nx) || (d.ny() != Ny) ) { - mlog << Error << "\n\n MtdFloatFile::put_data_plane() -> data plane is wrong size!\n\n"; + mlog << Error << "\n\n " << method_name << "data plane is wrong size!\n\n"; exit ( 1 ); @@ -993,6 +993,7 @@ if ( (d.nx() != Nx) || (d.ny() != Ny) ) { int x, y, n; double value; +const int data_cnt = Nx*Ny*Nt; for (x=0; x=data_cnt) { + mlog << Debug(4) << method_name << "offset " << n + << " is out of range (" << " from " << x << ", " << y <<", " << t <<")\n"; + continue; + } value = d(x, y); @@ -1011,18 +1017,6 @@ for (x=0; x, - map, map &); +static int combine_tqz_and_uv(map, map, + vector &); static float compute_pbl(map pqtzuv_map_tq, map pqtzuv_map_uv); static void copy_pqtzuv(float *to_pqtzuv, float *from_pqtzuv, bool copy_all=true); @@ -2959,14 +2959,16 @@ void copy_pqtzuv(float *to_pqtzuv, float *from_pqtzuv, bool copy_all) { //////////////////////////////////////////////////////////////////////// int combine_tqz_and_uv(map pqtzuv_map_tq, - map pqtzuv_map_uv, map &pqtzuv_map_merged) { + map pqtzuv_map_uv, vector &pqtzuv_merged_array) { static const char *method_name = "combine_tqz_and_uv() "; int tq_count = pqtzuv_map_tq.size(); int uv_count = pqtzuv_map_uv.size(); + map pqtzuv_map_merged; + pqtzuv_merged_array.clear(); if (tq_count > 0 && uv_count > 0) { IntArray common_levels, tq_levels; float *pqtzuv_tq, *pqtzuv_uv; - float *pqtzuv_merged = (float *) 0; + float *pqtzuv_merged = (float *) nullptr; float *next_pqtzuv, *prev_pqtzuv; float tq_pres_max, tq_pres_min, uv_pres_max, uv_pres_min; map::iterator it, it_tq, it_uv; @@ -3055,9 +3057,10 @@ int combine_tqz_and_uv(map pqtzuv_map_tq, } interpolate_pqtzuv(prev_pqtzuv, pqtzuv_merged, next_pqtzuv); } - float first_pres = (pqtzuv_merged[0] == 0 ? bad_data_float : pqtzuv_merged[0]); + float first_pres = (pqtzuv_merged[0] < 0 || is_eq(pqtzuv_merged[0], 0.) + ? bad_data_float : pqtzuv_merged[0]); pqtzuv_map_merged[first_pres] = pqtzuv_merged; - mlog << Debug(9) << method_name << "Added " << first_pres << " to merged records\n"; + mlog << Debug(9) << method_name << "Added " << first_pres << " to merged records (first record)\n"; if (pqtzuv_merged != 0) { //Merge UV into TQZ records @@ -3065,6 +3068,12 @@ int combine_tqz_and_uv(map pqtzuv_map_tq, //Merge TQZ into UV records merge_records(pqtzuv_merged, pqtzuv_map_uv, pqtzuv_map_tq, pqtzuv_map_merged); } + for (map::iterator it=pqtzuv_map_merged.begin(); + it!=pqtzuv_map_merged.end(); ++it) { + float *new_pqtzuv = new float[mxr8vt]; + for (int i=0; isecond[i]; + pqtzuv_merged_array.push_back(new_pqtzuv); + } if(mlog.verbosity_level() >= PBL_DEBUG_LEVEL) { log_merged_tqz_uv(pqtzuv_map_tq, pqtzuv_map_uv, pqtzuv_map_merged, method_name); @@ -3072,7 +3081,7 @@ int combine_tqz_and_uv(map pqtzuv_map_tq, delete [] pqtzuv_merged; } - return pqtzuv_map_merged.size(); + return pqtzuv_merged_array.size(); } //////////////////////////////////////////////////////////////////////// @@ -3093,12 +3102,13 @@ float compute_pbl(map pqtzuv_map_tq, mlog << Debug(7) << method_name << "is called: TQZ: " << tq_count << " UV: " << uv_count << "\n"; if (tq_count > 0 || uv_count > 0) { + float *pqtzuv = nullptr; int hgt_cnt, spfh_cnt; IntArray selected_levels; - map pqtzuv_map_merged; + vector pqtzuv_merged_array; pbl_level = combine_tqz_and_uv(pqtzuv_map_tq, pqtzuv_map_uv, - pqtzuv_map_merged); + pqtzuv_merged_array); mlog << Debug(7) << method_name << "pbl_level= " << pbl_level << " from TQ (" << tq_count << ") and UV (" << uv_count << ")\n"; @@ -3112,60 +3122,62 @@ float compute_pbl(map pqtzuv_map_tq, << "Skip CALPBL because of only one available record after combining TQZ and UV\n"; } else { - // Order all observations by pressure from bottom to top - index = pbl_level - 1; + // Reverse the order all observations by pressure from bottom to top + index = 0; hgt_cnt = spfh_cnt = 0; - for (it=pqtzuv_map_merged.begin(); it!=pqtzuv_map_merged.end(); ++it) { - if (index < 0) { - mlog << Error << "\n" << method_name << "negative index: " << index << "\n\n"; - break; - } - - if (index < MAX_PBL_LEVEL) { - float *pqtzuv = it->second; - pbl_data_pres[index] = pqtzuv[0]; - pbl_data_spfh[index] = pqtzuv[1]; - pbl_data_temp[index] = pqtzuv[2]; - pbl_data_hgt[index] = pqtzuv[3]; - pbl_data_ugrd[index] = pqtzuv[4]; - pbl_data_vgrd[index] = pqtzuv[5]; - if (is_valid_pb_data(pbl_data_spfh[index])) spfh_cnt++; - if (is_valid_pb_data(pbl_data_hgt[index])) hgt_cnt++; - selected_levels.add(nint(it->first)); - } - - index--; - } - if (index != -1) { - mlog << Error << "\n" << method_name << "Missing some levels (" << index << ")\n"; - } - - if (pbl_level > MAX_PBL_LEVEL) { - it = pqtzuv_map_tq.begin(); + int start_offset = (MAX_PBL_LEVEL >= pbl_level) ? 0 : (pbl_level-MAX_PBL_LEVEL); + for (int i=(pbl_level-1); i>=start_offset; i--,index++) { + pqtzuv = pqtzuv_merged_array[i]; + pbl_data_pres[index] = pqtzuv[0]; + pbl_data_pres[index] = pqtzuv[0]; + pbl_data_spfh[index] = pqtzuv[1]; + pbl_data_temp[index] = pqtzuv[2]; + pbl_data_hgt[index] = pqtzuv[3]; + pbl_data_ugrd[index] = pqtzuv[4]; + pbl_data_vgrd[index] = pqtzuv[5]; + if (is_valid_pb_data(pbl_data_spfh[index])) spfh_cnt++; + if (is_valid_pb_data(pbl_data_hgt[index])) hgt_cnt++; + selected_levels.add(nint(pqtzuv[0])); + } + if (start_offset > 0) { + // Replace the interpolated records with common records. + mlog << Error << "\n" << method_name << "Excluded " << start_offset << " records\n"; // Find vertical levels with both data float highest_pressure = bad_data_float; - for (; it!=pqtzuv_map_tq.end(); ++it) { + for (it = pqtzuv_map_tq.begin(); it!=pqtzuv_map_tq.end(); ++it) { if (pqtzuv_map_uv.count(it->first) > 0) { highest_pressure = it->first; break; } } if (!is_bad_data(highest_pressure)) { + bool found; + int vector_idx = start_offset - 1; index = MAX_PBL_LEVEL - 1; for (; it!=pqtzuv_map_tq.end(); ++it) { int pres_level = nint(it->first); + // Stop replacing if already exists at input list if (selected_levels.has(pres_level)) break; - float *pqtzuv = pqtzuv_map_merged[it->first]; - pbl_data_pres[index] = pqtzuv[0]; - pbl_data_spfh[index] = pqtzuv[1]; - pbl_data_temp[index] = pqtzuv[2]; - pbl_data_hgt[index] = pqtzuv[3]; - pbl_data_ugrd[index] = pqtzuv[4]; - pbl_data_vgrd[index] = pqtzuv[5]; - mlog << Debug(6) << method_name << "Force to add " - << pres_level << " into " << index << "\n"; - index--; + found = false; + for (; vector_idx>=0; vector_idx--) { + if (is_eq(pqtzuv_merged_array[vector_idx][0], it->first)) { + pqtzuv = pqtzuv_merged_array[vector_idx]; + pbl_data_pres[index] = pqtzuv[0]; + pbl_data_spfh[index] = pqtzuv[1]; + pbl_data_temp[index] = pqtzuv[2]; + pbl_data_hgt[index] = pqtzuv[3]; + pbl_data_ugrd[index] = pqtzuv[4]; + pbl_data_vgrd[index] = pqtzuv[5]; + mlog << Debug(6) << method_name << "Force to add " + << pres_level << " into " << index << "\n"; + vector_idx--; + found = true; + break; + } + } + if (vector_idx < 0) break; + if(found) index--; } } } @@ -3205,9 +3217,11 @@ float compute_pbl(map pqtzuv_map_tq, if (!is_valid_pb_data(hpbl)) mlog << Debug(5) << method_name << " fail to compute PBL. TQ records: " << tq_count << " UV records: " << uv_count << " merged records: " - << pqtzuv_map_merged.size() << "\n"; + << pqtzuv_merged_array.size() << "\n"; } } + for (int i=0; i