Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature 1731 docs #1781

Merged
merged 10 commits into from
May 7, 2021
30 changes: 18 additions & 12 deletions met/docs/Users_Guide/data_io.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ Data must often be preprocessed prior to using it for verification. Several MET
Input data formats
__________________

The MET package can handle gridded input data in one of four formats: GRIB version 1, GRIB version 2, NetCDF files following the Climate and Forecast (CF) conventions, and NetCDF files produced by the MET tools themselves. MET supports standard NCEP, USAF, UKMet Office and ECMWF grib tables along with custom, user-defined GRIB tables and the extended PDS including ensemble member metadata. See :numref:`Configuration File Details` for more information. Point observation files may be supplied in either PrepBUFR, ASCII, or MADIS format. Note that MET does not require the Unified Post-Processor to be used, but does require that the input GRIB data be on a standard, de-staggered grid on pressure or regular levels in the vertical. While the Grid-Stat, Wavelet-Stat, MODE, and MTD tools can be run on a gridded field at virtually any level, the Point-Stat tool can only be used to verify forecasts at the surface or on pressure or height levels. MET does not interpolate between native model vertical levels.
The MET package can handle multiple gridded input data formats: GRIB version 1, GRIB version 2, and NetCDF files following the Climate and Forecast (CF) conventions, containing WRF output post-processed using wrf_interp, or produced by the MET tools themselves. MET supports standard NCEP, USAF, UKMet Office and ECMWF GRIB tables along with custom, user-defined GRIB tables and the extended PDS including ensemble member metadata. See :numref:`Configuration File Details` for more information. Point observation files may be supplied in either PrepBUFR, ASCII, or MADIS format. Note that MET does not require the Unified Post-Processor to be used, but does require that the input GRIB data be on a standard, de-staggered grid on pressure or regular levels in the vertical. While the Grid-Stat, Wavelet-Stat, MODE, and MTD tools can be run on a gridded field at virtually any level, the Point-Stat tool can only be used to verify forecasts at the surface or on pressure or height levels. MET does not interpolate between native model vertical levels.

When comparing two gridded fields with the Grid-Stat, Wavelet-Stat, Ensemble-Stat, MODE, MTD, or Series-Analysis tools, the input model and observation datasets must be on the same grid. MET will regrid files according to user specified options. Alternatively, outside of MET, the copygb and wgrib2 utilities are recommended for re-gridding GRIB1 and GRIB2 files, respectively. To preserve characteristics of the observations, it is generally preferred to re-grid the model data to the observation grid, rather than vice versa.

Input point observation files in PrepBUFR format are available through NCEP. The PrepBUFR observation files contain a wide variety of point-based observation types in a single file in a standard format. However, some users may wish to use observations not included in the standard PrepBUFR files. For this reason, prior to performing the verification step in the Point-Stat tool, the PrepBUFR file is reformatted with the PB2NC tool. In this step, the user can select various ways of stratifying the observation data spatially, temporally, and by type. The remaining observations are reformatted into an intermediate NetCDF file. The ASCII2NC tool may be used to convert ASCII point observations that are not available in the PrepBUFR files into this NetCDF format for use by the Point-Stat verification tool. Users with METAR or RAOB data from MADIS can convert these observations into NetCDF format with the MADIS2NC tool, then use them with the Point-Stat or Ensemble-Stat verification tools.
Input point observation files in PrepBUFR format are available through NCEP. The PrepBUFR observation files contain a wide variety of point-based observation types in a single file in a standard format. However, some users may wish to use observations not included in the standard PrepBUFR files. For this reason, prior to performing the verification step in the Point-Stat tool, the PrepBUFR file is reformatted with the PB2NC tool. In this step, the user can select various ways of stratifying the observation data spatially, temporally, and by type. The remaining observations are reformatted into an intermediate NetCDF file. The ASCII2NC tool may be used to convert ASCII point observations that are not available in the PrepBUFR files into this common NetCDF point observation format. Several other MET tools, described below, are also provided to reformat point observations into this common NetCDF point observation format prior to passing them as input to the Point-Stat or Ensemble-Stat verification tools.

