Signal Processing Toolbox™

dfilt - Discrete-time filter

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.delay`	Delay
`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 Filter Design Toolbox product)
`dfilt.calatticepc`	Coupled, allpass lattice with power complementary output (available only with Filter Design Toolbox product)
`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, use the syntax help diflt.structure at the MATLAB prompt or 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 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 it is used without outputs.

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

Available methods are:

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 Signal Processing Blockset product) `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. If you enter the name of an existing subsytem in your model, the block is added to that subsystem. 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 `Blockname`. Default is `'off'`. `'MapStates`' specifies initial conditions in the block (`'on'`). Default is `'off'`. See Using Filter States. `'Link2Obj'` indicates whether to specify the filter by linking the block and the command line `dfilt` object `('on'`) or by inserting the coefficients directly into the block with no further connection between the command line `dfilt` object and the block (`'off'`). If you set `'link2obj'` to `'on'`, the `dfilt` variable name is inserted in the block and changes to the `dfilt` object via the command line are reflected in the linked block. Default value is `'off'`.
`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 Filter Design Toolboxx product 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. `y = filter(Hd,x)` filters `x` using the `Hd` filter and returns the filtered data in `y`. See Using Filter States for information on using initial conditions. If `x` is a matrix, each column is filtered as an independent channel. If `x` is a multidimensional array, `filter` operates on the first nonsingleton dimension. `y = filter(Hd,x,dim)` operates along the dimension `dim`. If `x` is a vector or matrix and `dim` is 1, every column of `x` is a channel. If `dim` is 2, every row is a channel.
`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 brief `dfilt` information, such as filter structure, length, stability, linear phase, and, when appropriate, lattice and ladder length. To display detailed information about the design method, options, etc, use `info(Hd, 'long')`. The default display is `'short'`. For multistage filters (`cascade` and `parallel`), use `info(Hd.Stage(x))`, where `x` is the stage number, to see information about that stage.
`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 software.) `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, create a new model, or place the block in an existing subsystem in your model. Valid values are `'current'`, `'new'`, or the name of an existing subsytem in your model. Default value is `'current'`. `'OverwriteBlock'` specifies whether to overwrite an existing block that was created by `realizemdl` or create a new block. Valid values are `'on'` and `'off'` and the default is `'off'`. Note that 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 of the following is `'on'.` `'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`.

For more information on each method, use the syntax help diflt/method at the MATLAB prompt.

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 Filter Design Toolbox product installed, 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 Filter Design Toolbox and Fixed-Point Toolbox products installed, 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 filtstate 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 of a previous filtering operation as the initial conditions of the next filtering operation. It also displays information about the filter states.

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.