Custom Labeling Functions

You can use the Signal Labeler app to perform automated labeling. The Automate Value gallery on the Label tab contains a function for labeling points found as peaks or valleys and a function for labeling regions of interest bound by a threshold or range. If you have Audio Toolbox™, the gallery contains functions for speech detection, speech-to-text transcription, and sound classification for labeling regions of interest in audio signals. You can also create custom autolabeling functions for each type of label: attribute, region of interest (ROI), point, or time-frequency ROI.

Automate Value gallery

Create Custom Labeling Functions for Time Domain Labels

For attribute, ROI, and point label definitions, the first line in every custom autolabeling function consists of a definition statement of this form.

function [labelVals,labelLocs] = fx(x,t,parentLabelVal,parentLabelLoc,varargin)

The definition statement contains the function name and a set of mandatory and optional input arguments:

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.
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 do not have to operate on all. You can choose which channels you want the function to operate on.
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.
parentLabelLoc contains:
- An empty vector when the parent label is an attribute
- A two-element numeric row vector of region of interest (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 operates on each selected member.
- For sublabels, the autolabeling function operates on one parent label instance at a time for each selected member.
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.

Output arguments include:

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
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 from any toolbox installed in your system.

For more details, see Automate Signal Labeling with Custom Functions and Label Spoken Words in Audio Signals.

Example: Mean RMS Value

This function computes the mean RMS value of a signal and labels the signal with the value as a numeric attribute. If a member has more than one channel, the function computes the RMS value of each channel and averages the values. The channels can have different lengths.

function [labelVals,labelLocs] = meanRMS(x,t,parentLabelVal,parentLabelLoc,varargin)
% Label signal with its mean RMS value as attribute

if iscell(x)
    labelVals = mean(cellfun(@rms,x))
else
    labelVals = mean(rms(x));
end
labelLocs = [];

end

Example: Zero Crossings

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"

nchan = size(x,2);
tt = t(:,1);

labelVals = cell(nchan,1);
labelLocs = cell(nchan,1);

for kj = 1:nchan

    [rate,count,indices] = zerocrossrate(x,TransitionEdge="rising");
    rloc = tt(indices == 1);
    rval = repmat("rising",length(rloc),1);
    
    [rate,count,indices] = zerocrossrate(x,TransitionEdge="falling");
    floc = tt(indices == 1);
    fval = repmat("falling",length(floc),1);
    
    labelLocs{kj} = [rloc;floc];
    labelVals{kj} = [rval;fval];

end

labelVals = cat(1,labelVals{:});
labelLocs = cell2mat(labelLocs);

end

Example: Multichannel Labeling

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, mx. If not specified, mx defaults to 0.1.

You can perform similar labeling of bounded regions using the sigrangebinmask function.

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(:,1);

ss = signalMask(xr < 0 & xx >= mx);
x = roimask(ss);

labelLocs = tt(x.ROILimits);
labelVals = logical(double(x.Value));

end

Example: Extract Spoken Words Using External API

This function uses the IBM® Watson Speech to Text API and the Audio Toolbox speech2text extended functionality to extract spoken words from an audio file.

function [labelVals,labelLocs] = stt(x,t,parentLabelVal,parentLabelLoc,varargin)

aspeechObjectIBM = speechClient("IBM",timestamps=true);

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

tixt = speech2text(aspeechObjectIBM,x,fs);

unifiedTable = vertcat(tixt.TimeStamps{:});
numLabels = numel(unifiedTable,1);
labelVals = strings(numLabels,1);
labelLocs = zeros(numLabels,2);

for idx = 1:numLabels
    labelVals(idx) = unifiedTable{idx}{1};
    labelLocs(idx,1) = unifiedTable{idx}{2};
    labelLocs(idx,2) = unifiedTable{idx}{3};
end

end

Create Custom Labeling Functions for Time-Frequency Domain Labels

For time-frequency ROI label definitions, the first line in every custom autolabeling function consists of a definition statement of this form.

function [labelVals,labelLocsTime,labelLocsFreq] = fx(x,tf,t,f,tfOptions,varargin)

The definition statement contains the function name and a set of mandatory and optional input arguments:

x is the input signal. When writing the function, expect x to be a column vector that contains the signal data in time domain.
tf is the spectrogram power estimate. When writing the function, expect tf to be a matrix where each column contains data corresponding to the power estimate of a windowed time segment and each row contains data corresponding to a power estimate of a frequency bin.
t stores the time values. When writing the function, expect t to be a column vector where each element value represents the centers of each windowed time segment for the spectrogram power estimate.
f stores the frequency values. When writing the function, expect f to be a column vector where each element value represents the centers of each frequency bin for the spectrogram power estimate.
tfOptions stores information about how the power estimate was calculated. When writing the function, expect tfOptions to be a labelSpectrogramOptions object.
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.

Output arguments include:

labelVals contains the label values. labelVals must be a column vector with numeric, logical, or string values.
labelLocsTime contains the label time locations. labelLocsTime must be a two-column matrix of ROI time limits.
labelLocsFreq contains the label time locations. labelLocsFreq must be a two-column matrix of ROI frequency limits.

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

Example: Maximum Spectral Entropy Value

This function computes the maximum spectral entropy value of a signal and labels the signal with the value as a numeric time-frequency ROI. If a member has more than one channel, the function computes the maximum spectral entropy value of the first channel.

function [labelVals,labelLocsTime,labelLocsFreq] = maxSpectralEntropy(x,tf,t,f,tfOptions,varargin)
% Label signal with its maximum spectral entropy at 3 time-frequency ROIs.

tLocMin = [0.3 0.5 0.7];
fLocMin = [0.5 0.2 0.6];

labelLocsTime = zeros(numel(tLocMin),2);
labelLocsFreq = zeros(numel(fLocMin),2);
labelVals = zeros(numel(tLocMin),1);

for i = 1:numel(tLocMin)
    labelLocsTime(i,:) = max(t)*[tLocMin(i) tLocMin(i)+0.1];
    labelLocsFreq(i,:) = max(f)*[fLocMin(i) fLocMin(i)+0.2];
    labelVals(i) = max(spectralEntropy(db2pow(tf),f,t, ...
        TimeLimits=labelLocsTime(i,:), ...
        Range = labelLocsFreq(i,:)));
end

end

Add Custom Labeling Functions to the Gallery

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, Point, or Time-Frequency ROI.
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 definition type.

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.

Manage Custom Labeling Functions in Gallery

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.