Main Content

SpectralMaskSpecification

Display upper and lower spectral mask lines on the Spectrum Analyzer

    Description

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

    You can check the status of the spectral mask from the scope toolbar, the command-line, or event listeners:

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

    Creation

    Description

    example

    mask = SpectralMaskSpecification() creates a spectral mask object mask.

    mask = SpectralMaskSpecification(Name,Value) sets properties using one or more name-value pairs. Enclose each property name in quotes. For example, mask = SpectralMaskSpecification("EnabledMasks","Lower").

    Properties

    expand all

    All properties are tunable.

    Specify which spectral masks to enable, specified as a character vector or string.

    Data Types: char | string

    Limit for upper 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.

    Dependency

    To apply offsets to the power and frequency values, use the ReferenceLevel and MaskFrequencyOffset property values, respectively.

    Limit for the lower 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.

    Dependency

    To apply offsets to the power and frequency values, use the ReferenceLevel and MaskFrequencyOffset property values, respectively.

    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.

    Custom reference level, specified as a real numeric scalar, 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.

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

    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.

    Object Functions

    getSpectralMaskStatusGet test results of current spectral mask

    Examples

    collapse all

    This example shows how to create and use a spectral mask with the dsp.SpectrumAnalyzer object.

    Create an upper spectral mask, set the reference level matrix, and add it to a Spectrum Analyzer object.

    mask = SpectralMaskSpecification();
    mask.EnabledMasks = 'Upper';
    mask.UpperMask = [...
          0 -17; ...
         90 -17; ...
         90  30; ...
        110  30; ...
        110 -17; ...
        500 -17];
    
    scope = dsp.SpectrumAnalyzer('PlotAsTwoSidedSpectrum',false,...
        'ShowLegend',true);
    scope.SpectralMask = mask;
    scope.SpectralMask
    ans = 
      SpectralMaskSpecification with properties:
    
                EnabledMasks: 'Upper'
                   UpperMask: [6x2 double]
                   LowerMask: -Inf
              ReferenceLevel: 'Custom'
        CustomReferenceLevel: 0
         MaskFrequencyOffset: 0
    
      Events for class SpectralMaskSpecification: MaskTestFailed
    
    

    Run the spectrum analyzer using a sine wave spectrum. In the Spectral Mask panel, you can see how the spectrum succeeded or failed to stay within your spectral mask.

    sine = dsp.SineWave('Frequency',[98 100],'SampleRate',1000);
    sine.SamplesPerFrame = 1024;   
    scope.SampleRate = sine.SampleRate;
    
    for i=1:100       
        scope(sine() + 0.05*randn(1024,2));
    end
    release(scope)

    Figure Spectrum Analyzer contains an axes object and other objects of type uiflowcontainer, uimenu, uitoolbar. The axes object contains 3 objects of type patch, line. These objects represent Lower Mask, Upper Mask, Channel 1, Channel 2.

    This example shows how to create a new model based on the dsp_basic_filter template, add a spectral mask to its Spectrum Analyzer block, and run the model.

    Masks are overlaid on the spectrum. If the mask is green, the signal is passing. If the mask is red, the signal is failing. The Spectral Mask panel shows what percentage of the time the mask is succeeding, which mask is failing, how many times the mask(s) failed, and which channels are causing the failure.

      [~,mdl] = fileparts(tempname);
      open_system(new_system(mdl,'FromTemplate','dsp_basic_filter'));
      saBlock = find_system(mdl,'BlockType','SpectrumAnalyzer');
    
      scopeConfig = get_param(saBlock{1},'ScopeConfiguration');
      upperMask = [0 50; 1200 50; 1200 -10; 24000 -10];
      scopeConfig.SpectralMask.UpperMask = upperMask;
      scopeConfig.SpectralMask.LowerMask = -100;
      scopeConfig.SpectralMask.EnabledMasks = 'Upper and lower';
    
      sim(mdl,'StopTime','20');
    

    This example shows how to add a spectral mask to an existing dsp.SpectrumAnalyzer System object scope and get the status with getSpectralMaskStatus.

    sine = dsp.SineWave('Frequency',[98 100],'SampleRate',1000);
    sine.SamplesPerFrame = 1024;
    scope = dsp.SpectrumAnalyzer('SampleRate',sine.SampleRate, ...
           'PlotAsTwoSidedSpectrum',false,'ShowLegend',true);
    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: 'Lower'
           FailingChannels: [1 2]
            SimulationTime: 101.3760
    
    

    In the Spectrum Analyzer, you can see the same information in the Spectral Mask panel.

    show(scope);
    release(scope);
    

    See Also

    Introduced in R2016b