Main Content

dsp.FIRHalfbandDecimator

Halfband decimator

Description

The dsp.FIRHalfbandDecimator System object™ performs an efficient polyphase decimation of the input signal by a factor of two. You can use dsp.FIRHalfbandDecimator to implement the analysis portion of a two-band filter bank to filter a signal into lowpass and highpass subbands. dsp.FIRHalfbandDecimator uses an FIR equiripple design or a Kaiser window design to construct the halfband filters and a polyphase implementation to filter the input.

To filter and downsample your data:

  1. Create the dsp.FIRHalfbandDecimator object and set its properties.

  2. 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

firhalfbanddecim = dsp.FIRHalfbandDecimator returns a halfband decimator, firhalfbanddecim, with the default settings. Under the default settings, the System object filters and downsamples the input data with a halfband frequency of 11025 Hz, a transition width of 4.1 kHz, and a stopband attenuation of 80 dB. The design method is set to "Auto".

example

firhalfbanddecim = dsp.FIRHalfbandDecimator(Name=Value) returns a halfband decimator, with additional properties specified by one or more Name-Value pair arguments.

Example: firhalfbanddecim = dsp.FIRHalfbandDecimator(Specification="Filter order and stopband attenuation") creates an FIR halfband decimator object with filter order set to 52 and stopband attenuation set to 80 dB.

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.

Main Properties

Filter design parameters, specified as a character vector. When you set Specification to one of the following, you choose two of the three available design parameters to design the FIR Halfband filter.

  • "Transition width and stopband attenuation" –– Transition width and stopband attenuation are the design parameters.

  • "Filter order and stopband attenuation" –– Filter order and stopband attenuation are the design parameters.

  • "Filter order and transition width" –– Filter order and transition width are the design parameters.

The filter is designed using the optimal equiripple filter design method or the kaiser-window-based design method.

When you set Specification to "Coefficients", you specify the halfband filter coefficients directly through the Numerator property.

Filter order, specified as an even positive integer.

Dependencies

To enable this property, set Specification to "Filter order and stopband attenuation" or "Filter order and transition width".

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

Stopband attenuation in dB, specified as a positive real scalar.

Dependencies

To enable this property, set Specification to "Filter order and stopband attenuation" or "Transition width and stopband attenuation".

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

Transition width in Hz, specified as a positive real scalar or in normalized frequency units (since R2023b).

If you set the NormalizedFrequency property to:

  • false –– The value of the transition width is in Hz and must be less than half the SampleRate property value.

  • true –– The value of the transition width is in normalized frequency units. The value must be a positive scalar less than 1.0.

    When you set the NormalizedFrequency property to true while creating the object and you do not set the transition width, the object automatically sets the default transition width to normalized frequency units using the default sample rate of 44100 Hz.

    When you set the NormalizedFrequency property to true after you create the object, you must specify the transition width in normalized units before you run the object algorithm. To specify the normalized frequency value, set NormalizedFrequency to true and manually convert the frequency value in Hz to the normalized value using the input sample rate in Hz. For example, if the input sample rate Fs is 44100 Hz, the corresponding transition width value in normalized units is TWHz/(Fs/2).

    firhalfbanddecim = dsp.FIRHalfbandDecimator;
    firhalfbanddecim.NormalizedFrequency = true;
    firhalfbanddecim.TransitionWidth = 4100/(44100/2)

(since R2023b)

Dependencies

To enable this property, set Specification to "Transition width and stopband attenuation" or "Filter order and transition width".

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

FIR halfband filter coefficients, specified as a row vector. The coefficients must comply with the FIR halfband impulse response format. For details on this format, see Halfband Filters and FIR Halfband Filter Design. If half the order of the filter, (length(Numerator) - 1)/2, is even, every other coefficient starting from the first coefficient must be a zero except for the center coefficient which must be a 0.5. If half the order of the filter is odd, the sequence of alternating zeros with a 0.5 at the center starts at the second coefficient.

Dependencies

To enable this property, set Specification to "Coefficients".

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

