setLabelValue

Set label value in labeled signal set

Syntax

setLabelValue(lss,midx,lblname,val)

setLabelValue(lss,midx,lblname,limits,val)

setLabelValue(lss,midx,lblname,locs,val)

setLabelValue(___,'LabelRowIndex',ridx)

setLabelValue(___,'SublabelRowIndex',sridx)

Description

setLabelValue(lss,midx,lblname,val) sets the attribute label lblname to value val, for the member of labeled signal set lss specified in midx. Omit val if lblname has a default value and you want to set the label to the default value.

setLabelValue(lss,midx,lblname,limits,val) adds regions delimited by limits to the ROI label named lblname. The number of rows of limits specifies the number of added regions.

setLabelValue(lss,midx,lblname,locs,val) adds points to the point label named lblname. locs specifies the number of added points and their locations.

setLabelValue(___,'LabelRowIndex',ridx) specifies the row index, ridx, of an ROI or point label. The specified value replaces the current value of that row. If you omit this argument, the function appends ROI or point values to any existing label values.

setLabelValue(___,'SublabelRowIndex',sridx) specifies the row index, sridx, of an ROI or point sublabel. The specified value replaces the current value of that sublabel row.

Examples

Set Label Value

Load a labeled signal set containing recordings of whale songs.

load whales
lss

lss = 
  labeledSignalSet with properties:

             Source: {2x1 cell}
         NumMembers: 2
    TimeInformation: "sampleRate"
         SampleRate: 4000
             Labels: [2x3 table]
        Description: "Characterize wave song regions"

 Use labelDefinitionsHierarchy to see a list of labels and sublabels.
 Use setLabelValue to add data to the set.

Add a new label to the signal set, corresponding to the maximum value of each member.

theMax = signalLabelDefinition('Maximum', ...
    'LabelDataType','numeric', ...
    'Description','Maximum value of the signal');
addLabelDefinitions(lss,theMax)

For each labeled signal, set the value of the new label to the signal maximum. Plot the signals and their maxima.

fs = lss.SampleRate;
for k = 1:lss.NumMembers
    sg = getSignal(lss,k);
    [mx,ix] = max(sg);
    
    setLabelValue(lss,k,'Maximum',mx)
    
    subplot(2,1,k)
    plot((0:length(sg)-1)/fs,sg,ix/fs,mx,'*')
end

Display the names and values of the labels in the set.

lbldefs = getLabelValues(lss)

lbldefs=2×4 table
                 WhaleType    MoanRegions    TrillRegions     Maximum  
                 _________    ___________    ____________    __________

    Member{1}      blue       {3x2 table}    {1x3 table}     {[0.2850]}
    Member{2}      blue       {3x2 table}    {1x3 table}     {[0.3791]}

Decide that the signal maximum is better represented as a point label than as an attribute. Remove the numeric definition and redefine the maximum.

removeLabelDefinition(lss,'Maximum')
theMax = signalLabelDefinition('Maximum', ...
    'LabelType','point','LabelDataType','numeric', ...
    'Description','Maximum value of the signal');
addLabelDefinitions(lss,theMax)

For each labeled signal, set the value of the new label to the signal maximum.

for k = 1:lss.NumMembers
    sg = getSignal(lss,k);
    [mx,ix] = max(sg);
    setLabelValue(lss,k,'Maximum',ix/fs,mx)
end

Plot the signals and their maxima.

for k = 1:lss.NumMembers
    subplot(2,1,k)
    sg = getSignal(lss,k);
    peaks = getLabelValues(lss,k,'Maximum');
    plot((0:length(sg)-1)/fs,sg, ...
        peaks.Location,cell2mat(peaks.Value),'*')
end

Input Arguments

lss — Labeled signal set

labeledSignalSet object

Labeled signal set, specified as a labeledSignalSet object.

Example: labeledSignalSet({randn(100,1) randn(10,1)},signalLabelDefinition('female')) specifies a two-member set of random signals containing the attribute 'female'.

midx — Member row number

positive integer

Member row number, specified as a positive integer. midx specifies the member row number as it appears in the Labels table of a labeled signal set.

lblname — Label or sublabel name

character vector | string scalar | cell array of character vectors | string array

Label name, specified as a character vector or string scalar.

Label or sublabel name. To specify a label, use a character vector or a string scalar. To specify a sublabel, use a two-element cell array of character vectors or a two-element string array:

• The first element is the name of the parent label.

• The second element is the name of the sublabel.

When targeting a sublabel of an ROI or point label, you must also specify the 'LabelRowIndex' of the parent label whose label you want to set. The row of the parent must already exist before you can set a sublabel value to it.

Example: signalLabelDefinition("Asleep",'LabelType','roi') specifies a label of name "Asleep" for a region of a signal in which a patient is asleep during a clinical trial.

Example: {'Asleep' 'REM'} or ["Asleep" "REM"] specifies a region of a signal in which a patient undergoes REM sleep.

val — Label values

numeric value or array | logical value or array | categorical value or array | character vector or cell array of character vectors | string or string array | table or table array | timetable or timetable array

Label values, specified as a numeric, logical, or categorical value, as a string, as a table, or as a timetable. val can also be an array of any of the previous types. val must be of the data type specified for lblname.

• If you specify locs, then val must have the same number of elements as locs.

• If you specify limits, then val must have a number of elements equal to the number of rows in limits.

  • If limits has more than one row, and lblname is of type 'numeric' or 'logical', then val must be a vector or a cell array.

  • If limits has more than one row, and lblname is of type 'string' or 'categorical', then val must be a string array or a cell array of character vectors.

  • If limits has more than one row, and lblname is of type 'table' or 'timetable', then val must be a cell array of tables or timetables.

Assign Nonscalar Label Values

To assign nonscalar label values to several points or regions of interest, you must use cell arrays. For example, given the labeled signal set

lss = labeledSignalSet(randn(10,1), [...
    signalLabelDefinition('pl','LabelType','point', ...
                               'LabelDataType','numeric') ...
    signalLabelDefinition('rl','LabelType','ROI', ...
                               'LabelDataType','numeric')]);

the commands

setLabelValue(lss,1,'pl',5,{[3 4]'})
setLabelValue(lss,1,'rl',[2 3; 8 9],{[2 1]' [6 7]})

label point 5 with the column vector [3 4]', the region limited by 2 and 3 with the column vector [2 1]', and the region limited by 8 and 9 with the row vector [6 7].

limits — Region limits

two-column matrix

Region limits, specified as a two-column matrix.

• If lss does not have time information, then limits defines the minimum and maximum indices over which the regions are defined.

• If lss has time information, then limits defines the minimum and maximum instants over which the regions are defined.

limits must be of the data type specified by the ROILimitsDataType property of the label definition for lblname.

Example: seconds([0:3;1:4]')

Example: [0:3;1:4]'

locs — Point locations

vector

Point locations, specified as a vector.

• If lss does not have time information, then locs defines the indices corresponding to the point locations.

• If lss has time information, then locs defines the instants corresponding to the point locations.

locs must be of the data type specified by the PointLocationsDataType property of the label definition for lblname.

ridx — Label row index

positive integer

Label row index, specified as a positive integer. This argument applies only for ROI and point labels.

sridx — Sublabel row index

positive integer

Sublabel row index, specified as a positive integer. This argument applies only when a label and sublabel pair has been specified in lblname and the sublabel is of type ROI or point.

Version History

Introduced in R2018b