filterAnalysisOptions

Filter analysis options

Since R2024a

Description

filterAnalysisOptions specifies analysis options for filters displayed in Filter Analyzer.

Creation

Syntax

opts = filterAnalysisOptions

opts = filterAnalysisOptions(analysis)

opts = filterAnalysisOptions(analysis,overlay)

opts = filterAnalysisOptions(___,Name=Value)

Description

opts = filterAnalysisOptions returns an object containing magnitude-response analysis options. Use opts to specify analysis options for the Filter Analyzer app.

opts = filterAnalysisOptions(analysis) returns filter analysis options for the specified analysis type. You can also specify analysis using a name-value argument.

opts = filterAnalysisOptions(analysis,overlay) returns filter analysis options for the specified analysis and overlay analysis types. You can also specify overlay using a name-value argument.

opts = filterAnalysisOptions(___,Name=Value) specifies the Properties of opts using name-value arguments.

Input Arguments

analysis — Analysis type

"magnitude" (default) | "phase" | "groupdelay" | "phasedelay" | "magestimate" | "noisepsd" | "impulse" | "step" | "polezero" | "info" | "coefficients"

Analysis type, specified as one of these:

• Frequency-domain analyses:

  • "magnitude" — Magnitude response

  • "phase" — Phase response

  • "groupdelay" — Group delay response

  • "phasedelay" — Phase delay response

  • "magestimate" — Magnitude response estimate

  • "noisepsd" — Noise power spectral density (PSD)

• Time-domain analyses:

  • "impulse" — Impulse response

  • "step" — Step response

• Other analyses:

  • "polezero" — Pole-zero plot

  • "info" — Filter information

  • "coefficients" — Filter coefficients

You can also specify analysis as a name-value argument: filterAnalysisOptions(Analysis=analysis) is equivalent to filterAnalysisOptions(analysis).

For more information, see Analysis.

overlay — Overlaid analysis

string

Overlaid analysis, specified as a string.

• If analysis is set to a frequency-domain analysis, then overlay must be also a frequency-domain analysis.

• If analysis is set to a time-domain analysis, then overlay must be also a time-domain analysis.

• analysis and overlay must be set to different values.

• This argument is not supported if analysis is set to "polezero", "info", or "coefficients".

You can also specify overlay as a name-value argument: filterAnalysisOptions(Analysis=analysis,OverlayAnalysis=overlay) is equivalent to filterAnalysisOptions(analysis,overlay)

Properties

Analysis Type

Analysis — Analysis type

"magnitude" (default) | "phase" | "groupdelay" | "phasedelay" | "magestimate" | "noisepsd" | "impulse" | "step" | "polezero" | "info" | "coefficients"

Analysis type, specified as one of these:

• Frequency-domain analyses:

  • "magnitude" — Magnitude response

  • "phase" — Phase response

  • "groupdelay" — Group delay response

  • "phasedelay" — Phase delay response

  • "magestimate" — Magnitude response estimate

  • "noisepsd" — Noise power spectral density (PSD)

• Time-domain analyses:

  • "impulse" — Impulse response

  • "step" — Step response

• Other analyses:

  • "polezero" — Pole-zero plot

  • "info" — Filter information

  • "coefficients" — Filter coefficients

For more information, see Analysis.

OverlayAnalysis — Overlaid analysis

string

Overlaid analysis, specified as a string.

• If Analysis is set to a frequency-domain analysis, then OverlayAnalysis must be also a frequency-domain analysis.

• If Analysis is set to a time-domain analysis, then OverlayAnalysis must be also a time-domain analysis.

• Analysis and OverlayAnalysis must be set to different values.

• This argument is not supported if Analysis is set to "polezero", "info", or "coefficients".

For more information, see Analysis.

Frequency Normalization and Sample Rate

FrequencyNormalizationMode — Frequency normalization mode

"auto" (default) | "normalized" | "unnormalized"

Frequency normalization mode, specified as one of these:

• "normalized" — The app normalizes the response of each input filter with respect to its sample rate and computes responses using normalized frequencies expressed in rad/sample.

• "unnormalized" — The app computes responses in cyclical frequencies expressed in hertz. Filters with no sample rate are assumed to work at 1 Hz.

