designBandstopIIR

Design and implement bandstop IIR filter

Since R2023b

Syntax

[B,A] = designBandstopIIR

[B,A] = designBandstopIIR(Name=Value)

[B,A,SV] = designBandstopIIR(Name=Value)

filtObj = designBandstopIIR(Name=Value)

Description

[B,A] = designBandstopIIR designs a bandstop IIR filter with the filter order of 10, lower 3-dB cutoff frequency of 0.25, and higher 3-dB cutoff frequency of 0.75. When you use this syntax, the function designs the IIR filter using the "default" window design method and does not compute the scale values.

B and A are the fourth-order section matrices of the size P-by-5, where P is the number of filter sections.

The System object™ argument is false by default. To implement the filter, assign the filter coefficients to a dsp.FourthOrderSectionFilter object.

[B,A] = designBandstopIIR(Name=Value) specifies options using one or more name-value arguments.

For example, [B,A] = designBandstopIIR(FilterOrder=30,HalfPowerFrequency1=0.3,HalfPowerFrequency2=0.8,DesignMethod="cheby1",CascadeSectionsForm="sos") designs a bandstop IIR filter with the filter order of 30, lower 3-dB cutoff frequency of 0.3, and higher 3-dB cutoff frequency of 0.8 by using the Chebyshev Type I window design method.

B and A are the second-order section matrices of the size P-by-3, where P is the number of filter sections.

When you specify only a partial list of filter parameters, the function designs the filter by setting the other design parameters to their default values.

When you specify any of the numeric input arguments in single precision, the function designs the filter coefficients in single precision. Alternatively, you can use the Datatype and like arguments to control the coefficients data type. (since R2024b)

The function supports three design methods. Each design method supports a specific set of design combinations. For more information, see DesignMethod.

[B,A,SV] = designBandstopIIR(Name=Value) also returns scale values when you specify the HasScaleValues argument. SV is a vector of 1s when you set the argument to false and a vector of scale values when you set it to true.

filtObj = designBandstopIIR(Name=Value) designs a bandstop IIR filter and implements a dsp.SOSFilter object or a dsp.FourthOrderSectionFilter object.

This syntax applies when you set the SystemObject argument to true.

Examples

Design and Implement Bandstop Chebyshev Type I IIR Filter using Fourth-Order Sections

Create a dsp.FourthOrderSectionFilter object.

fosFilt=dsp.FourthOrderSectionFilter

fosFilt = 
  FourthOrderSectionFilter with properties:

      Numerator: [1 0.1000 0.2000 0.3000 0.4000]
    Denominator: [1 0.1000 0.2000 0.3000 0.4000]

Create a spectrumAnalyzer object to visualize the spectra of the input and output signals.

spectrumScope = spectrumAnalyzer(SampleRate=96000,PlotAsTwoSidedSpectrum=false,...
    ChannelNames=["Input Signal","Filtered Signal"]);

Create a dsp.DynamicFilterVisualizer object to visualize the magnitude response of the varying filter.

filterViz = dsp.DynamicFilterVisualizer(NormalizedFrequency=true,YLimits=[-1000 200]);

Stream in random data and filter the signal using the dsp.FourthOrderSectionFilter object. Use the designBandstopIIR function to design the filter coefficients. By default, this function returns a P-by-5 matrix of numerator coefficients and a P-by-5 matrix of denominator coefficients. Assign these coefficients to the dsp.FourthOrderSectionFilter object.

Vary the higher 3-dB cutoff frequency of the filter during simulation. The designBandstopIIR function recomputes the coefficients based on the updated filter specifications. Redesign the fourth-order section filter using these updated coefficients. Visualize the spectra of the input and filtered signals using the spectrum analyzer.

F3dB2 = 0.6;
for idx = 1:500
    [b,a] = designBandstopIIR(FilterOrder=30,CascadeSectionsForm="fos",...
        HalfPowerFrequency1=0.25,...
        HalfPowerFrequency2=F3dB2,DesignMethod="cheby1");
    fosFilt.Numerator = b;
    fosFilt.Denominator = a;
    x = randn(1024,1);
    y = fosFilt(x);
    spectrumScope(x,y);
    filterViz(b,a);
    F3dB2 = F3dB2 + 0.0005;
