SpectrumAnalyzerConfiguration

Configure Spectrum Analyzer for programmatic access

Description

The spbscopes.SpectrumAnalyzerConfiguration 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 give 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 by a character vector or string scalar. Maximum number of input ports is 96.

Scope Window Use

Select File > Number of Input Ports.

Data Types: char | string

SpectrumType — Type of spectrum to show

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

Specify the spectrum type to display.

"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 hertz.

"RMS" — Root mean square. The root-mean-square shows the square root of the mean square. This option is useful when viewing the frequency of voltage or current signals.

Tunable: Yes

Scope Window Use

Open the Spectrum Settings. In the Main options section, set Type.

Data Types: char | string

SampleRateSource — Source of input sample rate

"Inherited" (default) | "Property"

Specify the source of the input sample rate as:

• "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

Open the Spectrum Settings. In the Main options section, in the Sample rate (Hz) combo box, enter a custom sample rate or select Inherited.

Data Types: char | string

SampleRate — Sample rate of input

"10e3" (default) | character vector | string scalar

Specify the sample rate of the input signals in hertz as a character vector or string scalar.

Dependency

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

Scope Window Use

Open the Spectrum Settings. In the Main options section, enter a Sample rate (Hz) in the combo box.

Data Types: char | string

PlotAsTwoSidedSpectrum — Two-sided spectrum flag

false (default) | true

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

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

  When this property is false, Spectrum Analyzer uses power-folding. The y-axis values are twice the amplitude that they would be if this property were set 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 of the Nyquist rate. For more information, see pwelch (Signal Processing Toolbox).

Scope Window Use

Open the Spectrum Settings. In the Trace options section, select Two-sided spectrum.

Data Types: logical

FrequencyScale — Frequency scale

"Linear" (default) | "Log"

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

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

Tunable: Yes

Scope Window Use

Open the Spectrum Settings. In the Trace options section, set Scale.

Data Types: char | string

Advanced

RBWSource — Source of resolution bandwidth value

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

Specify the source of the resolution bandwidth (RBW) as "Auto", "Property", or "InputPort".

• "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 is added to the Spectrum Analyzer block to read the RBW. This option is only applicable to frequency input.

Scope Window Use

Open the Spectrum Settings. In the Frequency input options section, set RBW (Hz).

Data Types: char | string

RBW — Resolution bandwidth

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

RBW controls the spectral resolution of the Spectrum Analyzer. Specify the resolution bandwidth in hertz as a character vector or string scalar. You must specify a value to ensure that there are at least two RBW intervals over the specified frequency span. Thus, the ratio of the overall span to RBW must be greater than two:

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

Dependency

To enable, set:

• RBWSource to "Property"

Scope Window Use

Open the Spectrum Settings. In the Main options section, set RBW (Hz).

Data Types: char | string

OverlapPercent — Overlap percentage

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

The percentage overlap between the previous and current buffered data segments, specified as a character vector or string scalar of a real scalar. The overlap creates a window segment that is used to compute a spectral estimate. The value must be greater than or equal to zero and less than 100.

Scope Window Use

Open the Spectrum Settings. In the Window options section, set Overlap (%).

Data Types: char | string

Window — Window function

"Hann" (default) | "Rectangular"

Specify a window function for the spectral estimation. The following table shows preset windows. For more information, follow the link to the corresponding function reference 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

Open the Spectrum Settings. In the Window options section, set Window.

Data Types: char | string

SpectrumUnits — Units of the spectrum

"dBm" (default)

This property is read-only.

Specify the units in which the Spectrum Analyzer displays power values. To change the spectrum units you must have DSP System Toolbox™.

AveragingMethod — Smoothing method

"Running" (default) | "Exponential"

Specify the smoothing method as:

• Running — Running average of the last n samples. Use the SpectralAverages property to specify n.

• Exponential — Weighted average of samples. Use the ForgettingFactor property to specify the weighted forgetting factor.

For more information about the averaging methods, see Averaging Method (DSP System Toolbox).

Scope Window Use

Open the Spectrum Settings. In the Trace options section, set Averaging method.

Data Types: char | string

SpectralAverages — Number of spectral averages

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

Specify the number of spectral averages as a character vector or string scalar. The Spectrum Analyzer computes the current power spectrum estimate by computing a running average of the last N power spectrum estimates. This property defines N.

Dependency

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

Scope Window Use

Open the Spectrum Settings. In the Trace options section, set Averages.

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]

Specify the exponential weighting as a scalar value greater than 0 and less than or equal to 1, specified as a string scalar or character vector.

Dependency

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

Scope Window Use

Open the Spectrum Settings. In the Trace options section, set Forgetting factor.

