dsp.CoupledAllpassFilter

Coupled allpass IIR filter

Description

The dsp.CoupledAllpassFilter object implements a coupled allpass filter structure composed of two allpass filters connected in parallel. Each allpass branch can contain multiple sections. The overall filter output is computed by adding the output of the two respective branches. An optional second output can also be returned, which is power complementary to the first. For example, from the frequency domain perspective, if the first output implements a lowpass filter, the second output implements the power complementary highpass filter. For real signals, the power complementary output is computed by subtracting the output of the second branch from the first. dsp.CoupledAllpassFilter supports double- and single-precision floating point and allows you to choose between different realization structures. This System object™ also supports complex coefficients, multichannel variable length input, and tunable filter coefficient values.

To filter each channel of the input:

Create the dsp.CoupledAllpassFilter 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

Syntax

caf = dsp.CoupledAllpassFilter

caf = dsp.CoupledAllpassFilter(AllpassCoeffs1,AllpassCoeffs2)

caf = dsp.CoupledAllpassFilter(struc,AllpassCoeffs1,AllpassCoeffs2)

caf = dsp.CoupledAllpassFilter(Name,Value)

Description

caf = dsp.CoupledAllpassFilter returns a coupled allpass filter System object, caf, that filters each channel of the input signal independently. The coupled allpass filter uses the default inner structures and coefficients.

caf = dsp.CoupledAllpassFilter(AllpassCoeffs1,AllpassCoeffs2) returns a coupled allpass filter System object, caf, with Structure set to 'Minimum multiplier', AllpassCoefficients1 set to AllpassCoeffs1, and AllpassCoefficients2 set to AllpassCoeffs2.

example

caf = dsp.CoupledAllpassFilter(struc,AllpassCoeffs1,AllpassCoeffs2) returns a coupled allpass filter System object, caf, with Structure set to struc and the relevant coefficients set to AllpassCoeffs1 and AllpassCoeffs2. struc can be 'Minimum multiplier' | 'Wave Digital Filter' | 'Lattice'.

caf = dsp.CoupledAllpassFilter(Name,Value) returns a Coupled allpass filter System object, caf, with each property set to the specified value.

Properties

