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.

UI Use

Select File > Number of Input Ports.

Data Types: char | string

InputDomain — Domain of the input signal

"Time" (default) | "Frequency"

The domain of the input signal you want to visualize. If you visualize time-domain signals, the signal is transformed to the frequency spectrum based on the algorithm specified by the Method parameter.

UI Use

Open the Spectrum Settings. In the Main options section, set Input Domain.

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 sum of the squared means. This option is useful when viewing the frequency of voltage or current signals.

Tunable: Yes

UI Use

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

Data Types: char | string

ViewType — Viewer type

"Spectrum" (default) | "Spectrogram" | "Spectrum and spectrogram"

Specify the spectrum type as one of "Spectrum", "Spectrogram", or "Spectrum and spectrogram".

• "Spectrum" — shows the power spectrum.

• "Spectrogram" — 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.

• "Spectrum and Spectrogram" — shows a dual view of a spectrum and spectrogram.

Tunable: Yes

UI Use

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

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.

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

UI Use

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

Data Types: char | string

Method — Spectrum estimation method

"Welch" (default) | "Filter Bank"

Specify the spectrum estimation method as Welch or Filter bank.

Dependency

To enable this property, set InputDomain to "Time".

UI Use

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

Data Types: char | string

PlotAsTwoSidedSpectrum — Two-sided spectrum flag

true (default) | false

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

UI 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

UI Use

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

Data Types: char | string

Advanced

FrequencySpan — Frequency span mode

"Full" (default) | "Span and center frequency" | "Start and stop frequencies"

• "Full" - The Spectrum Analyzer computes and plots the spectrum over the entire Nyquist frequency interval.

• "Span and center frequency" - The Spectrum Analyzer computes and plots the spectrum over the interval specified by the Span and CenterFrequency properties.

• "Start and stop frequencies" - The Spectrum Analyzer computes and plots the spectrum over the interval specified by the StartFrequency and StopFrequency properties.

Tunable: Yes

UI Use

Open the Spectrum Settings. In the Main options section, select Full frequency span for "Full". Otherwise, clear the Full frequency span check box and choose between Span or FStart.

Data Types: char | string

Span — Frequency span to compute spectrum

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

Specify (as a character vector or string scalar) the frequency span, in hertz, over which the Spectrum Analyzer computes and plots the spectrum. The overall span, defined by this property and the CenterFrequency property, must fall within the Nyquist frequency interval.

Dependency

To enable this property, set FrequencySpan to "Span and center frequency".

UI Use

Open the Spectrum Settings. In the Main options section, clear Full frequency span and set Span.

Data Types: char | string

CenterFrequency — Center of frequency span

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

Specify (as a character vector or string scalar) the frequency center, in hertz, over which the Spectrum Analyzer computes and plots the spectrum. The overall frequency span, defined by the Span and this property, must fall within the Nyquist frequency interval.

Dependency

To enable this property, set FrequencySpan to "Span and center frequency".

UI Use

Open the Spectrum Settings. In the Main options section, clear Full frequency span and set CF (Hz).

Data Types: char | string

StartFrequency — Start frequency to compute spectrum

"-5e3" (default) | character vector of a real scalar | string scalar of a real scalar

Start of the frequency interval over which spectrum is computed, specified in hertz as a character vector or string scalar of a real scalar. The overall span, which is defined by this property and StopFrequency, must fall within the Nyquist frequency interval.

Dependency

To enable this property, set FrequencySpan to "Start and stop frequencies".

UI Use

Open the Spectrum Settings. In the Main options section, clear the Full frequency span and change Span to FStart. Set FStart (Hz).

Data Types: char | string

StopFrequency — Stop frequency to compute spectrum

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

End of the frequency interval over which spectrum is computed, specified in hertz as a character vector or string scalar of a real scalar. The overall span, which is defined by this property and the StartFrequency property, must fall within the Nyquist frequency interval.

Dependency

To enable this property, set FrequencySpan to "Start and stop frequencies".

UI Use

Open the Spectrum Settings. In the Main options section, clear the Full frequency span and change Span to FStart. Set FStop (Hz).

Data Types: char | string

