info

Information about filter System object

Syntax

s = info(sysobj)

s = info(sysobj,infoType)

s = info(___,Arithmetic=arithType)

Description

s = info(sysobj) returns very basic information about the filter System object™. The particulars depend on the filter type and structure.

s = info(sysobj,infoType) returns the amount of filter information as specified by the infoType.

s = info(___,Arithmetic=arithType) analyzes the filter System object, based on the arithmetic specified in arithType, using either of the previous syntaxes.

For more input options, see info in Signal Processing Toolbox™.

Examples

Obtain Filter Information

Obtain short-format and long-format information about a filter.

d = fdesign.lowpass;
f = design(d,SystemObject=true);
info(f)

ans = 7×35 char array
    'Discrete-Time FIR Filter (real)    '
    '-------------------------------    '
    'Filter Structure  : Direct-Form FIR'
    'Filter Length     : 43             '
    'Stable            : Yes            '
    'Linear Phase      : Yes (Type 1)   '
    'Input sample rate : Normalized     '

info(f,'long')

ans = 46×45 char array
    'Discrete-Time FIR Filter (real)              '
    '-------------------------------              '
    'Filter Structure  : Direct-Form FIR          '
    'Filter Length     : 43                       '
    'Stable            : Yes                      '
    'Linear Phase      : Yes (Type 1)             '
    '                                             '
    'Design Method Information                    '
    'Design Algorithm : equiripple                '
    '                                             '
    'Design Options                               '
    'Density Factor : 16                          '
    'Maximum Phase  : false                       '
    'Minimum Order  : any                         '
    'Minimum Phase  : false                       '
    'Stopband Decay : 0                           '
    'Stopband Shape : flat                        '
    'SystemObject   : true                        '
    'Uniform Grid   : true                        '
    '                                             '
    'Design Specifications                        '
    'Sample Rate     : N/A (normalized frequency) '
    'Response        : Lowpass                    '
    'Specification   : Fp,Fst,Ap,Ast              '
    'Passband Edge   : 0.45                       '
    'Stopband Edge   : 0.55                       '
    'Passband Ripple : 1 dB                       '
    'Stopband Atten. : 60 dB                      '
    '                                             '
    'Measurements                                 '
    'Sample Rate      : N/A (normalized frequency)'
    'Passband Edge    : 0.45                      '
    '3-dB Point       : 0.46957                   '
    '6-dB Point       : 0.48314                   '
    'Stopband Edge    : 0.55                      '
    'Passband Ripple  : 0.89042 dB                '
    'Stopband Atten.  : 60.945 dB                 '
    'Transition Width : 0.1                       '
    '                                             '
    'Implementation Cost                          '
    'Number of Multipliers            : 43        '
    'Number of Adders                 : 42        '
    'Number of States                 : 42        '
    'Multiplications per Input Sample : 43        '
    'Additions per Input Sample       : 42        '
    'Input sample rate : Normalized               '

Decimate a Signal Using a CICDecimator Object

Decimate a signal from 44.1 kHz to 11.025 kHz using a dsp.CICDecimator System object™ with DecimationFactor set to 4. Begin by creating the dsp.CICDecimator object.

cicdec = dsp.CICDecimator(DecimationFactor=4, ...
    FixedPointDataType="Minimum section word lengths", ...
    OutputWordLength=16);

Construct a 1 kHz sinusoidal generator with a sample rate of 44.1 kHz and 64 samples per frame.

FsIn = 44.1e3;
sine = dsp.SineWave(Frequency=1e3,SampleRate=FsIn,SamplesPerFrame=64);

The input signal for the CIC decimator is a sine wave quantized to a signed fixed-point format with a word length of 16 bits and a fractional length of 15 bits.

inDT = numerictype(true,16,15);
src  = @()fi(sine(),inDT);

Decimate the input with a factor of 4 to obtain 16 samples per output frame. Use the gain function to compute the CIC filter gain. Use the outputDelay function to obtain the CIC latency rate and the output sample rate. Plot the output frames of the original and decimated signals using the parameters you computed.

% Determine the CIC gain
cicGain = gain(cicdec);

