SpectrumAnalyzerBlockConfiguration

Configure Spectrum Analyzer for programmatic access

Description

The SpectrumAnalyzerBlockConfiguration object contains the scope configuration information for the Spectrum Analyzer block.

Creation

MyScopeConfiguration = get_param(gcbh,'ScopeConfiguration') constructs a new spectrum analyzer configuration object. You must first select the block in the model or provide the full path to the block.

Properties

Frequently Used

NumInputPorts — Number of input ports

"1" (default) | character vector | string scalar

Number of input ports on a scope block, specified as a character vector or string scalar. The maximum number of input ports that you can specify is 96.

Scope Window Use

Click Settings in the Scope tab and specify Num Inputs.

Data Types: char | string

SpectrumType — Spectrum type

"Power" (default) | "Power density" | "RMS"

Spectrum type, specified as one of these:

"Power" — Power spectrum

"Power density" — Power spectral density. The power spectral density is the magnitude squared of the spectrum normalized to a bandwidth of 1 Hz.

"RMS" — Root mean square. The root mean square shows the square root of the mean square. Use this option to view the frequency of voltage or current signals.

Tunable: Yes

Scope Window Use

In the Scope tab on the Spectrum Analyzer toolstrip, select Spectrum. Click Spectrum to select Power, Power Density, or RMS.

Data Types: char | string

SampleRateSource — Source of input sample rate

"Inherited" (default) | "Property"

Source of the input sample rate, specified as one of these:

• "Inherited" — Spectrum Analyzer inherits the input sample rate from the model.

• "Property" — Specify the sample rate input directly using the SampleRate property.

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip. In the Bandwidth section, set Sample Rate (Hz) to Inherited or specify a finite scalar.

Data Types: char | string

SampleRate — Sample rate of input

"10e3" (default) | character vector of a positive scalar | string scalar of a positive scalar

Sample rate of the input signal in Hz, specified as a character vector or a string scalar of a positive scalar.

Dependency

To enable this property, set SampleRateSource to "Property".

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip. In the Bandwidth section, specify Sample Rate (Hz) to a finite scalar.

Data Types: char | string

PlotAsTwoSidedSpectrum — Option to plot a two-sided spectrum

false (default) | true

Option to plot a two-sided spectrum, specified as one of the following:

• false — Compute and plot one-sided spectral estimates. If you set this property to false, then the input signal must be real valued.

  When you set this property to false, the Spectrum Analyzer uses power-folding. The y-axis values are twice the amplitude that they would be if you were to set this property to true, except at 0 and the Nyquist frequency. A one-sided power spectral density (PSD) contains the total power of the signal in the frequency interval from DC to half the Nyquist rate. For more information, see pwelch (Signal Processing Toolbox).

• true — Compute and plot two-sided spectral estimates. When the input signal is complex valued, you must set this property to true.

Scope Window Use

Click the Spectrum tab of the Spectrum Analyzer toolstrip. In the Trace Options section, select Two-Sided Spectrum to compute and plot two-sided spectral estimates.

Data Types: logical

FrequencyScale — Scale to display frequency

"Linear" (default) | "Log"

Scale to display frequency, specified as one of the following:

• "Linear" — Use a linear scale to display frequencies on the x-axis. To use the "Linear" option, you must also set the PlotAsTwoSidedSpectrum property to true.

• "Log" — Use a logarithmic scale to display frequencies on the x-axis. To use the "Log" option, you must also set the PlotAsTwoSidedSpectrum property to false.

Tunable: Yes

Scope Window Use

Click the Spectrum tab on the Spectrum Analyzer toolstrip. In the Scale section, set the Frequency Scale to Linear or Log.

To set the Frequency Scale to Log, clear the Two-Sided Spectrum check box in the Trace Options section in the Spectrum tab. If you select the Two-Sided Spectrum check box, then you must set the Frequency Scale to Linear.

Data Types: char | string

PlotType — Plot type to display normal traces

"Line" (default) | "Stem"

Plot type to display normal traces, specified as "Line" or "Stem". Normal traces are traces that display free-running spectral estimates.

Tunable: Yes

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip, navigate to the Configuration section and click Settings. In the Spectrum Analyzer Settings window, under Display and Labels, set Plot Type to Line or Stem.

Data Types: char | string

AxesScaling — Axes scaling mode

"Auto" (default) | "Manual" | "OnceAtStop" | "Updates"

Axes scaling mode, specified as one of these:

• "Auto" — The scope scales the axes to fit the data, both during and after simulation.

• "Manual" — The scope does not scale the axes automatically.