expand all

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` — Internal structure of allpass branches
`'Minimum multiplier'` (default) | `'Wave Digital Filter'` | `'Lattice'`

Specify the internal structure of allpass branches as one of 'Minimum multiplier', 'Wave Digital Filter', or 'Lattice'. Each structure uses a different pair of coefficient values, independently stored in the relevant object property.

`AllpassCoefficients1` — Allpass polynomial coefficients of branch 1
`[0 0.5]` (default) | row vector | cell array

Specify the polynomial filter coefficients for the first allpass branch. This property can accept values either in the form of a row vector (single-section configuration) or a cell array with as many cells as filter sections.

Tunable: Yes

Dependencies

This property is applicable only if you set the Structure property to 'Minimum multiplier'.

Data Types: single | double

`WDFCoefficients1` — Wave Digital Filter coefficients of branch 1
`[0.5 0]` (default) | row vector | cell array

Specify the Wave Digital Filter coefficients for the first allpass branch. This property can accept values either in the form of a row vector (single-section configuration) or a cell array with as many cells as filter sections.

Tunable: Yes

Dependencies

This property is applicable only if you set the Structure property to 'Wave Digital Filter'.

Data Types: single | double

`LatticeCoefficients1` — Lattice coefficients of branch 1
`[0.5 0]` (default) | row vector | cell array

Specify the allpass lattice coefficients for the first allpass branch. This property can accept values either in the form of a row vector (single-section configuration) or a cell array with as many cells as filter sections.

Tunable: Yes

Dependencies

This property is applicable only if you set the Structure property to 'Lattice'.

Data Types: single | double

`Delay` — Length in samples for branch 1
`0` (default) | positive integer scalar

Integer number of the delay taps in the top branch, specified as a positive integer scalar.

Tunable: Yes

Dependencies

This property is applicable only if you set the PureDelayBranch property to true.

`Gain1` — Independent Branch 1 Phase Gain
`1` (default) | `'–1'` | `'0+i'` | `'0–i'`

Gain1 is the individual branch phase gain. This property can accept only values equal to '1', '–1', '0+i', or '0–i'. This property is nontunable.

Data Types: char

`AllpassCoefficients2` — Allpass polynomial coefficients of branch 2
`{[ ]}` (default) | row vector | cell array

Specify the polynomial filter coefficients for the second allpass branch. This property can accept values either in the form of a row vector (single-section configuration) or a cell array with as many cells as filter sections.

Tunable: Yes

Dependencies

This property is applicable only if you set the Structure property to 'Minimum multiplier'.

Data Types: single | double

`WDFCoefficients2` — Wave Digital Filter coefficients of branch 2
`{[ ]}` (default) | row vector | cell array

Specify the Wave Digital Filter coefficients for the second allpass branch. This property can accept values either in the form of a row vector (single-section configuration) or a cell array with as many cells as filter sections.

Tunable: Yes

Dependencies

This property is applicable only if you set the Structure property to 'Wave Digital Filter'.

Data Types: single | double

`LatticeCoefficients2` — Lattice coefficients of branch 2
`{[ ]}` (default) | row vector | cell array

Specify the allpass lattice coefficients for the second allpass branch. This property can accept values either in the form of a row vector (single-section configuration) or a cell array with as many cells as filter sections.

Tunable: Yes

Dependencies

This property is applicable only if you set the Structure property to 'Lattice'.

Data Types: single | double

`Gain2` — Independent Branch 2 Phase Gain
`'1'` (default) | `'–1'` | `'0+1i'` | `'0–1i'`

Specify the value of the independent phase gain applied to branch 2. This property can accept only values equal to '1', '–1', '0+i', or '0–i'. This property is nontunable.

Data Types: char

`Beta` — Coupled phase gain
`1` (default) | complex value with magnitude equal to 1

Specify the value of the phasor gain in complex conjugate form, in each of the two branches, and in complex coefficient configuration. The absolute value of this property should be 1 and its default value is 1.

Tunable: Yes

Dependencies

This property is applicable only when the selected Structure property supports complex coefficients.

Data Types: single | double

`PureDelayBranch` — Replace allpass filter in first branch with pure delay
`false` (default) | `true`

If you set PureDelayBranch to true, the property holding the coefficients for the first allpass branch is disabled and Delay becomes enabled. You can use this property to improve performance, when one of the two allpass branches is known to be a pure delay (e.g. for halfband filter designs)

Data Types: logical

`ComplexConjugateCoefficients` — Allow inferring coefficients of second allpass branch as complex conjugate of first
`false` (default) | `true`

When the input signal is real, this property triggers the use of an optimized structural realization. This property enables providing complex coefficients for only the first branch. The coefficients for the second branch are automatically inferred as complex conjugate values of the first branch coefficients

Dependencies

This property is only enabled if the currently selected structure supports complex coefficients. Use it only if the filter coefficients are actually complex.

Data Types: logical

Usage

Syntax

y = caf(x)

[y,ypc] = caf(x)

Description

y = caf(x) filters the input signal x to produce the output y. When x is a matrix, each column is filtered independently as a separate channel over time.

example

[y,ypc] = caf(x) also returns ypc, the power complementary signal to the primary output y.

Input Arguments

expand all

`x` — Data input
vector | matrix

Data input, specified as a vector or a matrix. This object also accepts variable-size inputs. Once the object is locked, you can change the size of each input channel, but you cannot change the number of channels.

Data Types: single | double
Complex Number Support: Yes

Output Arguments

expand all

`y` — Lowpass filtered output
vector | matrix

Lowpass filtered output, returned as a vector or a matrix. The size and data type of the output signal matches that of the input signal.

Data Types: double | single
Complex Number Support: Yes

`ypc` — Highpass filtered output
vector | matrix

Power complimentary highpass filtered output, returned as a vector or a matrix. The size and data type of the output signal matches that of the input signal.

Data Types: double | single
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)

expand all

Specific to `dsp.CoupledAllpassFilter`

`getBranches`	Return internal allpass branches
`freqz`	Frequency response of discrete-time filter System object
`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
`grpdelay`	Group delay response of discrete-time filter System object

Common to All System Objects