% Determine the CIC latency and the output sample rate
[cicDelay,FsOut] = outputDelay(cicdec,InputSampleRate=FsIn);

ts = timescope(NumInputPorts=2, ...
    SampleRate=[FsIn FsOut], ...
    TimeDisplayOffset=[0,-cicDelay], ...
    ChannelNames=["Input signal","Decimated signal"], ...
    YLimits=[-2 2], ...
    PlotType="stem");

for ii = 1:16
    u = src();        % Fetch an input frame
    y = cicdec(u);    % decimate
    ts(u, y/cicGain);
end

Using the info method in "long" format, obtain the word lengths and fraction lengths of the fixed-point filter sections and the filter output.

info(cicdec,"long")

ans = 17×56 char array
    'Discrete-Time FIR Multirate Filter (real)               '
    '-----------------------------------------               '
    'Filter Structure    : Cascaded Integrator-Comb Decimator'
    'Decimation Factor   : 4                                 '
    'Differential Delay  : 1                                 '
    'Number of Sections  : 2                                 '
    'Stable              : Yes                               '
    'Linear Phase        : Yes (Type 1)                      '
    '                                                        '
    '                                                        '
    'Implementation Cost                                     '
    'Number of Multipliers            : 0                    '
    'Number of Adders                 : 4                    '
    'Number of States                 : 4                    '
    'Multiplications per Input Sample : 0                    '
    'Additions per Input Sample       : 2.5                  '
    'Input sample rate : Normalized                          '

Interpolate Signal Using CICInterpolator System object

Create a dsp.CICInterpolator System object™ with InterpolationFactor set to 2. Interpolate a fixed-point signal by a factor of 2 from 22.05 kHz to 44.1 kHz.

cicint = dsp.CICInterpolator(InterpolationFactor=2)

cicint = 
  dsp.CICInterpolator with properties:

    InterpolationFactor: 2
      DifferentialDelay: 1
            NumSections: 2
     FixedPointDataType: 'Full precision'

Create a dsp.SineWave object with SampleRate set to 22.05 kHz, SamplesPerFrame set to 32, and OutputDataType set to "Custom". To generate a fixed-point signal, set the CustomOutputDataType property to a numerictype object. For the purpose of this example, set the value to numerictype([],16). The fraction length is computed based on the values of the generated sinusoidal signal to give the best possible precision.

To generate a fixed-point signal, set the Method property of the dsp.SineWave object to "Table lookup". This method of generating the sinusoidal signal requires that the period of every sinusoid in the output be evenly divisible by the sample period. That is, $1/f_i{T}_s=k_i$ must be an integer value for every channel i = 1, 2, ..., N. The value of $T_s$ equals $1/F_s$, the variable $f_i$ is the frequency of the sinusoidal signal, and $F_s$ is the sample rate of the signal. In other words, the ratio $F_s/f_i$ must be an integer. For more details, see the Algorithms section on the dsp.SineWave object page.

In this example, $F_s$ is set to 22050 Hz and $f_i$ is set to 1050 Hz.

FsIn = 22.05e3;      
sine = dsp.SineWave(Frequency=1050,...
    SampleRate=FsIn,...
    SamplesPerFrame=32,...
    Method="Table lookup",...
    OutputDataType="Custom",...
    CustomOutputDataType=numerictype([],16));

The output of the CIC interpolation filter is amplified by a specific gain value. You can determine this value using the gain function. This gain equals the gain of the $2N^{\text{th}}$ stage of the CIC interpolation filter and equals ${\left(I\times D\right)}^N/I$, where $I$ is the interpolation factor, $D$ is the differential delay, and $N$ is the number of sections of the CIC interpolator.

cicGain = gain(cicint)

cicGain = 
2

To adjust this amplified output and to match it to the amplitude of the original signal, divide the CIC interpolated signal with the computed gain value.

Stream the fixed-point sinusoidal signal of sample rate 22.05 kHz. Interpolate each input frame by a factor of 2, producing an interpolated output frame with 64 samples. Plot the original and the interpolated signals, accounting for the CIC interpolation latency and gain.