end

Design and Implement Bandstop Butterworth IIR Filter using Second-Order Sections

Create a dsp.SOSFilter object, and set the CoefficientSource property to 'Input port' so that you can vary the coefficients of the SOS filter during simulation.

sosFilt = dsp.SOSFilter(CoefficientSource="Input port")

sosFilt = 
  dsp.SOSFilter with properties:

            Structure: 'Direct form II transposed'
    CoefficientSource: 'Input port'
       HasScaleValues: false

  Use get to show all properties

Create a spectrumAnalyzer object to visualize the spectra of the input and output signals.

spectrumScope = spectrumAnalyzer(SampleRate=96000,PlotAsTwoSidedSpectrum=false,...
    ChannelNames=["Input Signal","Filtered Signal"]);

Create a dsp.DynamicFilterVisualizer object to visualize the magnitude response of the varying filter.

filterViz = dsp.DynamicFilterVisualizer(NormalizedFrequency=true,YLimits=[-1000,150]);

Stream in random data and filter the signal using the dsp.SOSFilter object. Use the designBandstopIIR function to design the filter coefficients. When you set CascadeSectionsForm to "sos", this function returns a P-by-3 matrix of numerator coefficients and a P-by-3 matrix of denominator coefficients. Assign these coefficients to the dsp.SOSFilter object.

Vary the lower 3-dB cutoff frequency of the filter during simulation. The designBandstopIIR function recomputes the coefficients based on the updated filter specifications. Redesign the SOS filter using these updated coefficients. Visualize the spectra of the input and filtered signals using the spectrum analyzer.

F3dB1 = 0.25;
for idx = 1:500
    [b,a] = designBandstopIIR(FilterOrder=30,CascadeSectionsForm="sos",...
        HalfPowerFrequency1=F3dB1,...
        HalfPowerFrequency2=0.75,DesignMethod="butter");
    x = randn(1024,1);
    y = sosFilt(x,b,a);
    spectrumScope(x,y);
    filterViz(b,a);
    F3dB1 = F3dB1 + 0.0005;
end

Design and Implement Bandstop Chebyshev Type II IIR Filter Object

Design and implement a bandstop IIR filter object using the designBandstopIIR function. The function returns a dsp.FourthOrderSectionFilter object when you set the SystemObject argument to true. To design the filter in single-precision, use the Datatype or like argument. Alternatively, you can specify any of the numerical arguments in single-precision.

fosFilt = designBandstopIIR(FilterOrder=30,DesignMethod="cheby2",...
    Datatype="single",SystemObject=true)

fosFilt = 
  FourthOrderSectionFilter with properties:

      Numerator: [8x5 single]
    Denominator: [8x5 single]

Create a dsp.DynamicFilterVisualizer object to visualize the magnitude response of the filter.

filterViz = dsp.DynamicFilterVisualizer(NormalizedFrequency=true,YLimits=[-80 20]);
filterViz(fosFilt)

Create a spectrumAnalyzer object to visualize the spectra of the input and output signals.

spectrumScope = spectrumAnalyzer(SampleRate=44100,PlotAsTwoSidedSpectrum=false,...
    ChannelNames=["Input Signal","Filtered Signal"]);

Stream in random data and filter the signal using the dsp.FourthOrderSectionFilter object. Visualize the spectra of the input and filtered signals using the spectrum analyzer.

for idx = 1:50
    x = randn(1024,1);
    y = fosFilt(x);
    spectrumScope(x,y);
end

Input Arguments

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: designBandstopIIR(FilterOrder=30,HalfPowerFrequency1=0.3,HalfPowerFrequency2=0.7,SystemObject=true)

FilterOrder — Order of bandstop IIR filter

10 (default) | even nonnegative integer

Order of the bandstop IIR filter, N, specified as an even nonnegative integer.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

HalfPowerFrequency1 — Lower 3-dB cutoff frequency of bandstop IIR filter

0.25 (default) | scalar in the range (0,1]

Lower 3-dB cutoff frequency of the bandstop IIR filter, F3dB1, specified as a normalized scalar in the range (0,1].

