# dsp.ParametricEQFilter

(To be removed) Tunable second-order parametric equalizer filter

## Compatibility

The `dsp.ParametricEQFilter` object will be removed in a future release. Existing instances of the object will continue to run. For new code, use the `designParamEQ` function from Audio Toolbox™ instead. For more information, see Compatibility Considerations.

## Description

The `ParametricEQFilter` object is a tunable, second-order parametric equalizer filter.

To apply the filter to each channel of the input:

1. Define and set up your equalizer filter. See Construction.

2. Call `step` to filter each channel according to the properties of `dsp.ParametricEQFilter`. The behavior of `step` is specific to each object in the toolbox.

### Note

Starting in R2016b, instead of using the `step` method to perform the operation defined by the System object™, you can call the object with arguments, as if it were a function. For example, `y = step(obj,x)` and `y = obj(x)` perform equivalent operations.

## Construction

`H = dsp.ParametricEQFilter` returns a second-order parametric equalizer filter that independently filters each channel of the input over time, using the default values for `Bandwidth`, `CenterFrequency`, and `PeakGaindB`. The `center frequency` and `bandwidth` are specified in Hz and are tunable. The ```peak gain``` (dip) is specified in dB and is also tunable. The `bandwidth` is measured at the arithmetic mean between the `peak gain` in absolute power units and one.

```H = dsp.ParametricEQFilter('Specification', 'Quality factor and center frequency')``` specifies the quality factor (Q factor) of the filter. The `Q factor` is defined as the center frequency/bandwidth. A higher `Q factor` corresponds to a narrower peak/dip. The Q factor should be a scalar value greater than 0. The Q factor is tunable.

`H = dsp.ParametricEQFilter('Specification', 'Coefficients')` specifies the gain values for the bandwidth and center frequency. This removes the trigonometry calculations involved when the properties are tuned. The `CenterFrequencyCoefficient` should be a scalar between -1 and 1, with -1 corresponding to 0 Hz, and 1 corresponding to the Nyquist frequency. The `BandwidthCoefficient` should be a scalar between -1 and 1, with -1 corresponding to the largest bandwidth, and 1 corresponding to the smallest bandwidth. In this mode, the peak gain is specified in linear units rather than dB.

`H = dsp.ParametricEQFilter('Name', Value, ...)` returns a parametric equalizer filter with each specified property name set to the specified value. You can specify several name-value pair arguments in any order as `('Name1',Value1,...,'NameN',ValueN)`.

## Properties

 `Specification` Design parameters or coefficients that specify the filter Choose one of the following `Specification` values. Use the corresponding tunable properties to specify the filter: `Bandwidth and center frequency` — Use `Bandwidth`, `CenterFrequency`, and `PeakGaindB`.`Quality factor and center frequency` — Use `QualityFactor`, `CenterFrequency`, and `PeakGaindB`.`Coefficients` — Use `BandwidthCoefficient`, `CenterFrequencyCoefficient`, and `PeakGain`. The default value is `Bandwidth and center frequency`. Using `Coefficients` specifies gain values for the bandwidth and center frequency. This approach does not require the trigonometric calculations of the other two approaches where design parameters are specified in Hz.
 `Bandwidth` bandwidth of filter Specify the bandwidth of the filter as a finite positive numeric scalar that is less than half the sample rate of the input signal, in Hz. This property is applicable if `Specification` is set to ```Bandwidth and center frequency```. The default is 2205 Hz. This property is tunable.
 `BandwidthCoefficient` Coefficient for bandwidth of filter Specify the value that determines the filter's bandwidth as a finite numeric scalar in the range `[-1 1]`: `-1` corresponds to the maximum bandwidth (`SampleRate`/4).`1` corresponds to the minimum bandwidth (0 Hz, that is, an allpass filter). This property is only applicable if `Specification` is set to `Coefficients`. The default is 0.72654. This property is tunable.
 `CenterFrequency` Center frequency of the filter Specify the filter's center frequency as a finite positive numeric scalar that is less than half the sample rate of the input signal, in Hz. This property is only applicable if `Specification` is set to ```Bandwidth and center frequency``` or ```Quality factor and center frequency```. The default is `11025` Hz. This property is tunable.
 `CenterFrequencyCoefficient` Coefficient for center frequency of filter Specify the value that determines the filter's center frequency as a finite numeric scalar between -1 and 1: -1 corresponds to the minimum center frequency (0 Hz).1 corresponds to the maximum center frequency (`SampleRate`/2 Hz). This property is only applicable if `Specification` is set to `Coefficients`. The default is `0`, which corresponds to `SampleRate`/4 Hz. This property is tunable.
 `PeakGain` Peak or dip gain of the filter in linear units Specify the filter’s peak or dip gain in linear units. A value greater than one boosts the signal. A value less than one attenuates the signal. The default is 2 (6.0206 dB). This property is tunable.
 `PeakGaindB` Peak or dip gain of the filter in dB Specify the filter’s peak or dip gain in dB. A positive value boosts the signal. A negative value attenuates the signal. The default is `6.0206` dB. This property is tunable.
 `QualityFactor` Quality factor of the parametric EQ filter Specify the Quality factor (Q factor) of the filter. The Q factor is defined as the center frequency divided by the bandwidth. A higher Q factor corresponds to a narrower peak or dip. This property is only applicable if `Specification` is set to ```Quality factor and center frequency```. The default value is 5. This property is tunable.
 `SampleRate` Input sample rate Specify the sample rate of the input as a finite numeric scalar, in Hz. The default is `44100` Hz.

