Radx C++ Software Package for Radial Radar Data


The Radx C++ package was developed at NCAR to provide support for the new CfRadial radar data format, and to provide translation between common radar data formats.

The software is open source and freely available as a community resource. It is designed to be run on LINUX and MacOSX platforms, but should also run on Windows under Cygwin.

Radx comprises a C++ library, which may be used by developers, and a number of applications built on that library.

You may download the softare and build it using the standard configure utility.


Download

We recommend you download not only the Radx package, but also all of the files on the ftp site, so that you can build a suitable version of NetCDF to support Radx.

A tar file of the latest Radx library may be downloaded from here.

The name of the tar file will be Radx-yyyymmdd.src.tgz, where yyyymmdd refers to the date on which the tar file was created.

After download, untar the file as follows:

        tar -xvfz Radx-*.tgz

Building

The Radx library may be built using a standard configure script.

A script build_radx is provided to build all support libraries and applications, using configure. This will build the HDF5, NetCDF and ununits2 packages, as well as Radx.

Generally you would build the package using:

    build_radx /usr/local

to install in the standard /usr/local location, or perhaps

    build_radx /opt/local

to install in a non-standard location, for example /opt/local

The build_netcdf script will build just the support libraries.

Please read the README file at the top level, for further information.


Radx C++ Applications


Overview

Radx applications are built using the Radx library, and other libraries as needed.

The following applications are available:

Radx-based applications
Application name Description Usage Default params file
RadxPrint Print radial data RadxPrint_usage RadxPrint_params
RadxCheck Check CfRadial files RadxCheck_usage RadxCheck_params
RadxConvert Convert between radial file formats RadxConvert_usage RadxConvert_params
RadxDiff Check 2 Radx-supported files for differences RadxDiff_usage RadxDiff_params
RadxEvad Compute Enhanced VAD RadxEvad_usage RadxEvad_params
RadxFilter Filter data fields in range RadxFilter_usage RadxFilter_params
RadxMergeFields Merge fields from 2 sets of radial data files RadxMergeFields_usage RadxMergeFields_params
Radx2Grid Convert from irregular polar to a regular Cartesian or polar grid Radx2Grid_usage Radx2Grid_params
RadxCov2Mom Compute moments from covariances RadxCov2Mom_usage RadxCov2Mom_params
RadxPartRain Derive NCAR particle-ID and precipitation rate from dual-polarization fields RadxPartRain_usage RadxPartRain_params
FixCfradialPaths Fix path names for CfRadial files, to conform to the expected directory and file naming conventions FixCfradialPaths_usage FixCfradialPaths_params
FixRadxPointing Correct pointing errors in radial data FixRadxPointing_usage FixCfradialPaths_params

Details are given below on:


Running the Radx applications

There are two main features which are important to the user:

Command line arguments

You can obtain the command line usage of an application by invoking the -h or -help command line argument. For example:

    RadxConvert -h
yields the usage

Run-time parameter file

The Radx applications use the NCAR Table-Driven Run-time Parameter (TDRP) package to handle parameters.

To create a default (or template) parameter file, use the -print_params command line option.

For example:

    RadxConvert -print_params > RadxConvert.params
creates the following file contents.

These parameter files are self-documenting, using comments inserted by the author of the code.

The user edits the default parameter file to control the application to produce the desired behavior.

To run the application, the user invokes the -params command line option.

For example:

    RadxConvert -params RadxConvert.params -start "2009 10 08 12 00 00" -end "2009 10 08 13 00 00"
will convert all of the files between 12 UTC and 13 UTC on 2009/10/08, using the parametes specified in the parameter file.

RadxPrint

RadxPrint allows you to print data from any of the files supported by Radx.

By default, the contents are printed in a generic form, which does not reflect the way the data is stored in the file format.

By using the -native option, you can see the details of how data is stored in DORADE or UF files.

Use ncdump to see the details of how data is stored in CfRadial or Foray netCDF files.

Back to top


RadxCheck

RadxCheck performs some basic checks on a CfRadial file, to ensure that it conforms with the format specification.

Use ncdump to see the details of how data is stored in CfRadial files.

Back to top


RadxConvert

RadxConvert allows you to convert data stored in one format to a different format.

RadxConvert can read/write the following formats:

