Main Content

SpectralMaskSpecification

Display upper and lower spectral mask lines on the Spectrum Analyzer

expand all in page

    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

    Syntax

    mask = SpectralMaskSpecification()
    mask = SpectralMaskSpecification(Name,Value)

    Description

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

    example

    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.

    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)

    This example uses:

    Open Script

    Create a new model based on the dsp_basic_filter template. Add a spectral mask to the Spectrum Analyzer block in the model. 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');

    Version History

    Introduced in R2016b