# dsp.SOSFilter

## Description

The `dsp.SOSFilter`

System object™ implements an IIR filter structure using second-order sections (SOS).

To implement an IIR filter structure using SOS:

Create the

`dsp.SOSFilter`

object and set its properties.Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

## Creation

### Description

returns a biquadratic
IIR filter System object, `sos`

= dsp.SOSFilter`sos`

, which independently filters each channel (column)
of the input over time using a specified biquadratic structure.

returns a biquadratic filter object with the `sos`

= dsp.SOSFilter(`num`

,`den`

)`Numerator`

property set
to `num`

and the `Denominator`

property set to
`den`

.

returns a biquadratic filter object with each property set to the specified value. Enclose
each property name in single quotes.`sos`

= dsp.SOSFilter(`Name,Value`

)

**Example: **```
sos = dsp.SOSFilter('CoefficientSource','Input
port')
```

## Properties

Unless otherwise indicated, properties are *nontunable*, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
`release`

function unlocks them.

If a property is *tunable*, you can change its value at
any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

`Structure`

— Filter structure

`'Direct form II transposed'`

(default) | `'Direct form I'`

| `'Direct form I transposed'`

| `'Direct form II'`

Filter structure, specified as one of `'Direct form I'`

,
`'Direct form I transposed'`

, `'Direct form II'`

, or
`'Direct form II transposed'`

.

`CoefficientSource`

— Source of filter coefficients

`'Property'`

(default) | `'Input port'`

Source of the filter coefficients, specified as one of the following:

`'Property'`

–– The filter coefficients are specified through the`Numerator`

,`Denominator`

, and`ScaleValues`

properties.`'Input port'`

–– The numerator coefficients, denominator coefficients, and the scale values are specified as inputs to the object while running the algorithm. For more details, see Usage.

`Numerator`

— Numerator coefficients of filter

[`0.0975 0.195 0.0975`

] (default) | *N*-by-3 matrix

Numerator coefficients of the filter, specified as an *N*-by-3
matrix, where *N* is the number of biquadratic sections.

The size of this property cannot be modified once you have run the System object algorithm. However, the coefficient values can change as the property is tunable.

**Tunable: **Yes

#### Dependencies

To enable this property, set the `CoefficientSource`

property
to `'Property'`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

**Complex Number Support: **Yes

`Denominator`

— Denominator coefficients of filter

[`1 -0.9428 0.3333`

] (default) | *N*-by-3 matrix

Denominator coefficients of the filter, specified as an *N*-by-3
matrix, where *N* is the number of biquadratic sections.

The leading denominator coefficient is always assumed to be 1. If any other value is specified in the first column, the object ignores this value and treats it as 1.

The size of this property cannot be modified once you step through the algorithm. However, the denominator values can be modified as the property is tunable.

**Tunable: **Yes

#### Dependencies

To enable this property, set `CoefficientSource`

property to
`'Property'`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

**Complex Number Support: **Yes

`HasScaleValues`

— Specify if filter has scale values for each section

`false`

(default) | `true`

Specify if the filter has scale values for each section. When set to
`true`

, using the `ScaleValues`

property, you can
specify the scale values to be applied before and after each section of the biquadratic
filter.

`ScaleValues`

— Scale values for each biquad second-order section

[`1 1`

] (default) | vector

Scale values to apply before and after each section of a biquadratic filter,
specified as a vector. The length of the `ScaleValues`

vector must be *N* + 1, where *N* is the number of
biqaudratic sections. If you set this property to a scalar value, the scalar value is
used as the gain value only before the first filter section. The remaining gain values
are set to `1`

. If you set this property to a vector of
*N* + 1 values, each value is used for a separate section of the
filter.

**Tunable: **Yes

#### Dependencies

This property applies only when you set the `CoefficientSource`

property to `'Property'`

and `HasScaleValues`

property to `true`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

### Fixed-Point Properties

`RoundingMethod`

— Rounding method for fixed-point operations

`'Floor'`

(default) | `'Ceiling'`

| `'Convergent'`

| `'Nearest'`

| `'Round'`

| `'Simplest'`

| `'Zero'`

Rounding method for fixed-point operations, specified as one of the following:

`'Floor'`

`'Ceiling'`

`'Convergent'`

`'Nearest'`

`'Round'`

`'Simplest'`

`'Zero'`

For more details, see Rounding Modes.

`OverflowAction`

— Overflow action for fixed-point operations

`Wrap`

(default) | `Saturate`

Overflow action for fixed-point operations, specified as one of the following:

`'Wrap'`

–– The object wraps the result of its fixed-point operations.`'Saturate'`

–– The object saturates the result of its fixed-point operations.

For more details on overflow actions, see Overflow Handling for fixed-point operations.

`SectionInputDataType`

