framelbl
Syntax
Description
Examples
Partition a categorical label sequence into frames of length 4.
catLbl = ["healthy" "healthy" "sick" ... "sick" "healthy" "healthy" ... "healthy" "sick" "sick" "sick"]; framedLabels = framelbl(catLbl,4)
framedLabels = 4×2 string
"healthy" "healthy"
"healthy" "healthy"
"sick" "healthy"
"sick" "sick"
Partition a single label defined as a categorical input into frames using name-value arguments.
Define a categorical scalar Y.
lblName = categorical("Y")lblName = categorical
Y
Note that this label definition has one element, and its datatype is categorical.
To frame a scalar label, either:
Set the input label mode to
"attribute"and specify a signal length.Repeat the scalar label. In this case, the input label mode must be
"mask"(default value) and you must not specify a signal length.
Partition a categorical scalar into four-sample frames. Set the input label mode to "attribute" with a signal length of 15 samples. Use an underlap length of 2 samples, an initial index of 3. Specify the incomplete frame rule to "padwithmissing".
fl = 4; sl = 15; ul = 2; ii0 = 3; flblAttr = framelbl(lblName,fl, ... InputLabelMode="attribute",SignalLength=sl,... UnderlapLength=ul,InitialIndex=ii0, ... IncompleteFrameRule="padwithmissing")
flblAttr = 4×3 categorical
Y Y Y
Y Y <undefined>
Y Y <undefined>
Y Y <undefined>
The output frame label sequence follows the framing specifications in this order:
The
framelblfunction reads the categorical scalar inputlblName, with the input label mode"attribute", and repeatsY15 times.The framing starts with the third sample, following the value of
InitialIndexspecified in the function call.Then, the first frames contains the samples 3, 4, 5, and 6. The framing operation skips the samples 7 and 8, as per the
UnderlapLengthspecification.The second frame includes samples 9 through 12. The
framelblfunction skips samples 13 and 14.The third frame includes the sample 15 and gets completed with missing-name values. Since
lblNameis categorical, then the frame completes with<undefined>values.
Define a label sequence by repeating a categorical scalar up to sl samples. Partition a categorical scalar into frames. Specify the frame length, underlap length, initial index, and incomplete frame rule. Set the input label mode to "mask".
lblSeq = repmat(lblName,sl,1); flblMask = framelbl(lblSeq,fl, ... InputLabelMode="mask", ... UnderlapLength=ul,InitialIndex=ii0, ... IncompleteFrameRule="padwithmissing")
flblMask = 4×3 categorical
Y Y Y
Y Y <undefined>
Y Y <undefined>
Y Y <undefined>
Framing a categorical scalar declared as "attribute" with a signal length yields the same results as framing a categorical array that explicitly lists the category signal.
Define a categorical sequence, two categories, and a category priority list. Partition a categorical sequence.
Consider a categorical sequence defined by the 18-by-2 logical matrix logMat. The first and second columns correspond to categories named "A" and "B", respectively.
logMat = logical([ ... 0 0 1 1 1 0 0 1 1 0 0 0 1 1 1 1 0 1; ... 1 1 0 0 0 1 1 1 1 0 1 1 0 1 0 1 1 0]'); catList = ["A" "B"];
In each row, the associated category is "A" if 1 is listed in the first column, or "B" if 1 is listed in the second column. If none of the columns lists 1, the corresponding category is <undefined>. For multiple instances of 1 listed, the priority list of categories defines the category to associate with each row.
Category "B" has higher priority than "A". Define a category priority list.
catPriority = ["B" "A"];
Partition the categorical sequence defined by the logical matrix into frames of length 7 with 3 samples of overlap between adjoining frames. Use the categories "A" and "B".
[framedLabels,finalCond] = framelbl(logMat,7, ... OverlapLength=3,Categories=catList, ... PriorityList=catPriority)
framedLabels = 7×3 categorical
B A B
B B <undefined>
A B B
A B B
A B A
B <undefined> B
B B A
finalCond = 6×2 logical array
1 0
0 1
1 0
0 1
0 1
1 0
Define an ROI table. Partition label sequence into frames. Consolidate label frames.
Specify five ranges between 5 and 20, and define the categories "A", "B", "C", "D", and "E". Let the variables minimums and maximums be the minimum and maximum values that correspond to each range associated with the categories. The value 12 associates with the categories "C" and "D", in which case framelbl enables labeling based on a priority order.
minimums = [5 10 12 15 18]'; maximums = [9 12 14 17 20]'; categories = ["E" "D" "C" "B" "A"]';
Define an ROI table with the numeric ranges and category labels. Specify the variable names as "Range" and "Category", respectively.
ROItable = table([minimums maximums],categories,... VariableNames=["Range" "Category"])
ROItable=5×2 table
Range Category
________ ________
5 9 "E"
10 12 "D"
12 14 "C"
15 17 "B"
18 20 "A"
Partition an ROI table into frames of length 6 samples.
fl = 6; [flbl,fnlcond,fnlidx] = framelbl(ROItable,fl)
flbl = 6×3 string
<missing> "E" "C"
<missing> "E" "C"
<missing> "E" "B"
<missing> "D" "B"
"E" "D" "B"
"E" "C" "A"
fnlcond=1×2 table
Range Category
________ ________
19 20 "A"
fnlidx = 1
The outputs from the framing operation show the following:
Since the ROI table limits range from 5 to 20, thus not having values from 1 to 4, the framing operation completes the first four labels of
flblwith<missing>values.The framing operation assigns
"C"to the last sample of the second frame because it has a higher priority over"D", from the default lexicographical priority order.
Partition an ROI table into frames. Consolidate the framed label sequence with the most frequent label in each frame.
flblGroup = framelbl(ROItable,fl,ConsolidationMethod="mode")flblGroup = 1×3 string
"E" "E" "B"
The most frequent grade label in each frame of flbl are "E", "E" and "B", which yield the same result as flblGroup.
Load a signal and its associated label sequence data. Create datastores and frame signal and labels. Combine, read, and show the framed signal and labels.
Load the file framedata, which contains a signal vector and its associated label sequence. The vector is a random audio-like signal with a length L of 100,000 samples at a sampling rate of 16 kHz. The label sequence is a categorical vector where "S" corresponds to speech samples and "N" corresponds to no speech.
load framedataCreate the datastores sigAds and lblAds from the arrays sig and lbl. Read L samples of data along the second dimension in each iteration.
sigAds = arrayDatastore(sig,IterationDimension=2,ReadSize=L); lblAds = arrayDatastore(lbl,IterationDimension=2,ReadSize=L);
Partition both signal and label sequence into frames of length 1024 with 512 samples of overlap between adjoining frames. Set the ConsolidationMethod property to "mode" for the label framing operation to assign the most frequent category in each framed label. Use the transform function to transform the datastores.
transformedSigDS = transform(sigAds,... @(x){framesig(x{:},1024,OverlapLength=512)}); transformedLblDS = transform(lblAds,... @(x){framelbl(x{:},1024,OverlapLength=512, ... ConsolidationMethod="mode")});
Combine the transformed datastores coming from the signal and label framing operations. Read and plot the resulting datastore frames, showing the samples 10, 20, and 30 of the framed signal data, and the labeled category in each frame.
combinedDS = combine(transformedSigDS,transformedLblDS); framedSignalAndLabel = read(combinedDS); tiledlayout flow nexttile strips(framedSignalAndLabel{1}(10:10:30,:)') title("Framed Signals") xlabel("Frame") ylabel("Sample number") yticklabels([30 20 10]) nexttile plot(framedSignalAndLabel{2}) title("Framed Labels") xlabel("Frame") legend("Category")
Label a speech signal. Extract time-domain features by frames. Partition a numeric label sequence into frames and consolidate values.
Load a data file containing a speech vector signal sampled at a frequency rate fs of 16 kHz. Define a labeling vector labels as a numeric vector describing the ratio between the signal amplitudes over the mean amplitude, rounding to the nearest integer.
[signal,fs] = audioread("MaleVolumeUp-16-mono-6secs.ogg");
amp = abs(signal);
labels = int8(amp/mean(amp));Set a frame length to 4096 samples. Extract time-domain features to a signal vector.
fl = 4096;
sFE = signalTimeFeatureExtractor(FrameSize=fl,SampleRate=fs, ...
ShapeFactor=true,RMS=true,CrestFactor=true);
fFeatures = extract(sFE,signal);Partition a numeric vector of labels into frames. Consolidate the label in each frame as the mean of the label values.
fLabels = framelbl(labels,fl,ConsolidationMethod="mean");Plot the signal and the numeric labels. Plot the consolidated frame labels and the normalized time-domain features in each frame.
tiledlayout vertical nexttile plot(signal) xline(fl:fl:length(signal),":") xlim([0 fl*ceil(length(signal)/fl)]) xlabel("Sample number") title("Signal") nexttile stairs(labels) xline(fl:fl:length(labels),":") xlim([0 fl*ceil(length(labels)/fl)]) xlabel("Sample number") title("Labels")
figure tiledlayout vertical nexttile b = bar((1:length(fLabels))-0.5,fLabels,FaceColor="flat"); xline(1:length(fLabels),":") xlim([0 ceil(length(labels)/fl)]) xticks((0:5:length(fLabels))+0.5) xticklabels((0:5:length(fLabels))+1) xlabel("Frame number") title("Label Frames") nexttile scatter(0.5:numel(fLabels)-0.5,fFeatures./max(fFeatures),"filled") xline(1:length(fLabels),":") xlabel("Frame Number") legend("Normalized "+["Shape Factor" "RMS Value" "Crest Factor"], ... Location="southoutside") title("Time-Domain Features") xlim([0 ceil(length(labels)/fl)]) xticks((0:5:length(fLabels))+0.5) xticklabels((0:5:length(fLabels))+1) box on
Input Arguments
Name-Value Arguments
Output Arguments
Tips
framelbl complements the framesig function
in supervised-learning problems in which a label sequence is paired with a data sequence.
While framesig is used
to partition the data sequence into overlapping frames, framelbl is
used to perform the same framing operation on the label sequence.
Version History
Introduced in R2024a
