Syntax Supported by the IML Procedure and the iml Action
DFDESIGN Call
CALL DFDESIGN (b, a, z, p, k, filterName, filterType, n, Wc <, R>) ;
This subroutine is supported by the IML procedure and the iml action.
The DFDESIGN subroutine returns the transfer function of a digital filter that meets the design specification. The specification includes a digital filter’s name, type, order, and low cutoff frequency (or low and high cutoff frequencies). The transfer function’s numerator polynomial coefficients, denominator polynomial coefficients, zeros, poles, and gain are returned.
When you are designing a Butterworth filter, you should call the DFDESIGN subroutine without the input argument R. When you are designing a Chebyshev type I or type II filter, the input argument R is required. R is the filter’s passband ripple for a Chebyshev type I filter or the filter’s stopband attenuation for a Chebyshev type II filter. A digital filter’s transfer function H(z) is defined as
where the order of the filter is the greater of N or M; 
are the transfer function’s numerator polynomial coefficients; 
are the transfer function’s denominator polynomial coefficients; and 
, 
, and k are the zeros, poles, and gain of the transfer function, respectively.
The input arguments to the DFDESIGN subroutine are as follows:
- filterName
is a string that specifies the name of the desired digital filter. The name is not case-sensitive. Currently the Butterworth, Chebyshev type I, and Chebyshev type II filters are supported. The input string can be "BUTTER" or "BUTTERWORTH", "CHEBY1" or "CHEBYSHEV1", "CHEBY2" or "CHEBYSHEV2".
- filterType
is a string that specifies the type of the desired digital filter. It is one of the following four values: "LOWPASS", "HIGHPASS", "BANDPASS", or "BANDSTOP". The input string is not case-sensitive.
- n
is a positive integer scalar that specifies the order of the digital filter. The maximum supported filter order is 200.
- Wc
specifies the digital filter’s cutoff frequencies. The mathematical notation for the cutoff frequency is
. For a lowpass or highpass filter, is a scalar value. For a bandpass or bandstop filter, is a 
or 
vector. The values of the cutoff frequencies are between 0 and 1, where 1 corresponds to the normalized Nyquist frequency (
rad/sample). See the DFORDER call for how to specify the cutoff frequencies for each type of filter. - R
specifies a filter’s passband ripple when you are designing a Chebyshev type I filter, or a filter’s stopband attenuation when you are designing a Chebyshev type II filter. The value of R is a positive scalar expressed in decibels (dB).
The DFDESIGN subroutine returns the following values:
- b
is a column vector that contains the numerator polynomial coefficients of the digital filter’s transfer function. For a lowpass or highpass filter, b is an
vector; for a bandpass or bandstop filter, b is a 
vector, where n is the input filter order. - a
is a column vector that contains the denominator polynomial coefficients of the digital filter’s transfer function. For a lowpass or highpass filter, a is an
vector; for a bandpass or bandstop filter, a is a vector, where n is the input filter order. - z
is a two-column matrix that contains the zeros of the digital filter’s transfer function. Each row of the matrix represents one zero value, which is a complex number whose real part is in the first column and whose imaginary part is in the second column. For a lowpass or highpass filter, z is an
matrix; for a bandpass or bandstop filter, z is a 
matrix, where n is the input filter order. - p
is a two-column matrix that contains the poles of the digital filter’s transfer function. Each row of the matrix represents one pole value, which is a complex number whose real part is in the first column and whose imaginary part is in the second column. For a lowpass or highpass filter, p is an
matrix; for a bandpass or bandstop filter, p is a matrix, where n is the input filter order. - k
is a scalar that contains the gain of the digital filter’s transfer function.
The following example uses the DFDESIGN call to design a lowpass Butterworth filter:
filter_name = "butter";
filter_type = "lowpass";
n = 7;
Wc = 0.3;
call dfdesign(b, a, z, p, k, filter_name, filter_type, n, Wc);
print b, a, z, p, k;
Figure 64: Output from the DFDESIGN Call for a Lowpass Butterworth Filter
| b |
|---|
| 0.0009629 |
| 0.0067403 |
| 0.0202208 |
| 0.0337013 |
| 0.0337013 |
| 0.0202208 |
| 0.0067403 |
| 0.0009629 |
| a |
|---|
| 1 |
| -2.782514 |
| 3.9668079 |
| -3.40515 |
| 1.8758627 |
| -0.650946 |
| 0.1308525 |
| -0.011663 |
| z | |
|---|---|
| -1 | 0 |
| -1 | 0 |
| -1 | 0 |
| -1 | 0 |
| -1 | 0 |
| -1 | 0 |
| -1 | 0 |
| p | |
|---|---|
| 0.4981133 | 0.6684049 |
| 0.4981133 | -0.668405 |
| 0.3907072 | 0.4204395 |
| 0.3907072 | -0.420439 |
| 0.3399766 | 0.2030305 |
| 0.3399766 | -0.203031 |
| 0.3249197 | 1.195E-17 |
| k |
|---|
| 0.0009629 |
The following example uses the DFDESIGN call to design a bandpass Chebyshev type I filter:
filter_name = "cheby1";
filter_type = "bandpass";
n = 4;
Wc = 0.2 || 0.5;
R = 5;
call dfdesign(b, a, z, p, k, filter_name, filter_type, n, Wc, R);
print b, a, z, p, k;
Figure 65: Output from the DFDESIGN Call for a Bandpass Chebyshev Type I Filter
| b |
|---|
| 0.0037152 |
| 0 |
| -0.014861 |
| 0 |
| 0.0222909 |
| 0 |
| -0.014861 |
| 0 |
| 0.0037152 |
| a |
|---|
| 1 |
| -3.462207 |
| 7.4548292 |
| -10.79509 |
| 11.963721 |
| -9.807116 |
| 6.1401745 |
| -2.569975 |
| 0.6760721 |
| z | |
|---|---|
| 1 | 5.551E-17 |
| 1 | 5.551E-17 |
| 1 | 5.551E-17 |
| 1 | 5.551E-17 |
| -1 | 0 |
| -1 | 0 |
| -1 | 0 |
| -1 | 0 |
| p | |
|---|---|
| 0.782414 | -0.591889 |
| 0.6189827 | -0.704573 |
| 0.6189827 | 0.7045725 |
| 0.782414 | 0.5918888 |
| 0.0318287 | 0.9683203 |
| 0.297878 | 0.8729537 |
| 0.297878 | -0.872954 |
| 0.0318287 | -0.96832 |
| k |
|---|
| 0.0037152 |
The output of the DFDESIGN call b, a, z, p, and k consists of the numerator and denominator coefficients, zeros, poles, and gain of the designed filter’s transfer function. This output can be used in the DFFILT and DFSOSFILT functions to filter a time series. To confirm that the designed filter meets your design specifications, you can use the DFFREQZ, DFFREQZZPK, DFSOSFREQZ, or DFSOSFREQZZPK function to generate the designed filter’s frequency response and visualize it.