Documentation

The decimation routine filters and decimates a time series by a factor (dec_factor), which must be a power of 2. The routine requires an input array (x) and an output array (y). If the same, the decimation is done in place; in this case, for multiple calls, the calling program must ensure that the output data is written starting at the proper array index. In general a filter/decimation algorithm is applied repeatly on subsequent parts of a much longer time series. In order to avoid that the filter algorithm is restarted for each part, the routine takes two additional parameters, prev and next, which are used to pass temporary data from one part to the next. When called for the first time the pointer to the previous temporary data must be set to NULL, indicating that the routine should allocate a temporary data structure and pass it back through the next argument (pointer to pointer). When called for intermediate parts of the time series, the prev argument must be set to the temporary data structure which was returned by the previous call through the next argument. On the last call, the next pointer should be set to NULL, telling the routine to deallocate the temporary data structure. The start-up transient of the filter may be dealt with by including in the initial call at least dec_factor*(filter-order) points; the initial returned data can then be discarded to eliminate the transient. Subsequent calls should also be made with at least dec_factor*(filter-order) for calculational efficiency.

The decimation is performed using a half-band FIR filter; for decimation factors greater than 2, multiple stages of the same filter are applied serially to the data. Several FIR filter designs are available:

flag	design method	filter order	cut-off freq (f_p/f_N)	passbnd ripple (stopbnd error)
1	least-squares	42	0.9	0.015-0.2 dB
2	equiripple	42	0.9	0.06 dB
3	least-squares	22	0.9	0.1-1 dB
4	least-squares	82	0.9	0.0006-.01 dB

Example:
float       x[1024];
float       y[128];
float*       temp;

// initialize the filter data using an empty array
decimate (1, x, y, 0, 8, NULL, &temp);

// loop over parts of the time series and decimate data by 
// a factor of 8 
while (dataIsAvailable) {
  getData (x);
  decimate (1, x, y, 1024, 8, temp, &temp);
  saveResult (y);
}
 
// cleanup
decimate (1, x, y, 0, 8, temp, NULL);

Returns:

int (GDS_ERROR)

Parameters:

flag - FIR filter option
x - input time series
y - output time series (return)
n - number of point in the input array
dec_factor - decimation factor; MUST be a power of 2
prev - temporary filter data from previous decimation
next - temporary filter data for next decimation (return)

Author:

PF, Oct 1998

See Also:

Multirate Digital Signal Processing; R Crochiere, L Rabiner