% Determine the CIC latency and the output sample rate
[cicDelay,FsOut] = outputDelay(cicint,InputSampleRate=FsIn);

ts = timescope(NumInputPorts=2, ...
    SampleRate=[FsOut FsIn], ...
    TimeDisplayOffset=[0,cicDelay], ...
    ChannelNames=["Interpolated signal","Input signal"], ...
    YLimits=[-2 2], ...
    PlotType="stem"...
    );

for i = 1:16
    % Fetch an input frame and interpoalte it
    u = sine();
    y = cicint(u);
    ts(y/cicGain,u);
end

Using the info function in the "long" format, obtain the word lengths and fraction lengths of the fixed-point filter sections and the filter output.

info(cicint,"long")

ans = 17×61 char array
    'Discrete-Time FIR Multirate Filter (real)                    '
    '-----------------------------------------                    '
    'Filter Structure      : Cascaded Integrator-Comb Interpolator'
    'Interpolation Factor  : 2                                    '
    'Differential Delay    : 1                                    '
    'Number of Sections    : 2                                    '
    'Stable                : Yes                                  '
    'Linear Phase          : Yes (Type 1)                         '
    '                                                             '
    '                                                             '
    'Implementation Cost                                          '
    'Number of Multipliers            : 0                         '
    'Number of Adders                 : 4                         '
    'Number of States                 : 4                         '
    'Multiplications per Input Sample : 0                         '
    'Additions per Input Sample       : 6                         '
    'Input sample rate : Normalized                               '

Specify Input Sample Rate in dsp.FIRFilter Object

Since R2026a

Using SampleRate Argument

Specify the input sample rate explicitly while constructing the dsp.FIRFilter object using the SampleRate argument.

firFilt = dsp.FIRFilter(SampleRate=22050)

firFilt = 
  dsp.FIRFilter with properties:

            Structure: 'Direct form'
      NumeratorSource: 'Property'
            Numerator: [0.5000 0.5000]
    InitialConditions: 0

  Show all properties

You can view this information using the Input sample rate field of the info function.

info(firFilt)

ans = 7×35 char array
    'Discrete-Time FIR Filter (real)    '
    '-------------------------------    '
    'Filter Structure  : Direct-Form FIR'
    'Filter Length     : 2              '
    'Stable            : Yes            '
    'Linear Phase      : Yes (Type 2)   '
    'Input sample rate : 22050          '

Visualize the frequency response of the filter using filterAnalyzer. Note the frequency range from 0 to 11025 Hz.

filterAnalyzer(firFilt,FilterNames="FIRFilter22050Hz")

Using setInputSampleRate Function

To specify the input sample rate after constructing the object, use the setInputSampleRate function.

setInputSampleRate(firFilt,44100)

To confirm, view the sample rate information using the info function.

info(firFilt)

ans = 7×35 char array
    'Discrete-Time FIR Filter (real)    '
    '-------------------------------    '
    'Filter Structure  : Direct-Form FIR'
    'Filter Length     : 2              '
    'Stable            : Yes            '
    'Linear Phase      : Yes (Type 2)   '
    'Input sample rate : 44100          '

Visualize the frequency response of the filter using filterAnalyzer. Note the change in frequency interval from 0 to 22050 Hz.

filterAnalyzer(firFilt,FilterNames="FIRFilter44100Hz")

Input Arguments

sysobj — Input filter

filter System object

One of the following types of filter System objects:

• dsp.AllpassFilter

• dsp.AllpoleFilter

• dsp.CICCompensationDecimator

• dsp.CICCompensationInterpolator

• dsp.CICDecimator

• dsp.CICInterpolator

• dsp.ComplexBandpassDecimator

• dsp.CoupledAllpassFilter

• dsp.Delay

• dsp.FarrowRateConverter

• dsp.FilterCascade

• dsp.FIRDecimator

• dsp.FIRFilter

• dsp.FIRHalfbandDecimator

• dsp.FIRHalfbandInterpolator

• dsp.FIRInterpolator

• dsp.FIRRateConverter

• dsp.FourthOrderSectionFilter

• dsp.HighpassFilter