FrequencyResolutionMethod — Frequency resolution method

"RBW" (default) | "WindowLength" | "NumFrequencyBands"

Specify the frequency resolution method of the Spectrum Analyzer.

• "RBW" - the RBWSource and RBW properties control the frequency resolution (in Hz) of the analyzer. The FFT length is the window length that results from achieving the specified RBW value or 1024, whichever is larger.

• "WindowLength" - applies only when the Method property is set to "Welch". The WindowLength property controls the frequency resolution. You can control the number of FFT points only when the FrequencyResolutionMethod property is "WindowLength".

• "NumFrequencyBands" - applies only when the Method property is set to "Filter Bank". The FFTLengthSource and FFTLength properties control the frequency resolution.

Tunable: Yes

Dependency

To enable this property, set InputDomain to "Time".

UI Use

Open the Spectrum Settings. In the Main options section, set the frequency resolution method by selecting the RBW (Hz) dropdown.

Data Types: char | string

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.

Dependencies

To enable this property, set:

• InputDomain to "Time" and FrequencyResolutionMethod to "RBW".

• InputDomain to "Frequency".

UI Use

• Time domain input — Open the Spectrum Settings. In the Main options section, set RBW (Hz).

• Frequency domain input — 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$$

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

Dependency

To enable, set:

• RBWSource to "Property"

UI Use

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

Data Types: char | string

WindowLength — Window length

"1024" (default) | character vector of an integer greater than 2 | string scalar of an integer greater than 2

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, specified as a character vector or string scalar.

Dependencies

To enable this property, set:

• FrequencyResolutionMethod to "WindowLength", which controls the frequency resolution based on your window length setting.

• Method to "Welch".

UI Use

Open the Spectrum Settings. Change the RBW (Hz) dropdown to Window length.

Data Types: char | string

FFTLengthSource — Source of the FFT length

"Auto" (default) | "Property"

• "Auto" - sets the FFT length to the window length specified in the WindowLength property or 1024, whichever is larger.

• "Property" - number of FFT points using the FFTLength property. FFTLength must be greater than WindowLength.

Tunable: Yes

Dependency

To enable this property, set FrequencyResolutionMethod to "WindowLength".

UI Use

Open the Spectrum Settings. In the Main options section, next to the RBW (Hz) option, enter a number or select Auto.

Data Types: char | string

FFTLength — Length of FFT

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

Specify the length of the FFT that the Spectrum Analyzer uses to compute spectral estimates.

If FrequencyResolutionMethod is "RBW", the FFT length is set as the window length required to achieve the specified resolution bandwidth value or 1024, whichever is larger.

Dependencies

To use this property, the following must be true:

• FFTLength value is greater than or equal to the WindowLength.

• FrequencyResolutionMethod is set to "WindowLength" or "NumFrequencyBands"

• FFTLengthSource is set to "Property".

UI Use

Open the Spectrum Settings. In the Main options section, next to the RBW (Hz) option, enter a number or select Auto.

Data Types: char | string

NumTapsPerBand — Number of filter taps per frequency band

"12" (default) | character vector of even integer | string scalar of even integer

Specify the number of filter taps or coefficients for each frequency band as a character vector or a string scalar. This number must be a positive even integer. This value corresponds to the number of filter coefficients per polyphase branch. The total number of filter coefficients is equal to NumTapsPerBand + FFTLength.

Dependency

To enable this property, set Method to "Filter Bank".

UI Use

Open the Spectrum Settings. In the Main options section, set Taps per band.

Data Types: char | string

FrequencyVectorSource — Source of frequency vector

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

• "Auto" — The frequency vector is calculated from the length of the input. See Frequency Vector.

• "Property" — Enter a custom vector as the frequency vector.

• "InputPort" — An input port appears on the block to read the frequency vector input.

Dependency

To enable this property, set InputDomain to "Frequency".

UI Use

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

Data Types: char | string

FrequencyVector — Custom frequency vector

[-5000 5000] (default) | monotonically increasing vector

Set the frequency vector that determines the x-axis of the display. The vector must be monotonically increasing and of the same size as the input frame size.

Dependency

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

