Automatically Label Signals

You can use Signal Labeler to perform automated labeling tasks. The Automate Value gallery on the Label tab contains functions that you can use to label signals automatically.

Add Custom Labeling Functions

To add a custom autolabeling function, click the arrow next to the Automate Value gallery and then select Add Custom Function. In the dialog box, specify these fields:

  • Name — Specify the name of the function you want to add.

  • Description — Add a short description of what the function does and describe the optional input arguments.

  • Label Type — Specify the type of label that the function generates. Select Attribute (the default), ROI, or Point.

    Note

    Based on the Label Type you specify, Signal Labeler places the function in the appropriate category in the Automate Value gallery. When you select a label definition, the gallery enables only those functions that can be used with that type of definition.

If you have already written a function, and the function is in the current folder or in the MATLAB® path, Signal Labeler incorporates it in the gallery. If you have not written the function yet, Signal Labeler opens a blank template in the Editor.

Custom autolabeling functions have mandatory and optional arguments:

  • The first input argument, x, is the input signal. When writing the function, expect x to be a matrix where each column contains data corresponding to a channel. If the channels have different lengths, then expect x to be a cell array of column vectors.

  • The second input argument, t, stores the time values. When writing the function, expect t to be a matrix where each column contains time information corresponding to a channel. If the channels have different lengths, then expect t to be a cell array of column vectors.

    Note

    • For single-channel members, custom autolabeling functions get data and time values as double precision vectors.

    • For multichannel members, custom autolabeling functions get data and time values as matrices or cell arrays.

    • Custom autolabeling functions get all the channels of a member as input, but they need not operate on all of them. You can choose what channels you want the function to operate on.

  • The third input argument, parentLabelVal, is the parent label value associated with the output sublabel and contains a numeric, logical, or string scalar. This argument is passed in only for functions that automate the labeling of sublabels. If the function is for a parent label, expect parentLabelVal to be empty.

  • The fourth input argument, parentLabelLoc, contains:

    • An empty vector when the parent label is an attribute

    • A two-element numeric row vector of ROI limits when the parent label is an ROI

    • A numeric scalar representing a point location when the parent label is a point

    This argument is passed in only for functions that automate the labeling of sublabels. If the function is for a parent label, expect parentLabelLoc to be empty.

    Note

    • For parent labels, the autolabeling function is called for each selected member.

    • For sublabels, the autolabeling function is called for all selected members, one instance of the parent label at a time.

  • Use varargin to specify additional input arguments. If you do not have additional input arguments, you can omit varargin. Enter the additional arguments as an ordered comma-separated list in the dialog box that appears when you click the Auto-Label button.

  • The first output argument, labelVals, contains the label values. labelVals must be:

    • A numeric, logical, or string scalar when the output labels are attributes

    • A column vector with numeric, logical, or string values when the output labels are ROIs or points

  • The second output argument, labelLocs, contains the label locations. labelLocs must be:

    • An empty vector when the output labels are attributes

    • A two-column matrix of ROI limits when the output labels are ROIs

    • A column vector of point locations when the output labels are points

  • To implement your algorithm, you can use any function from MATLAB or any toolbox installed in your system.

See Label QRS Complexes and R Peaks of ECG Signals Using Deep Network and Label Spoken Words in Audio Signals Using External API for more details.

Example: This function computes the mean RMS value of a signal and labels the signal with the value as a numeric attribute.

function [labelVals,labelLocs] = meanRMS(x,t,parentLabelVal,parentLabelLoc,varargin)
% Label signal with its mean RMS value as attribute
    if iscell(x)
      q = cellfun(@rms,r,'UniformOutput',false);
      labelVals = cell2mat(q)';
    else
      labelVals = mean(rms(x));
    end
    labelLocs = [];
end
The function computes the RMS value of each member separately. If a member has more than one channel, the function computes the RMS value of each channel and averages the values. The output is the same for the two three-channel signals a and b, even though a is a matrix and b is a cell array of column vectors.
fs = 1000;
t = 0:1/fs:14-1/fs;
a = [chirp(t-1,0.1,17,2,'quadratic',1).*sin(2*pi*t/5);
    chirp(t-2,2,2,2.1,'quadratic',100).*exp(-(t-6.5).^2/20).*sin(2*pi*t*2);
    0.85*besselj(0,5*(sin(2*pi*(t+1.5).^2/20).^2)).*sin(2*pi*t/9)]';
b = labeledSignalSet({a});

Example: This logical function labels as true those regions of a multichannel signal where:

  • The amplitude of the first channel is negative.

  • The amplitude of the third channel is larger than a user-specified value that defaults to 0.1.

