Signal Processing Toolbox

dfilt

Discrete-time filters

Syntax

• Hd = dfilt.structure(input1,...)
  Hd = [dfilt.structure(input1,...),dfilt.structure(input1,...),...]
  

Description

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

Note    You must use a structure with dfilt.

Hd = [dfilt.structure(input1,...),dfilt.structure(input1,...),...] returns a vector containing dfilt filters.

Structures

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

dfilt.structure	Description
dfilt.df1	Direct-form I
dfilt.df1sos	Direct-form I, second-order sections
dfilt.df1t	Direct-form I transposed
dfilt.df1tsos	Direct-form I transposed, second-order sections
dfilt.df2	Direct-form II
dfilt.df2sos	Direct-form II, second-order sections
dfilt.df2t	Direct-form II transposed
dfilt.df2tsos	Direct-form II transposed, second-order sections
dfilt.dffir	Direct-form FIR
dfilt.dffirt	Direct-form FIR transposed
dfilt.dfsymfir	Direct-form symmetric FIR
dfilt.dfasymfir	Direct-form antisymmetric FIR
dfilt.fftfir	Overlap-add FIR
dfilt.latticeallpass	Lattice allpass
dfilt.latticear	Lattice autoregressive (AR)
dfilt.latticearma	Lattice autoregressive moving- average (ARMA)
dfilt.latticemamax	Lattice moving-average (MA) for maximum phase
dfilt.latticemamin	Lattice moving-average (MA) for minimum phase
dfilt.calattice	Coupled, allpass lattice (available only with the Filter Design Toolbox)
dfilt.calatticepc	Coupled, allpass lattice with power complementary output (available only with the Filter Design Toolbox)
dfilt.statespace	State-space
dfilt.scalar	Scalar gain object
dfilt.cascade	Filters arranged in series
dfilt.parallel	Filters arranged in parallel

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

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 below in this way.

Note    If your variable is a 1-D array 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 it is used without outputs.

Some of the methods listed below have the same name as functions in the Signal Processing Toolbox and they behave similarly. This is called overloading of functions.

Method	Description
addstage	Adds a stage to a cascade or parallel object, where a stage is a separate, modular filter. See dfilt.cascade and dfilt.parallel.
block	(Available only with the Signal Processing Blockset) block(Hd) creates a Signal Processing Blockset block of the dfilt object. The block method can specify these properties/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 string 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'. See Using Filter States.
cascade	Returns the series combination of two dfilt objects. See 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. If the Filter Design Toolbox is installed, the file can contain multirate filters (mfilt) or adaptive filters (adaptfilt). Default filename is untitled.fcf. fcfwrite(Hd,filename) writes to a disk file named filename in the current working directory. The .fcf extension is added automatically. fcfwrite(...,fmt) writes the coefficients in the format fmt, where valid fmt strings 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. Note that 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. See 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 or create a new block. Valid values are 'on' and 'off'. 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 cascaded chains of delay block with a single integer delay block set to the appropriate delay.
removestage	Removes a stage from a cascade or parallel dfilt. See dfilt.cascade and dfilt.parallel.
setstage	Overwrites a stage of a cascade or parallel dfilt. See 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 Hz.
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, you can 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    If you have the Filter Design Toolbox, an arithmetic property is displayed. You can change the internal arithmetic of the filter from double- precision to single-precision using: Hd.arithmetic = 'single' If you have both the Filter Design Toolbox and the Fixed-Point Toolbox, 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,...) 
  

Note that you must use single quotation marks around the property name.

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

Converting Between Filter Structures

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

• Hd2=convert(Hd,'structure_string');
  

where structure_string is any valid structure name in single quotation marks. If Hd is a cascade or parallel structure, each of its stages 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 conditioons or to reuse the final conditions of a previous filtering operation as the initial conditions of the next filtering operation. It 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)
   
  Hd = 
           FilterStructure: 'Direct-Form I'
                 Numerator: [1x9 double]
               Denominator: [1x9 double]
          PersistentMemory: false
      
  isstable(Hd)
  ans =
       1
  

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

• get(Hd,'numerator')
  
  ans =
  Columns 1 through 6 
      0.0001    0.0009    0.0030    0.0060    0.0076    0.0060
    Columns 7 through 9 
      0.0030    0.0009    0.0001
  

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

• b = fir1(5,.5);
  Hd = dfilt.dffir(b);              % create an FIR object
  [b,a] = butter(5,.5);
  Hd(2) = dfilt.df2t(b,a);          % create a DF2T object and place
                                    % it in the second column of Hd
  
  [h,w] = freqz(Hd);
  size(h)                           % verify that resulting h is
  ans =                             % 2 columns
          8192           2
  size(w)                           % verify that resulting w is
  ans =                             % 1 column
          8192           1
  
  test_fir = isfir(Hd)
  test_fir =
       1     0                      % Hd(1) is FIR and Hd(2) is not
  

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

See Also

dfilt.cascade , dfilt.df1, dfilt.df1t, dfilt.df2, dfilt.df2t, dfilt.dfasymfir, dfilt.dffir, dfilt.dffirt, dfilt.dfsymfir, dfilt.latticeallpass, dfilt.latticear, dfilt.latticearma, dfilt.latticemamax, dfilt.latticemamin, dfilt.parallel, dfilt.statespace, filter, freqz, grpdelay, impz, sos, step, tf, zpk, zplane

demod

dfilt.cascade

© 1994-2005 The MathWorks, Inc.