%% Label Definitions for Whale Songs
% Consider a set of whale sound recordings. The recorded whale sounds consist of trills and moans. Trills sound like series of clicks. Moans are low-frequency cries similar to the sound made by a ship's horn. You want to look at each signal and label it to identify the whale type, the trill regions, and the moan regions. For each trill region, you also want to label the signal peaks higher than a certain threshold.
%% Signal Label Definitions
% Define an attribute label to store whale types. The possible categories are blue whale, humpback whale, and white whale.

dWhaleType = signalLabelDefinition('WhaleType',...
   'LabelType','attribute',...
   'LabelDataType','categorical',...
   'Categories', ["blue" "humpback" "white"],...
   'Description','Whale type'); 

% Define a region-of-interest (ROI) label to capture moan regions. Define another ROI label to capture trill regions.

dMoans = signalLabelDefinition('MoanRegions',...
   'LabelType','roi',...
   'LabelDataType','logical',...
   'Description','Regions where moans occur');

dTrills = signalLabelDefinition('TrillRegions',...
   'LabelType','roi',...
   'LabelDataType','logical',...
   'Description','Regions where trills occur');        

% Finally, define a point label to capture the trill peaks. Set this label as a sublabel of the dTrills definition.

dTrillPeaks = signalLabelDefinition('TrillPeaks',...
   'LabelType','point',...
   'LabelDataType','numeric',...
   'Description','Trill peaks');

dTrills.Sublabels = dTrillPeaks;

%% Labeled Signal Set
% Create a labeledSignalSet with the whale signals and the label definitions. Add label values to identify the whale type, the moan and trill regions, and the peaks of the trills.

load labelwhalesignals
lbldefs = [dWhaleType dMoans dTrills];

lss = labeledSignalSet({whale1 whale2},lbldefs,'MemberNames',{'Whale1' 'Whale2'}, ...
   'SampleRate',Fs,'Description','Characterize wave song regions');     

% Visualize the label hierarchy and label properties using labelDefinitionsHierarchy and labelDefinitionsSummary.

labelDefinitionsHierarchy(lss)
labelDefinitionsSummary(lss)

% The signals in the loaded data correspond to songs of two blue whales. Set the 'WhaleType' values for both signals.

setLabelValue(lss,1,'WhaleType','blue');
setLabelValue(lss,2,'WhaleType','blue');

% Visualize the 'Labels' property. The table has the newly added 'WhaleType' values for both signals.

lss.Labels      

%
%% Visualize Region Labels
% Visualize the whale songs to identify the trill and moan regions.

subplot(2,1,1)
plot((0:length(whale1)-1)/Fs,whale1)
ylabel('Whale 1')

subplot(2,1,2)
plot((0:length(whale2)-1)/Fs,whale2)
ylabel('Whale 2')

% Moan regions are sustained low-frequency wails.
% whale1 has moans centered at about 7 seconds, 12 seconds, and 17 seconds.
% whale2 has moans centered at about 3 seconds, 7 seconds, and 16 seconds.
% Add the moan regions to the labeled set. Specify the ROI limits in seconds and the label values.

moanRegionsWhale1 = [6.1 7.7; 11.4 13.1; 16.5 18.1];
mrsz1 = [size(moanRegionsWhale1,1) 1];
setLabelValue(lss,1,'MoanRegions',moanRegionsWhale1,true(mrsz1));

moanRegionsWhale2 = [2.5 3.5; 5.8 8; 15.4 16.7];
mrsz2 = [size(moanRegionsWhale2,1) 1];
setLabelValue(lss,2,'MoanRegions',moanRegionsWhale2,true(mrsz2));

% Trill regions have distinct bursts of sound punctuated by silence.
% whale1 has a trill centered at about 2 seconds.
% whale2 has a trill centered at about 12 seconds.
% Add the trill regions to the labeled set.

trillRegionWhale1 = [1.4 3.1];
trsz1 = [size(trillRegionWhale1,1) 1];
setLabelValue(lss,1,'TrillRegions',trillRegionWhale1,true(trsz1));

trillRegionWhale2 = [11.1 13];
trsz2 = [size(trillRegionWhale1,1) 1];
setLabelValue(lss,2,'TrillRegions',trillRegionWhale2,true(trsz2));

%
% Create a signalMask object for each whale song and use it to visualize and label the different regions. For better visualization, change the label values from logical to categorical.

mr1 = getLabelValues(lss,1,'MoanRegions');
mr1.Value = categorical(repmat("moan",mrsz1));
tr1 = getLabelValues(lss,1,'TrillRegions');
tr1.Value = categorical(repmat("trill",trsz1));

msk1 = signalMask([mr1;tr1],'SampleRate',Fs);

subplot(2,1,1)
plotsigroi(msk1,whale1)
ylabel('Whale 1')
hold on

mr2 = getLabelValues(lss,2,'MoanRegions');
mr2.Value = categorical(repmat("moan",mrsz2));
tr2 = getLabelValues(lss,2,'TrillRegions');
tr2.Value = categorical(repmat("trill",trsz2));

msk2 = signalMask([mr2;tr2],'SampleRate',Fs);

subplot(2,1,2)
plotsigroi(msk2,whale2)
ylabel('Whale 2')
hold on

%
%% Visualize Point Labels
% Label three peaks for each trill region. For point labels, you specify the point locations and the label values. In this example, the point locations are in seconds.

peakLocsWhale1 = [1.553 1.626 1.7];
peakValsWhale1 = [0.211 0.254 0.211];

setLabelValue(lss,1,["TrillRegions" "TrillPeaks"],...
   peakLocsWhale1,peakValsWhale1,'LabelRowIndex',1);

subplot(2,1,1)
plot(peakLocsWhale1,peakValsWhale1,'v')
hold off

peakLocsWhale2 = [11.214 11.288 11.437];
peakValsWhale2 = [0.119 0.14 0.15];

setLabelValue(lss,2,["TrillRegions" "TrillPeaks"],...
   peakLocsWhale2,peakValsWhale2,'LabelRowIndex',1);

subplot(2,1,2)
plot(peakLocsWhale2,peakValsWhale2,'v')
hold off

%
%% Explore Label Values
% Explore the label values using getLabelValues.

getLabelValues(lss)

% Retrieve the moan regions for the first member of the labeled set.

getLabelValues(lss,1,'MoanRegions')

% Use a second output argument to list the sublabels of a label.

[value,valueWithSublabel] = getLabelValues(lss,1,'TrillRegions')

% To retrieve the values in a sublabel, express the label name as a two-element array.

getLabelValues(lss,1,["TrillRegions" "TrillPeaks"])

% Find the value of the third trill peak corresponding to the second member of the set.

getLabelValues(lss,2,["TrillRegions" "TrillPeaks"], ...
    'LabelRowIndex',1,'SublabelRowIndex',3)

% Copyright 2018 The MathWorks, Inc.