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.


  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.