• "OnceAtStop" — The scope scales the axes when the simulation stops.

• "Updates" — The scope scales the axes after a specific number of visual updates. It determines the number of updates using the AxesScalingNumUpdates property.

Tunable: Yes

Data Types: char | string

AxesScalingNumUpdates — Number of updates before scaling

"100" (default) | character vector of a positive integer | string scalar of a positive integer

Number of updates before scaling, specified as a character vector or a string scalar of a positive integer.

Tunable: Yes

Dependency

To enable this property, set AxesScaling to "Updates".

Data Types: char | string

Advanced

RBWSource — Source of resolution bandwidth value

"Auto" (default) | "Property" | "InputPort"

Source of the resolution bandwidth (RBW) value, specified as one of these:

• "Auto" — The Spectrum Analyzer adjusts the spectral estimation resolution to ensure that there are 1024 RBW intervals over the defined frequency span.

• "Property" — Specify the resolution bandwidth directly using the RBW property.

• "InputPort" — An input port appears on the Spectrum Analyzer block through which you specify the RBW. You can use this option only for frequency inputs.

Tunable: Yes

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Frequency Resolution section, set RBW (Hz) to Auto, Input port or to a positive scalar.

Data Types: char | string

RBW — Resolution bandwidth

"9.76" (default) | character vector of a positive scalar | string scalar of a positive scalar

Resolution bandwidth (RBW) in Hz, specified as a character vector or a string scalar of a positive scalar. Specify the value to ensure that there are at least two RBW intervals over the specified frequency span. The ratio of the overall span to RBW satisfies this condition:

$$\frac{span}{RBW}>2$$

You can specify the overall span in different ways based on how you set the FrequencySpan property.

RBW controls the spectral resolution of the displayed signal. The RBW value determines the spacing between frequencies that can be resolved. A smaller value gives a higher spectral resolution and lowers the noise floor, that is, the Spectrum Analyzer can resolve frequencies that are closer to each other. However, this comes at the cost of a longer sweep time.

Tunable: Yes

Dependency

To enable this property, set RBWSource to "Property".

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Frequency Resolution section, set RBW (Hz) to a positive scalar.

Data Types: char | string

WindowInvariantSamplesPerUpdate — Maintain samples per update

false or 0 (default) | true or 1

Since R2024b

Set this property to true to maintain the number of samples per update N_samples at 1024 regardless of the window you choose in the Window property. The RBW value adjusts according to the window you choose.

$$N_{samples}=\frac{\left(1-\frac{O_p}{100}\right)\times NENBW\times F_s}{RBW}$$

where,

• O_p is the overlap percent you specify in the OverlapPercent property.

• Fs is the sample rate you specify using the SampleRateSource and SampleRate properties.

• RBW is the resolution bandwidth you specify in the RBWSource and RBW properties.

• NENBW is the normalized effective noise bandwidth. For more information, see the Spectrum Analyzer block reference page.

When you set this parameter to false or 0, the object maintains the same RBW value and adjusts the required number of samples per update N_samples depending on the window you choose.

Tunable: Yes

Dependencies

To enable this property, set RBWSource to "Auto".

Data Types: logical

OverlapPercent — Overlap percentage

"0" (default) | character vector of a real scalar in the range [0 100) | string scalar of a real scalar in the range [0 100)

Overlap percentage between the previous and current buffered data segments, specified as a character vector or string scalar of a real scalar in the range [0 100). The overlap creates a window segment that the Spectrum Analyzer uses to compute a spectral estimate.

Tunable: Yes

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Window Options section, set the Overlap (%).

Data Types: char | string

Window — Window function

"Hann" (default) | "Rectangular"

Specify a window function for the spectral estimation. You can select one of the window options in the following table. For more information on the window functions, click the link to the function reference page in the Signal Processing Toolbox™ documentation.

Window Option	Corresponding Signal Processing Toolbox Function
"Rectangular"	rectwin (Signal Processing Toolbox)
"Hann"	hann (Signal Processing Toolbox)

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Window Options section, set the Window.

Data Types: char | string

AveragingMethod — Smoothing method

"Exponential" (default) | "VBW"

Averaging method, specified as one of the following:

• "Exponential" — Weighted average of samples. The object computes the average over samples weighted by an exponentially decaying forgetting factor. Use the ForgettingFactor property to specify the weighted forgetting factor.

• "VBW" — Video bandwidth method. The object uses a lowpass filter to smooth the trace and decrease noise. Use the VBWSource and VBW properties to specify the VBW value.

