Whereas the EOS_SW_DEFBOXREGION and EOS_SW_DEFTIMEPERIOD functions perform subsetting along the “Track” dimension, this function allows the user to subset along any dimension. The region is specified by a set of minimum and maximum values and can represent either a dimension index (case 1) or field value range (case 2). In the second case, the field must be one-dimensional and the values must be monotonic (strictly increasing or decreasing) in order that the resulting dimension index range be contiguous. (For the current version of this function, the second option is restricted to fields with one of the following HDF data types: 22, 24, 5, 6.)
This function may be called after EOS_SW_DEFBOXREGION or EOS_SW_DEFTIMEPERIOD to provide both geographic or time and “vertical” subsetting. In this case the user provides the id from the previous subset call. (This same id is then returned by the function.) This function may also be called “stand-alone” by setting the input id to (–1).
This function may be called up to eight times with the same region ID. It this way a region can be subsetted along a number of dimensions.
The EOS_SW_REGIONINFO and EOS_SW_EXTRACTREGION functions work as before, however, because there is no mapping performed between geolocation dimensions and data dimensions the field to be subsetted, (the field specified in the call to EOS_SW_REGIONINFO and EOS_SW_EXTRACTREGION) must contain the dimension used explicitly in the call to EOS_SW_DEFVRTREGION (case 1) or the dimension of the one-dimensional field (case 2).
Examples
Suppose we have a field called Pressure of dimension Height whose values increase from 100 to1000, and we desire all the elements with values between 500 and 800:
range[0] = 500.d
range[1] = 800.d
regionID = EOS_SW_DEFVRTREGION(swathID, -1, "Pressure", range)
The function determines the elements in the Height dimension that correspond to the values of the Pressure field between 500 and 800.
If we wish to specify the subset as elements 2 through 5 (0 - based) of the Height dimension, the call would be:
range[0] = 2.d
range[1] = 5.d
regionID = EOS_SW_DEFVRTREGION(swathID, -1, "DIM:Height", range)
The “DIM:” prefix tells the routine that the range corresponds to elements of a dimension rather than values of a field. In this example, any field to be subsetted must contain the Height dimension.
If a previous subset region or period was defined with an id of subsetID that we wish to refine further with the vertical subsetting defined above, we make the call:
regionID = EOS_SW_DEFVRTREGION(swathID, subsetID, $
"Pressure", range)
The return value, regionID, is set equal to subsetID. That is, the subset region is modified rather than a new one created. We can further refine the subset region with another call to the function:
freq[0] = 1540.3d
freq[1] = 1652.8d
regionID = EOS_SW_DEFVRTREGION(swathID, regionID, $
"FreqRange", freq)
Syntax
Result = EOS_SW_DEFVRTREGION(swathID, regionID, vertObj, range)
Return Value
Returns the swath region ID if successful and FAIL (–1) otherwise.
Arguments
swathID
Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH.
regionID
Region or period id (long) from previous subset call, or –1 to create a new region within the entire dataset.
vertObj
Dimension or field (string) to subset by.
range
Minimum and maximum range (double) for subset.
Keywords
None
Version History