# spbscopes.SpectrumAnalyzerConfiguration class

Package: spbscopes

Configure Spectrum Analyzer for programmatic access

## Description

The `spbscopes.SpectrumAnalyzerConfiguration` object contains the scope configuration information for the Spectrum Analyzer block.

## Construction

Call the `get_param` function, specifying a Spectrum Analyzer block.

`htsc = get_param(gcbh,'ScopeConfiguration')` constructs a new Spectrum Analyzer Configuration object.

## Properties

`CenterFrequency`

Frequency over which frequency span is centered

Specify as a real scalar the center frequency, in hertz, of the frequency span over which the Spectrum Analyzer computes and plots the spectrum. This property applies when you set the `FrequencySpan` property to ```'Span and center frequency'```. The overall frequency span, defined by the `Span` and `CenterFrequency` properties, must fall within the Nyquist frequency interval. When the `PlotAsTwoSidedSpectrum` property is set to `true`, the interval is $\left[-\frac{SampleRate}{2},\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz. When the `PlotAsTwoSidedSpectrum` property is set to `false`, the interval is$\left[0,\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz.

This property is Tunable.

Default: `0`

`ChannelNames`

Channel names

Specify as a cell array of strings the input channels names to display in the legend, the Style dialog, and in some Measurements panels. The channel names only appear in the legend when the `ShowLegend` property is `true`. The default is an empty cell array, which labels the channels as `Channel 1`, ```Channel 2```, etc.

This property is Tunable.

`FFTLength`

FFT length

Specify as a positive, scalar integer the length of the FFT that the Spectrum Analyzer uses to compute spectral estimates. This property applies only when you set the `FrequencyResolutionMethod` property to `'WindowLength'` and the `FFTLengthSource` property to `'Property'`. The `FFTLength` must be greater than or equal to the `WindowLength`. You cannot control the FFT length when the `FrequencyResolutionMethod` property is `'RBW'`. In that case, the FFT length is set as the window length required to achieve the specified resolution bandwidth value or 1024, whichever is larger.

This property is Tunable.

Default: `128`

`FFTLengthSource`

Source of the FFT length value

Specify the source of the FFT length value as one of `'Auto'` or `'Property'`.

• When you set this property to `'Auto'`, the Spectrum Analyzer sets the FFT length to the window length specified in the `WindowLength` property or to 1024, whichever is larger.

• When you set this property to `'Property'`, specify the number of FFT points using the `FFTLength` property. The `FFTLength` must be greater than the `WindowLength`.

This property applies only when you set the `FrequencyResolutionMethod` property to `'WindowLength'` and the `FFTLengthSource` property to `'Property'`.

This property is Tunable.

Default: `'Auto'`

`FrequencyOffset`

Frequency offset

Specify as a real, scalar value to apply the same frequency offset, in Hertz, to all channels. To apply a specific frequency offset for each channel, specify a vector of real, scalar values. 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. When the `PlotAsTwoSidedSpectrum` property is `true`, the Nyquist interval is $\left[-\frac{SampleRate}{2},\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz. When you set the `PlotAsTwoSidedSpectrum` property to `false`, the Nyquist interval is$\left[0,\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz. You can control the overall span in different ways based on how you set the `FrequencySpan` property.

This property is Tunable.

Default: `0`

`FrequencyResolutionMethod`

Frequency resolution method

Specify how to control the frequency resolution of the spectrum analyzer as either `'RBW'` or `'WindowLength'`. When you set this property to `'RBW'`, the `RBWSource` and `RBW` properties control the frequency resolution (in Hz) of the analyzer. When you set this property to `'WindowLength'`, the `WindowLength` property controls the frequency resolution.

In this case, the frequency resolution of the analyzer is defined as where NENBW is the normalized effective noise bandwidth of the window currently specified in the `Window` property. You can control the number of FFT points only when the `FrequencyResolutionMethod` property is `'WindowLength'`. When the `FrequencyResolutionMethod` property is `'RBW'`, the FFT length is the window length that results from achieving the specified RBW value or 1024, whichever is larger.

This property is Tunable.

Default: `'RBW'`

`FrequencyScale`

Frequency scale

Specify the frequency scale as either `'Linear'` or `'Log'`. When you set the `FrequencyScale` property to `'Log'`, the Spectrum Analyzer 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`. When the `PlotAsTwoSidedSpectrum` property is `true`, you must set this property to `'Linear'`.

This property is Tunable.

Default: `'Linear'`

`FrequencySpan`

Frequency span mode

Specify the frequency span mode as one of `'Full'`, ```'Span and center frequency'```, or `'Start and stop frequencies'`.

• When you set this property to `'Full'`, the Spectrum Analyzer computes and plots the spectrum over the entire Nyquist frequency interval. When the `PlotAsTwoSidedSpectrum` property is `true`, the Nyquist interval is $\left[-\frac{SampleRate}{2},\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz. If you set the `PlotAsTwoSidedSpectrum` property to `false`, the Nyquist interval is$\left[0,\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz.

• When you set this property to ```'Span and center frequency'```, the Spectrum Analyzer computes and plots the spectrum over the interval specified by the `Span` and `CenterFrequency` properties.

• When you set this property to ```'Start and stop frequencies'```, the Spectrum Analyzer computes and plots the spectrum over the interval specified by the `StartFrequency` and `StopFrequency` properties.

This property is Tunable.

Default: `'Full'`

`Name`

Caption to display on Spectrum Analyzer window

Specify as a string the caption to display on the scope window. This property is Tunable.

Default: `'Spectrum Analyzer'`

`NumInputPorts`

Number of input ports

Number of input ports, specified as an integer. Each signal coming through an input port becomes a separate channel in the Spectrum Analyzer.

Default: `1`

`OpenAtSimulationStart`

Open scope when starting simulation

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.

Default: `true`

`OverlapPercent`

Overlap percentage

Specify as a real, scalar value, the percentage overlap between the previous and current buffered data segments. 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. This property is Tunable.

Default: `0`

`PlotAsTwoSidedSpectrum`

Two sided spectrum flag

Set this property to `true` to compute and plot two-sided spectral estimates. Set this property to `false` to compute and plot one-sided spectral estimates. If you set this property to `false`, then the input signal must be real valued. When the input signal is complex valued, you must set this property to `true`.

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 PSD contains the total power of the signal in the frequency interval from DC to half of the Nyquist rate. For more information, see the `pwelch` function reference page.

Default: `true`

`PlotMaxHoldTrace`

Max-hold trace flag

Set this property to `true` to compute and plot the maximum-hold spectrum of each input channel. The maximum-hold spectrum at each frequency bin is computed by keeping the maximum value of all the power spectrum estimates. When you toggle this property, the Spectrum Analyzer resets its maximum-hold computations. This property applies only when you set the `SpectrumType` property to `'Power'` or `'Power density'`.

This property is Tunable.

See also: `PlotMinHoldTrace` and `PlotNormalTrace`.

Default: `false`

`PlotMinHoldTrace`

Min-hold trace flag

Set this property to `true` to compute and plot the minimum-hold spectrum of each input channel. The minimum-hold spectrum at each frequency bin is computed by keeping the minimum value of all the power spectrum estimates. When you toggle this property, the Spectrum Analyzer resets its minimum-hold computations. This property applies only when you set the `SpectrumType` property to `'Power'` or `'Power density'`.

This property is Tunable.

See also: `PlotMaxHoldTrace` and`PlotNormalTrace`.

Default: `false`

`PlotNormalTrace`

Normal trace flag

Set this property to `false` to remove the display of the normal traces. These traces display the free-running spectral estimates. Note that even when the traces are removed from the display, the Spectrum Analyzer continues its spectral computations. This property applies only when you set the `SpectrumType` property to `'Power'` or ```'Power density'```.

This property is Tunable.

See also: `PlotMaxHoldTrace` and `PlotMinHoldTrace`.

Default: `true`

`PlotType`

Plot type for normal traces

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. This property applies only when you set the `SpectrumType` property to `'Power'` or `'Power density'`. and the `PlotNormalTrace` property to `true`.

This property is Tunable.

Default: `'Line'`

`Position`

Spectrum Analyzer window position in pixels

Specify, in pixels, the size and location of the scope window as a 4-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. This property is Tunable.

Default: The default depends on your screen resolution. By default, the Spectrum Analyzer window appears in the center of your screen with a width of `800` pixels and height of `450` pixels.

`PowerUnits`

Power units

Specify the units in which the Spectrum Analyzer displays power values as either `'dBm'`, `'dBW'`, or `'Watts'`.

This property is Tunable.

Default: `'dBm'`

`RBW`

Resolution bandwidth

Specify as a real, positive scalar the resolution bandwidth (RBW), in hertz. RBW controls the spectral resolution of Spectrum Analyzer. This property applies only when you set the `FrequencyResolutionMethod` property to `'RBW'` and the `RBWSource` property to `'Property'`. 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$. You can specify the overall span in different ways based on how you set the `FrequencySpan` property.

This property is Tunable.

See also: `RBWSource`.

Default: `9.76`

`RBWSource`

Source of resolution bandwidth value

Specify the source of the resolution bandwidth (RBW) as either `'Auto'` or `'Property'`. This property is relevant only when you set the `FrequencyResolutionMethod` property to `'RBW'`.

• When you set this property to `'Auto'`, the Spectrum Analyzer adjusts the spectral estimation resolution to ensures that there are 1024 RBW intervals over the defined frequency span.

• When you set this property to `'Property'`, specify the resolution bandwidth directly using the `RBW` property.

This property is Tunable.

See also: `RBW`.

Default: `'Auto'`

`ReducePlotRate`

Reduce plot rate to improve performance

When you set this property to `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. When you set this property to `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. The simulation speed is faster when this property is set to `true`. This property is Tunable.

Default: `true`

`ReferenceLoad`

Specify as a real, positive scalar the load, in ohms, that the Spectrum Analyzer uses as a reference to compute power values.

This property is Tunable.

Default: `1`

`SampleRate`

Sample rate of input

Specify the sample rate, in hertz, of the input signals.

The sample rate must be a finite numeric scalar.

Default: `10e3`

`ShowGrid`

Option to enable or disable grid display

When you set this property to `true`, the grid appears. When you set this property to `false`, the grid is hidden. This property is Tunable.

Default: `false`

`ShowLegend`

Show or hide legend

When you set this property to `true`, the scope displays a legend with the input channels string labels specified in the `ChannelNames` property. When you set this property to `false`, the scope does not display a legend. This property applies only when you set the `SpectrumType` property to `'Power'` or `'Power density'`. This property is Tunable.

Default: `false`

`SidelobeAttenuation`

Sidelobe attenuation of window

Specify as a real, positive scalar the window sidelobe attenuation, in decibels (dB). This property applies only when you set the `Window` property to `'Chebyshev'` or `'Kaiser'`. The value must be greater than or equal to `45`.

This property is Tunable.

Default: `60`

`Span`

Frequency span over which spectrum is computed and plotted

Specify as a real, positive scalar the frequency span, in hertz, over which the Spectrum Analyzer computes and plots the spectrum. This property applies only when you set the `FrequencySpan` property to ```'Span and center frequency'```. The overall span, defined by this property and the `CenterFrequency` property, must fall within the Nyquist frequency interval. When the `PlotAsTwoSidedSpectrum` property is `true`, the Nyquist interval is $\left[-\frac{SampleRate}{2},\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz. When you set the `PlotAsTwoSidedSpectrum` property to `false`, the Nyquist interval is$\left[0,\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz.

This property is Tunable.

Default: `10e3`

`SpectralAverages`

Number of spectral averages

Specify as a positive, scalar integer the number of spectral averages. This property applies only when you set the `SpectrumType` property to `'Power'` or ```'Power density'```. The Spectrum Analyzer computes the current power spectrum estimate by computing a running average of the last N power spectrum estimates. This property defines the number of spectral averages, N.

This property is Tunable.

Default: `1`

`SpectrumType`

Spectrum type

Specify the spectrum type as one of `'Power'`, ```'Power density'```, or `'Spectrogram'`.

• When you set this property to `'Power'`, the Spectrum Analyzer shows the power spectrum.

• When you set this property to `'Power density'`, the Spectrum Analyzer shows the power spectral density. The power spectral density is the magnitude squared of the spectrum normalized to a bandwidth of 1 hertz.

• When you set this property to `'Spectrogram'`, the Spectrum Analyzer open a spectrogram view, which shows frequency content over time. Each line of the spectrogram is one periodogram. Time scrolls from the bottom to the top of the display. The most recent spectrogram update is at the bottom of the display.

This property is Tunable.

Default: `'Power'`

`StartFrequency`

Start frequency over which spectrum is computed

Specify as a real scalar the start frequency, in hertz, over which the Spectrum Analyzer computes and plots the spectrum. This property applies only when you set the `FrequencySpan` property to `'Start and stop frequencies'`. The overall span, which is defined by `StopFrequency` and this property, must fall within the Nyquist frequency interval. When the `PlotAsTwoSidedSpectrum` property is `true`, the Nyquist interval is $\left[-\frac{SampleRate}{2},\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz. If you set the `PlotAsTwoSidedSpectrum` property to `false`, the Nyquist interval is$\left[0,\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz.

This property is Tunable.

Default: `-5e3`

`StopFrequency`

Stop frequency over which spectrum is computed

Specify as a real scalar the stop frequency, in hertz, over which the Spectrum Analyzer computes and plots the spectrum. This property applies only when you set the `FrequencySpan` property to `'Start and stop frequencies'`. The overall span, defined by this property and the `StartFrequency` property, must fall within the Nyquist frequency interval. When the `PlotAsTwoSidedSpectrum` property is set to `true`, the interval is $\left[-\frac{SampleRate}{2},\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz. When the `PlotAsTwoSidedSpectrum` property is set to `false`, the interval is$\left[0,\frac{SampleRate}{2}\right]+FrequencyOffset$ hertz.

This property is Tunable.

Default: `5e3`

`Title`

Display title

Specify the display title as a string. Enter `%<SignalLabel>` to use the signal labels in the Simulink Model as the axes titles. This property is Tunable.

Default: `''`

`TreatMby1SignalsAsOneChannel`

Treat unoriented sample-based input signal as a column vector

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.

Default: `true`

`Window`

Window function

Specify a window function for the spectral estimator as one of the options in the following table. For information on any window function, follow the link to the corresponding function reference in the Signal Processing Toolbox™ documentation.

Window OptionCorresponding Function in Signal Processing Toolbox
`'Rectangular'``rectwin`
`'Chebyshev'``chebwin`
`'Flat Top'``flattopwin`
`'Hamming'``hamming`
`'Hann'``hann`
`'Kaiser'``kaiser`

This property is Tunable.

Default: `'Hann'`

`WindowLength`

The window length

Control the frequency resolution by specifying the window length, in samples used to compute the spectral estimates. The window length must be an integer scalar greater than 2. This property applies only when you set the `FrequencyResolutionMethod` property to `'WindowLength'`, which controls the frequency resolution based on your window length setting. The resulting resolution bandwidth (RBW) is where Nwindow is the `WindowLength` value.

This property is Tunable.

See also: `Window`.

Default: `1024`

`YLabel`

The label for the y-axis

Specify as a string the text for the scope to display to the left of the y-axis. Tunable

This property applies only when you set the `SpectrumType` property to `'Power'` or ```'Power density'```. Regardless of this property, Spectrum Analyzer always displays power units as one of `'dBm'`, `'dBW'`, `'Watts'`, `'dBm/Hz'`, `'dBW/Hz'`, `'Watts/Hz'`.

See also: `PowerUnits`.

Default: `''`

`YLimits`

The limits for the y-axis

Specify the y-axis limits as a 2-element numeric vector, `[ymin ymax]`. This property is Tunable.

This property applies only when you set the `SpectrumType` property to `'Power'` or ```'Power density'```. The units directly depend upon the `PowerUnits` property.

Default: `[-80, 20]`

## Examples

expand all

### Example: Construct a Spectrum Analyzer Configuration Object

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.

`hsac = get_param([sysname,'/SpectrumAnalyzer'],'ScopeConfiguration')`
```hsac = SpectrumAnalyzerConfiguration with properties: Name: 'SpectrumAnalyzer' NumInputPorts: '1' OpenAtSimulationStart: 1 Visible: 0 Position: [560 375 800 450] SampleRateSource: 'Inherited' SampleRate: '10e3' SpectrumType: 'Power' FrequencySpan: 'Full' Span: '10e3' CenterFrequency: '0' StartFrequency: '-5e3' StopFrequency: '5e3' FrequencyResolutionMethod: 'RBW' RBWSource: 'Auto' RBW: '9.76' WindowLength: '1024' FFTLengthSource: 'Auto' FFTLength: '1024' OverlapPercent: '0' Window: 'Hann' SidelobeAttenuation: '60' TimeResolutionSource: 'Auto' TimeResolution: '1e-3' TimeSpanSource: 'Auto' TimeSpan: '100e-3' SpectralAverages: '1' PowerUnits: 'dBm' ReferenceLoad: '1' PlotMaxHoldTrace: 0 PlotMinHoldTrace: 0 PlotNormalTrace: 1 PlotType: 'Line' PlotAsTwoSidedSpectrum: 1 FrequencyScale: 'Linear' FrequencyOffset: '0' Title: '' YLimits: [-80 20] YLabel: '' ShowLegend: 0 ChannelNames: {''} ShowGrid: 1 ReducePlotRate: 1 TreatMby1SignalsAsOneChannel: 1```