For more information, see Averaging Method.

Tunable: Yes

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Averaging section, set Averaging Method to VBW or Exponential.

Data Types: char | string

ForgettingFactor — Weighting forgetting factor

"0.9" (default) | string scalar of scalar in the range (0,1] | character vector of scalar in the range (0,1]

Forgetting factor of the exponential weighted averaging method, specified as a character vector or string scalar of a real scalar in the range (0,1].

Tunable: Yes

Dependency

To enable this property, set AveragingMethod to "Exponential".

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Averaging section, adjust the Forgetting Factor slider.

To enable the Forgetting Factor, set Averaging Method to Exponential.

Data Types: char | string

VBWSource — Source of video bandwidth

"Auto" (default) | "Input port" | "Property"

Source of the video bandwidth (VBW), specified as one of these:

• "Auto" — The Spectrum Analyzer adjusts the VBW such that the equivalent forgetting factor is 0.9.

• "Input port" –– An input port appears on the scope and you can specify the VBW value through this port.

• "Property" — The Spectrum Analyzer adjusts the VBW using the value specified in the VBW property.

For more details on the video bandwidth method, see Averaging Method.

Tunable: Yes

Dependency

To enable this property, set AveragingMethod to "VBW".

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Averaging section, set VBW (Hz) to either Auto or a positive real scalar less than or equal to Sample Rate (Hz)/2.

To enable the VBW (Hz), set Averaging Method to VBW.

Data Types: char | string

VBW — Video bandwidth

"9.76" (default) | character vector of a positive scalar | string scalar of a positive scalar

Video bandwidth, specified as a character vector or a string scalar of a positive scalar less than or equal to SampleRate/2. For more information on the video bandwidth method, see Averaging Method.

Tunable: Yes

Dependency

To enable this property, set VBWSource to "Property".

Scope Window Use

Click the Estimation tab on the Spectrum Analyzer toolstrip. In the Averaging section, set VBW (Hz) to Auto or enter a positive real scalar that is less than or equal to Sample Rate (Hz)/2.

To enable the VBW (Hz), set Averaging Method to VBW.

Data Types: double

SpectrumUnits — Units of the spectrum

"dBm" (default) | "dBm/Hz" | "dBV" | "dBuV" (since R2023b) | "Vrms"

Units of the spectrum, specified as one of these:

• "dBm"

• "dBm/Hz"

• "dBV"

• "dBuV" (since R2023b)

• "Vrms"

The Spectrum Analyzer displays power values in the units you select in this property.

Tunable: Yes

Dependency

The available spectrum units depend on the value you specify in the SpectrumType property.

SpectrumType	Allowed SpectrumUnits
"Power"	"dBm"
"Power density"	"dBm/Hz"
"RMS"	"dBV", "dBuV" (since R2023b), "Vrms"

Scope Window Use

Click the Spectrum tab on the Spectrum Analyzer toolstrip. In the Scale section, set Spectrum Unit.

Data Types: char | string

ReferenceLoad — Reference load to compute power levels

"1" (default) | character vector of a real positive scalar | string scalar of a real positive scalar

Reference load to compute the power levels, specified as a character vector or a string scalar of a positive scalar in Ohms.

Tunable: Yes

Scope Window Use

Click the Spectrum tab on the Spectrum Analyzer toolstrip. In the Scale section, set Reference Load (Ω).

Data Types: char | string

FrequencyOffset — Frequency offset

"0" (default) | numeric scalar character vector | numeric vector character vector | numeric scalar string scalar | numeric vector string scalar

Frequency offset, specified as one of these:

• Numeric scalar — Apply the same frequency offset to all channels, specified as a character vector or a string scalar in Hz.

• Numeric vector — Apply a specific frequency offset for each channel, specified as a character vector or a string scalar in Hz. The vector length must be equal to the number of input channels.

  The frequency-axis values are offset by the values you specify in this property. The overall span must fall within the Nyquist Frequency Interval.

Tunable: Yes

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip. In the Bandwidth section, set Offset (Hz).

Data Types: char | string

TreatMby1SignalsAsOneChannel — Option to treat unoriented input signal as a column vector

true (default) | false

Option to treat unoriented input signal as a column vector, specified as true or false. Set this property to true to treat M-by-1 and unoriented inputs as a column vector or one channel. Set this property to false to treat M-by-1 and unoriented inputs as a 1-by-M row vector.

Data Types: logical

Measurements

MeasurementChannel — Channel for which to obtain measurements

"1" (default) | character vector | string scalar

