wiki:decimate
Last modified 8 years ago Last modified on 03/25/12 13:13:51

Earthworm Module: decimate

Contributed by:

Function

Implements filter and decimate routines.

Details

The Decimate module implements multi-stage filter and decimation routines to process wave data (TYPE_TRACEBUF2) coming from the InRing defined in decimate.d. Decimated trace messages are written to the OutRing with their SCNs changed as specified in decimate.d. The decimated trace message retains its TYPE_TRACEBUF2 type, but it (normally) has a new SCNL name.

Decimate uses FIR filters to reduce the incoming wave frequency content down to the Nyquist frequency of the output wave. FIR filters have the advantage of being strictly causal and stable. However, there is considerable delay introduced by a FIR filter. Fortunately FIR filters have linear phase so the delay does not change the shape of the wave. The delay will be removed from the data by adjusting their timestamps. This adjustment makes the filter acausal: small precursory artifacts will be seen in front of impulsive wave arrivals. This is an inherent characteristic of FIR filters. See "Of Poles and Zeros" by Frank Scherbaum for a method of removing these artifacts.

The decimation is performed as part of the filter routine for efficiency. The FIR filter coefficients are determined from the specified decimation rate, using the Remez Exchange algorithm. This produces an equi-ripple filter. Currently the ripple limits are hard coded to 0.005 in the pass band and 0.0031 in the stop band (see decimate.h in the source directory.) The foefficients zeroes of each filter, as well as the effective delay, are logged on startup. FIR filters have no poles.

Example Configuration File

#
#                     Configuration File for decimate
#
MyModId          MOD_DECIMATE
InRing           WAVE_RING       # Transport ring to find waveform data on,
OutRing          WAVE_RING       # Transport ring to write output to,
                                 # InRing and OutRing may be the same.
HeartBeatInterval     30         # Heartbeat interval, in seconds,
LogFile            1             # 1 -> Keep log, 0 -> no log file
#Debug		 		 # Write out debug messages (optional)

# Specify the decimation rates as one or more integer values greater than 1,
# all on one "DecimationRates" line, enclosed in quotes.
# These will be used in successive stages of decimation. The overall
# decimation rate is the product of all the stage decomation rates.
# The filters will be more efficient if several small decimation stages
# are used instead of one large one, and if largest rates are given first.
# Currently a maximum of 10 stages is enforced.
DecimationRates    "5 2"     # Decimation rates of each stage, in quotes!

MinTraceBuf         10       # Minimum number of samples in output TRACE_BUF.

MaxGap              1.5      # Maximum gap, in sample periods, allowed
                             # between trace data points.
                             # When exceeded, channel is restarted.
# If you want Decimate to compute and log its filter coefficients and then
# exit, specify "TestMode".
#TestMode

#
# Specify logo of the messages to grab from the InRing.
# TYPE_TRACEBUF2 is assumed, therefore only module ID and
# installation ID need to be specified
#
GetWavesFrom    INST_WILDCARD MOD_WILDCARD  # TYPE_TRACEBUF2 (assumed)

#
# List SCNL codes of trace messages to decimate and their output SCNL codes
# Wildcard characters are not allowed here.
#
#        IN-SCNL     OUT-SCNL
GetSCNL ABC EHZ UW --  ABC EWZ UW --

Helpful Hints