Documentation

# fvtool

Open Filter Visualization Tool

## Syntax

```fvtool(b,a) fvtool(sos) fvtool(d) fvtool(b1,a1,b2,a2,...,bN,aN) fvtool(sos1,sos2,...,sosN) fvtool(Hd) fvtool(Hd1,Hd2,...,HdN) h = fvtool(...) ```

## Description

`fvtool(b,a)` opens FVTool and displays the magnitude response of the digital filter defined with numerator, `b` and denominator, `a`. Using FVTool you can display the phase response, group delay, impulse response, step response, pole-zero plot, and coefficients of the filter. You can export the displayed response to a file with File > Export.

### Note

If the input to `fvtool` is single precision, the magnitude response is calculated using single-precision arithmetic.

`fvtool(sos)` opens FVTool and displays the magnitude response of the digital filter defined by the L-by-6 matrix of second order sections

`$\text{sos}=\left[\begin{array}{cccccc}{b}_{01}& {b}_{11}& {b}_{21}& 1& {a}_{11}& {a}_{21}\\ {b}_{02}& {b}_{12}& {b}_{22}& 1& {a}_{12}& {a}_{22}\\ ⋮& ⋮& ⋮& ⋮& ⋮& ⋮\\ {b}_{0L}& {b}_{1L}& {b}_{2L}& 1& {a}_{1L}& {a}_{2L}\end{array}\right].$`

The rows of sos contain the numerator and denominator coefficients bik and aik of the cascade of second-order sections of H(z):

`$H\left(z\right)=g\prod _{k=1}^{L}{H}_{k}\left(z\right)=g\prod _{k=1}^{L}\frac{{b}_{0k}+{b}_{1k}{z}^{-1}+{b}_{2k}{z}^{-2}}{1+{a}_{1k}{z}^{-1}+{a}_{2k}{z}^{-2}}.$`

The number of sections, L, must be greater than or equal to 2. If the number of sections is less than 2, `fvtool` considers the input to be a numerator vector.

`fvtool(d)` opens FVTool and displays the magnitude response of a digital filter, `d`. Use `designfilt` to generate `d` based on frequency-response specifications.

`fvtool(b1,a1,b2,a2,...,bN,aN)` opens FVTool and displays the magnitude responses of multiple filters defined with numerators, `b1`, …, `bN`, and denominators, `a1`, ..., `aN`.

`fvtool(sos1,sos2,...,sosN)` opens FVTool and displays the magnitude responses of multiple filters defined with second order section matrices, `sos1`, `sos2`, ..., `sosN`.

`fvtool(Hd)` opens FVTool and displays the magnitude responses for the `dfilt` filter object, `Hd`, or the array of `dfilt` filter objects.

`fvtool(Hd1,Hd2,...,HdN)` opens FVTool and displays the magnitude responses of the filters in the `dfilt` objects `Hd1`, `Hd2`, ...`HdN`.

If you have the DSP System Toolbox™ product installed, you can also use `fvtool(H)` and `fvtool(H1,H2,...)` to analyze:

• Quantized filter objects (`dfilt` with arithmetic set to `'single'` or `'fixed'`)

• Any of the following filter System objects.

The following Filter System objects are supported by this analysis function:

`dsp.DigitalDownConverter` and `dsp.DigitalUpConverter` System objects support FVTool. You must pass the `'Arithmetic'` input to the FVTool when you call FVTool on these System objects.

When the input filter is a `dfilt` object, FVTool performs fixed-point analysis if the arithmetic property of the filter object is set to `'fixed'`. However, for filter System objects, `fvtool(H,'Arithmetic',ARITH,...)` analyzes `H`, based on the arithmetic specified in the `ARITH` input.

`ARITH` can be one of `'double'`, `'single'`, or `'fixed'`. The `'Arithmetic'` input is only relevant for the analysis of filter System objects. The arithmetic setting `ARITH`, applies to all the filter System objects that you input to FVTool. When you specify `'double'` or `'single'`, the function performs double- or single-precision analysis. When you specify `'fixed'` , the arithmetic changes depending on the setting of the `CoefficientDataType` property and whether the System object is locked or unlocked.

If you do not specify the arithmetic for non-CIC structures, and the System object is in an unlocked state, the function uses double-precision arithmetic. If the System object is locked, the function performs analysis based on the locked input data type. CIC structures only support fixed-point arithmetic.