Radx file format support
Format Read access Write access
CfRadial - NCAR/EOL/UNIDATA Yes Yes
DORADE - NCAR/EOL Yes Yes
UF - Universal Format Yes Yes
Foray-1 netCDF - NCAR/EOL Yes Yes
DOE ARM netcdf - precedes CfRadial Yes No
MDV radial - NCAR/RAL Yes Yes
NEXRAD msg31 level 2 archive Yes Yes
NEXRAD msg1 level 2 archive Yes No
SIGMET - raw format (Vaisala) Yes No
RAPIC - BOM Australia Yes No
HRD - HRD NOAA Yes No
LEOSPHERE LIDAR, ASCII format Yes No
EEC - now supports CfRadial Yes N/A

Back to top


RadxDiff

RadxDiff performs a logical difference between 2 files supported by Radx. You can set the levels of the checks both on the command line and in the parameter file. This application is intended to check that the information content of the files is consistent, rather than the fact that everything is exactly equal.

To see the exact differences between two files, run:

   RadxPrint -rays -data -f filename1 > /tmp/filename1.txt

   RadxPrint -rays -data -f filename2 > /tmp/filename2.txt

The .txt ASCII files will contain all of the information in the Radx files. Then use the normal unix diff utilities to check for differences between the two. For example:

   tkdiff filename1.txt filename2.txt

Since the output from RadxPrint can be rather long, this procedure might take too much memory. In order to only examine the top of each file, use the following:

   RadxPrint -rays -data -f filename1 | head -n 10000 > /tmp/filename1.txt

   RadxPrint -rays -data -f filename2 | head -n 10000 > /tmp/filename2.txt

Back to top


RadxEvad

RadxEvad RadxEvad reads in Doppler data from a polar radar file, computes volumetric VAD (VVP) winds and writes them out to NetCDF.

The implementation in Mdv2Vad is based on the paper 'An Improved Version of the Extended Velocity-Azimuth Display Analysis of Single-Doppler Radar Data' by Thomas Metejka and Ramesh C. Srivastava, Journal of Atmospheric and Oceanic Technology, Vol 8, No 4, August 1991. The code is designed to match the terminology in the paper as fas as is posible. Please refer to the paper for a detailed explanation of the method.

Back to top


RadxMergeFields

RadxMergeFields allows you to merge fields from a primary set of radial files with fields from a secondary set of files.

The ray geometry is determined from the primary data set. If the secondary data set has a different geometry, the data will be mapped onto the geometry of the primary data set.

Back to top


Radx2Grid

Radx2Grid performs coordinate transformations from the polar grid on which radar data is collected to a regular grid.

The following regular grids are supported:

Back to top


RadxCov2Mom

RadxCov2Mom computes radar moments from raw covariances. The advantage of storing the covariances is that later on you can go back and re-compute the moments with updated calibration values and improved algorithms.

For this to work, during data acquisition you need to save the covariance fields for the dual-polarization mode you are working in. These details are provided in the default parameter file.

You will also need a calibration file, in XML - see this example

Back to top


RadxPartRain

RadxPartRain computes the NCAR Particle Identification, and the NCAR precipition estimates, from dual polarization data.

These algorithms need to be tuned for each of the various wavelengths. See the following examples:

Back to top


Radx C++ library


Overview

The Radx C++ library provides an API for handling ray-by-ray radial data from radars and lidars. The basic API is designed to be file-format independent. For example, the RadxVol class is a general purpose class for data volumes, irrespective of format.

Radx provides adapters to read and write data files, as follows:

Radx file format support
Format Read access Write access Radx lib Adapter class
CfRadial - NCAR/EOL/UNIDATA Yes Yes NcfRadxFile
DORADE - NCAR/EOL Yes Yes DoradeRadxFile
UF - Universal Format Yes Yes UfRadxFile
Foray-1 netCDF - NCAR/EOL Yes Yes ForayNcRadxFile
DOE ARM netcdf Yes No DoeNcRadxFile
NEXRAD msg1 level 2 archive Yes Yes NexradNcRadxFile
NEXRAD msg31 level 2 archive Yes Yes NexradNcRadxFile
SIGMET - raw format (Vaisala) Yes No SigmetNcRadxFile
RAPIC - BOM Australia Yes No RapicRadxFile
HRD - HRD/NOAA Yes No HrdRadxFile
LEOSPHERE LIDAR, ASCII format Yes No LeoRadxFile

The Foray-1 netCDF file format has been replaced by CfRadial. Therefore, write access is not provided for this format.


Documentation

The Radx library is well commented, both in the header files and implementation files, to assist the programmer in its use.

Doxygen documentation is provided here.


Author: Mike Dixon
EOL/RAL, NCAR, P.O.Box 3000, Boulder, CO, 80307-3000
July 2010