UI Use

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

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

InputUnits — Units of frequency input

"dBm" (default) | "dBV" | "dBW" | "Vrms" | "Watts"

Select the units of the frequency-domain input. This property allows the Spectrum Analyzer to scale frequency data if you choose a different display unit with the Units property.

Dependency

This option is only available when InputDomain is set to Frequency.

UI Use

Open the Spectrum Settings. In the Frequency input options section, set Input units.

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.

UI Use

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

Data Types: char | string

Window — Window function

"Hann" (default) | "Rectangular" | "Chebyshev" | "Flat Top" | "Hamming" | "Kaiser" | "Blackman-Harris" | "Custom"

Specify a window function for the spectral estimator. 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
"Chebyshev"	chebwin
"Flat Top"	flattopwin
"Hamming"	hamming
"Hann"	hann
"Kaiser"	kaiser
"Blackman-Harris"	blackmanharris

To set your own spectral estimation window, set this property to "Custom" and specify a custom window function in the CustomWindow property.

Tunable: Yes

UI Use

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

Data Types: char | string

CustomWindow — Custom window function

"hann" (default) | character array | string scalar

Specify a custom window function as a character array or string. The custom window function name must be on the MATLAB path. This property is useful if you want to customize the window using additional properties available with the Signal Processing Toolbox version of the window function.

Tunable: Yes

Example

Define and use a custom window function.

function w = my_hann(L)
    w = hann(L, 'periodic')
end

scope.Window = 'Custom';
scope.CustomWindow = 'my_hann'

Dependency

To use this property, set Window to "Custom".

UI Use

Open the Spectrum Settings. In the Window options section, in the Window option box, enter a custom window function name.

Data Types: char | string

SidelobeAttenuation — Sidelobe attenuation of window

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

The window sidelobe attenuation, in decibels (dB). The value must be greater than or equal to 45.

Dependency

To enable this property, set Window to "Chebyshev" or "Kaiser".

UI Use

Open the Spectrum Settings. In the Window options section, set Attenuation (dB).

Data Types: char | string

SpectrumUnits — Units of the spectrum

"Auto" (default) | "dBm" | "dBFS" | "dBV" | "dBW" | "Vrms" | "Watts"

Specify the units in which the Spectrum Analyzer displays power values.

Tunable: Yes

Dependency

The available spectrum units depend on the value of SpectrumType.

InputDomain	SpectrumType	Allowed SpectrumUnits
Time	Power or Power density	"dBFS", "dBm", "dBW", "Watts"
	RMS	"Vrms", "dBV"
Frequency	―	"dBm", "dBV", "dBW", "Vrms", "Watts",

UI Use

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

Data Types: char | string

FullScaleSource — Source of full scale

"Auto" (default) | "Property"

Specify the source of the dBFS scaling factor as either "Auto" or "Property".

• "Auto" - The Spectrum Analyzer adjusts the scaling factor based on the input data.

• "Property" - Specify the full-scale scaling factor using the FullScale property.

Dependency

To enable this property, set SpectrumUnits to "dBFS".

UI Use

Open the Spectrum Settings. In the Trace options section, set Full scale to Auto or enter a number.

Data Types: char | string

FullScale — Full scale

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

Specify a character vector or string scalar of a real positive scalar for the dBFS full scale.

Dependency

To enable this option set:

• SpectrumUnits to "dBFS"

• FullScaleSource to "Property"

UI Use

Open the Spectrum Settings. In the Trace options section, set Full scale to Auto or enter a number.

Data Types: char | string

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.

Dependency

To enable this property, set ViewType to "Spectrum" or "Spectrum and spectrogram".

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

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

UI 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

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

UI 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. You can control the overall span in different ways based on how you set the FrequencySpan property.

UI 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

Spectrogram

SpectrogramChannel — Channel for which spectrogram is plotted

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

Specify the channel for which the spectrogram is plotted, as a character vector or string scalar of a real, positive scalar integer in the range [1 N], where N is the number of input channels.

Dependency

To enable this property, set ViewType to "Spectrogram" or "Spectrum and spectrogram".

UI Use