• dsp.IIRFilter

• dsp.IIRHalfbandDecimator

• dsp.IIRHalfbandInterpolator

• dsp.LowpassFilter

• dsp.ParallelFilter

• dsp.SOSFilter

• dsp.VariableBandwidthFIRFilter

• dsp.VariableBandwidthIIRFilter

infoType — Amount of information to display

'short' (default) | 'long'

Amount of filter information to be displayed. When this property is set to:

• 'short' –– The function displays the same information as info(sysobj), which is the basic filter information.

• 'long' –– The function returns the following information about the filter:

  • Specifications such as the filter structure and filter order.

  • Information about the design method and options.

  • Performance measurements for the filter response, such as the passband cutoff or stopband attenuation, included in the measure method

    .

  • Cost of implementing the filter in terms of operations required to apply the filter to data, included in the cost method.

  When the filter uses fixed-point arithmetic, the function returns additional information about the filter, including the arithmetic setting and details about the filter internals.

Data Types: char | string

arithType — Arithmetic type

'double' (default) | 'single' | 'Fixed'

Arithmetic used in the filter analysis, specified as 'double', 'single', or 'Fixed'. When the arithmetic input is not specified and the filter System object is unlocked, the analysis tool assumes a double-precision filter. When the arithmetic input is not specified and the System object is locked, the function performs the analysis based on the data type of the locked input.

The 'Fixed' value applies to filter System objects with fixed-point properties only.

When the 'Arithmetic' input argument is specified as 'Fixed' and the filter object has the data type of the coefficients set to 'Same word length as input', the arithmetic analysis depends on whether the System object is unlocked or locked.

• unlocked –– The analysis object function cannot determine the coefficients data type. The function assumes that the coefficients data type is signed, has a 16-bit word length, and is auto scaled. The function performs fixed-point analysis based on this assumption.

• locked –– When the input data type is 'double' or 'single', the analysis object function cannot determine the coefficients data type. The function assumes that the data type of the coefficients is signed, has a 16-bit word length, and is auto scaled. The function performs fixed-point analysis based on this assumption.

To check if the System object is locked or unlocked, use the isLocked function.

When the arithmetic input is specified as 'Fixed' and the filter object has the data type of the coefficients set to a custom numeric type, the object function performs fixed-point analysis based on the custom numeric data type.

Output Arguments

s — store filter information

character array

Filter information, returned as a character array.

When the infoType is 'short', the function displays basic filter information. When the infoType is 'long', the function displays the following information:

• Specifications such as the filter structure and filter order

• Information about the design method and options

• Performance measurements for the filter response, such as the passband cutoff or stopband attenuation, included in the measure method

• Cost of implementing the filter in terms of operations required to apply the filter to data, included in the cost method

When the filter uses fixed-point arithmetic, the function returns additional information about the filter, including the arithmetic setting and details about the filter internals.

Version History

Introduced in R2011a

R2026a: info function displays input sample rate information

The info function now displays the Input sample rate field as Normalized or a scalar value.

Specify the sample rate during object construction.

firFilt = dsp.FIRFilter(SampleRate=2205)

View the input sample rate information using the info function.

info(firFilt)

ans =
  8×35 char array
    'Discrete-Time FIR Filter (real)    '
    '-------------------------------    '
    'Filter Structure  : Direct-Form FIR'
    'Filter Length     : 2              '
    'Stable            : Yes            '
    'Linear Phase      : Yes (Type 2)   '
    '----------------------------       '
    'Input sample rate : 2205  

R2024b: dsp.BiquadFilter object warns

The dsp.BiquadFilter object issues a warning and will be removed in a future release. Use the dsp.SOSFilter object instead. For more information on how to replace your existing code, see the Compatibility Considerations section in the dsp.BiquadFilter reference page.

R2023b: Support for dsp.ParallelFilter and dsp.Delay Objects

Starting in R2023b, the info analysis function supports the dsp.ParallelFilter and the dsp.Delay objects.

R2023b: dsp.BiquadFilter object will be removed

The dsp.BiquadFilter object will be removed in a future release. Use the dsp.SOSFilter object instead.