This function subsets on a monotonic field or contiguous elements of a dimension. Whereas the EOS_GD_DEFBOXREGION function subsets along the XDim and YDim dimensions, this function allows the user to subset along any other 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 routine, the second option is restricted to fields with number type: 22, 24, 5, 6)
This function may be called after EOS_GD_DEFBOXREGION to provide both geographic 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 routine 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_GD_REGIONINFO and EOS_GD_EXTRACTREGION functions work as before, however the field to be subsetted, (the field specified in the call to EOS_GD_REGIONINFO and EOS_GD_EXTRACTREGION) must contain the dimension used explicitly in the call to EOS_GD_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. If we desire all the elements with values between 500 and 800, we make the call:
range[0] = 500.d
range[1] = 800.d
regionID = EOS_GD_DEFVRTREGION(gridID, -1, "Pressure", range)
The routine determines the elements in the Height dimension which 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_GD_DEFVRTREGION(gridID, -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.
If a previous subset region or period was defined with id, subsetID, that we wish to refine further with the vertical subsetting defined above we make the call:
regionID = EOS_GD_DEFVRTREGION(gridID, 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.
In this example, any field to be subsetted must contain the Height dimension.
Syntax
Result = EOS_GD_DEFVRTREGION(gridID, regionID, vertObj, range)
Return Value
Returns the grid region ID if successful and FAIL (–1) otherwise.
Arguments
gridID
Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH.
regionID
Region or period id (long) from previous subset call or –1 to start a new region.
vertObj
Dimension or field to subset (string).
range
Minimum and maximum range for subset (double) 2 element array.
Keywords
None
Version History