`step`	Run System object algorithm
`release`	Release resources and allow changes to System object property values and input characteristics
`reset`	Reset internal states of System object

Examples

collapse all

Allpass Realization of a Butterworth Lowpass Filter

Open Script

Realize a Butterworth lowpass filter of order 3. Use a coupled allpass structure with inner minimum multiplier structure.

Fs = 48000;    % in Hz
Fc = 12000;    % in Hz
frameLength = 1024;
[b, a] = butter(3,2*Fc/Fs);
AExp = [freqz(b,a,frameLength/2); NaN];
[c1, c2] = tf2ca(b,a);
caf = dsp.CoupledAllpassFilter(c1(2:end),c2(2:end));
tfe = dsp.TransferFunctionEstimator('FrequencyRange', 'onesided',...
    'SpectralAverages', 2);
aplot = dsp.ArrayPlot('PlotType', 'Line',...
    'YLimits', [-40 5],...
    'YLabel', 'Magnitude (dB)',...
    'SampleIncrement', Fs/frameLength,...
    'XLabel', 'Frequency (Hz)',...
    'Title', 'Magnitude Response',...
    'ShowLegend', true,'ChannelNames',{'Actual','Expected'});
Niter = 200;
for k = 1:Niter
    in = randn(frameLength,1);
    out = caf(in);
    A = tfe(in,out);
    aplot(db([A,AExp]));
end

Allpass Realization of an Elliptic Highpass Filter

Open Script

Remove a low-frequency sinusoid using an elliptic highpass filter design implemented through a coupled allpass structure.

Initialize

Fs = 1000;
f1 = 50; f2 = 100;
Fpass = 70; Apass = 1;
Fstop = 60; Astop = 80;
filtSpecs = fdesign.highpass(Fstop,Fpass,Astop,Apass,Fs);
hpSpec = design(filtSpecs,'ellip','FilterStructure','cascadeallpass',...
    'SystemObject',true);
frameLength = 1000;
nFrames = 100;
sine   = dsp.SineWave('Frequency',[f1,f2],'SampleRate',Fs,...
  'SamplesPerFrame',frameLength); % Input composed of two sinusoids.

sa = spectrumAnalyzer('SampleRate',Fs,...
  'PlotAsTwoSidedSpectrum',false,'ShowLegend',true,...
  'Method','welch','AveragingMethod','exponential',...
  'Title','Original (Channel 1) Filtered (Channel 2)',...
  'ChannelNames',{'Original','Filtered'});

Simulate

for k = 1:1000
  original = sum(sine(),2); % Add the two sinusoids together
  filtered = hpSpec(original);
  sa([original,filtered]);
end
release(sa)

View Power Complementary Output of Coupled Allpass Filter

Open Live Script

Design a Butterworth lowpass filter of order 3. Use a coupled allpass structure with inner minimum multiplier structure.

Fs = 48000;    % in Hz
Fc = 12000;    % in Hz
frameLength = 1024;
[b,a] = butter(3,2*Fc/Fs);
AExp = [freqz(b,a,frameLength/2); NaN];
[c1,c2] = tf2ca(b,a);
caf = dsp.CoupledAllpassFilter(c1(2:end),c2(2:end));

Using the 'SubbandView' option of the dsp.CoupledAllpassFilter, you can visualize the lowpass filter output, the power complementary highpass filter output, or both using the fvtool.

To view the lowpass filter output, set 'SubbandView' to 1.

fvtool(caf,'SubbandView',1,'Fs',Fs)

To view the highpass filter output, set 'SubbandView' to 2.

fvtool(caf,'SubbandView',2,'Fs',Fs)

To view both the outputs, set 'SubbandView' to 'all', [1 2] or [1;2].

fvtool(caf,'SubbandView','all','Fs',Fs);

Algorithms

The following three figures summarize the main structures supported by dsp.CoupledAllpassFilter.

Minimum Multiplier and WDF
Lattice
Lattice with Complex Conjugate Coefficients

References

[1] Regalia, Philip A., Mitra, Sanjit K., and P.P Vaidyanathan “ The Digital All-Pass Filter: A Versatile Signal Processing Building Block.” Proceedings of the IEEE 1988, Vol. 76, No. 1, pp. 19–37.