Data Types: char | string

ReferenceLoad — Reference load

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

The load the scope uses as a reference to compute power levels.

Scope Window Use

Open the Spectrum Settings. In the Trace options 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

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

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

  The frequency-axis values are offset by the values specified in this property. The overall span must fall within the Nyquist frequency interval.

Scope Window Use

Open the Spectrum Settings. In the Trace options section, set Offset (Hz).

Data Types: char | string

TreatMby1SignalsAsOneChannel — Treat unoriented sample-based input signal as a column vector

true (default) | false

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

Data Types: logical

Measurements

MeasurementChannel — Channel for which measurements are obtained

"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 greater than 0 and less than or equal to 100. The maximum number you can specify is the number of channels (columns) in the input signal.

Tunable: Yes

Scope Window Use

Click on Tools > Measurements and open the Trace Selection settings.

Data Types: char | string

PeakFinder — Peak finder measurement

PeakFinderSpecification object

Enable peak finder to compute and display the largest calculated peak values. The PeakFinder property uses the PeakFinderSpecification properties.

The PeakFinderSpecification properties are:

• MinHeight –– Level above which peaks are detected, specified as a scalar value.

  Default: -Inf

• NumPeaks –– Maximum number of peaks to show, specified as a positive integer scalar less than 100.

  Default: 3

• MinDistance –– Minimum number of samples between adjacent peaks, specified as a positive real scalar.

  Default: 1

• Threshold –– Minimum height difference between peak and its neighboring samples, specified as a nonnegative real scalar.

  Default: 0

• LabelFormat –– Coordinates to display next to the calculated peak value, specified as a character vector or a string scalar. Valid values are "X", "Y", or "X + Y".

  Default: "X + Y"

• Enable –– Set this property to true to enable peak finder measurements. Valid values are true or false.

  Default: false

All PeakFinderSpecification properties are tunable.

Tunable: Yes

Scope Window Use

Open the Peak Finder pane () and modify the Settings options.

CursorMeasurements — Cursor measurements

CursorMeasurementsSpecification object

Enable cursor measurements to display screen or waveform cursors. The CursorMeasurements property uses the CursorMeasurementsSpecification properties.

The CursorMeasurementsSpecification properties are:

• Type –– Type of the display cursors, specified as either "Screen cursors" or "Waveform cursors".

  Default: "Waveform cursors"

• ShowHorizontal –– Set this property to true to show the horizontal screen cursors. This property applies when you set the Type property to "Screen cursors".

  Default: true

• ShowVertical –– Set this property to true to show the vertical screen cursors. This property applies when you set the Type property to "Screen cursors".

  Default: true

• Cursor1TraceSource –– Specify the waveform cursor 1 source as a positive real scalar. This property applies when you set the Type property to "Waveform cursors".

  Default: 1

• Cursor2TraceSource –– Specify the waveform cursor 2 source as a positive real scalar. This property applies when you set the Type property to "Waveform cursors".

  Default: 1

• LockSpacing –– Lock spacing between cursors, specified as a logical scalar.

  Default: false

• SnapToData –– Snap cursors to data, specified as a logical scalar.

  Default: true

• XLocation –– x-coordinates of the cursors, specified as a real vector of length equal to 2.

  Default: [-2500 2500]

• YLocation –– y-coordinates of the cursors, specified as a real vector of length equal to 2. This property applies when you set the Type property to "Screen cursors".

  Default: [-55 5]

• Enable –– Set this property to true to enable cursor measurements. Valid values are true or false.

  Default: false

All CursorMeasurementsSpecification properties are tunable.

Scope Window Use

Open the Cursor Measurements pane () and modify the Settings options.

DistortionMeasurements — Distortion measurements

DistortionMeasurementsSpecification object

Enable distortion measurements to compute and display the harmonic distortion and intermodulation distortion. The DistortionMeasurements property uses the DistortionMeasurementsSpecification properties.

The DistortionMeasurementsSpecification properties are:

• Algorithm –– Type of measurement data to display, specified as either "Harmonic" or "Intermodulation".

  Default: "Harmonic"

• NumHarmonics –– Number of harmonics to measure, specified as a real, positive integer. This property applies when you set the Algorithm to "Harmonic".

  Default: 6

• Enable –– Set this property to true to enable distortion measurements.

  Default: false

All DistortionMeasurementsSpecification properties are tunable.

Scope Window Use

Open the Distortion Measurements pane () and modify the Distortion and Harmonics options.

Visualization

Name — Window name

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

Title of the scope window.

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

PlotType — Plot type for normal traces

"Line" (default) | "Stem"

Specify the type of plot to use for displaying normal traces as either "Line" or "Stem". Normal traces are traces that display free-running spectral estimates.

