Expression Evaluation Using "offt" Dimension Override
A Diagonal Slice
A Time-Varying Diagonal Slice
Applying a Function Over a Time-Varying Diagonal Slice
The time axis in the grads environment is a simple, linear, one-dimensional object, defined by its start time, a time increment, and its length. The ensemble axis in the grads environment is also a linear, one-dimensional object, but it can become complicated when the metadata for individual ensemble members is time axis related. Such is the case when individual ensemble members have a start time and a length that is different from the defined time axis. For these kinds of data sets, the notion of "initial time" takes on a subtlety: clarifying the difference between the first time step in the defined time axis, and the first time step for an individual member.
Beginning with version 2.0.a7, grads has a new interface for making the clarification between absolute time axis indices and indices that are offsets from an ensemble member's initial time. It has been implemented in the expression syntax as part of a complete variable declaration, which has three components:
abbrevis the abbreviation for the variable as specified in the data descriptor file
file#is the file number that contains this variable. If
file#is absent, grads assumes the default file number.
dimexpris a dimension expression that locally modifies the current dimension environment.
The new interface allows a
dimexpr that specifies an offset
from the variable's initial time (which may be different for each ensemble member). The syntax is "
offt" followed by "
=/+/-" followed by an offset value.
offt" dimension override is currently supported
only for variables associated with a data file -- it will not work with
defined variables or for dimension expressions given as arguments to
functions such as
For the purposes of explaining how to use expressions that employ the "
dimension override, we use a lag ensemble data set that contains 10
members. Each member is a 96-hour forecast, with output every 6 hours,
and initialized at 12-hour intervals. The figure below illustrates the
coverage of all 10 members in the Time-Ensemble domain; the rainbow
colored boxes represent indivual time steps in each member.
Suppose you want to extract the 12-hour precipitation forecast from each ensemble member -- this is the third time step from the initial time of each forecast, which would be a diagonal slice through the domain, highlighted in the figure below with a solid black outline:
'set t 1''set e 1 10'
offt=" with the offset value:
grads will retrieve the third valid time step from each ensemble member (GrADS knows the start time of each member because that information is provided in the EDEF entry of the data descriptor file). GrADS then aligns all the retrieved values into a single column and returns a result grid with a fixed T and a varying E dimension:
Note that the original valid time of the precipitation value from
each member is not retained ... the new valid time associated with
this result is taken from the current dimension environment. In this
example, the new valid time is first time step in the data set, since
the time dimension had been fixed with the
'set t 1' command.
Now we expand our data request to include more than one time step. Suppose you want to extract the precipitation values over the first 24 hours of each ensemble member -- you need the second, third, fourth, and fifth time step from each forecast. This request would be a time-varying diagonal slice through the domain, highlighted in the figure below with a solid black outline:
tloopfunction with an expression that contains the "
offt" dimension override. Begin by setting time to be a varying dimension in the dimension environment. The ensemble dimension is also set to include all desired members:
'set t 1 4''set e 1 10'
tloopfunction will evaluate the expression at fixed times, then reconstruct the time series to obtain a final result that is time varying. At each step, when
tloopis evaluating the expression at a fixed time, it will override the time dimension value with a time offset value instead. The tricky part is creating the "
offt" dimension override expression, which must be relative to the T index of the dimension environment. In our example, want the second, third, fourth, and fifth time steps which correspond to offset values of 1, 2, 3, and 4. Thus, our offset values are equivalent to the T index values of our set dimension environment, so the final expression will be:
The dimension override expression, in this case "
is a kind of formula for calculating the offset value using the current
t value of the dimension environment. In this case, when t=1, the
offset value will be t+0 or 1; when t=2, the offset value will be t+0 or
2; etc. This will achieve the desired result -- as
tloop builds the time-varying result, it steps through the desired offset
values, retrieving the second, third, fourth, and fifth timesteps of
each ensemble member, and stacking them in an aligned grid:
Note that if the dimension override expression contained "
then this would indicate a straightforward assignment of the time
offset value that does not depend on the current dimension environment.
tloop to retrieve a time-varying diagonal slice, the "
dimension override must be a relative expression (i.e. "+/-value")
instead of an assignment expression (i.e. "=value"), otherwise GrADS
will retrieve the same offset value for each time step -- this would not
be the desired result.
tloop(as described above), then
sumover that defined variable:
'set t 1 4''set e 1 10'
'define pnew = tloop(p(offt+0))''set t 1''d sum(pnew,t=1,t=4)'
sumfunction do the work that the
tloopfunction would do --
sumloops over each time evaluating the expression at a fixed time and returns the sum of all values:
'set t 1''set e 1 10'
offt" dimension override is supported only for variables associated with a data file -- it will not work with defined variables or for dimension expressions given as arguments to functions such as
sum. The following expression will return an error message:
'd sum(p,offt=1,offt=4)' <=== THIS IS INCORRECT