The value of HalfPowerFrequency1 must be less than the value of HalfPowerFrequency2.

Data Types: single | double

HalfPowerFrequency2 — Higher 3-dB cutoff frequency of bandstop IIR filter

0.75 (default) | scalar in the range (0,1]

Higher 3-dB cutoff frequency of the bandstop IIR filter, F3dB2, specified as a normalized scalar in the range (0,1].

The value of HalfPowerFrequency1 must be less than the value of HalfPowerFrequency2.

Data Types: single | double

DesignMethod — Window design method

"default" (default) | "butter" | "cheby1" | "cheby2"

Window design method, specified as one of these options:

• "default" –– The function designs the bandpass IIR filter using one of these methods:

  • Chebyshev Type I method when you specify the PassBandRipple (APASS) argument

  • Chebyshev Type II method when you specify the StopbandAttenuation (ASTOP) argument

  • Butterworth method when you do not specify the PassBandRipple (APASS) and the StopbandAttenuation (ASTOP) arguments

• "butter" –– The function designs the bandpass IIR filter using the Butterworth design method. You can use this method when you specify one of these design specification combinations:

  • FilterOrder (N)

  • FilterOrder (N) and HalfPowerFrequency1 (F3dB1)

  • FilterOrder (N) and HalfPowerFrequency2 (F3dB2)

  • FilterOrder (N), HalfPowerFrequency1 (F3dB1), and HalfPowerFrequency2 (F3dB2)

• "cheby1" –– The function designs the bandpass IIR filter using the Chebyshev Type I design method. You can use this method when you specify one of these design specification combinations:

  • FilterOrder (N), HalfPowerFrequency1 (F3dB1), and PassBandRipple (APASS)

  • FilterOrder (N), HalfPowerFrequency2 (F3dB2), and PassBandRipple (APASS)

  • FilterOrder (N), HalfPowerFrequency1 (F3dB1), HalfPowerFrequency2 (F3dB2), and PassBandRipple (APASS)

• "cheby2" –– The function designs the bandpass IIR filter using the Chebyshev Type II design method. You can use this method when you specify one of these design specification combinations:

  • FilterOrder (N), HalfPowerFrequency1 (F3dB1), and StopbandAttenuation (ASTOP)

  • FilterOrder (N), HalfPowerFrequency2 (F3dB2), and StopbandAttenuation (ASTOP)

  • FilterOrder (N), HalfPowerFrequency1 (F3dB1), HalfPowerFrequency2 (F3dB2), and StopbandAttenuation (ASTOP)

Data Types: char | string

PassbandRipple — Passband ripple of IIR filter

1 (default) | positive scalar

Passband ripple of the IIR filter, APASS, specified as a positive scalar.

To specify the PassbandRipple argument, set DesignMethod to "default" or "cheby1".

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

StopbandAttenuation — Stopband attenuation of IIR filter

60 (default) | positive scalar

Stopband attenuation of the IIR filter, ASTOP, specified as a positive scalar.

To specify the StopbandAttenuation argument, set DesignMethod to "default" or "cheby2".

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

CascadeSectionsForm — Form of filter cascade sections

"fos" (default) | "sos"

Form of filter cascade sections, specified as one of these:

• "fos" –– The function designs the filter using the fourth-order section form and outputs the filter coefficients as P-by-5 matrices.

• "sos" –– The function designs the filter using the second-order section form and outputs the filter coefficients as P-by-3 matrices.

Data Types: char | string

HasScaleValues — Option to compute scale values

false (default) | true

Option to compute the scale values, SV, specified as true or false.

To set the HasScaleValues argument, set CascadeSectionsForm to "sos".

Data Types: logical

Datatype — Data type of filter coefficients by type name

"double" (default) | "single"

Since R2024b

Data type of the filter coefficients, specified by type name as "double" or "single".

You can use the Dataype or the like argument to specify the data type of the filter coefficients, but you cannot use both arguments at the same time.

If you specify the data type of the filter coefficients using this argument, the function ignores the data types of the other numeric arguments.

Data Types: char | string

like — Data type of filter coefficients by prototype

real floating-point value

Since R2024b