Analysis methods `noisepsd` and `freqrespest` have behavior restrictions in `fvtool`. To see the rules, click the links to these methods.

`h = fvtool(...)` returns a figure handle `h`. You can use this handle to interact with FVTool from the command line. See Controlling FVTool from the MATLAB Command Line.

FVTool has two toolbars.

• An extended version of the MATLAB® plot editing toolbar. The following table shows the toolbar icons specific to FVTool.

Icon

Description

Restore default view. This view displays buffer regions around the data and shows only significant data. To see the response using standard MATLAB plotting, which shows all data values, use View > Full View.

Toggle legend

Toggle grid

Link to Filter Designer (appears only if FVTool was started from Filter Designer)

Toggle Add mode/Replace mode (appears only if FVTool was launched from Filter Designer)

• Analysis toolbar with the following icons

 Magnitude response of the current filter. See `freqz` and `zerophase` for more information. To see the zero-phase response, right-click the y-axis label of the Magnitude plot and select Zero-phase from the context menu. Phase response of the current filter. See `phasez` for more information. Superimposes the magnitude response and the phase response of the current filter. See `freqz` for more information. Shows the group delay of the current filter. Group delay is the average delay of the filter as a function of frequency. See `grpdelay` for more information. Shows the phase delay of the current filter. Phase delay is the time delay the filter imposes on each component of the input signal. See `phasedelay` for more information. Impulse response of the current filter. The impulse response is the response of the filter to a impulse input. See `impz` for more information. Step response of the current filter. The step response is the response of the filter to a step input. See `stepz` for more information. Pole-zero plot, which shows the pole and zero locations of the current filter on the z-plane. See `zplane` for more information. Filter coefficients of the current filter, which depend on the filter structure (e.g., direct-form, lattice, etc.) in a text box. For SOS filters, each section is displayed as a separate filter. Detailed filter information.

In the Filter Designer app, selecting View > Filter Visualization Tool or the toolbar button when an analysis is displayed starts FVTool for the current filter. You can synchronize Filter Designer and FVTool with the toolbar button. Any changes made to the filter in Filter Designer are immediately reflected in FVTool.

Two link modes are provided via the toggle toolbar button  / :

• Replace — removes the filter currently displayed in FVTool and inserts the new filter.

• Add — retains the filter currently displayed in FVTool and adds the new filter to the display.

### Modifying the Axes

You can change the x- or y-axis units by right-clicking the mouse on the axis label or by right-clicking on the plot and selecting Analysis Parameters. Available options for the axes units are as follows.

PlotX-Axis UnitsY-Axis Units

Magnitude

 Normalized Frequency Linear Frequency
 Magnitude Magnitude (dB) Magnitude squared Zero-Phase

Phase

 Normalized Frequency Linear Frequency

Magnitude and Phase

 Normalized Frequency Linear Frequency

(y-axis on left side)

 Magnitude Magnitude (dB) Magnitude squared Zero-Phase

(y-axis on right side)

Group Delay

 Normalized Frequency Linear Frequency
 Samples Time

Phase Delay

 Normalized Frequency Linear Frequency

Impulse Response

 Samples Time

Amplitude

Step Response

 Samples Time

Amplitude

Pole-Zero

Real Part

Imaginary Part

### Modifying the Plot

You can use any of the plot editing toolbar buttons to change the properties of your plot.

Analysis Parameters are parameters that apply to the displayed analyses. To display them, right-click in the plot area and select Analysis Parameters from the menu. (Note that you can access the menu only if the button is inactive.) The following analysis parameters are displayed. (If more than one response is displayed, parameters applicable to each plot are displayed.) Not all of these analysis fields are displayed for all types of plots:

• Normalized Frequency — if checked, frequency is normalized between 0 and 1, or if not checked, frequency is in Hz

• Frequency Scaley-axis scale (`Linear` or `Log`)

• Frequency Range — range of the frequency axis or `Specify freq. vector`

• Number of Points — number of samples used to compute the response

• Frequency Vector — vector to use for plotting, if `Specify freq. vector` is selected in Frequency Range.

• Magnitude Displayy-axis units (`Magnitude`, `Magnitude (dB)`, ```Magnitude squared```, or `Zero-Phase`)

• Phase Unitsy-axis units (`Degrees` or `Radians`)

• Phase Display — type of phase plot (`Phase` or `Continuous Phase`)

• Group Delay Unitsy-axis units (`Samples` or `Time`)