Open the Spectrum Settings. In the Spectrogram options section, select a Channel.

Data Types: char | string

TimeResolutionSource — Source of the time resolution value

"Auto" (default) | "Property"

Specify the source for the time resolution of each spectrogram line as either "Auto" or "Property". The TimeResolution property shows the time resolution for the different frequency resolution methods and time resolution properties.

Tunable: Yes

Dependency

To enable this property, set ViewType to "Spectrogram" or "Spectrum and spectrogram".

UI Use

Open the Spectrum Settings. In the Spectrogram options section, set Time res (s).

Data Types: char | string

TimeResolution — Time resolution

"1e-3" (default) | character vector of a positive scalar | string scalar of a positive scalar

Specify the time resolution of each spectrogram line as a character vector or string scalar of a positive scalar, expressed in seconds.

The time resolution value is determined based on frequency resolution method, the RBW setting, and the time resolution setting.

Method	Frequency Resolution Method	Frequency Resolution Setting	Time Resolution Setting	Resulting Time Resolution in Seconds
Welch or Filter Bank	RBW (Hz)	Auto	Auto	1/RBW
Welch or Filter Bank	RBW (Hz)	Auto	Manually entered	Time Resolution
Welch or Filter Bank	RBW (Hz)	Manually entered	Auto	1/RBW
Welch or Filter Bank	RBW (Hz)	Manually entered	Manually entered	Must be equal to or greater than the minimum attainable time resolution, 1/RBW. Several spectral estimates are combined into one spectrogram line to obtain the desired time resolution. Interpolation is used to obtain time resolution values that are not integer multiples of 1/RBW.
Welch	Window length	—	Auto	1/RBW
Welch	Window length	—	Manually entered	Must be equal to or greater than the minimum attainable time resolution. Several spectral estimates are combined into one spectrogram line to obtain the desired time resolution. Interpolation is used to obtain time resolution values that are not integer multiples of 1/RBW.
Filter Bank	Number of frequency bands	—	Auto	1/RBW
Filter Bank	Number of frequency bands	—	Manually entered	Must be equal to or greater than the minimum attainable time resolution, 1/RBW.

Dependency

To enable this property, set:

• ViewType to "Spectrogram" or "Spectrum and spectrogram"

• TimeResolutionSource to "Property.

UI Use

Open the Spectrum Settings. In the Spectrogram options section, in the Time res (s) box, enter a number.

Data Types: char | string

TimeSpanSource — Source of time span value

"Auto" (default) | "Property"

Specify the source for the time span of the spectrogram as either "Auto" or "Property". If you set this property to "Auto", the spectrogram displays 100 spectrogram lines at any given time. If you set this property to "Property", the spectrogram uses the time duration you specify in seconds in the TimeSpan property.

Tunable: Yes

Dependency

To enable this property, set ViewType to "Spectrogram" or "Spectrum and spectrogram".

UI Use

Open the Spectrum Settings. In the Spectrogram options section, set Time span (s).

Data Types: char | string

TimeSpan — Time span

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

Specify the time span of the spectrogram display in seconds. You must set the time span to be at least twice as large as the duration of the number of samples required for a spectral update.

Dependency

To enable this property, set:

• ViewType to "Spectrogram" or "Spectrum and spectrogram".

• TimeSpanSource to "Property".

UI Use

Open the Spectrum Settings. In the Spectrogram options section, in the Time span (s) box, enter a number.

Data Types: char | string

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

UI Use

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

Data Types: char | string

SpectralMask — Spectral mask lines

SpectralMaskSpecification object

Specify whether to display upper and lower spectral mask lines on a spectrum plot. This property uses SpectralMaskSpecification properties to enable and configure the spectral masks. The SpectralMaskSpecification properties are:

• EnabledMasks — Masks to enable, specified as a character vector or string. Valid values are "None", "Upper", "Lower", or "Upper and lower".

  Default: "None"