Tropical cyclone forecasts and observations are typically provided in a specific ASCII format, in A Deck and B Deck files.
Tropical cyclone forecasts and observations are typically provided in a specific ATCF (Automated Tropical Cyclone Forecasting) ASCII format, in A-deck, B-deck, and E-deck files.

.. _Intermediate data formats:

Expand Down Expand Up @@ -55,32 +55,38 @@ The following is a summary of the input and output formats for each of the tools

#. **PB2NC Tool**

* **Input**: One PrepBUFR point observation file and one configuration file.
* **Input**: PrepBUFR point observation file(s) and one configuration file.

* **Output**: One NetCDF file containing the observations that have been retained.

#. **ASCII2NC Tool**

* **Input**: One or more ASCII point observation file(s) that has (have) been formatted as expected, and optional configuration file.
* **Input**: ASCII point observation file(s) that has (have) been formatted as expected, and optional configuration file.

* **Output**: One NetCDF file containing the reformatted observations.

#. **MADIS2NC Tool**

* **Input**: One MADIS point observation file.
* **Input**: MADIS point observation file(s) in NetCDF format.

* **Output**: One NetCDF file containing the reformatted observations.


#. **LIDAR2NC Tool**

* **Input**: One CALIPSO satellite HDF file
* **Input**: One CALIPSO satellite HDF file.

* **Output**: One NetCDF file containing the reformatted observations.

#. **IODA2NC Tool**

* **Input**: IODA observation file(s) in NetCDF format.

* **Output**: One NetCDF file containing the reformatted observations.

#. **Point2Grid Tool**

* **Input**: One NetCDF file containing point observation from the ASCII2NC, PB2NC, MADIS2NC, or LIDAR2NC tool.
* **Input**: One NetCDF file in the common point observation format.

* **Output**: One NetCDF file containing a gridded representation of the point observations.

Expand Down Expand Up @@ -116,7 +122,7 @@ The following is a summary of the input and output formats for each of the tools

#. **Point-Stat Tool**

* **Input**: One gridded model file, at least one point observation file in NetCDF format (as the output of the PB2NC, ASCII2NC, MADIS2NC, or LIDAR2NC tool), and one configuration file.
* **Input**: One gridded model file, at least one NetCDF file in the common point observation format, and one configuration file.

* **Output**: One STAT file containing all of the requested line types and several ASCII files for each line type requested.

Expand Down Expand Up @@ -194,9 +200,9 @@ The following is a summary of the input and output formats for each of the tools

#. **TC-Pairs Tool**

* **Input**: At least one A-deck and one B-deck ATCF format file containing output from a tropical cyclone tracker and one configuration file. The A-deck files contain forecast tracks while the B-deck files are typically the NHC Best Track Analysis but could also be any ATCF format reference.
* **Input**: At least one A-deck or E-deck file and one B-deck ATCF format file containing output from a tropical cyclone tracker and one configuration file. The A-deck files contain forecast tracks, the E-deck files contain forecast probabilities, and the B-deck files are typically the NHC Best Track Analysis but could also be any ATCF format reference.

* **Output**: ASCII output with the suffix .tcstat.
* **Output**: ASCII output with the suffix .tcst.

#. **TC-Stat Tool**

Expand All @@ -208,7 +214,7 @@ The following is a summary of the input and output formats for each of the tools

* **Input**: One or more Tropical Cyclone genesis format files, one or more verifying operational and BEST track files in ATCF format, and one configuration file.

* **Output**: One STAT file containing all of the requested line types and several ASCII files for each line type requested.
* **Output**: One STAT file containing all of the requested line types, several ASCII files for each line type requested, and one gridded NetCDF file containing counts of track points.

#. **TC-RMW Tool**

Expand Down
4 changes: 3 additions & 1 deletion met/docs/Users_Guide/grid-diag.rst
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,9 @@ _____________________
];
}