• "auto" — The app uses the "unnormalized" mode if all filters under analysis have a specified sample rate and the "normalized" mode otherwise.

Data Types: char | string

ReferenceSampleRateMode — Reference sample rate selection mode

"max" (default) | "specify"

Reference sample rate selection mode, specified as one of these:

• "max" — The app uses the maximum sample rate of all the filters under analysis in a display.

• "specify" — You specify a sample rate value using the ReferenceSampleRate property.

This property does not apply if FrequencyNormalizationMode is "normalized".

Data Types: char | string

ReferenceSampleRate — Reference sample rate

positive scalar

Reference sample rate, specified as a positive scalar. The app uses the specified reference sample rate to normalize filter responses and to define the overall Nyquist range over which the filters are analyzed. This property applies only if ReferenceSampleRateMode is set to "specify".

Example: 44.1e3

Data Types: double

Frequency-Domain Analysis

FrequencyRange — Analysis frequency range

"auto" (default) | "onesided" | "twosided" | "centered" | "freqvector"

Analysis frequency range, specified as one of these:

• "onesided" — The app computes responses over the range [0, π) when using normalized frequencies and over the range [0, referenceSampleRate/2) when using unnormalized frequencies.

• "twosided" — The app computes responses over the range [0, 2π) when using normalized frequencies and over the range [0, referenceSampleRate) when using unnormalized frequencies.

• "centered" — The app computes responses over the range [–π, π) when using normalized frequencies and over the range [–referenceSampleRate/2, referenceSampleRate/2) when using unnormalized frequencies. This option does not apply when FrequencyScale is set to "log".

• "freqvector" — The app computes responses at the frequency points specified using FrequencyVector.

• "auto" — The app computes one-sided responses if all filters under analysis in a display have real-valued coefficients and two-sided responses if at least one filter has complex-valued coefficients.

Data Types: char | string

NFFT — Number of discrete Fourier transform points

8192 (default) | positive integer

Number of discrete Fourier transform points used to compute filter responses, specified as a positive integer. This property does not apply when FrequencyRange is set to "freqvector".

Example: 1024

Data Types: double

FrequencyScale — Frequency scale for filter responses

"linear" (default) | "log"

Frequency scale to visualize filter responses, specified as "linear" for linear frequency scale or "log" for logarithmic frequency scale. The "log" option does not apply if FrequencyRange is set to "centered".

Data Types: char | string

FrequencyVector — Frequency vector

real vector

Frequency vector over which filters are computed, specified as a vector of finite real values. If FrequencyVectorUnits is set to "normalized", the vector is assumed to be in units of rad/sample. Otherwise, the vector is assumed to be in the selected units.

This property applies only when FrequencyRange is set to "freqvector". This property is not supported when either analysis or overlay is set to "magestimate" or "noisepsd".

Example: [-pi/3 0 pi/6 pi/2] and [-200 0 100 300] are equivalent when the sample rate is 600 Hz.

Data Types: double

FrequencyVectorUnits — Units for frequency vector values

"normalized" (default) | "Hz" | "kHz" | "MHz" | "GHz"

Units for frequency vector values, specified as a string. If this property is set to "normalized", the frequency vector is assumed to be normalized in units of rad/sample. Otherwise, the vector is assumed to be in the selected units.

This property applies only when FrequencyRange is set to "freqvector". This property is not supported when either analysis or overlay is set to "magestimate" or "noisepsd".

Data Types: double

Magnitude Response and Magnitude Estimate

MagnitudeMode — Magnitude response mode

"db" (default) | "linear" | "squared" | "zerophase"

Magnitude response mode, specified as one of these:

• "linear" — The app computes the filter response as the absolute value of the frequency response.

• "squared" — The app computes the filter response as the magnitude squared of the frequency response.

• "db" — The app computes the filter response as the magnitude, in decibel scale, of the frequency response.

• "zerophase" — The app computes the filter response as the zero-phase response. This option does not apply if either analysis or overlay is specified as "magestimate".

Data Types: char | string

MagnitudeEstimateNumTrials — Number of trials to compute frequency response estimate

12 (default) | positive integer