• UpperMask — Upper limit spectral mask, specified as a scalar or two-column matrix. If UpperMask is a scalar, the upper limit mask uses the power value of the scalar for all frequency values applicable to the Spectrum Analyzer. If UpperMask is a matrix, the first column contains the frequency values (Hz), which correspond to the x-axis values. The second column contains the power values, which correspond to the associated y-axis values. To apply offsets to the power and frequency values, use the ReferenceLevel and MaskFrequencyOffset property values, respectively.

  Default: Inf

• LowerMask — Lower limit spectral mask, specified as a scalar or two-column matrix. If LowerMask is a scalar, the lower limit mask uses the power value of the scalar for all frequency values applicable to the Spectrum Analyzer. If LowerMask is a matrix, the first column contains the frequency values (Hz), which correspond to the x-axis values. The second column contains the power values, which correspond to the associated y-axis values. To apply offsets to the power and frequency values, use the ReferenceLevel and MaskFrequencyOffset property values, respectively.

  Default: -Inf

• ReferenceLevel — Reference level for mask power values, specified as either "Custom" or "Spectrum peak". When ReferenceLevel is "Custom", the CustomReferenceLevel property value is used as the reference to the power values, in dBr, in the UpperMask and LowerMask properties. When ReferenceLevel is "Spectrum peak", the peak value of the current spectrum of the SelectedChannel is used.

  Default: "Custom"

• CustomReferenceLevel — Custom reference level, specified as a real value, in the same units as the power units. The reference level is the value to which the power values in the UpperMask and LowerMask properties are referenced. This property applies when ReferenceLevel is set to "Custom". This property uses the same units as the PowerUnits property of the Spectrum Analyzer.

  Default: 0

• SelectedChannel — Input channel with peak spectrum to use as the mask reference level, specified as an integer. This property applies when ReferenceLevel is set to "Spectrum peak".

  Default: 1

• MaskFrequencyOffset — Frequency offset, specified as a finite, numeric scalar. Frequency offset is the amount of offset to apply to frequency values in the UpperMask and LowerMask properties.

  Default: 0

All SpectralMaskSpecification properties are tunable.

Masks are overlaid on the spectrum. If the mask is green, the signal is passing the mask limitations. If the mask is red, the signal is failing the mask limits.

You can check the status of the spectral mask using any of these methods:

• To modify the spectral mask and see the spectral mask status, in the scope toolbar, select the spectral mask button, . In the Spectral Mask pane that opens, you can modify the masks and see details about what percentage of the time the mask is succeeding, which mask is failing, how many times the mask failed, and which channels are causing the failure.

• To get the current status of the spectral masks, call the function getSpectralMaskStatus.

• To perform an action every time the mask fails, use the MaskTestFailed event. To trigger a function when the mask fails, create a listener to the MaskTestFailed event and define a callback function to trigger. For more details about using events, see Events (MATLAB).

Tunable: Yes

UI Use

Open the Spectral Mask pane and modify the Settings options.

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

UI 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.

UI Use

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

ChannelMeasurements — Channel measurements

ChannelMeasurementsSpecification object

Enable channel measurements to compute and display the occupied bandwidth or adjacent channel power ratio. The ChannelMeasurements property uses the ChannelMeasurementsSpecification properties.

The ChannelMeasurementsSpecification properties are:

• Algorithm –– Type of measurement data to display, specified as either "Occupied BW" or "ACPR".

  Default: "Occupied BW"

• FrequencySpan –– Frequency span mode, specified as either "Span and center frequency" or "Start and stop frequencies"

  Default: "Span and center frequency"

• Span –– Frequency span over which the channel measurements are computed, specified as a real, positive scalar in Hz. This property applies when you set the FrequencySpan property to "Span and center frequency".

  Default: 2000 Hz

• CenterFrequency –– Center frequency of the span over which the channel measurements are computed, specified as a real scalar in Hz. This property applies when you set the FrequencySpan property to "Span and center frequency".

  Default: 0 Hz

• StartFrequency –– Start frequency over which the channel measurements are computed, specified as a real scalar in Hz. This property applies when you set the FrequencySpan property to "Start and stop frequencies".

  Default: -1000 Hz

• StopFrequency –– Stop frequency over which the channel measurements are computed, specified as a real scalar in Hz. This property applies when you set the FrequencySpan property to "Start and stop frequencies".

  Default: 1000 Hz