Channel over which the measurements are obtained, specified as a character vector or a string scalar which evaluates to a positive integer less than or equal to 100. The highest number you can specify is equal to the number of channels (columns) in the input signal.

Tunable: Yes

Scope Window Use

Click the Measurements tab on the Spectrum Analyzer toolstrip. In the Channel section, select a Channel.

Data Types: char | string

CursorMeasurements — Cursor measurements

CursorMeasurementsConfiguration object

Cursor measurements, specified as a CursorMeasurementsConfiguration object. Enable cursor measurements to display waveform cursors. All CursorMeasurementsConfiguration properties are tunable.

Tunable: Yes

Scope Window Use

Click the Measurements tab on the Spectrum Analyzer toolstrip and modify the cursor measurements in the Cursors section.

DistortionMeasurements — Distortion measurements

DistortionMeasurementsConfiguration object

Distortion measurements, specified as a DistortionMeasurementsConfiguration object. Enable distortion measurements to compute and display the harmonic distortion and intermodulation distortion. All DistortionMeasurementsConfiguration properties are tunable.

Tunable: Yes

Scope Window Use

Click the Measurements tab on the Spectrum Analyzer toolstrip and modify the distortion measurements in the Distortion section.

PeakFinder — Peak finder measurement

PeakFinderConfiguration object

Peak finder measurement, specified as a PeakFinderConfiguration object. Enable peak finder to compute and display the largest calculated peak values. All PeakFinderConfiguration properties are tunable.

Tunable: Yes

Scope Window Use

Click the Measurements tab on the Spectrum Analyzer toolstrip and modify the peak finder measurements in the Peaks section.

Visualization

Name — Caption to display in spectrum Analyzer window

"Spectrum Analyzer" (default) | character vector | string scalar

Caption to display in the scope window, specified as a character vector or string scalar.

Tunable: Yes

Data Types: char | string

Position — Window position

screen center (default) | [left bottom width height]

Spectrum Analyzer window position in pixels, specified by the size and location of the scope window as a four-element double vector of the form [left bottom width height]. You can place the scope window in a specific position on your screen by modifying the values to this property.

By default, the window appears in the center of your screen with a width of 800 pixels and height of 450 pixels. The exact center coordinates depend on your screen resolution.

Tunable: Yes

MaximizeAxes — Maximize axes control

"Auto" (default) | "On" | "Off"

Maximize axes control, specified as one of the following:

• "Auto" –– The Spectrum Analyzer maximizes axes only if the display does not contain any labels or title annotations.

• "On" –– The Spectrum Analyzer maximizes axes in all displays.

• "Off" –– The Spectrum Analyzer does not maximize axes in any display.

Tunable: Yes

Scope Window Use

Click the control on the Spectrum Analyzer display to maximize the axes.

Data Types: char | string

Title — Display title

'' (default) | character vector | string scalar

Display title, specified as a character vector or a string scalar.

Tunable: Yes

Scope Window Use

Click the Scope tab on the spectrum analyzer toolstrip. In the Configuration section, click Settings, and enter Title.

Data Types: char | string

YLabel — Y-axis label

'' (default) | character vector | string scalar

y-axis label, specified as a character vector or a string scalar. The Spectrum Analyzer displays the label to the left of the y-axis.

Regardless of the value of this property, Spectrum Analyzer always displays power units as one of the SpectrumUnits values.

Tunable: Yes

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip. In the Configuration section, click Settings. In the Spectrum Analyzer Settings window that opens up, under Display and labels, enter Y-Label.

Data Types: char | string

YLimits — Y-axis limits

[-80, 20] (default) | [ymin ymax]

y-axis limits, specified as a two-element numeric vector of the form [ymin ymax]. The units of the y-axis limits depend on the SpectrumUnits property.

Example: scope.YLimits = [-10,20]

Tunable: Yes

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip. In the Configuration section, click Settings. In the Spectrum Analyzer Settings window that opens up, under Display and Labels, enter Y-Limits.

ShowGrid — Flag to show grid

true (default) | false

Flag to show the grid, specified as true or false. Set this property to true to show grid lines in the plot.

Tunable: Yes

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip. In the Configuration section, click Settings, and select Show Grid.

Data Types: logical

ChannelNames — Channel names

empty cell (default) | cell array of character vectors | array of strings

Channel names in the input data, specified as a cell array of character vectors or an array of strings. The names you specify in this property appear in the following locations:

• Legend

• Spectrum Analyzer Settings > Color and styling section

• Measurements and Channel Measurements tabs

If you do not specify channel names, the spectrum analyzer names the channels as Channel 1, Channel 2, and so on.

