Applies a low or highpass Butterworth filter to a time series.
The Module ButterworthTimeSeries.c provides specific advice and guidelines for building a numerically stable timedomain filter, but the general procedure is as follows.
<datatype>ZPGFilter
WToZ<datatype>ZPGFilter()
to transform the filter to the more conventional \(z=\exp(2\pi if\Delta t)\) frequency variable. These routines perform an inplace timedomain bandpass filtering of a data sequence *series
, using a Butterworth filter generated from parameters *params
. The routines construct a filter with the square root of the desired amplitude response, which it then applied to the data once forward and once in reverse. This gives the full amplitude response with little or no frequencydependent phase shift.
The routine LALDButterworthREAL4TimeSeries()
applies a doubleprecision filter to singleprecision data, using LALDIIRFilterREAL4Vector()
and LALDIIRFilterREAL4VectorR()
.
The frequency response of a Butterworth lowpass filter is easiest to express in terms of the transformed frequency variable \(w=\tan(\pi f\Delta t)\), where \(\Delta t\) is the sampling interval (i.e. series>deltaT
). In this parameter, then, the power response (attenuation) of the filter is:
\[ R^2 = \sqrt{a} = \frac{1}{1+(w/w_c)^{2n}} \; , \]
where \(n\) is the filter order and \(w_c\) is the characteristic frequency. We have written the attenuation as \(\sqrt{a}\) to emphasize that the full attenuation \(a\) is achieved only after filtering twice (once forward, once in reverse). Similarly, a Butterworth highpass filter is given by
\[ R^2 = \sqrt{a} = \frac{1}{1+(w_c/w)^{2n}} \; . \]
If one is given a filter order \(n\), then the characteristic frequency can be determined from the attenuation at some any given frequency. Alternatively, \(n\) and \(w_c\) can both be computed given attenuations at two different frequencies.
Frequencies in *params
are assumed to be real frequencies \(f\) given in the inverse of the units used for the sampling interval series>deltaT
. In order to be used, the pass band parameters must lie in the ranges given below; if a parameter lies outside of its range, then it is ignored and the filter is calculated from the remaining parameters. If too many parameters are missing, the routine will fail. The acceptable parameter ranges are:
If both pairs of frequencies and amplitudes are given, then a1
, a2
specify the minimal requirements on the attenuation of the filter at frequencies f1
, f2
. Whether the filter is a low or highpass filter is determined from the relative sizes of these parameters. In this case the nMax
parameter is optional; if given, it specifies an upper limit on the filter order. If the desired attenuations would require a higher order, then the routine will sacrifice performance in the stop band in order to remain within the specified nMax
.
If one of the frequency/attenuation pairs is missing, then the filter is computed using the remaining pair and nMax
(which must be given). The filter is taken to be a lowpass filter if f1
, a1
are given, and highpass if f2
, a2
are given. If only one frequency and no corresponding attenuation is specified, then it is taken to be the characteristic frequency (i.e. the corresponding attenuation is assumed to be \(\sqrt{a}=1/2\)). If none of these conditions are met, the routine will return an error.
The following table summarizes the decision algorithm. A \(\bullet\) symbol indicates that the parameter is specified in the range given above. A \(\circ\) symbol indicates that the parameter is not given, i.e. not specified in the valid range.
nMax  f1  a1  f2  a2  Procedure 