Specify the filter design method as one of the following:

  • "Auto" –– The algorithm automatically chooses the filter design method depending on the filter design parameters. The algorithm uses the equiripple or the Kaiser window method to design the filter.

    If the design constraints are very tight, such as very high stopband attenuation or very narrow transition width, then the algorithm automatically chooses the Kaiser method, as this method is optimal for designing filters with very tight specifications. However, if the design constraints are not tight, then the algorithm chooses the equiripple method.

    When you set the DesignMethod property to "Auto", you can determine the method used by the algorithm by examining the passband and stopband ripple characteristics of the designed filter. If the object used the equiripple method, the passband and stopband ripples of the designed filter have a constant amplitude in the frequency response. If the filter design method the object chooses in the "Auto" mode is not suitable for your application, manually specify the DesignMethod as "Equiripple" or "Kaiser".

  • "Equiripple" –– The algorithm uses the equiripple method.

  • "Kaiser" –– The algorithm uses the Kaiser window method.

For more details on these two methods, see Algorithms.

Dependencies

To enable this property, set Specification to "Transition width and stopband attenuation", "Filter order and stopband attenuation", or "Filter order and transition width".

Data Types: char | string

Since R2023b

Flag to set frequencies in normalized units, specified as one of these values:

  • true –– The transition width must be in the normalized frequency units and less than 1.0.

    When you set the NormalizedFrequency property to true while creating the object and you do not set the transition width, the object automatically sets the default transition width to normalized frequency units using the default sample rate of 44100 Hz.

    When you set the NormalizedFrequency property to true after you create the object, you must specify the transition width in normalized units before you run the object algorithm. To specify the normalized frequency value, set NormalizedFrequency to true and manually convert the frequency value in Hz to the normalized value using the input sample rate in Hz. For example, if the input sample rate Fs is 44100 Hz, the corresponding transition width value in normalized units is TWHz/(Fs/2).

    firhalfbanddecim = dsp.FIRHalfbandDecimator;
    firhalfbanddecim.NormalizedFrequency = true;
    firhalfbanddecim.TransitionWidth = 4100/(44100/2)

  • false –– The transition width is in Hz. You can specify the input sample rate through the SampleRate property.

Dependency

To enable this property, set Specification to any accepted value except "Coefficients".

Data Types: logical

Input sample rate in Hz, specified as a positive real scalar. The input sample rate defaults to 44100 Hz. If you specify transition width as one of your filter design parameters, the transition width cannot exceed 1/2 the input sample rate.

Dependency

To enable this property, set:

  • Specification to any accepted value except "Coefficients".

  • NormalizedFrequency to false. (since R2023b)

Data Types: single | double

Code Generation Properties

Allow arbitrary frame length for fixed-size input signals in the generated code, specified as true or false. When you specify:

  • true –– The input frame length does not have to be a multiple of the decimation factor 2. The output of the object in the generated code is a variable-size array.

  • false –– The input frame length must be a multiple of the decimation factor 2.

When you specify variable-size signals, the input frame length can be arbitrary and the object ignores this property in the generated code. When you run this object in MATLAB®, the object supports arbitrary input frame lengths for fixed-size and variable-size signals and this property does not affect the object behavior.

Data Types: logical

Fixed-Point Properties

Word and fraction lengths of coefficients, specified as a signed or unsigned numerictype object. The default, numerictype(1,16) corresponds to a signed numeric type object with 16-bit coefficients and a fraction length determined based on the coefficient values, to give the best possible precision.

This property is not tunable.

Word length of the output is same as the word length of the input. Fraction length of the output is computed such that the entire dynamic range of the output can be represented without overflow. For details on how the fraction length of the output is computed, see Fixed-Point Precision Rules for Avoiding Overflow in FIR Filters.

Rounding method for output fixed-point operations, specified as a character vector. For more information on the rounding modes, see Precision and Range.

Usage

Description

example

ylow = firhalfbanddecim(x) filters the input signal x using the FIR halfband filter, firhalfbanddecim, and downsamples the output by a factor of 2.

example

