## tloop

`tloop(expr)`

When time is a varying dimension in the dimension environment, the `tloop` function evaluates the `expr` at fixed times, then reconstructs the time series to obtain a final result that is time varying. The `tloop` function is required due to the implementation of the GrADS expression evaluation rules, and the implementation of certain other functions. The `tloop` function can also improve performance for certain calculations.

The `tloop` function is provided as a way to obtain time series from functions that themselves are not implemented to be able to operate when time is a varying dimension. See the examples below.

### Usage Notes

1. The `tloop` function loops through time based on the time increment of the default file; it is thus important to have the default file set appropriately.

2. The `tloop` function and the `define` command work very similarly. In many cases, the `define` command can be used to obtain the same result as using `tloop`. In fact, the `define` command can be even more useful along those lines, since it also loops through the Z dimension, in effect creating a `zloop` function. See the define command for more information.

### Examples

1. A typical application of the `tloop` function is to obtain a time series of areal averages using the `aave` function. Since the `aave` function will not work when time is a varying dimension, the useof `tloop` is required:

```set x 1 ```
```set y 1 ```
```set t 1 31 ```
`d tloop(aave(ts,lon=0,lon=360,lat=-90,lat=90)) `

Note that the dimension environment is set up to reflect the kind of plot desired, namely a `line` plot where time is the varying dimension. Thus it is necessary to fix the X and Y dimensions; the values of those dimensions in this case are not relevent.

2. The `tloop` function can be used to smooth in time:

```set lon -180 0 ```
```set lat 40 ```
```set lev 500 ```
```set t 3 28 ```
`d tloop(ave(z,t-2,t+2)) `

In this example, we are plotting a time-longitude cross section, where each time is a 5 time period mean centered at that time.

3. If we wanted to display a time-longitude cross section (X and T varying), with the data being averaged over latitude, the 'standard' way to do this might be:

```set lon -180 0 ```
```set lat 40 ```
```set lev 500 ```
```set t 1 31 ```
`d ave(z,lat=20,lat=40) `

This calculation could be fairly time consuming, since to perform the average, a longitude-time section is obtained at each latitude. If the time period is long, then this would be a very inneficient operation, due to the ordering of data in a typical GrADS data set. The `tloop` function might substantially improve the performance of this calculation:

`d tloop(ave(z,lat=20,lat=40)) `

since the average is then done at each fixed time, and is thus just an average of X varying data over Y. Thus the `tloop` function here is simply being used to force a different ordering to the calculation, although the result is the same.