Main Content

dfilt

Discrete-time filter

Syntax

hd = dfilt.structure(input1,...)
hd = design(d,'designmethod')

Description

hd = dfilt.structure(input1,...) returns a discrete-time filter, hd, of type structure. Each structure takes one or more inputs. When you specify a dfilt.structure with no inputs, a default filter is created.

You must use a structure with dfilt.

You can get a vector of dfilt filters by concatenating dfilt.structure(input1,...) as an array.

hd = [dfilt.dffir, dfilt.df1, dfilt.df2]
hd = 

dfilt.dffir
dfilt.df1
dfilt.df2

Structures

Structures for dfilt.structure specify the type of filter structure. Available types of structures for dfilt are shown below.

dfilt.structure

Description

Coefficient Mapping Support in realizemdl

dfilt.allpass

Allpass filter

Supported

dfilt.cascadeallpass

Cascade of allpass filter sections

Supported

dfilt.cascadewdfallpass

Cascade of allpass wave digital filters

Supported

dfilt.delay

Delay

Not supported

dfilt.df1

Direct-form I

Supported

dfilt.df1sos

Direct-form I, second-order sections

Supported

dfilt.df1t

Direct-form I transposed

Supported

dfilt.df1tsos

Direct-form I transposed, second-order sections

Supported

dfilt.df2

Direct-form II

Supported

dfilt.df2sos

Direct-form II, second-order sections

Supported

dfilt.df2t

Direct-form II transposed

Supported

dfilt.df2tsos

Direct-form II transposed, second-order sections

Supported

dfilt.dffir

Direct-form FIR

Supported

dfilt.dffirt

Direct-form FIR transposed

Supported

dfilt.dfsymfir

Direct-form symmetric FIR

Supported

dfilt.dfasymfir

Direct-form antisymmetric FIR

Supported

dfilt.farrowfd

Generic fractional delay Farrow filter

Supported

dfilt.farrowlinearfd

Linear fractional delay Farrow filter

Not supported

dfilt.fftfir

Overlap-add FIR

Not supported

dfilt.latticeallpass

Lattice allpass

Supported

dfilt.latticear

Lattice autoregressive (AR)

Supported

dfilt.latticearma

Lattice autoregressive moving- average (ARMA)

Supported

dfilt.latticemamax

Lattice moving-average (MA) for maximum phase

Supported

dfilt.latticemamin

Lattice moving-average (MA) for minimum phase

Supported

dfilt.calattice

Coupled, allpass lattice

Supported

dfilt.calatticepc

Coupled, allpass lattice with power complementary output

Supported

dfilt.statespace

State-space

Supported

dfilt.scalar

Scalar gain object

Supported

dfilt.wdfallpass

Allpass wave digital filter object

Supported

dfilt.cascade

Filters arranged in series

Supported

dfilt.parallel

Filters arranged in parallel

Supported

For more information on each structure, refer to its reference page.

hd = design(d,'designmethod') returns the dfilt object hd resulting from the filter specification object d and the design method you specify in designmethod. When you omit the designmethod argument, design uses the default design method to construct a filter from the object d.