[ylow,yhigh] = firhalfbanddecim(x) computes the ylow and yhigh, of the analysis filter bank, firhalfbanddecim for input x. A Ki-by-N input matrix is treated as N independent channels. The System object generates two power-complementary output signals by adding and subtracting the two polyphase branch outputs respectively. ylow and yhigh are of the same size and data type.

Input Arguments

expand all

Data input, specified as a column vector or a matrix of size Ki-by-N. If the input signal is a matrix, each column of the matrix is treated as an independent channel.

The number of rows in the input signal Ki can be arbitrary and does not have to be a multiple of 2. (since R2023b)

This object supports variable-size input signal, that is, the frame length (number of rows) of the signal can change even when the object is locked. However, the number of channels (columns) must remain constant.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi
Complex Number Support: Yes

Output Arguments

expand all

Lowpass subband of decimator output, returned as a column vector or a matrix. The output, ylow is a lowpass halfband filtered and downsampled version of the input x. Due to the halfband nature of the filter, the downsampling factor is always 2.

When the input is of size Ki-by-N, and Ki is not a multiple of 2, the lowpass subband has an upper bound size of ceil(Ki/2)-by-N. (since R2023b)

If Ki is a multiple of 2, then the lowpass subband is of size (Ki/2)-by-N. The number of channels (columns) does not change.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi
Complex Number Support: Yes

Highpass subband of decimator output, returned as a column vector or a matrix. The output, yhigh is a highpass halfband filtered and downsampled version of the input x. Due to the halfband nature of the filter, the downsampling factor is always 2.

When the input is of size Ki-by-N, and Ki is not a multiple of 2, the highpass subband has an upper bound size of ceil(Ki/2)-by-N. (since R2023b)

If Ki is a multiple of 2, then the highpass subband is of size (Ki/2)-by-N. The number of channels (columns) does not change.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | 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)

expand all

freqzFrequency response of discrete-time filter System object
fvtoolVisualize frequency response of DSP filters
infoInformation about filter System object
costEstimate cost of implementing filter System object
coeffsReturns the filter System object coefficients in a structure
polyphasePolyphase decomposition of multirate filter
outputDelayDetermine output delay of single-rate or multirate filter
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

Create two lowpass halfband decimation filters. The design method in the first filter is set to "Equiripple" and in the second filter is set to "Kaiser".

Specify the filter order to be 52. Specify the transition width in normalized frequency units.

filterspec = "Filter order and transition width";
Order = 52;
TW = 0.1859;
firhalfbanddecimEqui = dsp.FIRHalfbandDecimator(...
    NormalizedFrequency=true,...
    Specification=filterspec,...
    FilterOrder=Order,...
    TransitionWidth=TW,...
    DesignMethod="Equiripple");
firhalfbanddecimKaiser = dsp.FIRHalfbandDecimator(...
    NormalizedFrequency=true,......
    Specification=filterspec,...
    FilterOrder=Order,...
    TransitionWidth=TW,...
    DesignMethod="Kaiser");

Plot the impulse response of both the filters. The zeroth-order coefficient is delayed 26 samples, which is equal to the group delay of the filter. This yields a causal halfband filter.

hfvt = fvtool(firhalfbanddecimEqui,firhalfbanddecimKaiser,...
    Analysis="impulse");
legend(hfvt,{'Equiripple','Kaiser'})

Figure Figure 1: Impulse Response contains an axes object. The axes object with title Impulse Response, xlabel Samples, ylabel Amplitude contains 2 objects of type stem. These objects represent Equiripple, Kaiser.

Plot the magnitude and phase response.

If the filter specifications are tight, say a very high filter order with a very narrow transition width, the filter designed using the "Kaiser" method converges more effectively.

hvftMag = fvtool(firhalfbanddecimEqui,firhalfbanddecimKaiser,...
    Analysis="Magnitude");
legend(hvftMag,{'Equiripple','Kaiser'})

Figure Figure 2: Magnitude Response (dB) contains an axes object. The axes object with title Magnitude Response (dB), xlabel Normalized Frequency ( times pi blank rad/sample), ylabel Magnitude (dB) contains 3 objects of type line. These objects represent Equiripple, Kaiser.

