## Expression Evaluation Using "offt" Dimension Override

####
Motivation

Syntax

A Diagonal Slice

A Time-Varying Diagonal Slice

Applying a Function Over a Time-Varying Diagonal Slice

### Motivation

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.

### Syntax

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:

`abbrev.file#(dimexpr,dimexpr,...)`

where:

`abbrev `

is 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.

```
````dimexpr `

is 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.

The "`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 `ave`

or `sum`

.

### A Diagonal Slice

For the purposes of explaining how to use expressions that employ the "`offt`

"
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:
```
'd p(offt=2)'
```

**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.

### A Time-Varying Diagonal Slice

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:

`tloop`

function 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'
```

`tloop`

function 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 `tloop`

is 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:
```
'd tloop(p(offt+0))'
```

The dimension override expression, in this case "`offt+0`

",
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 "`offt=0`

",
then this would indicate a straightforward assignment of the time
offset value that does not depend on the current dimension environment.
When using `tloop`

to retrieve a time-varying diagonal slice, the "`offt`

"
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.

### Applying a Function Over a Time-Varying Diagonal Slice

`tloop`

(as described above), then `sum`

over 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)'
```

`sum`

function do the work that the `tloop`

function would do -- `sum`

loops over each time evaluating the expression at a fixed time and returns the sum of all values:
```
'set t 1'
'set e 1 10'
```

```
'd sum(p(offt+0),t=1,t=4)'
```

`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 `ave`

or `sum`

. The following expression will return an error message:
```
'd sum(p,offt=1,offt=4)' <=== THIS IS INCORRECT
```