Custom Labeling Functions

You can useSignal Labelerto perform automated labeling tasks. Apart fromPeak Labeler, theAutomate Valuegallery on theLabel选项卡包含函数,您可以使用标签ignals automatically.

Automate Value gallery

Create Custom Labeling Functions

The first line in every custom autolabeling function consists of a definition statement of the form

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

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

The first input argument,x, is the input signal. When writing the function, expectxto be a matrix where each column contains data corresponding to a channel. If the channels have different lengths, then expectxto be a cell array of column vectors.
The second input argument,t, stores the time values. When writing the function, expecttto be a matrix where each column contains time information corresponding to a channel. If the channels have different lengths, then expecttto 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.
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, expectparentLabelValto 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 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, expectparentLabelLocto 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.
Usevararginto specify additional input arguments. If you do not have additional input arguments, you can omitvarargin. Enter the additional arguments as an ordered comma-separated list in the dialog box that appears when you click theAuto-Labelbutton.
The first output argument,labelVals, contains the label values.labelValsmust 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.labelLocsmust be:
- An empty vector when the output labels are attributes
- A two-column matrix of ROI limits when the output labels are ROIs
- 一个列向量的点位置时,输出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, seeAutomate Signal Labeling with Custom FunctionsandLabel 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 attributeifiscell(x) labelVals = mean(cellfun(@rms,x))elselabelVals = mean(rms(x));endlabelLocs = [];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);forkj = 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];endlabelVals = 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,mxdefaults 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 valueifnargin<5 mx = 0.1;elsemx = varargin{1};endxr = 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™speech2textextended 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);foridx = 1:numLabels labelVals(idx) = unifiedTable{idx}{1}; labelLocs(idx,1) = unifiedTable{idx}{2}; labelLocs(idx,2) = unifiedTable{idx}{3};endend

Add Custom Labeling Functions to the Gallery

To add a custom autolabeling function, click the arrow next to theAutomate Valuegallery and then selectAdd 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指定标签的类型,功能基因rates. SelectAttribute(the default),ROI, orPoint.

Note

Based on theLabel Typeyou specify,Signal Labelerplaces the function in the appropriate category in theAutomate Valuegallery. 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 Labelerincorporates it in the gallery. If you have not written the function yet,Signal Labeleropens 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 theManage Custom Functionsoption in theAutomate Valuegallery.

Note

Using theManage Custom Functionsoption changes only the function descriptions displayed in theAutomate Valuegallery. If you want to change the description in the file that contains the function, you must edit the file.