Documentation |
Discrete-time filter
Hd = dfilt.structure(input1,...)
Hd = [dfilt.structure(input1,...),dfilt.structure(input1,...),...]
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.
Hd = [dfilt.structure(input1,...),dfilt.structure(input1,...),...] returns a vector containing dfilt filters.
Available structures for the dfilt object are shown below. The target block for the block method depends on the filter structure. Depending on the target block, the DSP System Toolbox™ software may be required.
dfilt.structure | Description | Coefficient Mapping Support in realizemdl | Target Filter Block for block Method |
---|---|---|---|
Delay | Not supported | Delay Requires DSP System Toolbox | |
Direct-form I | Supported | Discrete Filter | |
Direct-form I, second-order sections | Supported | Discrete Filter Requires DSP System Toolbox | |
Direct-form I transposed | Supported | Discrete Filter | |
Direct-form I transposed, second-order sections | Supported | Biquad Filter Requires DSP System Toolbox | |
Direct-form II | Supported | Discrete Filter | |
Direct-form II, second-order sections | Supported | Discrete Filter | |
Direct-form II transposed | Supported | Discrete Filter | |
Direct-form II transposed, second-order sections | Supported | Biquad Filter Requires DSP System Toolbox | |
Direct-form FIR | Supported | Discrete FIR Filter | |
Direct-form FIR transposed | Supported | Discrete FIR Filter | |
Direct-form symmetric FIR | Supported | Discrete FIR Filter | |
Direct-form antisymmetric FIR | Supported | Discrete FIR Filter | |
Overlap-add FIR | Not supported | Overlap-Add FFT Filter Requires DSP System Toolbox | |
Lattice allpass | Supported | Not supported | |
Lattice autoregressive (AR) | Supported | Allpole Filter Requires DSP System Toolbox | |
Lattice autoregressive moving- average (ARMA) | Supported | Not supported | |
Lattice moving-average (MA) for maximum phase | Supported | Not supported | |
Lattice moving-average (MA) for minimum phase | Supported | Discrete FIR Filter | |
State-space | Supported. | Not supported | |
Scalar gain object | Supported | Gain Requires DSP System Toolbox | |
Filters arranged in series | Supported | Target blocks depend on filter structures in the series | |
Filters arranged in parallel | Supported | Target blocks depend on filter structures in the parallel system |
For more information on each structure, use the syntax help diflt.structure at the MATLAB^{®} prompt or refer to its reference page.
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 |
---|---|
Adds a stage to a cascade or parallel object, where a stage is a separate, modular filter. See dfilt.cascade and dfilt.parallel. | |
block(Hd) creates a Simulink^{®} filter block of the dfilt object. The target filter block depends on the filter structure. You must have Simulink to use this method. Additionally, the DSP System Toolbox may be required depending on the filter structure. See Structures for a mapping between the target blocks and filter structures. The block method can specify these properties/values: 'MapCoeffstoPorts' indicates whether to map the filter coefficients to constant blocks connected to the generated block. Default value is 'off'. Setting 'MapCoeffstoPorts' to 'on' turns on the mapping and enables the 'CoeffNames' property, which defines the constant block parameter names. 'CoeffNames' is a cell array of strings. Default values are {'Num'} for Direct form FIR filters, {'K'} for lattice filters, {'Num','Den'} for IIR filters, and {Num','Den','g'} for biquad filters. Variables, defined by 'CoeffNames', are created in the MATLAB workspace and have the same data type as the filter's 'Arithmetic' property. Any existing variable with the same name is overwritten. Note that you can use either 'Link2Obj' or 'MapCoeffstoPorts', but not both simultaneously. 'InputProcessing' specifies sample-based, 'elementsaschannels', frame-based, 'columnsaschannels', processing, or 'inherited'. The default is frame-based processing. If you do not have the DSP System Toolbox software, explicitly set the 'InputProcessing' property to 'elementsaschannels' to avoid a runtime error. Setting 'InputProcessing' to 'inherited' targets the Digital Filter block regardless of structure. | |
Returns the series combination of two dfilt objects. See dfilt.cascade. | |
Returns the filter coefficients in a structure containing fields that use the same property names as those in the original dfilt. | |
Converts a dfilt object from one filter structure to another filter structure. | |
Writes a filter coefficient ASCII file. The file can contain a single filter or a vector of objects. If the DSP System Toolbox 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. | |
Returns the frequency-domain coefficients used when filtering with a dfilt.fftfir. | |
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. | |
Returns the type (1-4) of a linear phase FIR filter. | |
Plots the frequency response in fvtool. Note that unlike the freqz function, this dfilt freqz method has a default length of 8192. | |
Plots the group delay in fvtool. | |
Plots the impulse response in fvtool. | |
Returns the length of the impulse response. | |
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. | |
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. | |
Returns a logical 1 if the dfilt object is cascaded or a logical 0 if it is not. | |
Returns a logical 1 if the dfilt object has finite impulse response (FIR) or a logical 0 if it does not. | |
Returns a logical 1 if the dfilt object is linear phase or a logical 0 if it is not. | |
Returns a logical 1 if the dfilt object is maximum-phase or a logical 0 if it is not. | |
Returns a logical 1 if the dfilt object is minimum-phase or a logical 0 if it is not. | |
Returns a logical 1 if the dfilt object has parallel stages or a logical 0 if it does not. | |
Returns a logical 1 if the dfilt object has real-valued coefficients or a logical 0 if it does not. | |
Returns a logical 1 if the dfilt object is a scalar or a logical 0 if it is not scalar. | |
Returns a logical 1 if the dfilt object has second-order sections or a logical 0 if it does not. | |
Returns a logical 1 if the dfilt object is stable or a logical 0 if it are not. | |
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). | |
Returns the number of stages of the filter, where a stage is a separate, modular filter. | |
Returns the number of states for an object. | |
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. | |
Returns the parallel combination of two dfilt filters. See dfilt.parallel. | |
Plots the phase response in fvtool. | |
(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 subsystem 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. | |
Removes a stage from a cascade or parallel dfilt. See dfilt.cascade and dfilt.parallel. | |
Overwrites a stage of a cascade or parallel dfilt. See dfilt.cascade and dfilt.parallel. | |
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. | |
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). | |
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. | |
Converts the dfilt to a filter System object. See the reference page for a list of supported objects. To use this method, you must have DSP System Toolbox software installed. | |
Converts the dfilt to a transfer function. | |
Plots the zero-phase response in fvtool. | |
Converts the dfilt to zeros-pole-gain form. | |
Plots a pole-zero plot in fvtool. |
For more information on each method, use the syntax help diflt/method at the MATLAB prompt.
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)
To set specific properties, use
set(Hd,'property1',value,'property2',value,...)
Note that you must use single quotation marks around the property name.
Alternatively, you can get or set a property value with Object.property:
b = [0.05 0.9 0.05]; Hd = dfilt.dffir(b); % Lowpass direct-form I FIR filter Hd.arithmetic % get arithmetic property % returns double Hd.arithmetic = 'single'; % Set arithmetic property to single precision
To create a copy of an object, use the copy method.
H2 = copy(Hd)
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.
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.
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)
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')
or alternatively
Hd.numerator
Refer to the reference pages for each structure for more examples.
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 | step | tf | zpk | zplane