• PercentOccupiedBW –– Percent of power over which to compute the occupied bandwidth, specified as a positive real scalar. This property applies when you set the Algorithm property to "Occupied BW".

  Default: 99

• NumOffsets –– Number of adjacent channel pairs, specified as a real, positive integer. This property applies when you set the Algorithm property to "ACPR".

  Default: 2

• AdjacentBW –– Adjacent channel bandwidth, specified as a real, positive scalar. This property applies when you set the Algorithm property to "ACPR".

  Default: 1000

• FilterShape –– Filter shape for both main and adjacent channels, specified as "None", "Gaussian", or "RRC". This property applies when you set the Algorithm property to "ACPR".

  Default: "None"

• FilterCoeff –– Channel filter coefficient, specified as a real scalar between 0 and 1. This property applies when you set the Algorithm property to "ACPR" and the FilterShape property to either "Gaussian" or "RRC".

  Default: 0.5

• ACPROffsets –– Frequency of the adjacent channel relative to the center frequency of the main channel, specified as a real vector of length equal to the number of offset pairs specified in NumOffsets. This property applies when you set the Algorithm property to "ACPR".

  Default: [2000 3500]

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

  Default: false

All ChannelMeasurementsSpecification properties are tunable.

UI Use

Open the Channel Measurements pane () and modify the Measurement and Channel 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.

UI Use

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

CCDFMeasurements — CCDF measurements

CCDFMeasurementsSpecification object

Enable CCDF measurements to display the probability of the input signal's instantaneous power being a certain amount of dB above the signal's average power. The CCDFMeasurements property uses the CCDFMeasurementsSpecification properties.

The CCDFMeasurementsSpecification properties are:

• PlotGaussianReference –– Show a reference CCDF curve of additive white Gaussian noise. Set this property to true to plot a reference CCDF curve.

  Default: false

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

  Default: false

All CCDFMeasurementsSpecification properties are tunable.

UI Use

Open the CCDF Measurements pane () and enable the Plot Gaussian reference option.

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

Dependencies

To enable this property, set:

• ViewType to "Spectrum" or "Spectrum and spectrogram"

• PlotNormalTrace to true

UI Use

Open the Style properties and set Plot type.

Data Types: char | string

PlotNormalTrace — Normal trace flag

true (default) | false

Set this property to false to remove the display of the normal traces. These traces display the free-running spectral estimates. Even when the traces are removed from the display, the Spectrum Analyzer continues its spectral computations.

Tunable: Yes

Dependency

To enable this property, set ViewType to "Spectrum" or "Spectrum and spectrogram".

UI Use

Open the Spectrum Settings. In the Trace options section, select Normal trace.

Data Types: logical

PlotMaxHoldTrace — Max-hold trace flag

false (default) | true

To compute and plot the maximum-hold spectrum of each input channel, set this property to true. 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.

Tunable: Yes

Dependency

To enable this property, set ViewType to "Spectrum" or "Spectrum and spectrogram".

UI Use

Open the Spectrum Settings. In the Trace options section, select Max-hold trace.

Data Types: logical

PlotMinHoldTrace — Min-hold trace flag

false (default) | true

To compute and plot the minimum-hold spectrum of each input channel, set this property to true. 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.

Tunable: Yes

Dependency

To enable this property, set ViewType to "Spectrum" or "Spectrum and spectrogram".

UI Use

Open the Spectrum Settings. In the Trace options section, select Min-hold trace.

Data Types: logical

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.

UI 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

UI 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

Dependency

To enable this property, set ViewType to "Spectrum" or "Spectrum and spectrogram".

UI 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

UI 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

Specify the input channel names as a cell array of character vectors. 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.

UI 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

UI 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

Dependencies

• To enable this property, set the ViewType property to "Spectrum" or "Spectrum and spectrogram".

• The units directly depend upon the SpectrumUnits property.

UI Use

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

ColorLimits — Scale spectrogram color limits

[-80, 20] (default) | [colorMin colorMax]

Control the color limits of the spectrogram using a two-element numeric vector, [colorMin colorMax].

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

Dependencies

