getSpectralMaskStatus

Get test results of current spectral mask

Syntax

results = getSpectralMaskStatus(scope)

Description

results = getSpectralMaskStatus(scope) returns the current status of the spectral mask on the spectrum analyzer, scope, in a structure, results.

Examples

Get Spectral Mask Status

Add a spectral mask to an existing spectrumAnalyzer object. Use the getSpectralMaskStatus function to get the spectral mask status.

sine = dsp.SineWave(Frequency=[98 100],SampleRate=1000);
sine.SamplesPerFrame = 1024;   
scope = spectrumAnalyzer(SampleRate=sine.SampleRate,...
       PlotAsTwoSidedSpectrum=false,ShowLegend=true,YLimits=[-60 40]);
hide(scope);

scope.SpectralMask.EnabledMasks = "upper-and-lower";
upperMask = [0 -10; 90 -10; 90 30; 110 30; 110 -10; 500 -10];
set(scope.SpectralMask,UpperMask=upperMask,LowerMask=-55);

for i=1:100       
    scope(sine() + 0.05*randn(1024,2));
end

res = getSpectralMaskStatus(scope)

res = struct with fields:
    IsCurrentlyPassing: 1
        NumPassedTests: 44
         NumTotalTests: 51
           SuccessRate: 86.2745
          FailingMasks: ''
       FailingChannels: [1×0 double]
        SimulationTime: 102.3990

You can also view the status in the Spectral Mask tab on the Spectrum Analyzer toolstrip.

show(scope);
release(scope);

Input Arguments

scope — Spectrum Analyzer

object name | block configuration

Spectrum Analyzer with spectral masks, specified as one of the following:

• spectrumAnalyzer object

• SpectrumAnalyzerBlockConfiguration object for a Spectrum Analyzer block

Output Arguments

results — Current status of spectral mask

structure

Current status of the spectral mask, returned as a structure with these fields.

Field	Description
IsCurrentlyPassing	Pass status of one or more masks. 1 — All masks have passed 0 — One or more masks have failed
NumPassedTests	Number of mask tests that have passed
NumTotalTests	Total number of mask tests
SuccessRate	Percentage of tests that have passed
FailingChannels	Array of channel numbers that have currently failed the mask test
FailingMasks	Masks that have currently failed: "none", "upper", "lower", or "upper-and-lower"
SimulationTime	Simulation time

Version History

Introduced in R2017a

R2024a: dsp.SpectrumAnalyzer System object warns

The dsp.SpectrumAnalyzer System object™ warns in R2024a. Use the spectrumAnalyzer object instead.

Update Code

No updates to your code are required except replacing instances of dsp.SpectrumAnalyzer with spectrumAnalyzer.

This table shows how the getSpectralMaskStatus function typically uses the dsp.SpectrumAnalyzer System object and explains how to update existing code to use the spectrumAnalyzer object.

Discouraged Usage

Recommended Replacement

Add a spectral mask to an existing dsp.SpectrumAnalyzer System object scope and get its status using the getSpectralMaskStatus function. sine = dsp.SineWave('Frequency',[98 100],'SampleRate',1000); sine.SamplesPerFrame = 1024; scope = dsp.SpectrumAnalyzer('SampleRate',sine.SampleRate, ... 'PlotAsTwoSidedSpectrum',false,'ShowLegend',true,... 'YLimits',[-60 40]); hide(scope); scope.SpectralMask.EnabledMasks = 'Upper and lower'; upperMask = [0 -10; 90 -10; 90 30; 110 30; 110 -10; 500 -10]; set(scope.SpectralMask,'UpperMask',upperMask,'LowerMask',-55); for i=1:100 scope(sine() + 0.05*randn(1024,2)); end res = getSpectralMaskStatus(scope) res = struct with fields: IsCurrentlyPassing: 0 NumPassedTests: 1 NumTotalTests: 33 SuccessRate: 3.0303 FailingMasks: 'Upper and lower' FailingChannels: [1 2] SimulationTime: 101.3760 You can see the same information in the Spectral Mask panel of the Spectrum Analyzer. show(scope); release(scope);

Add a spectral mask to an existing spectrumAnalyzer object scope and get its status using the getSpectralMaskStatus function. The spectrumAnalyzer object uses the filter bank method as the default spectral estimation method. Compared to the Welch method, the filter bank method has a lower noise floor, better frequency resolution, and also requires fewer samples per update. To retain the same default behavior as the dsp.SpectrumAnalyzer System object, change the Method property to "welch" and the AveragingMethod property to "exponential". If needed, adjust the value of the forgetting factor. sine = dsp.SineWave(Frequency=[98 100],SampleRate=1000); sine.SamplesPerFrame = 1024; scope = spectrumAnalyzer(SampleRate=sine.SampleRate,... PlotAsTwoSidedSpectrum=false,ShowLegend=true,... Method="welch",AveragingMethod="exponential",... ForgettingFactor=0.4,YLimits=[-60 40]); hide(scope); scope.SpectralMask.EnabledMasks = "upper-and-lower"; upperMask = [0 -10; 90 -10; 90 30; 110 30; 110 -10; 500 -10]; set(scope.SpectralMask,UpperMask=upperMask,LowerMask=-55); for i=1:100 scope(sine() + 0.05*randn(1024,2)); end res = getSpectralMaskStatus(scope) res = struct with fields: IsCurrentlyPassing: 1 NumPassedTests: 32 NumTotalTests: 33 SuccessRate: 96.9697 FailingMasks: '' FailingChannels: [1×0 double] SimulationTime: 102.3990 You can see the same information in the Spectral Mask tab on the Spectrum Analyzer toolstrip. show(scope); release(scope);

R2022a: Support for dsp.SpectrumAnalyzer object will be removed

The getSpectralMaskStatus function will stop supporting the dsp.SpectrumAnalyzer object in a future release. Use the spectrumAnalyzer object instead.