plotMask

Plot labels and time-frequency map based on time-frequency mask

Since R2026a

collapse all in page

    Syntax

    plotMask(msk,x)
    plotMask(msk,x,Parent=h)

    Description

    plotMask(msk,x) plots the time-frequency map of the input signal x along with an array of rectangular label masks, both in the current figure, using the time-frequency mask msk.

    • If msk.MaskFormat is "pixel", then plotMask displays the time-frequency map and the label array on two subplots.

    • If msk.MaskFormat is "boundingbox", then plotMask displays the time-frequency map and the labeled time-frequency regions of interest (ROIs) on a single plot.

    • If msk.MaskFormat is "table", then plotMask displays only the time-frequency map.

    • The plotMask function uses the labelSpectrogramOptions object stored in msk.TimeFrequencyOptions to compute the time-frequency map.

    example

    plotMask(msk,x,Parent=h) plots the time-frequency map and label array in the target parent container h.

    Examples

    collapse all

    Open Live Script

    Label Gaussian atoms in the time-frequency domain using a time-frequency region-of-interest (ROI) label definition and spectrogram options. Plot mask from labeled signal in the time-frequency domain.

    Generate Signal and Visualize Spectrogram

    Generate a signal that consists of a voltage-controlled oscillator and five Gaussian atoms. The signal is sampled at 14 kHz for two seconds. Plot the spectrogram of the signal.

    Fs = 14000;
t = (0:1/Fs:2)';
st = 0.01;
gaussFun = @(A,x,mu,f) exp(-(x-mu).^2/(2*st^2)).*sin(2*pi*f.*x)*A';
atomTimeCenters = [0.2 0.5 1 1.3 1.8];
atomFreqCenters = [2 6 2 5 1]*1000;
atomAmplitudes = [1 1 1 1 1]/10;
s = gaussFun(atomAmplitudes,t,atomTimeCenters,atomFreqCenters) ...
    + vco(chirp(t+0.1,0,t(end),3).*exp(-2*(t-1).^2),[0.1 0.4]*Fs,Fs);

bt = 0.2;
tr = 0.05;
op = 99;
pspectrum(s,Fs,"spectrogram", ...
    Leakage=bt,TimeResolution=tr,OverlapPercent=op)

    Figure contains an axes object. The axes object with title Fres = 64.5333 Hz, Tres = 50 ms, xlabel Time (s), ylabel Frequency (kHz) contains an object of type image.

    The spectrogram shows four patches in time-frequency domain that correspond with the Gaussian atoms. Define the times and frequencies for all the atoms.

    atomTimes = atomTimeCenters'+[-st st]*5.5;
atomFreqs = atomFreqCenters'+[-1 1]*200;

    Label Signal in Time-Frequency Domain

    Create a logical time-frequency ROI label definition to label the Gaussian atoms. Specify spectrogram options with leakage properties.

    opts = labelSpectrogramOptions("leakage", ...
    Leakage=40*(1-bt),Overlap=op, ...
    TimeResolutionMode="specify",TimeResolution=tr);

lblDef = signalLabelDefinition("Atom", ...
    LabelDataType="logical", ...
    LabelType="roiTimeFrequency",TimeFrequencyOptions=opts);

    Create a labeled signal set from the signal and time-frequency ROI label definition.

    lss = labeledSignalSet(s,lblDef,SampleRate=Fs);

    Label the atoms in time-frequency domain. Set the label values to true.

    setLabelValue(lss,1,"Atom",atomTimes,atomFreqs,true(5,1))

    Display the label table. Each label has its time-frequency ROI limits and a logical value.

    lblTable = lss.Labels.Atom{1};
lblTable.Value = cell2mat(lblTable.Value)
    lblTable=5×3 table
    TimeROILimits     FrequencyROILimits    Value
    ______________    __________________    _____

    0.145    0.255       1800    2200       true 
    0.445    0.555       5800    6200       true 
    0.945    1.055       1800    2200       true 
    1.245    1.355       4800    5200       true 
    1.745    1.855        800    1200       true

    Visualize Labeled Signal in Time-Frequency Domain

    Create a time-frequency mask with the label table and spectrogram options. Specify the signal sample rate and mask format.

    msk = timeFrequencyMask(lblTable,opts, ...
    SampleRate=Fs,MaskFormat="boundingbox")
    msk = 
  timeFrequencyMask with properties:

             FreqLocation: "yaxis"
       IncludePartialBins: 0
               MaskFormat: "boundingbox"
    MaxFrequencyBandwidth: Inf
          MaxTimeDuration: Inf
    MinFrequencyBandwidth: 0
          MinTimeDuration: 0
               SampleRate: 14000
          SpecifyMaskSize: 0
     TimeFrequencyOptions: [1×1 labelSpectrogramOptions]

    Read the time-frequency mask and display it above the time-frequency image.

    plotMask(msk,s)

    Figure contains an axes object. The axes object with title Time-Frequency Map, xlabel Time (s), ylabel Frequency (kHz) contains 11 objects of type image, rectangle, text.

    Input Arguments

    collapse all

    Time-frequency mask, specified as a timeFrequencyMask object.

    Example: msk = timeFrequencyMask(table([0.1 0.2],[160 180],true),labelSpectrogramOptions,SampleRate=1000) specifies a time-frequency mask with a true time-frequency region that spans from 0.1 to 0.2 seconds and from 160 to 180 Hz, where the time-frequency map of the signal is computed using default label spectrogram options.

    Example: msk = timeFrequencyMask(table([10 20;120 150;160 190],[0.16 0.18;0.08 0.14;0.2 0.22],categorical(["whale1";"whale2";"whale1"])), labelSpectrogramOptions("rbw")) specifies a time-frequency mask with two whale1 time-frequency regions and one whale2 time-frequency region, where the time-frequency map of the signal is computed using resolution-bandwidth (RBW) label spectrogram options. The time limits are in samples and the frequency limits are in radians/sample.

    Input signal, specified as a vector.

    Example: chirp(0:1/1e3:1,25,1,50) specifies a chirp sampled at 1 kHz.

    Data Types: single | double
    Complex Number Support: Yes

    Target parent container, specified as an Axes object or a Panel object.

    If you specify this argument, the plotMask function plots the time-frequency map and label array on the specified target parent container h.

    For more information about target containers and the parent-child relationship in MATLAB® graphics, see Graphics Object Hierarchy. For more information about using Parent in UIAxes and Panel objects to design apps, see Plot Spectral Representations of Signal in App Designer.

    Example: h = axes(figure,Position=[0.1 0.1 0.6 0.5]) defines an axes parent container. When you specify plotMask(msk,x,Parent=h), the function plots the time-frequency map and label array in the parent container h.

    Version History

    Introduced in R2026a

    See Also

    Apps

    Objects