[2] Mitra, Sanjit K., and James F. Kaiser, "Handbook for Digital Signal Processing" New York: John Wiley & Sons, 1993.

Version History

Introduced in R2013b

dsp.CoupledAllpassFilter

Description

Creation

Syntax

Description

Properties

Structure — Internal structure of allpass branches 'Minimum multiplier' (default) | 'Wave Digital Filter' | 'Lattice'

AllpassCoefficients1 — Allpass polynomial coefficients of branch 1 [0 0.5] (default) | row vector | cell array

Dependencies

WDFCoefficients1 — Wave Digital Filter coefficients of branch 1 [0.5 0] (default) | row vector | cell array

Dependencies

LatticeCoefficients1 — Lattice coefficients of branch 1 [0.5 0] (default) | row vector | cell array

Dependencies

Delay — Length in samples for branch 1 0 (default) | positive integer scalar

Dependencies

Gain1 — Independent Branch 1 Phase Gain 1 (default) | '–1' | '0+i' | '0–i'

AllpassCoefficients2 — Allpass polynomial coefficients of branch 2 {[ ]} (default) | row vector | cell array

Dependencies

WDFCoefficients2 — Wave Digital Filter coefficients of branch 2 {[ ]} (default) | row vector | cell array

Dependencies

LatticeCoefficients2 — Lattice coefficients of branch 2 {[ ]} (default) | row vector | cell array

Dependencies

Gain2 — Independent Branch 2 Phase Gain '1' (default) | '–1' | '0+1i' | '0–1i'

Beta — Coupled phase gain 1 (default) | complex value with magnitude equal to 1

Dependencies

PureDelayBranch — Replace allpass filter in first branch with pure delay false (default) | true

ComplexConjugateCoefficients — Allow inferring coefficients of second allpass branch as complex conjugate of first false (default) | true

Dependencies

Usage

Syntax

Description

Input Arguments

x — Data input vector | matrix

Output Arguments

y — Lowpass filtered output vector | matrix

ypc — Highpass filtered output vector | matrix

Object Functions

Specific to dsp.CoupledAllpassFilter

Common to All System Objects

Examples

Allpass Realization of a Butterworth Lowpass Filter

Allpass Realization of an Elliptic Highpass Filter

View Power Complementary Output of Coupled Allpass Filter

Algorithms

References

Version History

See Also

Functions

Objects

Topics

`Structure` — Internal structure of allpass branches
`'Minimum multiplier'` (default) | `'Wave Digital Filter'` | `'Lattice'`

`AllpassCoefficients1` — Allpass polynomial coefficients of branch 1
`[0 0.5]` (default) | row vector | cell array

`WDFCoefficients1` — Wave Digital Filter coefficients of branch 1
`[0.5 0]` (default) | row vector | cell array

`LatticeCoefficients1` — Lattice coefficients of branch 1
`[0.5 0]` (default) | row vector | cell array

`Delay` — Length in samples for branch 1
`0` (default) | positive integer scalar

`Gain1` — Independent Branch 1 Phase Gain
`1` (default) | `'–1'` | `'0+i'` | `'0–i'`

`AllpassCoefficients2` — Allpass polynomial coefficients of branch 2
`{[ ]}` (default) | row vector | cell array

`WDFCoefficients2` — Wave Digital Filter coefficients of branch 2
`{[ ]}` (default) | row vector | cell array

`LatticeCoefficients2` — Lattice coefficients of branch 2
`{[ ]}` (default) | row vector | cell array

`Gain2` — Independent Branch 2 Phase Gain
`'1'` (default) | `'–1'` | `'0+1i'` | `'0–1i'`

`Beta` — Coupled phase gain
`1` (default) | complex value with magnitude equal to 1

`PureDelayBranch` — Replace allpass filter in first branch with pure delay
`false` (default) | `true`

`ComplexConjugateCoefficients` — Allow inferring coefficients of second allpass branch as complex conjugate of first
`false` (default) | `true`

`x` — Data input
vector | matrix

`y` — Lowpass filtered output
vector | matrix

`ypc` — Highpass filtered output
vector | matrix

Specific to `dsp.CoupledAllpassFilter`