RSL in IDL for TRMM GV Data


Version 1.0 August 1, 2007 Type of Change: Added functionality.


Introduction

RSL in IDL is a package of routines for working with TRMM Ground Validation radar data. The programs and data structures are modeled on TRMM GV's C-based Radar Software Library (RSL), but are written in the Interactive Data Language (IDL). The idea is to provide the utility of RSL in an IDL environment.

RSL in IDL is a work in progress, and as such does not include all of the functions found in RSL. Because it is easy to locate and extract data from arrays and structures in IDL, some of the functions provided in the original RSL for these tasks are no longer necessary.

To use this package, you will need to have IDL installed on your computer, or otherwise have access to an IDL server. IDL can be purchased from ITT Visual Information Solutions.

Data Formats

RSL in IDL can read data written in the following formats: It can also write data in Universal Format.

The Radar Structure

As in RSL, the primary data object is the radar structure, which provides a consistent interface for a variety of radar formats. This is the structure returned by rsl_anyformat_to_radar, the generic function for reading a raw radar data file. The IDL version of the radar structure is essentially the same as its C language counterpart, so users of RSL should find it familiar. The most important difference in the IDL version is that data is stored directly in floating point format, so functions for packing and unpacking data are no longer needed.

The radar structure is designed to represent a radar volume scan. It is a hierarchical organization of nested structures which represent the individual sweeps, rays, range bins, and data fields of the volume scan. At the top of the hierarchy, radar is made up of volumes, where there is one volume for each radar field. Volumes are then made up of sweeps, sweeps are made up of rays, and rays contain the actual data. The hierarchy is accomplished by having each structure contain an array of structures of the next object descending in the hierarchy. Each structure also contains a header which holds information relating to that part of the radar scan represented by the structure. The sweep header, for example, contains the elevation angle for that sweep.

We can examine the radar structure using IDL's help command with the structures keyword. Let's suppose we have a volume scan of WSR-88D Level II data in a file called NEXRAD.dat. To read the file into a radar structure named radar, we enter the following at the IDL prompt ("IDL>"):

IDL> radar = rsl_anyformat_to_radar('NEXRAD.dat')
Now we can display the structure by entering the command
IDL> help, /structures, radar
IDL prints the following:
** Structure <817bd74>, 2 tags, length=99362364, data length=99026114, refs=1:
   H               STRUCT    -> <Anonymous> Array[1]
   VOLUME          STRUCT    -> <Anonymous> Array[3]
We see that the radar structure contains two members, as mentioned earlier. These are To display the volume structure:
IDL> help, /str, radar.volume
** Structure <817b7ac>, 2 tags, length=33120744, data length=33008662, refs=2:
   H               STRUCT    -> <Anonymous> Array[1]
   SWEEP           STRUCT    -> <Anonymous> Array[20]

The sweep:

IDL> help, /str, radar.volume.sweep
** Structure <81c46dc>, 2 tags, length=1656036, data length=1650432, refs=2:
   H               STRUCT    -> <Anonymous> Array[1]
   RAY             STRUCT    -> <Anonymous> Array[400]

And the ray:

IDL> help, /str, radar.volume.sweep.ray
** Structure <81c04bc>, 2 tags, length=4140, data length=4126, refs=2:
   H               STRUCT    -> <Anonymous> Array[1]
   RANGE           FLOAT     Array[1000]
Notice that range in the ray structure is not an array of structures, but a floating point array. Each element of range represents a range bin, and contains either the value returned at that range, or an indicator of missing data. The size of the actual range bin can be found in the ray header, along with other information about the ray and data. The value used to indicate missing data is contained in the volume header in the member named no_data_flag.

Accessing Structure Contents

To get data for a particular field, you form a structure reference consisting of the volume containing that field, followed by the sweep, and ray. To determine the fields present in our volume scan, we look at field_type in the volume headers. To print the field_type from all our volume headers, we enter the following at the IDL prompt:
IDL> print, radar.volume.h.field_type
IDL prints
DZ VR SW
We could also use the function rsl_get_fields, which returns a string array containing the fields:
IDL> fields = rsl_get_fields(radar)
IDL> print, fields
DZ VR SW

The first field, DZ, is reflectivity. To copy the reflectivity data for the first ray of the first sweep into a separate array, we enter the following:

IDL> nbins = radar.volume[0].sweep[0].ray[0].h.nbins
IDL> refl = radar.volume[0].sweep[0].ray[0].range[0:nbins-1]
IDL> help, refl
REFL            FLOAT     = Array[460]
Notice we used the value of nbins from the ray header in our subscript range. This is the true numberof range bins in the ray, as opposed to the total number of array elements in range, which is 1000. In cases where you want to loop through parts of the radar structure, it is necessary to know the number of items of each object, and this information is supplied in the headers. Each header has a member which stores the number of items of the next object in the hierarchy. These are
radar.h.nvolumes
volume.h.nsweeps
sweep.h.nrays
ray.h.nbins

Using Functions to Access Structures

Functions are provided as in RSL to select substructures of the radar structure.

The function rsl_get_volume returns a volume structure which contains all of the sweeps in the volume scan for a particular field. The following will return the volume structure for the reflectivity field.

    vol = rsl_get_volume(radar,'dz')

Once we have a volume, we can use rsl_get_sweep to select a sweep. To get the first sweep (base scan), enter:

    sweep = rsl_get_sweep(vol)
An optional argument is provided to select the sweep by elevation, as well as keywords for selection by either sweep number or array index. See the function discription rsl_get_sweep for details.

Rsl_get_ray_from_sweep can be used to return a particular ray as a structure. This will return the ray with azimuth closest to 140 degrees:

    ray = rsl_get_ray_from_sweep(sweep, 140.)

Rsl_get_ray can return a ray from a volume structure, skipping the step of retrieving a sweep. The following will return the same ray retrieved in the previous example:

    ray = rsl_get_ray(vol, 0., 140.)

For the functions presented in these examples, only the first argument is required. Omitted arguments default to the first item of whatever is being retrieved. For example, entering

    ray = rsl_get_ray(vol)

will return the first ray of the first sweep in vol.

Reading and Writing Data

To read a radar file in any of the formats mentioned previously into a radar structure, use rsl_anyformat_to_radar:
    radar = rsl_anyformat_to_radar('NEXRAD.dat')
To write a radar structure to a file in Universal Format, use the procedure rsl_radar_to_uf. The following writes the radar structure to the file named NEXRAD.uf:
    rsl_radar_to_uf, radar, 'NEXRAD.uf'
To write a radar structure as a compressed (through gzip) Universal Format file, use the procedure rsl_radar_to_uf_gzip:
    rsl_radar_to_uf_gzip, radar, 'NEXRAD.uf'
The name of the compressed file will have the added extension .gz, so NEXRAD.uf becomes NEXRAD.uf.gz.

Making Radar Images

The procedure rsl_plotsweep_from_radar plots the radar image for a sweep. The following will plot the base scan:
    rsl_plotsweep_from_radar, radar