• Specify Length — length type of impulse or step response (`Default` or `Specified`)

• Length — number of points to use for the impulse or step response

In addition to the above analysis parameters, you can change the plot type for Impulse and Step Response plots by right-clicking and selecting Line with Marker, Stem or Line from the context menu. You can change the x-axis units by right-clicking the x-axis label and selecting `Samples` or `Time`.

To save the displayed parameters as the default values to use when Filter Designer or FVTool is opened, click Save as default.

To restore the default values, click .

Data tips display information about a particular point in the plot. See Interactively Explore Plotted Data (MATLAB) for information on data tips.

If you have the DSP System Toolbox software, FVTool displays a specification mask along with your designed filter on a magnitude plot.

### Note

To use View > Passband zoom, your filter must have been designed using `fdesign` or Filter Designer. Passband zoom is not provided for cascaded integrator-comb (CIC) filters because CICs do not have conventional passbands.

### Overlaying a Response

You can overlay a second response on the plot by selecting Analysis > Overlay Analysis and selecting an available response. A second y-axis is added to the right side of the response plot. The Analysis Parameters dialog box shows parameters for the x-axis and both y-axes. See Display Analysis Parameters for a sample Analysis Parameters dialog box.

### Controlling FVTool from the MATLAB Command Line

After you obtain the handle for FVTool, you can control some aspects of FVTool from the command line. In addition to the standard Handle Graphics® properties (see Handle Graphics in the MATLAB documentation), FVTool has the following properties:

• `'Analysis'` — displays the specified type of analysis plot. The following table lists all analysis types and how to invoke them. Note that the only analyses that use filter internals are magnitude response estimate and round-off noise power, which are available only with the DSP System Toolbox product.

Analysis TypeAnalysis Option

Magnitude plot

`'magnitude'`

Phase plot

`'phase'`

Magnitude and phase plot

``freq'`

Group delay plot

`'grpdelay'`

Phase delay plot

``phasedelay'`

Impulse response plot

`'impulse'`

Step response plot

`'step'`

Pole-zero plot

`'polezero'`

Filter coefficients

`'coefficients'`

Filter information

`'info'`

Magnitude response estimate

(available only with the DSP System Toolbox product, see `freqrespest` for more information)

`'magestimate'`

Round-off noise power

(available only with the DSP System Toolbox product, see `noisepsd` for more information)

`'noisepower'`

• `'Grid'` — controls whether the grid is `'on'` or `'off'`

• `'Legend'` — controls whether the legend is `'on'` or `'off'`

• `'Fs'` — controls the sampling frequency of filters in FVTool. The sampling frequency vector must be of the same length as the number of filters or a scalar value. If it is a vector, each value is applied to its corresponding filter. If it is a scalar, the same value is applied to all filters.

• `SosViewSettings` — (This option is available only if you have the DSP System Toolbox product.) For second-order sections filters, this controls how the filter is displayed. The `SOSViewSettings` property contains an object so you must use this syntax to set it: `set(h.SOSViewSettings,'View',viewtype)`, where `viewtype` is one of the following:

• `'Complete'` — Displays the complete response of the overall filter

• `'Individual'` — Displays the response of each section separately

• 'Cumulative' — Displays the response for each section accumulated with each prior section. If your filter has three sections, the first plot shows section one, the second plot shows the accumulation of sections one and two, and the third plot show the accumulation of all three sections.

You can also define whether to use `SecondaryScaling`, which determines where the sections should be split. The secondary scaling points are the scaling locations between the recursive and the nonrecursive parts of the section. The default value is `false`, which does not use secondary scaling. To turn on secondary scaling, use this syntax: `set(h.SOSViewSettings,'View','Cumulative',true)`

• `'UserDefined'` — Allows you to define which sections to display and the order in which to display them. Enter a cell array where each section is represented by its index. If you enter one index, only that section is plotted. If you enter a range of indices, the combined response of that range of sections is plotted. For example, if your filter has four sections, entering `{1:4}` plots the combined response for all four sections, and entering `{1,2,3,4}` plots the response for each section individually.

### Note

You can change other properties of FVTool from the command line using the `set` function. Use `get(h)` to view property tags and current property settings.

You can use the following methods with the FVTool handle.

`addfilter(h,filtobj)` adds a new filter to FVTool. The new filter, `filtobj`, must be a `dfilt` filter object. You can specify the sampling frequency of the new filter with `addfilter(h,filtobj,'Fs',10)`.

