# Equi_Ripple

Advanced Analysis Library Only

AnalysisLibErrType Equi_Ripple (int numberOfBands, double A[], double weights[], double samplingFreq, double cutoffs[], int filterType, int numberOfCoef, double coefficientArray[], double *delta);

## Purpose

Designs a multiband FIR linear phase filter, a differentiator, or a Hilbert Transform using the Parks-McClellan algorithm. The resulting frequency response in each band has equal ripples that you can adjust by a weighting factor. Equi_Ripple generates only the filter coefficients; it does not actually perform data filtering.

The Parks-McClellan algorithm does not always generate a completely accurate filter. Always verify the filter design by applying it to a sample impulse response.

Although Equi_Ripple is the most flexible way to design an FIR linear phase filter, it has more complex parameters and requires some digital signal processing (DSP) knowledge. You might find it more convenient to use EquiRpl_LPF, EquiRpl_HPF, EquiRpl_BPF, and EquiRpl_BSF. These functions, which provide lowpass, highpass, bandpass, and bandstop FIR filters with equal weighting factors in all bands, are special cases of Equi_Ripple with simplified parameters.

### Example

/* Design a 24-point lowpass filter and filter the incoming signal. */
double x[256], coef[24], y[280], fs, delta;
double A[2]; /* array of frequency responses */
double wts[2]; /* array of weighting factors */
double cutoffs[4]; /* frequency points */
int n, m;
int bands; /* number of bands */
int type; /* filter type */
bands = 2; /* one pass band and one stop band */
fs = 1000.0; /* sampling frequency */
A[0] = 1.0; /* 1 for the pass band */
A[1] = 0.0; /* 0 for the stop band */
wts[0] = 1.0; /* weighting factor for the pass band */
wts[1] = 1.0; /* weighting factor for the stop band */
cutoffs[0] = 0.0;
cutoffs[1] = 300.0; /* the first stop band [0, 300.0] */
cutoffs[2] = 400.0;
cutoffs[3] = 500.0; /* the pass band [400, 500] */
type = 1; /* multiple band filter */
n = 24; /* filter length */
m = 256;
Equi_Ripple (bands, A, wts, fs, cutoffs, type, n, coef, &delta);
Convolve (coef, n, x, m, y); /* Convolve the filter with the signal. */

### Example

/* Design a 31-point bandpass filter and filter the incoming signal. */
double x[256], coef[55], y[287], fs, delta;
double A[3]; /* array of frequency responses */
double wts[3]; /* array of weighting factors */
double cutoffs[6]; /* frequency points */
int n, m;
int bands; /* number of bands */
int type; /* filter type */
bands = 3; /* one pass band and two stop bands */
fs = 1000.0; /* sampling frequency */
A[0] = 0.0; /* 0 for the first stop band */
A[1] = 1.0; /* 1 for the stop band */
A[2] = 0.0; /* 0 for second stop band */
wts[0] = 10.0; /* weighting factor for the first stop band */
wts[1] = 1.0; /* weighting factor for the pass band */
wts[2] = 4.0; /* weighting factor for the second stop band */
cutoffs[0] = 0.0;
cutoffs[1] = 200.0; /* the first stop band [0, 200.0] */
cutoffs[2] = 250.0;
cutoffs[3] = 350.0; /* the pass band [250, 350] */
cutoffs[4] = 400.0;
cutoffs[5] = 500.0; /* the second stop band */
type = 1; /* multiple band filter */
n = 31; /* filter length */
m = 256;
Equi_Ripple (bands, A, wts, fs, cutoffs, type, n, coef, &delta);
Convolve (coef, n, x, m, y); /* Convolve the filter with the signal. */

### Example

/* Design a 30-point differentiator. */
double coef[30], fs, delta;
double A[1]; /* array of frequency responses */
double wts[1]; /* array of weighting factors */
double cutoffs[2]; /* frequency points */
int n;
int bands; /* number of bands */
int type; /* filter type */
bands = 1; /* one pass band and one stop band */
fs = 1000.0; /* sampling frequency */
A[0] = 1.0; /* 1 for the band */
wts[0] = 1.0; /* weighting factor for the band */
cutoffs[0] = 0.0;
cutoffs[1] = 500.0; /* the entire frequency range */
type = 2; /* differentiator */
n = 30; /* filter length */
Equi_Ripple (bands, A, wts, fs, cutoffs, type, n, coef, &delta);

### Example

/* Design a 20-point Hilbert transform. */
double coef[20], fs, delta;
double A[1]; /* array of frequency responses */
double wts[1]; /* array of weighting factors */
double cutoffs[2]; /* frequency points */
int n;
int bands; /* number of bands */
int type; /* filter type */
bands = 1; /* one pass band and one stop band */
fs = 1000.0; /* sampling frequency */
A[0] = 1.0; /* 1 for the band */
wts[0] = 1.0; /* weighting factor for the band */
cutoffs[0] = 100.0;
cutoffs[1] = 500.0;
type = 3; /* Hilbert transform */
n = 20; /* filter length */
Equi_Ripple (bands, A, wts, fs, cutoffs, type, n, coef, &delta);

## Parameters

Input
Name | Type | Description
numberOfBands | integer | Number of bands in the filter. Default Value: 2.
A | double-precision array | Frequency response magnitude of each band. The values in the array must be between 0.0 and 1.0. A value of 0.0 indicates that the corresponding band is a stopband. A value of 1.0 indicates that the corresponding band is a passband. If filterType is multiband and the numberOfCoef is even, then AnumberOfBands — 1 must be 0.
weights | double-precision array | Weighting factor for each band. The weighting factor determines the relative damping of the generated ripple for the band. A higher value causes a smaller ripple to be generated for the band. Whether a value is high or low depends on its relation to the average of all the weights in the array. To achieve uniform ripple for all bands, set each element of the array to the same positive value, for example, 1.0.
samplingFreq | double-precision | Sampling frequency in Hertz.
cutoffs | double-precision array | An array that specifies the frequency values of the lower and upper end points of each band. The array contains two entries for each band, as follows: Cutoffs[0] - First band, lower Cutoffs[1] - First band, upper Cutoffs[2] - Second band, lower Cutoffs[3] - Second band, upper If filterType is multiband or differentiator, cutoffs[0] must be 0. If filterType is Hilbert transform, then cutoffs[0] must not be 0. NI recommends that you use a value slightly greater than zero to define a transitional region. For all filter types, cutoffs[(2*NumberOfBands) — 1] must be samplingFreq/2.
filterType | integer | Filter type. When filterType is 1, the function generates filter coefficients for a multiband filter. numberOfBands must be greater than or equal to two. When filterType is 2, the function generates filter coefficients for a differentiator. numberOfCoef must be even. When filterType is 3, the function generates filter coefficients for a Hilbert transform. numberOfCoef must be even.
numberOfCoef | integer | Length of the window FIR filter. If filterType is Hilbert transform or differentiator, the value must be even. Valid Range: 8 to 511.
Output
Name | Type | Description
coefficientArray | double-precision array | Calculated output window FIR filter coefficients.
delta | double-precision | Calculated normalized ripple size. To obtain the amplitude of a passband ripple in decibels, use the following formula: 20*log(1 + Delta/Weights[i]) To obtain the attenuation of a stopband in decibels, use the following formula: 20*log(Delta/Weights[i])

## Return Value

Name | Type | Description
status | AnalysisLibErrType | A value that specifies the type of error that occurred. Refer to analysis.h for definitions of these constants.