\(\circ\)  \(\bullet\)  \(\bullet\)  \(\bullet\)  \(\bullet\)  Type of filter (low or highpass), \(w_c\), and \(n\) are computed from all four transitionband parameters. 
\(\bullet\)  \(\bullet\)  \(\bullet\)  \(\bullet\)  \(\bullet\)  Ditto, but if the resulting \(n>\) nMax , \(w_c\) is computed from nMax and the (f ,a ) pair with the larger a . 
\(\bullet\)  \(\bullet\)  \(\bullet\)  \(\circ\)  \(\circ\)  Lowpass filter; \(w_c\) is computed from nMax , f1 , and a1 . 
\(\bullet\)  \(\bullet\)  \(\bullet\)  \(\circ\)  \(\bullet\)  Ditto; a2 is ignored. 
\(\bullet\)  \(\bullet\)  \(\bullet\)  \(\bullet\)  \(\circ\)  Ditto; f2 is ignored. 
\(\bullet\)  \(\bullet\)  \(\circ\)  \(\circ\)  \(\circ\)  Lowpass filter; \(w_c\) is computed as above with a1 treated as 1/4. 
\(\bullet\)  \(\bullet\)  \(\circ\)  \(\circ\)  \(\bullet\)  Ditto; a2 is ignored. 
\(\bullet\)  \(\circ\)  \(\circ\)  \(\bullet\)  \(\bullet\)  Highpass filter; \(w_c\) is computed from nMax , f2 , and a2 . 
\(\bullet\)  \(\circ\)  \(\bullet\)  \(\bullet\)  \(\bullet\)  Ditto; a1 is ignored. 
\(\bullet\)  \(\bullet\)  \(\circ\)  \(\bullet\)  \(\bullet\)  Ditto; f1 is ignored. 
\(\bullet\)  \(\circ\)  \(\circ\)  \(\bullet\)  \(\circ\)  Highpass filter; \(w_c\) is computed as above with a2 treated as 1/4. 
\(\bullet\)  \(\circ\)  \(\bullet\)  \(\bullet\)  \(\circ\)  Ditto; a1 is ignored. 
Other  Subroutine returns an error. 
Once an order \(n\) and characteristic frequency \(w_c\) are known, the zeros and poles of a ZPG filter are readily determined. A stable, physically realizable Butterworth filter will have \(n\) poles evenly spaced on the upper half of a circle of radius \(w_c\); that is,
\[ R = \frac{(iw_c)^n}{\prod_{k=0}^{n1}(w  w_c e^{2\pi i(k+1/2)/n})} \]
for a lowpass filter, and
\[ R = \frac{w^n}{\prod_{k=0}^{n1}(w  w_c e^{2\pi i(k+1/2)/n})} \]
for a highpass filter. By choosing only poles on the upperhalf plane, one ensures that after transforming to \(z\) the poles will have \(z<1\). Furthermore, the phase factor \((i)^n\) in the numerator of the lowpass filter is chosen so that the DC response is purely real; this ensures that the response function in the \(z\)plane will have a real gain factor, and the resulting IIR filter will be physically realizable. The highpass filter has a purely real response at Nyquist ( \(w\rightarrow\infty\)), which similarly gives a physical IIR filter.
Although higher orders \(n\) would appear to produce better (i.e. sharper) filter responses, one rapidly runs into numerical errors, as one ends up adding and subtracting \(n\) large numbers to obtain small filter responses. One way around this is to break the filter up into several lowerorder filters. The routines in this module do just that. Poles are paired up across the imaginary axis, (and combined with pairs of zeros at \(w=0\) for highpass filters,) to form \([n/2]\) secondorder filters. If \(n\) is odd, there will be an additional firstorder filter, with one pole at \(w=iw_c\) (and one zero at \(w=0\) for a highpass filter).
Each ZPG filter in the \(w\)plane is first transformed to the \(z\)plane by a bilinear transformation, and is then used to construct a timedomain IIR filter. Each filter is then applied to the time series. As mentioned in the description above, the filters are designed to give an overall amplitude response that is the square root of the desired attenuation; however, each timedomain filter is applied to the data stream twice: once in the normal sense, and once in the timereversed sense. This gives the full attenuation with very little frequencydependent phase shift.
Prototypes  
static int  XLALParsePassBandParamStruc (PassBandParamStruc *params, INT4 *n, REAL8 *wc, REAL8 deltaT) 
void  LALButterworthREAL4TimeSeries (LALStatus *stat, REAL4TimeSeries *series, PassBandParamStruc *params) 
Deprecated. More...  
void  LALButterworthREAL8TimeSeries (LALStatus *stat, REAL8TimeSeries *series, PassBandParamStruc *params) 
Deprecated. More...  
void  LALDButterworthREAL4TimeSeries (LALStatus *stat, REAL4TimeSeries *series, PassBandParamStruc *params) 
Deprecated. More...  
Macros  
#define  COMPLEX_DATA 
#define  SINGLE_PRECISION 
#define  SINGLE_PRECISION 

static 
Definition at line 447 of file ButterworthTimeSeries.c.
void LALButterworthREAL4TimeSeries  (  LALStatus *  stat, 
REAL4TimeSeries *  series,  
PassBandParamStruc *  params  
) 
Deprecated.
Definition at line 240 of file ButterworthTimeSeries.c.
void LALButterworthREAL8TimeSeries  (  LALStatus *  stat, 
REAL8TimeSeries *  series,  
PassBandParamStruc *  params  
) 
Deprecated.
Definition at line 394 of file ButterworthTimeSeries.c.
void LALDButterworthREAL4TimeSeries  (  LALStatus *  stat, 
REAL4TimeSeries *  series,  
PassBandParamStruc *  params  
) 
#define COMPLEX_DATA 
Definition at line 224 of file ButterworthTimeSeries.c.
#define SINGLE_PRECISION 
Definition at line 230 of file ButterworthTimeSeries.c.
#define SINGLE_PRECISION 
Definition at line 230 of file ButterworthTimeSeries.c.