tmave()

This function does time averaging while applying a mask. The syntax is:

tmave(maskexpr,expr,timexpr1,timexpr2)

where:

maskexpr     - the mask expression; when evaluated at a fixed time, it must give a single value
expr         - the expression to be averaged
timexpr1,2   - the limits of the time averaging domain

Usage Notes

1. This function works similarly to the ave function, except for the masking. Using tmave is much more efficient than using maskout with ave).

2. The function loops through the specified time steps, and evaluates maskexpr at each fixed time. maskexpr must yeild a single value. If this value is the undefined/missing data value, then expr for that time is not included in the average.

3. If maskexpr is not the undefined data value, it is used as the weight for expr in the average. So if you define maskexpr accordingly, you can use the tmave function to do weighted time averaging.

4. The tricky aspect of using tmave is setting up maskexpr. If expr is a grid with X and/or Y and/or Z varying, then maskexpr *MUST* refer to either a defined variable or a file with only time varying. In general, you have to set up maskexpr in advance.

Examples

1. Say you want to average slp over some time range but only when sst over some region is above some value. You can do this by:

   set x 1
   set y 1
   set t 1 last
   define sstmask = aave(sst,lon=-180,lon=-90,lat=-20,lat=20)
   define sstmask = const(maskout(sstmask,sstmask-25.0),1)
   

   Now sstmask is a time series where the value is 1 when the sst areal average is above 25 and undefined when the value is below 25. maskout set the values below 25 to missing; const set the non-missing values to 1. We can now do our tmave:

   set lon -180 -90
   set lat -20 20
   set t 1
   d tmave(sstmask,slp,t=1,t=last)
   

2. The mask could also be written to a file with all dimensions nonvarying except for time. Here is what some of the records in the data descriptor file might look like:

   dset maskfilename
   xdef 1 linear 1 1
   ydef 1 linear 1 1
   zdef 1 linear 1 1
   tdef 100 linear 
   ....