hvftPhase = fvtool(firhalfbanddecimEqui,firhalfbanddecimKaiser,...
    Analysis="Phase");
legend(hvftPhase,{'Equiripple','Kaiser'})

Figure Figure 3: Phase Response contains an axes object. The axes object with title Phase Response, xlabel Normalized Frequency ( times pi blank rad/sample), ylabel Phase (radians) contains 2 objects of type line. These objects represent Equiripple, Kaiser.

Design an equiripple FIR halfband decimator object of order 48 using the designHalfbandFIR function. Set the Verbose argument to true.

hbFIR = designHalfbandFIR(FilterOrder=48,SystemObject=true,...
    Structure='decim',Verbose=true)
designHalfbandFIR(FilterOrder=48, TransitionWidth=0.1, DesignMethod="equiripple", Passband="lowpass", Structure="decim", SystemObject=true)
hbFIR = 
  dsp.FIRHalfbandDecimator with properties:

   Main
    Specification: 'Coefficients'
        Numerator: [0 -0.0041 0 0.0040 0 -0.0058 0 0.0082 0 -0.0114 0 0.0155 0 -0.0209 0 0.0286 0 -0.0400 0 0.0597 0 -0.1037 0 0.3175 0.5000 0.3175 0 -0.1037 0 0.0597 0 -0.0400 0 0.0286 0 -0.0209 0 0.0155 0 -0.0114 0 0.0082 0 -0.0058 0 0.0040 0 -0.0041 0]

  Use get to show all properties

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

dfv = dsp.DynamicFilterVisualizer(NormalizedFrequency=true);
dfv(hbFIR);

The input is a cosine wave with an angular frequency of π4 radians/sample.