Tunable: Yes

Dependency

To see the channel names, set ShowLegend to true.

Scope Window Use

Click the Scope tab on the spectrum analyzer toolstrip. To see the legend, click Legend in the Configuration section.

Data Types: char

ShowLegend — Flag to show legend

false (default) | true

Flag to show the legend, specified as true or false. To show a legend with the input names, set this property to true.

Use the legend to control which signals are visible. In the scope legend, click a signal name to hide the signal in the scope. To show the signal, click the signal name again. To show only one signal, right-click the signal name. To show all signals, press Esc.

Tunable: Yes

Scope Window Use

Click the Scope tab on the Spectrum Analyzer toolstrip. To see the legend, click Legend in the Configuration section.

Data Types: logical

OpenAtSimulationStart — Flag to open scope when simulation starts

true (default) | false

Flag to open scope when simulation starts, specified as true or false.

Set this property to true to open the scope when the simulation starts. Set this property to false to prevent the scope from opening when you simulate the model.

Scope Window Use

Click Settings in the Scope tab. In the Spectrum Analyzer Settings window that opens, select Open at Simulation Start.

Data Types: logical

Visible — Visibility of the Spectrum Analyzer

false (default) | true

Set this property to true to display the spectrum analyzer window, and to false to hide the spectrum analyzer window.

Data Types: logical

Examples

Construct Spectrum Analyzer Configuration Object

Create the configuration object for a Spectrum Analyzer block.

Create a new Simulink® model with a randomly generated name.

sysname=char(randi(26,1,7)+96);
new_system(sysname);

Add a new Spectrum Analyzer block to the model.

add_block('built-in/SpectrumAnalyzer',[sysname,'/SpectrumAnalyzer'])

Call the get_param function to retrieve the default Spectrum Analyzer block configuration properties.

config = get_param([sysname,'/SpectrumAnalyzer'],'ScopeConfiguration')

config = 

  SpectrumAnalyzerBlockConfiguration with properties:

                   NumInputPorts: '1'
                    SpectrumType: 'Power'
                SampleRateSource: 'Inherited'
          PlotAsTwoSidedSpectrum: 1
                  FrequencyScale: 'Linear'
                        PlotType: 'Line'
                     AxesScaling: 'Auto'

   Advanced
                       RBWSource: 'Auto'
                 AveragingMethod: 'VBW'
                       VBWSource: 'Auto'
                   SpectrumUnits: 'dBm'
                   ReferenceLoad: '1'
                 FrequencyOffset: '0'
    TreatMby1SignalsAsOneChannel: 1

   Spectrogram
    No properties.

   Measurements
              MeasurementChannel: '1'
              CursorMeasurements: [1×1 CursorMeasurementsConfiguration]
          DistortionMeasurements: [1×1 DistortionMeasurementsConfiguration]
                      PeakFinder: [1×1 PeakFinderConfiguration]

   Visualization
                            Name: 'SpectrumAnalyzer'
                        Position: [880 470 800 500]
                    MaximizeAxes: 'Auto'
                           Title: ''
                          YLabel: ''
                         YLimits: [-80 20]
                        ShowGrid: 1
                    ChannelNames: {''}
                      ShowLegend: 0
           OpenAtSimulationStart: 1
                         Visible: 0

Version History

Introduced in R2016b

R2024b: Higher display precision in scope UI

You can now increase the display precision to 15 digits using the Display Precision property in the scope settings under Display and Labels. This precision affects all the measurements and data that the scope displays on its status bar.

R2024b: Preserve Colors is now available in scope toolstrip

The Preserve colors for copy to clipboard property has been renamed to Preserve Colors and is now available in the scope toolstrip under Copy Display.

R2024b: Window Invariant Samples Per Update: Adjust RBW value to always require 1024 samples per spectral update

The spectrum analyzer can now automatically adjust the resolution bandwidth (RBW) such that it always requires 1024 samples per spectral update (Nsamples = 1024) irrespective of the window you choose.

To enable this mode in the SpectrumAnalyzerBlockConfiguration object, set:

• RBWSource to "Auto".

• WindowInvariantSamplesPerUpdate to true.

R2023b: Spectrum Analyzer supports dBuV units

You can set SpectrumUnits to "dBuV" when you set SpectrumType to "RMS".

R2023a: Spectrum Analyzer with better responsiveness and toolstrip interface in Simulink

In R2023a, the Spectrum Analyzer block comes with better responsiveness and a toolstrip interface that gives you easy access to spectral analysis, estimation, and measurements.