The **name** and **level** entries in the **data** dictionary define the data to be processed. The **n_bins** parameter specifies the number of histogram bins for that variable, and the **range** parameter the lower and upper bounds of the histogram. The interval length is the upper and lower difference divided by **n_bins**.
The **name** and **level** entries in the **data** dictionary define the data to be processed. The **n_bins** parameter specifies the number of histogram bins for that variable, and the **range** parameter the lower and upper bounds of the histogram. The interval length is the upper and lower difference divided by **n_bins**. Each bin is inclusive on the left side and exclusive on the right, such as [a,b).

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
~~~~~~~~~~~~~~~~~~~~~
Expand Down
7 changes: 3 additions & 4 deletions met/docs/Users_Guide/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ This User's guide is provided as an aid to users of the Model Evaluation Tools (

It is important to note here that MET is an evolving software package. This documentation describes the |release| release dated |release_date|. Previous releases of MET have occurred each year since 2008. Intermediate releases may include bug fixes. MET is also able to accept new modules contributed by the community. If you have code you would like to contribute, we will gladly consider your contribution. Please send an email to: `met_help@ucar.edu <mailto:>`__. We will then determine the maturity of the new verification method and coordinate the inclusion of the new module in a future version.

This User's Guide was prepared by many current and former developers of MET, including David Ahijevych, Lindsay Blank, Barbara Brown, Randy Bullock, Tatiana Burek, David Fillmore, Tressa Fowler, Eric Gilleland, Lisa Goodrich, John Halley Gotway, Tracy Hertneky, Lacey Holland, Anne Holmes, Michelle Harrold, Tara Jensen, George McCabe, Kathryn Newman, Paul Oldenburg, John Opatz, Julie Prestopnik, Paul Prestopnik, Nancy Rehak, Howard Soh, Bonny Strong, and Minna Win-Gildenmeister.

**Model Evaluation Tools (MET) TERMS OF USE - IMPORTANT!**

Copyright |copyright|
Expand All @@ -26,13 +24,14 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License.

.. _citations:

**Citations**

The citation for this User's Guide should be:

|author_list|, |release_year|: The MET Version |version| User's Guide.
Developmental Testbed Center.
Available at: `MET releases <https://github.com/dtcenter/MET/releases>`_
Developmental Testbed Center. Available at: https://github.com/dtcenter/MET/releases

**Acknowledgments**

Expand Down
2 changes: 1 addition & 1 deletion met/docs/Users_Guide/overview.rst
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ The MODE (Method for Object-based Diagnostic Evaluation) tool also uses gridded

The MODE-TD tool extends object-based analysis from two-dimensional forecasts and observations to include the time dimension. In addition to the two dimensional information provided by MODE, MODE-TD can be used to examine even more features including displacement in time, and duration and speed of moving areas of interest.

The Grid-Diag tools produce multivariate probability density functions (PDFs) that may be used either for exploring the relationship between two fields, or for the computation of percentiles generated from the sample for use with percentile thresholding. The output from this tool requires post-processing by METplus or user-provided utilities.
The Grid-Diag tool produces multivariate probability density functions (PDFs) that may be used either for exploring the relationship between two fields, or for the computation of percentiles generated from the sample for use with percentile thresholding. The output from this tool requires post-processing by METplus or user-provided utilities.

The Wavelet-Stat tool decomposes two-dimensional forecasts and observations according to the Intensity-Scale verification technique described by :ref:`Casati et al. (2004) <Casati-2004>`. There are many types of spatial verification approaches and the Intensity-Scale technique belongs to the scale-decomposition (or scale-separation) verification approaches. The spatial scale components are obtained by applying a wavelet transformation to the forecast and observation fields. The resulting scale-decomposition measures error, bias and skill of the forecast on each spatial scale. Information is provided on the scale dependency of the error and skill, on the no-skill to skill transition scale, and on the ability of the forecast to reproduce the observed scale structure. The Wavelet-Stat tool is primarily used for precipitation fields. However, the tool can be applied to other variables, such as cloud fraction.

Expand Down
Loading