## Methods

 getBandwidth Convert quality factor or bandwidth coefficient to bandwidth in Hz getCenterFrequency Convert center frequency coefficient to frequency in Hz getOctaveBandwidth Measure bandwidth of parametric equalizer filter in octaves getPeakGain Convert peak or notch gain from dB to absolute units getPeakGaindB Convert peak or notch gain from absolute units to dB getQualityFactor Convert bandwidth to quality factor reset Reset states of `ParametricEQFilter` object step Filter input with `ParametricEQFilter` object tf Compute transfer function
Common to All System Objects
`release`

Allow System object property value changes

## Examples

collapse all

Create a `ParametricEQFilter` object where the center frequency and bandwidth of the equalizer filter are 5000 Hz and 500 Hz respectively. The sample rate for the filter is the default, 44,100 Hz.

```h = dsp.ParametricEQFilter('CenterFrequency',5000,... 'Bandwidth',500); ```

Create objects to estimate and display the transfer function of the filter.

```htf = dsp.TransferFunctionEstimator('FrequencyRange','onesided',... 'SpectralAverages',50); hplot = dsp.ArrayPlot('PlotType','Line','YLimits',[-15 15],... 'SampleIncrement',44100/1024); ```

Generate a random signal and filter the signal.

```for i=1:1000 x = randn(1024,1); % Random signal y = h(x); % Filter signal H = htf(x,y); % Estimate transfer function magdB = 20*log10(abs(H));% Convert to dB hplot(magdB); % Display transfer function if (i==1) % Pause to display initial transfer function pause; end if (i==500) % Tune filter h.CenterFrequency = 10000; h.Bandwidth = 2000; h.PeakGaindB = -10; end end```

The software displays the initial transfer function estimate.

To continue, press any key.

At `i=500`, the filter is tuned. The center frequency, bandwidth, and peak gain of the filter now have different values. The software displays the new transfer function.

## Algorithm

The parametric equalizer is formed by a linear combination of a peak and a notch filter. See the Algorithm section of `dsp.NotchPeakFilter` for details.

`$H\left(z\right)={H}_{notch}\left(z\right)+G{H}_{peak}\left(z\right)$`

Here is a graph of the two cases (boost and cut) of the magnitude squared of the transfer functions:

The transfer function can be written as:

`$\begin{array}{l}H\left(z\right)=\frac{\left(\frac{1+G\gamma }{1+\gamma }\right)-2\left(\frac{\mathrm{cos}{\omega }_{0}}{1+\gamma }\right){z}^{-1}+\left(\frac{1-G\gamma }{1+\gamma }\right){z}^{-2}}{1-2\left(\frac{\mathrm{cos}{\omega }_{0}}{1+\gamma }\right){z}^{-1}+\left(\frac{1-\gamma }{1+\gamma }\right){z}^{-2}}\\ where\\ \gamma =\mathrm{tan}\left(\frac{\Delta \omega }{2}\right)\\ and\\ {G}_{B}{}^{2}=\frac{1+{G}^{2}}{2}\end{array}$`

G is the parametric equalizer gain, and GB is the bandwidth gain, that is, the gain level at which the bandwidth Δω is measured.

The `dsp.NotchPeakFilter` that does most of the work is implemented in a decoupled way so that the center frequency can be tuned independently from the bandwidth. Note that the Q factor is defined as center frequency/bandwidth.

## References

[1] Orfanidis, Sophocles J. Introduction to Signal Processing Upper Saddle River, NJ: Prentice-Hall, 1996

## Compatibility Considerations

expand all

Warns starting in R2019a

Watch now