— Section input word- and fraction-length designations

`'Same as input'`

(default) | `numerictype`

object

Section input word- and fraction-length designations, specified as either
`'Same as input'`

or a `numerictype`

(Fixed-Point Designer) object.

When specified as a `numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias.

#### Dependencies

This property applies only when you set the `HasScaleValues`

property to `true`

.

`SectionOutputDataType`

— Section output word- and fraction-length designations

`'Same as section input'`

(default) | `numerictype`

object

Section output word- and fraction-length designations, specified as either
`'Same as section input'`

or a `numerictype`

(Fixed-Point Designer) object.

When specified as a `numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias.

#### Dependencies

This property applies only when you set the `HasScaleValues`

property to `true`

.

`NumeratorDataType`

— Numerator coefficients word- and fraction-length designations

`'Same word length as input'`

(default) | `numerictype`

object

Numerator coefficients word- and fraction-length designations, specified as either
`'Same word length as input'`

or as a
`numerictype`

object.

When specified as a `numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias. If not specified, the
fraction length is determined based on the numerator coefficient values to give the
best possible precision.

#### Dependencies

This property applies only when you set the
`CoefficientSource`

property to
`'Property'`

.

`DenominatorDataType`

— Denominator coefficients word- and fraction-length designations

`'Same word length as input'`

(default) | `numerictype`

object

Denominator coefficients word- and fraction-length designations, specified as
either `'Same word length as input'`

or as a
`numerictype`

object.

When specified as a `numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias. If not specified, the
fraction length is determined based on the denominator coefficient values to give the
best possible precision.

#### Dependencies

This property applies only when you set the
`CoefficientSource`

property to
`'Property'`

.

`ScaleValuesDataType`

— Scale values word- and fraction-length designations

`'Same word length as input'`

(default) | `numerictype`

object

Scale values word- and fraction-length designations, specified as either
`'Same word length as input'`

or as a
`numerictype`

object.

When specified as a `numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias. If not specified, the
fraction length is determined based on the scale values to give the best possible
precision.

#### Dependencies

This property applies only when you set the
`CoefficientSource`

property to `'Property'`

and `HasScaleValues`

property to `true`

.

`MultiplicandDataType`

— Multiplicand word- and fraction-length designations

`'Same as output'`

(default) | `numerictype`

object

Multiplicand word- and fraction-length designations, specified as either
`'Same as output'`

or as a `numerictype`

object.

When specified as a `numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias.

#### Dependencies

This property applies only when you set the `Structure`

property to `'Direct form I transposed'`

.

`StateDataType`

— State word- and fraction-length designations

`'Full precision'`

(default) | `numerictype`

object

State word- and fraction-length designations, specified as either ```
'Full
precision'
```

or as a `numerictype`

object.

`numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias.

#### Dependencies

This property applies only when you set the `Structure`

property to `'Direct form II'`

.

`DenominatorAccumulatorDataType`

— Denominator accumulator word- and fraction-length designations

`numerictype(1,64,48)`

(default) | `numerictype`

object

Denominator accumulator word- and fraction-length designations, specified as a
`numerictype`

object.

`OutputDataType`

— Output word- and fraction-length designations

`'Full precision'`

(default) | `numerictype`

object

Output word- and fraction-length designations, specified as either ```
'Full
precision'
```

or as a `numerictype`

object.

`numerictype`

object, the data type must be
signed fixed point with a power-of-two slope and zero bias.

## Usage

### Description

### Input Arguments

`x`

— Data input

vector | matrix

Data input, specified as a vector or a matrix.

This object also accepts variable-size inputs. Once you have run the System object algorithm, you can change the size of each input channel, but you cannot change the number of channels.

If the input is fixed-point, it must be signed fixed point with a power-of-two slope and zero bias. When the fraction length is not specified, the object determines the fraction length based on the input data to give the best possible precision.

The data type of all inputs must be the same.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `fi`

**Complex Number Support: **Yes

`num`

— Numerator coefficients

*N*-by-3 matrix

Numerator coefficients, specified as an *N*-by-3 matrix, where
*N* is the number of biquadratic sections.

Once you step through the algorithm, the size of this input cannot be modified. However, the numerator coefficient values can be modified as the input is tunable.

If `num`

is fixed-point, it must be signed fixed point with a
power-of-two slope and zero bias. When the fraction length is not specified, the
object determines the fraction length based on the numerator coefficient values to
give the best possible precision.

The data type of all inputs must be the same.

The size and complexity of the `num`

and
`den`

inputs must be the same.

**Tunable: **Yes

#### Dependencies

This input applies only when you set the `CoefficientSource`

property to `'Input port'`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `fi`

**Complex Number Support: **Yes

`den`

— Denominator coefficients

*N*-by-3 matrix

Denominator coefficients of the filter, specified as an *N*-by-3
matrix, where *N* is the number of biquadratic sections.

The leading denominator coefficient is always assumed to be 1. If any other value is specified in the first column, the object ignores this value and treats it as 1.

The size of this input cannot be modified once you step through the algorithm. However, the denominator values can be modified as the input is tunable.

If `den`

is fixed-point, it must be signed fixed point with a
power-of-two slope and zero bias. When the fraction length is not specified, the
object determines the fraction length based on the denominator coefficient values to
give the best possible precision.

The data type of all inputs must be the same.

The size and complexity of the `num`

and
`den`

inputs must be the same.

**Tunable: **Yes

#### Dependencies

This input applies only when you set the `CoefficientSource`

property to `'Input port'`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `fi`

**Complex Number Support: **Yes

`g`

— Scale values for each biquad second-order section

1-by-(*N *+1) vector

Scale values of the biquadratic filter, specified as a
1-by-(*N*+1) vector, where *N* is the number of
biquadratic filter sections.

If `g`

is fixed-point, it must be signed fixed point with a
power-of-two slope and zero bias. When the fraction length is not specified, the
object determines the fraction length based on the scale values to give the best
possible precision.

The data type of all inputs must be the same.

**Tunable: **Yes

#### Dependencies

This input applies only when you set the `CoefficientSource`

property to `'Input port'`

and `HasScaleValues`

property to `true`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `fi`

### Output Arguments

`y`

— Filtered output

vector | matrix

Filtered output, returned as a vector or a matrix. The size and complexity of the output signal matches that of the input signal.

The data type of the output is determined based on the value of the
`OutputDataType`

property. If set to ```
'Full
precision'
```

, the output data type is computed based on the signal flow
diagrams shown in the Fixed-Point
Conversion section. If set to a custom numeric type, the output data type is
cast to the specified numeric type.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `fi`

**Complex Number Support: **Yes

## Object Functions

To use an object function, specify the
System object as the first input argument. For
example, to release system resources of a System object named `obj`

, use
this syntax:

release(obj)

### Specific to `dsp.SOSFilter`

`freqz` | Frequency response of discrete-time filter System object |

`fvtool` | Visualize frequency response of DSP filters |

`impz` | Impulse response of discrete-time filter System object |

`info` | Information about filter System object |

`coeffs` | Returns the filter System object coefficients in a structure |

`cost` | Estimate cost of implementing filter System object |

`scale` | Scale second-order sections |

`scaleopts` | Create an options object for second-order section scaling |

`scalecheck` | Check scaling of biquadratic filter |

`cumsec` | Cumulative second-order section of the biquadratic filter |

`tf` | Convert discrete-time filter System object to transfer function |

`reorder` | Reorder second-order sections of biquadratic filter System object |

## Examples

### Remove High-Frequency Noise Using Biquad SOS Filter

Lowpass filter a noisy sinusoidal signal using the `dsp.SOSFilter`

System object. Visualize the original and filtered signals using a spectrum analyzer.

**Input Signal**

The input signal is a sinusoidal signal with two tones, one at 1 kHz and the other at 3 kHz. The sampling frequency is 8 kHz.

f1 = 1000; f2 = 3000; Fs = 8000; sine = dsp.SineWave('Frequency',[f1,f2],... 'SampleRate',Fs,... 'SamplesPerFrame',1024);

**Create Biquad SOS Filter**

Design a 10th-order lowpass Butterworth IIR filter with a cutoff frequency of 2 kHz. The numerator and denominator coefficients are extracted from the designed SOS matrix.

Fcutoff = 2000; [z,p,k] = butter(10,Fcutoff/(Fs/2)); [s, g] = zp2sos(z,p,k); num = s(:,1:3); den = s(:,4:6); sosFilter = dsp.SOSFilter(num,den,... 'HasScaleValues',true,... 'ScaleValues',g)

sosFilter = dsp.SOSFilter with properties: Structure: 'Direct form II transposed' CoefficientSource: 'Property' Numerator: [5x3 double] Denominator: [5x3 double] HasScaleValues: true ScaleValues: [0.0029 1 1 1 1 1] Show all properties

Visualize the frequency response of the designed SOS filter.

`fvtool(sosFilter,'Fs',8000)`

**Streaming**

Add zero-mean white Gaussian noise with a standard deviation of 0.1 to the sum of sine waves. Filter the noisy sinusoidal signal with the designed SOS filter.

While running the simulation, the spectrum analyzer shows that the high-frequency tone above 2 kHz in the source signal is attenuated. The resulting signal maintains the peak at 1 kHz because it falls in the passband of the lowpass filter.

SA = spectrumAnalyzer(... 'PlotAsTwoSidedSpectrum',false, ... 'SampleRate',Fs, ... 'ShowLegend',true,... 'YLimits',[-200 100],... 'ChannelNames',{'Input signal','Filtered signal'}); % Stream processing loop for k = 1:100 input = sum(sine(),2) + 0.1.*randn(sine.SamplesPerFrame,1); filteredOutput = sosFilter(input); SA(input,filteredOutput); end

### Design a Time-Varying Lowpass IIR Filter

Design a lowpass biquadratic SOS filter with time-varying coefficients. Visualize the magnitude response of the filter using a dynamic filter visualizer.

`dfv = dsp.DynamicFilterVisualizer('YLimits',[-120 10])`

dfv = dsp.DynamicFilterVisualizer with properties: FFTLength: 2048 NormalizedFrequency: 0 SampleRate: 44100 FrequencyRange: [0 22050] XScale: 'Linear' MagnitudeDisplay: 'Magnitude (dB)' PlotAsMagnitudePhase: 0 PlotType: 'Line' AxesScaling: 'Manual' Show all properties

Create a `dsp.SOSFilter`

object.

sosfilt = dsp.SOSFilter

sosfilt = dsp.SOSFilter with properties: Structure: 'Direct form II transposed' CoefficientSource: 'Property' Numerator: [0.0975 0.1950 0.0975] Denominator: [1 -0.9428 0.3333] HasScaleValues: false Show all properties

Use the `maxflat`

function to design a lowpass maximally flat filter. Set the numerator and denominator order of the filter to 2 since the SOS filter is biquadratic. Vary the cutoff frequency in 0.001 increments and design the filter for each increment. Pass the computed coefficients to the SOS filter. Visualize the time-varying magnitude response of the SOS filter using the `dsp.DynamicFilterVisualizer`

object.

for Wn = 0.1:0.001:0.6 [b,a] = maxflat(2,2,Wn); sosfilt.Numerator = b; sosfilt.Denominator = a; dfv(sosfilt) end

## More About

### Fixed Point

These diagrams show the data types used in the `dsp.SOSFilter`

object when the input is fixed-point. For each filter structure
the object supports, the data types shown in the diagrams can be set through the respective
fixed-point properties of the object.

**Direct Form I**

This diagram shows the data types for one section of the filter for fixed-point
signals. The gain operations *b _{0}*,

*b*,

_{1}*b*,

_{2}*a*, and

_{1}*a*operate in full precision.

_{2}These diagrams show the fixed-point data types between filter sections.

When the data is not optimized:

When you specify scale values to 1:

**Direct Form I Transposed**

This diagram shows the data types for one section of the filter for fixed-point
signals. The dashed casts are omitted when you set `HasScaleValues`

to
`false`

. The gain operations
*b _{0}*,

*b*,

_{1}*b*,

_{2}*a*, and

_{1}*a*operate in full precision.

_{2}These diagrams show the fixed-point data types between filter sections.

When the data is not optimized:

When you specify scale values to 1:

**Direct Form II**

This diagram shows the data types for one section of the filter for fixed-point
signals. The dashed casts are omitted when you set `HasScaleValues`

to
`false`

. The gain operations
*b _{0}*,

*b*,

_{1}*b*,

_{2}*a*, and

_{1}*a*operate in full precision.

_{2}These diagrams show the fixed-point data types between filter sections.

When the data is not optimized:

When you set scale values to 1:

**Direct Form II Transposed**

This diagram shows the data types for one section of the filter for fixed-point
signals. The gain operations *b _{0}*,

*b*,

_{1}*b*,

_{2}*a*, and

_{1}*a*operate in full precision. When you set

_{2}`HasScaleValues`

to `false`

, the data type at the
section output is automatically determined by the object algorithm and is not controlled
by the value of the `SectionOutputDataType`

property.These diagrams show the fixed-point data types between filter sections.

When the data is not optimized:

When you specify scale values to 1:

## Extended Capabilities

### C/C++ Code Generation

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

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).

The `dsp.SOSFilter`

System object supports optimized C code generation on ARM^{®}
Cortex^{®}-M processors under these conditions:

Input is a single-channel real-valued signal.

When you set

`CoefficientSource`

to`'Property'`

or`'Input port'`

.Data type of the input is

`single`

.When you set

`Structure`

to`'Direct form I'`

or`'Direct form II transposed'`

.When you set

`HasScaleValues`

to`false`

after setting`CoefficientSource`

to`'Input port'`

.

## Version History

**Introduced in R2020a**

### R2022b: Optimized C code generation for `dsp.SOSFilter`

object on ARM Cortex-M processors

In R2022b, you can generate optimized C code for the `dsp.SOSFilter`

object
on ARM
Cortex-M processors under certain conditions. For more details, see Code Generation.

## See Also

### Functions

### Objects

### Blocks

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)