Data type of the filter coefficients, specified as a prototype of a real floating-point value.

You can use the Dataype or the like argument to specify the data type of filter coefficients, but you cannot use both arguments at the same time.

If you specify the data type of the filter coefficients using this argument, the function ignores the data types of the other numeric arguments.

Example: B = designBandstopIIR(FilterOrder=N,HalfPowerFrequency1=F3dB1,like=single(N))

Example: N = single(110); B = designBandstopIIR(FilterOrder=N,HalfPowerFrequency1=F3dB1,like=N)

Data Types: single | double

SystemObject — Option to create System object

false (default) | true

Option to create System object, specified as one of these:

• false –– The function returns second-order section matrices or fourth-order section matrices.

• true –– The function returns a dsp.SOSFilter object or a dsp.FourthOrderSectionFilter object.

Data Types: logical

Verbose — Option to print function call in MATLAB^®

false (default) | true

Option to print the entire function call in MATLAB, specified as one of these:

• false –– The function does not print the function call.

• true –– The function prints the entire function call including the default values of the Name=Value arguments that you did not specify when calling the function.

  Use this argument to view all the values used by the function to design and implement the filter.

Data Types: logical

Output Arguments

B — Numerator coefficients in second-order section form or fourth-order section form

P-by-3 matrix | P-by-5 matrix

Numerator coefficients of the bandstop IIR filter in one of these forms:

• Second-order section form –– B is a P-by-3 matrix, where P is the number of filter sections and equals ceil(FilterOrder/2).

• Fourth-order section form –– B is a P-by-5 matrix and P equals ceil(FilterOrder/4).

If you specify single-precision values in any of the input arguments, the function designs single-precision filter coefficients. (since R2024a)

If you specify the data type using the Datatype or the like argument, the function ignores the data types of the other numeric arguments. (since R2024b)

Data Types: single | double

A — Denominator coefficients in second-order section form or fourth-order section form

P-by-3 matrix | P-by-5 matrix

Denominator coefficients of the bandstop IIR filter in one of these forms:

• Second-order section form –– A is a P-by-3 matrix, where P is the number of filter sections and equals ceil(FilterOrder/2).

• Fourth-order section form –– A is a P-by-5 matrix and P equals ceil(FilterOrder/4).

The leading denominator coefficient is always 1.

If you specify single-precision values in any of the input arguments, the function designs single-precision filter coefficients. (since R2024a)

If you specify the data type using the Datatype or the like argument, the function ignores the data types of the other numeric arguments. (since R2024b)

Data Types: single | double

SV — Scale values for each section

(P+1)-by-1 vector

Scale values for each section, returned as a (P+1)-by-1 vector, where P is the number of filter sections and equals ceil(FilterOrder/2).

If you set HasScaleValues to false, SV is a vector of 1s of size (P+1)-by-1.

If you specify single-precision values in any of the input arguments, the function outputs the scale values in single precision. (since R2024a)

If you specify the data type using the Datatype or the like argument, the function ignores the data types of the other numeric arguments. (since R2024b)

Dependencies

To enable this output argument, set CascadeSectionsForm to "sos".

Data Types: single | double

filtObj — Bandstop IIR filter object

dsp.FourthOrderSectionFilter object | dsp.SOSFilter object

Bandstop IIR filter object, returned as a:

• dsp.FourthOrderSectionFilter object if CascadeSectionsForm is set to "fos".

• dsp.SOSFilter object if CascadeSectionsForm is set to "sos".

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

When you set the SystemObject argument to false, the function supports code generation with no limitations.

When you set the SystemObject argument to true, the inputs to the function must be constants when generating code.

This function supports strict single precision in generated code. If any of the input arguments are in single precision, or you use the Datatype and like arguments to specify single-precision (since R2024b), the code you generate uses strictly single-precision arithmetic. (since R2024a)

Version History

Introduced in R2023b

R2024b: Specify data type of filter coefficients explicitly

You can now specify the data type of filter coefficients explicitly using the Datatype and like arguments.

R2024a: Support for strict single precision

When you specify single-precision values in any of the input arguments, the function designs filter coefficients and scale values in single precision both in simulation and in generated code.