framelbl

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 = 4x2 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:

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 = 4x3 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:

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 = 4x3 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 = 7x3 categorical
     B      A                B           
     B      B                <undefined> 
     A      B                B           
     A      B                B           
     A      B                A           
     B      <undefined>      B           
     B      B                A           

finalCond = 6x2 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 = 6x3 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:

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 = 1x3 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 framedata

Create 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