Number of trials to compute the frequency response estimate, specified as a positive integer. This property applies only when either Analysis or OverlayAnalysis is specified as "magestimate".

Example: 24

Data Types: double

NormalizeMagnitude — Option to normalize magnitude response

false (default) | true

Option to normalize the magnitude response, specified as a logical value. If this property is set to true, the filter magnitude response is normalized to 1.

Data Types: logical

Phase Response and Phase Delay Response

PhaseUnits — Units for phase response or phase delay response

"radians" (default) | "degrees"

Units for phase response or phase delay response, specified as "radians" or "degrees".

Data Types: char | string

ContinuousPhase — Option to use continuous phase when computing phase response

false (default) | true

Option to use continuous phase when computing phase response, specified as a logical value.

Data Types: logical

Group Delay Response

GroupDelayUnits — Units for group delay response

"samples" (default) | "time"

Units for group delay response, specified as "samples" or "time".

Data Types: char | string

Noise PSD

NoisePSDNumTrials — Number of trials to compute noise PSD

12 (default) | positive integer

Number of trials to compute the noise power spectral density, specified as a positive integer.

Example: 10

Data Types: double

Time-Domain Analysis

ResponseLengthMode — Response length mode

"auto" (default) | "specify"

Response length mode, specified as one of these:

• "auto" — The app uses the impzlength function to estimate the response length.

• "specify" — You set the response length using the ResponseLength property.

Data Types: char | string

ResponseLength — Length of time-domain response

positive integer

Length of time-domain response, specified as a positive integer. This property applies only if ResponseLengthMode is set to "specify".

Example: 128

Data Types: double

Coefficients

CoefficientsFormat — Format for filter coefficients

"decimal" (default) | "hex" | "binary"

Format for filter coefficients, specified as "decimal", "hex", or "binary".

Data Types: char | string

All Domains

ReferenceFilter — View double-precision reference filter

false (default) | true

Option to view double-precision reference filter, specified as a logical value. If this property is set to true, Filter Analyzer displays responses of quantized filters and their double-precision references.

Data Types: logical

PolyphaseDecomposition — View polyphase decomposition of polyphase filter

false (default) | true

Option to view polyphase decomposition of polyphase filter, specified as a logical value.

Data Types: logical

CTFAnalysisMode — Cascaded transfer function computation mode

"complete" (default) | "individual" | "cumulative" | "specify"

Cascaded transfer function computation mode, specified as one of these:

• "complete" — The app computes the overall response of the cascaded sections

• "individual" — The app computes the response of each section.

• "cumulative" — The app computes cumulative responses.

• "specify" — You use the CTFAnalysisSections property to specify the combination of sections over which to compute responses.

Data Types: char | string

CTFAnalysisSections — Section combinations for CTF response computation

cell array

Section combinations over which to compute cascaded transfer function responses, specified as a cell array. This property applies only when CTFAnalysisMode is set to "specify".

Example: {[1 2 3],[4 5 6]} directs the app to compute responses for a cascade of sections 1, 2, and 3 and a cascade of sections 4, 5, and 6.

Data Types: cell

Examples

Filter Analysis Options

Design a lowpass FIR filter and display its phase response in Filter Analyzer. Use 1024 NFFT points and display the phase in degrees.

d = designfilt("lowpassfir", ...
    PassbandFrequency=0.45,StopbandFrequency=0.55, ...
    PassbandRipple=1,StopbandAttenuation=60);
opts = filterAnalysisOptions("phase")

opts = 
  filterAnalysisOptions with properties:

                      Analysis: "phase"
               OverlayAnalysis: "none"
    FrequencyNormalizationMode: "auto"
       ReferenceSampleRateMode: "max"
                FrequencyRange: "auto"
                          NFFT: 8192
                FrequencyScale: "linear"
                    PhaseUnits: "radians"
               ContinuousPhase: 0
               ReferenceFilter: 1
        PolyphaseDecomposition: 0
               CTFAnalysisMode: "complete"

opts.NFFT = 1024;
opts.PhaseUnits = "degrees";
filterAnalyzer(d,AnalysisOptions=opts)

Version History

Introduced in R2024a