• To enable this property, set the ViewType property to "Spectrogram" or "Spectrum and spectrogram".

• The units directly depend upon the SpectrumUnits property.

UI Use

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

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.

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

UI Use

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

Data Types: char | string

AxesLayout — Orientation of the spectrum and spectrogram

"Vertical" (default) | "Horizontal"

Specify the layout type as "Horizontal" or "Vertical". A vertical layout stacks the spectrum above the spectrogram. A horizontal layout puts the two views side-by-side.

Tunable: Yes

Dependency

To enable this property, set ViewType to "Spectrum and spectrogram".

UI Use

Open the Spectrum Settings. Set Axes layout.

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.

UI 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.

Examples

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.

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

config = 
  SpectrumAnalyzerConfiguration with properties:

                   NumInputPorts: '1'
                     InputDomain: 'Time'
                    SpectrumType: 'Power'
                        ViewType: 'Spectrum'
                SampleRateSource: 'Inherited'
                          Method: 'Welch'
          PlotAsTwoSidedSpectrum: 1
                  FrequencyScale: 'Linear'

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

   Measurements
              MeasurementChannel: '1'
                    SpectralMask: [1x1 SpectralMaskSpecification]
                      PeakFinder: [1x1 PeakFinderSpecification]
              CursorMeasurements: [1x1 CursorMeasurementsSpecification]
             ChannelMeasurements: [1x1 ChannelMeasurementsSpecification]
          DistortionMeasurements: [1x1 DistortionMeasurementsSpecification]
                CCDFMeasurements: [1x1 CCDFMeasurementsSpecification]

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

Obtain Measurements Data Programmatically for Spectrum Analyzer Block

Compute and display the power spectrum of a noisy sinusoidal input signal using the Spectrum Analyzer block. Measure the peaks, cursor placements, adjacent channel power ratio, distortion, and CCDF values in the spectrum by enabling these block configuration properties:

• PeakFinder

• CursorMeasurements

• ChannelMeasurements

• DistortionMeasurements

• CCDFMeasurements

Open and Inspect the Model

Filter a streaming noisy sinusoidal input signal using a Lowpass Filter block. The input signal consists of two sinusoidal tones: 1 kHz and 15 kHz. The noise is white Gaussian noise with zero mean and a variance of 0.05. The sampling frequency is 44.1 kHz. Open the model and inspect the various block settings.

model = 'spectrumanalyzer_measurements.slx';
open_system(model)

Access the configuration properties of the Spectrum Analyzer block using the get_param function.

sablock = 'spectrumanalyzer_measurements/Spectrum Analyzer';
cfg = get_param(sablock,'ScopeConfiguration');

Enable Measurements Data

To obtain the measurements, set the Enable property of the measurements to true.

cfg.CursorMeasurements.Enable = true;
cfg.ChannelMeasurements.Enable = true;
cfg.PeakFinder.Enable = true;
cfg.DistortionMeasurements.Enable = true;

Simulate the Model

Run the model. The Spectrum Analyzer block compares the original spectrum with the filtered spectrum.

sim(model)

The right side of the spectrum analyzer shows the enabled measurement panes.

Using getMeasurementsData

Use the getMeasurementsData function to obtain these measurements programmatically.

data = getMeasurementsData(cfg)

data =

  1x5 table

    SimulationTime     PeakFinder     CursorMeasurements    ChannelMeasurements    DistortionMeasurements
    ______________    ____________    __________________    ___________________    ______________________

       [0.9985]       [1x1 struct]       [1x1 struct]          [1x1 struct]             [1x1 struct]     

The values shown in measurement panes match the values shown in data. You can access the individual fields of data to obtain the various measurements programmatically.

Compare Peak Values

As an example, compare the peak values. Verify that the peak values obtained by data.PeakFinder match with the values seen in the Spectrum Analyzer window.

peakvalues = data.PeakFinder.Value
frequencieskHz = data.PeakFinder.Frequency/1000

peakvalues =

   26.7463
   26.3949
   -4.4762


frequencieskHz =

   14.9966
    1.0046
   10.5478

Save and Close the Model

save_system(model);
close_system(model);