input = cos(pi/4*(0:39)');

Decimate the cosine signal using the FIR halfband decimator.

output = hbFIR(input);

Plot the original and decimated signals. In order to plot the two signals in the same plot, you must account for the output delay of the FIR halfband decimator and the scaling introduced by the filter. Use the outputDelay function to compute the delay introduced by the decimator. Shift the output by this delay value.

Visualize the input and the resampled signals. After a short transition, the output converges to a cosine of frequency π2, as expected, which is twice the frequency of the input signal, π4. Due to the decimation factor of 2, the output samples coincide with every other input sample.

[delay,FsOut] = outputDelay(hbFIR,FsIn=1)
delay = 24
FsOut = 0.5000
nInput = (0:length(input)-1);
tOutput = (0:length(output)-1)/FsOut-delay;
stem(tOutput,output,'filled',MarkerSize=4); hold on;
stem(nInput,input); hold off;
xlim([-10,15])
legend('Decimated by 2','Input signal','Location','best');

Figure contains an axes object. The axes object contains 2 objects of type stem. These objects represent Decimated by 2, Input signal.

Use a halfband analysis filter bank and interpolation filter to extract the low frequency subband from a speech signal.

Note: The audioDeviceWriter System object™ is not supported in MATLAB Online.

Set up the audio file reader, the analysis filter bank, audio device writer, and interpolation filter. The sample rate of the audio data is 22050 Hz. The order of the halfband filter is 52, with a transition width of 2 kHz.

Set the design method to "Auto". This mode chooses one of the filter design methods, equiripple or Kaiser, based on the design parameters of the filter.

afr = dsp.AudioFileReader(...
    "speech_dft.mp3",...
    SamplesPerFrame=1024);

filtSpec = "Filter order and transition width";
Order = 52;
TW = 2000;

firhalfbanddecim = dsp.FIRHalfbandDecimator(...
    Specification=filtSpec,...
    FilterOrder=Order,...
    TransitionWidth=TW,...
    DesignMethod="Auto",...
    SampleRate=afr.SampleRate);

firhalfbandinterp = dsp.FIRHalfbandInterpolator(...
    Specification=filtSpec,...
    FilterOrder=Order,...
    TransitionWidth=TW,...
    DesignMethod="Auto",...
    SampleRate=afr.SampleRate/2);

adw = audioDeviceWriter(SampleRate=afr.SampleRate);

View the magnitude response of the halfband filter.

fvtool(firhalfbanddecim)

Figure Figure 1: Magnitude Response (dB) contains an axes object. The axes object with title Magnitude Response (dB), xlabel Frequency (kHz), ylabel Magnitude (dB) contains 2 objects of type line.

Read the speech signal from the audio file in frames of 1024 samples. Filter the speech signal into lowpass and highpass subbands with a halfband frequency of 5512.5 Hz. Reconstruct a lowpass approximation of the speech signal by interpolating the lowpass subband. Play the filtered output.

while ~isDone(afr)
  audioframe = afr();
  xlo = firhalfbanddecim(audioframe);
  ylow = firhalfbandinterp(xlo);
  adw(ylow);
end

Wait until the audio file is played to the end, then close the input file and release the audio output resource.

release(afr);           
release(adw);

Use a halfband decimator and interpolator to implement a two-channel filter bank. This example uses an audio file input and shows that the power spectrum of the filter bank output does not differ significantly from the input.

Note: The audioDeviceWriter System object™ is not supported in MATLAB Online.

Set up the audio file reader and device writer. Construct the FIR halfband decimator and interpolator. Finally, set up the spectrum analyzer to display the power spectra of the filter-bank input and output.

AF = dsp.AudioFileReader("speech_dft.mp3",SamplesPerFrame=1024);
AP = audioDeviceWriter(SampleRate=AF.SampleRate);

filterspec = "Filter order and transition width";
Order = 52;
TW = 2000;

firhalfbanddecim = dsp.FIRHalfbandDecimator(...
    Specification=filterspec,FilterOrder=Order,...
    TransitionWidth=TW,DesignMethod="Auto",...
    SampleRate=AF.SampleRate);

firhalfbandinterp = dsp.FIRHalfbandInterpolator(...
    Specification=filterspec,FilterOrder=Order,...
    TransitionWidth=TW,SampleRate=AF.SampleRate/2,...
    DesignMethod="Auto",...
    FilterBankInputPort=true);

SpecAna = spectrumAnalyzer(SampleRate=AF.SampleRate,...
    PlotAsTwoSidedSpectrum=false,...
    ShowLegend=true,...
    ChannelNames={'Input signal','Filtered output signal'});

Read the audio 1024 samples at a time. Filter the input to obtain the lowpass and highpass subband signals decimated by a factor of two. This is the analysis filter bank. Use the halfband interpolator as the synthesis filter bank. Display the running power spectrum of the audio input and the output of the synthesis filter bank. Play the output.

while ~isDone(AF)
    audioInput = AF();
    [xlo,xhigh] = firhalfbanddecim(audioInput);
    audioOutput = firhalfbandinterp(xlo,xhigh);
    spectrumInput = [audioInput audioOutput];
    SpecAna(spectrumInput);
    AP(audioOutput);
end

release(AF);
release(AP);
release(SpecAna);

Create a halfband decimator. Use a minimum-order design with a transition width of 0.0952 in normalized frequency units and a stopband attenuation of 60 dB.

Set the design method to "Auto". This mode chooses one of the filter design methods, equiripple or Kaiser, based on the specified filter design parameters.

hfirhalfbanddecim = dsp.FIRHalfbandDecimator(...
    NormalizedFrequency=true,...
    Specification="Transition width and stopband attenuation",...
    TransitionWidth=0.0952,...
    StopbandAttenuation=60,...
    DesignMethod="Auto");

Filter a two-channel input into low and highpass subbands. The input signal can be of arbitrary frame size, that is, the number of input rows does not have to be a multiple of 2.

x = randn(1025,2);
[ylow,yhigh] = hfirhalfbanddecim(x);

More About

expand all

Algorithms

expand all

References

[1] Harris, F.J. Multirate Signal Processing for Communication Systems, Prentice Hall, 2004, pp. 208–209.

Extended Capabilities

Version History

Introduced in R2014b

expand all