Tunable: Yes

Scope Window Use

Open the Style properties and set Plot type.

Data Types: char | string

ReducePlotRate — Improve performance with reduced plot rate

true (default) | false

The simulation speed is faster when this property is set to true.

• true — the scope logs data for later use and updates the display at fixed intervals of time. Data occurring between these fixed intervals might not be plotted.

• false — the scope updates every time it computes the power spectrum. Use the false setting when you do not want to miss any spectral updates at the expense of slower simulation speed.

Scope Window Use

Select Simulation > Reduce plot rate to improve performance.

Data Types: logical

Title — Display title

'' (default) | character vector | string scalar

Specify the display title as a character vector or string.

Tunable: Yes

Scope Window Use

Open the Configuration Properties. Set Title.

Data Types: char | string

YLabel — Y-axis label

'' (default) | character vector | string scalar

Specify the text for the scope to display to the left of the y-axis.

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

Tunable: Yes

Scope Window Use

Open the Configuration Properties. Set Y-label.

Data Types: char | string

ShowLegend — Show legend

false (default) | true

To show a legend with the input names, set this property to true.

From the legend, you can control which signals are visible. This control is equivalent to changing the visibility in the Style dialog box. 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.

Note

The legend only shows the first 20 signals. Any additional signals cannot be viewed or controlled from the legend.

Tunable: Yes

Scope Window Use

Open the Configuration Properties. On the Display tab, select Show legend.

Data Types: logical

ChannelNames — Channel names

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

Specify the input channel names as a cell array of character vectors or an array of strings. The names appear in the legend, Style dialog box, and Measurements panels. If you do not specify names, the channels are labeled as Channel 1, Channel 2, etc.

Tunable: Yes

Dependency

To see channel names, set ShowLegend to true.

Scope Window Use

On the legend, double-click the channel name.

Data Types: char

ShowGrid — Grid visibility

true (default) | false

Set this property to true to show gridlines on the plot.

Tunable: Yes

Scope Window Use

Open the Configuration Properties. On the Display tab, set Show grid.

Data Types: logical

YLimits — Y-axis limits

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

Specify the y-axis limits as a two-element numeric vector, [ymin ymax].

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

Tunable: Yes

Scope Window Use

Open the Configuration Properties. Set Y-limits (maximum) and Y-limits (minimum).

AxesScaling — Axes scaling mode

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

Specify when the scope automatically scales the axes. Valid values are:

• "Auto" — The scope scales the axes as-needed 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 once after 10 updates.

Scope Window Use

Select Tools > Axes Scaling.

Data Types: char | string

AxesScalingNumUpdates — Number of updates before scaling

"10" (default) | integer character vector | integer string scalar

Set this property to delay auto scaling the y-axis.

Dependency

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

Scope Window Use

Open the Axes Scaling dialog box and set Number of updates.

Data Types: char | string

OpenAtSimulationStart — Open scope when starting simulation

true (default) | 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 at the start of simulation.

Scope Window Use

Select File > Open at Start of Simulation.

Data Types: logical

Visible — Visibility of the Spectrum Analyzer

false | true

Set this property to true to show the spectrum analyzer window, or false to hide the spectrum analyzer window.

Data Types: logical

Examples

Construct a 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 = 

  SpectrumAnalyzerConfiguration with properties:

                   NumInputPorts: '1'
                    SpectrumType: 'Power'
                SampleRateSource: 'Inherited'
          PlotAsTwoSidedSpectrum: 1
                  FrequencyScale: 'Linear'

   Advanced
                       RBWSource: 'Auto'
                  OverlapPercent: '0'
                          Window: 'Hann'
                   SpectrumUnits: 'dBm'
                 AveragingMethod: 'Running'
                SpectralAverages: '1'
                   ReferenceLoad: '1'
                 FrequencyOffset: '0'
    TreatMby1SignalsAsOneChannel: 1

   Measurements
              MeasurementChannel: '1'
                      PeakFinder: [1×1 PeakFinderSpecification]
              CursorMeasurements: [1×1 CursorMeasurementsSpecification]
          DistortionMeasurements: [1×1 DistortionMeasurementsSpecification]

   Visualization
                            Name: 'SpectrumAnalyzer'
                        Position: [560 375 800 450]
                        PlotType: 'Line'
                  ReducePlotRate: 1
                           Title: ''
                          YLabel: ''
                      ShowLegend: 0
                    ChannelNames: {''}
                        ShowGrid: 1
                         YLimits: [-80 20]
                     AxesScaling: 'Auto'
           OpenAtSimulationStart: 1
                         Visible: 0

Version History

Introduced in R2016b