With this syntax, you design filters by:

  1. Specifying the filter specifications, such as the response shape (perhaps highpass) and details (passband edges and attenuation).

  2. Selecting a method (such as equiripple) to design the filter.

  3. Applying the method to the specifications object with design(d,'designmethod).

Using the specification-based technique can be more effective than the coefficient-based filter design techniques.

Design Methods for Design Syntax

When you use the hd = design(d,'designmethod') syntax, you have a range of design methods available depending on d, the filter specification object. The next table lists all of the design methods in the toolbox.

Design Method

Filter Design Result

butter

Butterworth IIR

cheby1

Chebyshev Type I IIR

cheby2

Chebyshev Type II IIR

ellip

Elliptic IIR

equiripple

Equiripple with the same ripple in the pass and stopbands

firls

Least-squares FIR

freqsamp

Frequency-Sampled FIR

ifir

Interpolated FIR

iirlpnorm

Least Pth norm IIR

iirls

Least-Squares IIR

kaiserwin

Kaiser-windowed FIR

lagrange

Fractional delay filter

multistage

Multistage FIR

window

Windowed FIR

As the specifications object d changes, the available methods for designing filters from d also change. For instance, if d is a lowpass filter with the default specification 'Fp,Fst,Ap,Ast', the applicable methods are:

% Create an object to design a lowpass filter.
d=fdesign.lowpass; 
designmethods(d) % What design methods apply to object d?

If you change the specification to 'N,F3dB', the available design methods change:

d=fdesign.lowpass('N,F3dB');
designmethods(d)

Analysis Methods

Methods provide ways of performing functions directly on your dfilt object without having to specify the filter parameters again. You can apply these methods directly on the variable you assigned to your dfilt object.

For example, if you create a dfilt object, hd, you can check whether it has linear phase with islinphase(hd), view its frequency response plot with fvtool(hd), or obtain its frequency response values with h = freqz(hd). You can use all of the methods described here in this way.

Note

If your variable hd is a 1-D array of dfilt filters, the method is applied to each object in the array. Only freqz, grpdelay, impz, is*, order, and stepz methods can be applied to arrays. The zplane method can be applied to an array only if zplane is used without outputs.

Some of the methods listed here have the same name as functions in Signal Processing Toolbox™ software. They behave similarly.

Method

Description

addstage

Adds a stage to a cascade or parallel object, where a stage is a separate, modular filter. Refer to dfilt.cascade and dfilt.parallel.

block

block(hd) creates a block of the dfilt object. The block method can specify these properties and values:

'Destination' indicates where to place the block. 'Current' places the block in the current Simulink® model. 'New' creates a new model. Default value is 'Current'.

'Blockname' assigns the entered character vector to the block name. Default name is 'Filter'.

'OverwriteBlock'indicates whether to overwrite the block generated by the block method ('on') and defined by Blockame. Default is 'off'.

'MapStates' specifies initial conditions in the block ('on'). Default is 'off'. Refer to "Using Filter States" in Signal Processing Toolbox documentation.

cascade

Returns the series combination of two dfilt objects. Refer to dfilt.cascade.

coeffs

Returns the filter coefficients in a structure containing fields that use the same property names as those in the original dfilt.

convert

Converts a dfilt object from one filter structure, to another filter structure.

fcfwrite

Writes a filter coefficient ASCII file. The file can contain a single filter or a vector of objects. The default file name is untitled.fcf.

fcfwrite(hd,filename) writes to a disk file named filename in the current working folder. The .fcf extension is added automatically.

fcfwrite(...,fmt) writes the coefficients in the format fmt, where valid fmt character vectors are:

'hex' for hexadecimal

'dec' for decimal

'bin' for binary representation

fftcoeffs

Returns the frequency-domain coefficients used when filtering with a dfilt.fftfir

filter

Performs filtering using the dfilt object.

firtype

Returns the type (1-4) of a linear phase FIR filter.

freqz

Plots the frequency response in FVTool. Unlike the freqz function, this dfilt freqz method has a default length of 8192.

grpdelay

Plots the group delay in FVTool.

impz

Plots the impulse response in FVTool.

impzlength

Returns the length of the impulse response.

info

Displays dfilt information, such as filter structure, length, stability, linear phase, and, when appropriate, lattice and ladder length.

isallpass

Returns a logical 1 (i.e., true) if the dfilt object in an allpass filter or a logical 0 (i.e., false) if it is not.

iscascade

Returns a logical 1 if the dfilt object is cascaded or a logical 0 if it is not.

isfir

Returns a logical 1 if the dfilt object has finite impulse response (FIR) or a logical 0 if it does not.

islinphase

Returns a logical 1 if the dfilt object is linear phase or a logical 0 if it is not.

ismaxphase

Returns a logical 1 if the dfilt object is maximum-phase or a logical 0 if it is not.

isminphase

Returns a logical 1 if the dfilt object is minimum-phase or a logical 0 if it is not.

isparallel

Returns a logical 1 if the dfilt object has parallel stages or a logical 0 if it does not.

isreal

Returns a logical 1 if the dfilt object has real-valued coefficients or a logical 0 if it does not.

isscalar

Returns a logical 1 if the dfilt object is a scalar or a logical 0 if it is not scalar.

issos

Returns a logical 1 if the dfilt object has second-order sections or a logical 0 if it does not.

isstable

Returns a logical 1 if the dfilt object is stable or a logical 0 if it are not.

nsections

Returns the number of sections in a second-order sections filter. If a multistage filter contains stages with multiple sections, using nsections returns the total number of sections in all the stages (a stage with a single section returns 1).

nstages

Returns the number of stages of the filter, where a stage is a separate, modular filter.

nstates

Returns the number of states for an object.

order

Returns the filter order. If hd is a single-stage filter, the order is given by the number of delays needed for a minimum realization of the filter. If hd has multiple stages, the order is given by the number of delays needed for a minimum realization of the overall filter.

parallel

Returns the parallel combination of two dfilt filters. Refer to dfilt.parallel.

phasez

Plots the phase response in FVTool.

realizemdl

(Available only with Simulink.)

realizemdl(hd) creates a Simulink model containing a subsystem block realization of your dfilt.

realizemdl(hd,p1,v1,p2,v2,...) creates the block using the properties p1, p2,... and values v1, v2,... specified.

The following properties are available:

'Blockname' specifies the name of the block. The default value is 'Filter'.

'Destination' specifies whether to add the block to a current Simulink model or create a new model. Valid values are 'Current' and 'New'.

'OverwriteBlock' specifies whether to overwrite an existing block that was created by realizemdl or create a new block. Valid values are 'on' and 'off'. Only blocks created by realizemdl are overwritten.

The following properties optimize the block structure. Specifying 'on' turns the optimization on and 'off' creates the block without optimization. The default for each block is 'off'.

'OptimizeZeros' removes zero-gain blocks.

'OptimizeOnes' replaces unity-gain blocks with a direct connection.

'OptimizeNegOnes' replaces negative unity-gain blocks with a sign change at the nearest summation block.

'OptimizeDelayChains' replaces delay chains made up of n unit delays with a single delay by n.

removestage

Removes a stage from a cascade or parallel dfilt. Refer to dfilt.cascade and dfilt.parallel.

setstage

Overwrites a stage of a cascade or parallel dfilt. Refer to dfilt.cascade and dfilt.parallel.

sos

Converts the dfilt to a second-order sections dfilt. If hd has a single section, the returned filter has the same class.

sos(hd,flag) specifies the ordering of the second-order sections. If flag='UP', the first row contains the poles closest to the origin, and the last row contains the poles closest to the unit circle. If flag='down', the sections are ordered in the opposite direction. The zeros are always paired with the poles closest to them.

sos(hd,flag,scale) specifies the scaling of the gain and the numerator coefficients of all second-order sections. scale can be 'none', 'inf' (infinity-norm), or 'two' (2-norm). Using infinity-norm scaling with up ordering minimizes the probability of overflow in the realization. Using 2-norm scaling with down ordering minimizes the peak roundoff noise.

ss

Converts the dfilt to state-space. To see the separate A,B,C,D matrices for the state-space model, use [A,B,C,D]=ss(hd).

stepz

Plots the step response in FVTool.

stepz(hd,n) computes the first n samples of the step response.

stepz(hd,n,Fs) separates the time samples by T = 1/Fs, where Fs is assumed to be in hertz.

sysobj

Converts the dfilt to a filter System object™. See the reference page for a list of supported objects.

tf

Converts the dfilt to a transfer function.

zerophase

Plots the zero-phase response in FVTool.

zpk

Converts the dfilt to zeros-pole-gain form.

zplane

Plots a pole-zero plot in FVTool.

Viewing Properties

As with any object, use get to view a dfilt properties. To see a specific property, use

 get(hd,'property')

To see all properties for an object, use

get(hd)

Note

dfilt objects include an arithmetic property. You can change the internal arithmetic of the filter from double- precision to single-precision using: hd.arithmetic = 'single'.

If you have Fixed-Point Designer™ software, you can change the arithmetic property to fixed-point using: hd.arithmetic = 'fixed'

Changing Properties

To set specific properties, use

set(hd,'property1',value,'property2',value,...)

You must use single quotation marks around the property name. Use single quotation marks around the value argument when the value is a character vector, such as specifyall or fixed.

Copying an Object

To create a copy of an object, use the copy method.

h2 = copy(hd)

Note

Using the syntax H2 = hd copies only the object handle and does not create a new, independent object.

Converting Between Filter Structures

To change the filter structure of a dfilt object hd, use

hd2 = convert(hd,'structure_charactervector');

where structure_charactervector is any valid structure name in single quotation marks. If hd is a cascade or parallel structure, each stage is converted to the new structure.

Using Filter States

Two properties control the filter states:

  • states — Stores the current states of the filter. Before the filter is applied, the states correspond to the initial conditions and after the filter is applied, the states correspond to the final conditions. For df1, df1t, df1sos and df1tsos structures, states returns a filtstates object.

  • PersistentMemory — Controls whether filter states are saved. The default value is 'false', which causes the initial conditions to be reset to zero before filtering and turns off the display of states information. Setting PersistentMemory to 'true' allows the filter to use your initial conditions or to reuse the final conditions from a previous filtering operation as the initial conditions of the next filtering operation. The true setting also displays information about the filter states.

Note

If you set the states and want to use them for filtering, you must set PersistentMemory to 'true' before you use the filter.

Examples

Create a direct-form I filter, and use a method to see if it is stable.

[b,a] = butter(8,0.25);
hd = dfilt.df1(b,a);
isstable(hd)

If a dfilt's numerator values do not fit on a single line, a description of the vector is displayed. To see the specific numerator values for this example, use

B = get(hd,'numerator');
% or
B1 = hd.numerator;

Create an array containing two dfilt objects, apply a method and verify that the method acts on both objects. Use a method to test whether the objects are FIR objects.

b = fir1(5,.5);
hd = dfilt.dffir(b);         % Create an FIR filter object
[b,a] = butter(5,.5);        % Create IIR filter
hd(2) = dfilt.df2t(b,a);	     % Create DF2T object and place
                              % in the second column of hd.
[h,w] = freqz(hd);
test_fir = isfir(hd) 
% hd(1) is FIR and hd(2) is not.

Refer to the reference pages for each structure for more examples.

Version History

Introduced in R2011a