`setfilter(h,filtobj)` replaces the filter in FVTool with the filter specified in `filtobj`. You can set the sampling frequency as described above.

`deletefilter(h, index)` deletes the filter at the FVTool cell array `index` location.

`legend(h,str1,str2,...)` creates a legend in FVTool by associating `str1` with filter 1, `str2` with filter 2, etc. See `legend` in the MATLAB documentation for information.

## Examples

collapse all

Display the magnitude response of a 6th-order elliptic filter. Specify a passband ripple of 3 dB, a stopband attenuation of 50 dB, a sample rate of 1 kHz, and a normalized passband edge of 300 Hz. Start FVTool from the command line.

```[b,a] = ellip(6,3,50,300/500); fvtool(b,a)```

Display and analyze multiple FIR filters, starting FVTool from the command line.

```b1 = firpm(20,[0 0.4 0.5 1],[1 1 0 0]); b2 = firpm(40,[0 0.4 0.5 1],[1 1 0 0]); fvtool(b1,1,b2,1)```

Display the associated analysis parameters.

Start FVTool from the command line. Display the magnitude response of a 6th-order elliptic filter. Specify a passband ripple of 3 dB, a stopband attenuation of 50 dB, a sample rate of 1 kHz, and a normalized passband edge of 300 Hz.

```[b,a] = ellip(6,3,50,300/500); h = fvtool(b,a);```

Display the phase response of the filter.

`h.Analysis = 'phase';`

Turn on the plot legend and add text.

`legend(h,'Phase plot')`

Specify a sample rate of 1 kHz. Display the two-sided centered response.

```h.Fs = 1000; h.FrequencyRange='[-Fs/2, Fs/2)';```

View the all the properties of the plot. The properties specific to FVTool are at the end of the list.

`get(h)`
``` Grid: 'on' Legend: 'on' AnalysisToolbar: 'on' FigureToolbar: 'on' DesignMask: 'off' SOSViewSettings: [1x1 dspopts.sosview] Fs: 1000 Alphamap: [1x64 double] CloseRequestFcn: 'closereq' Color: [0.9400 0.9400 0.9400] Colormap: [64x3 double] CurrentAxes: [1x1 Axes] CurrentCharacter: '' CurrentObject: [0x0 GraphicsPlaceholder] CurrentPoint: [0 0] DockControls: 'on' FileName: '' IntegerHandle: 'on' InvertHardcopy: 'on' KeyPressFcn: '' KeyReleaseFcn: '' MenuBar: 'none' Name: 'Filter Visualization Tool - Phase Response' NextPlot: 'new' NumberTitle: 'on' PaperUnits: 'inches' PaperOrientation: 'portrait' PaperPosition: [1.3350 3.3150 5.8300 4.3700] PaperPositionMode: 'auto' PaperSize: [8.5000 11] PaperType: 'usletter' Pointer: 'arrow' PointerShapeCData: [16x16 double] PointerShapeHotSpot: [1 1] Position: [346.5000 282.5000 583 437] Renderer: 'opengl' RendererMode: 'auto' Resize: 'on' ResizeFcn: '' SelectionType: 'normal' ToolBar: 'auto' Type: 'figure' Units: 'pixels' WindowButtonDownFcn: '' WindowButtonMotionFcn: '' WindowButtonUpFcn: '' WindowKeyPressFcn: '' WindowKeyReleaseFcn: '' WindowScrollWheelFcn: '' WindowStyle: 'normal' BeingDeleted: 'off' ButtonDownFcn: '' Children: [15x1 Graphics] Clipping: 'on' CreateFcn: '' DeleteFcn: '' BusyAction: 'queue' HandleVisibility: 'on' HitTest: 'on' Interruptible: 'on' Parent: [1x1 Root] Selected: 'off' SelectionHighlight: 'on' Tag: 'filtervisualizationtool' UIContextMenu: [0x0 GraphicsPlaceholder] UserData: [] Visible: 'on' FrequencyScale: 'Linear' FrequencyVector: [1x256 double] PolyphaseView: 'off' OverlayedAnalysis: '' Analysis: 'phase' NumberofPoints: 8192 FrequencyRange: '[-Fs/2, Fs/2)' NormalizedFrequency: 'off' PhaseUnits: 'Radians' PhaseDisplay: 'Phase' ShowReference: 'on' ```