function [labelVals,labelLocs] = greaterThan(x,t,parentLabelVal,parentLabelLoc,varargin)
% Label regions with negative first channel and third channel larger than a given value

if nargin<5
    mx = 0.1;
else
    mx = varargin{1};
end

xr = x(:,1);
xx = x(:,3);
tt = t(:,3);

idx = find(xx >= mx & xr < 0); 
fir = [true;diff(idx)~=1];
ide = [idx(fir) idx(fir([2:end 1]))];

labelLocs = tt(ide);
labelVals = true(size(ide,1),1);

labelVals = logical(labelVals);

end

Example: This function finds the zero crossings of a signal and labels them as "rising" for positive-going transitions and "falling" for negative-going transitions.

function [labelVals,labelLocs] = transitions(x,t,parentLabelVal,parentLabelLoc,varargin)
% Label zero crossings as "rising" or "falling"

if isempty(t)
    t = 0:length(x)-1;
end

fs = 1/(t(2)-t(1));

[~,ltup,utup] = risetime(x,fs,'StateLevels',0.1*[-1 1]);

ups = (utup+ltup)/2;
upc = repmat("rising",length(ups),1);

[~,ltdn,utdn] = falltime(x,fs,'StateLevels',0.1*[-1 1]);

dns = (utdn+ltdn)/2;
dnc = repmat("falling",length(dns),1);

labelLocs = [ups;dns];

labelVals = categorical(string([upc;dnc]),["rising" "falling"]);

end

Manage Custom Labeling Functions

At any time, you can edit functions, edit function descriptions, or remove functions using the Manage Custom Functions option in the Automate Value gallery.

Note

Using the Manage Custom Functions option changes only the function descriptions displayed in the Automate Value gallery. If you want to change the description in the file that contains the function, you must edit the file.

Automatically Label Signals Using Custom Labeling Functions

To autolabel signals using a custom function, start by selecting or creating a signal label definition that you want to apply. The Automate Value gallery shows the automated labeling functions that you can use with the definition. Choose a function from the gallery and click the Auto-Label button. Signal Labeler prompts you to select the members you want to label and specify any optional input arguments.

Note

See Add Custom Labeling Functions for examples.

Note

You can undo the last automated custom labeling you performed. However, you lose this ability once you add, modify, or delete any labels or label definitions.

Automatically Label Signal Peaks Using Peak Labeler

To autolabel signals peaks using Peak Labeler, start by selecting or creating a numeric point label definition. In the Automate Value gallery, select Peak Labeler and click the Auto-Label button. Signal Labeler uses the MATLAB functions islocalmax and islocalmin to find and label local maxima and minima. Peak Labeler returns the location of each peak and the numeric value of its amplitude.

Note

You can select multiple members for peak labeling, but you can label only one channel of each member at a time. By default, Signal Labeler chooses the first channel of each selected member, but you can select which signal of the member you want to use for labeling.

Note

You can undo the last automated peak labeling you performed. However, you lose this ability once you add, modify, or delete any labels or label definitions.

  • You can choose to label all the peaks or valleys in the selected signal that satisfy the specified conditions. Alternatively, you can label a specific number of peaks or valleys that satisfy the specified conditions, sorted in order of descending prominence. See Prominence for more information about peak prominence. The default value is three peaks.

  • If a local maximum or minimum value is repeated consecutively, the peak or valley belongs to a flat region. For a signal with flat peak or valley regions, you can choose to label the center of the region, the first point of the region, the last point of the region, or all points in the region.

  • You can choose to label only those peaks or valleys with prominence larger than a specified value. You can also specify the width of the window centered on a peak or valley that is used to measure its prominence.

    • If you do not specify a window width, the algorithm uses the whole signal as the window.

    • For a flat peak or valley region, the window is centered at the midpoint of the region.

  • You can select to label only those peaks separated by a specified distance. The algorithm:

    1. Chooses the most prominent peak in the signal and ignores all peaks within the specified distance.

    2. Repeats the procedure for the most prominent remaining peak.

    3. Iterates until it runs out of peaks to consider.

Tip

If you label peaks in a signal using Peak Labeler and then move one of the labels, Signal Labeler still shows the amplitude value returned by Peak Labeler. To update the amplitude:

  1. Read the new value on the data cursor you used to move the point label.

  2. On the Labeled Signal Set browser, right-click the label that you moved and select Edit.

  3. Enter the new value in the Value field of the dialog box that appears.

See Also

Apps

Functions

Related Examples

More About