framelbl

Partition label sequence into frames

Since R2024a

Syntax

flbl = framelbl(x,fl)

flbl = framelbl(x,fl,Name=Value)

[flbl,fnlcond] = framelbl(___)

[flbl,fnlcond,fnlidx] = framelbl(___)

Description

flbl = framelbl(x,fl) partitions a label sequence x into frames of length fl samples.

flbl = framelbl(x,fl,Name=Value) specifies additional options using name-value arguments.

[flbl,fnlcond] = framelbl(___) also returns the final condition array for any of the previous syntaxes.

[flbl,fnlcond,fnlidx] = framelbl(___) also returns the final index output.

Examples

Partition Categorical Label Sequence into Frames

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"   

Framing of Single Categorical Label

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

• The framelbl function reads the categorical scalar input lblName, with the input label mode "attribute", and repeats Y 15 times.

• The framing starts with the third sample, following the value of InitialIndex specified 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 UnderlapLength specification.

• The second frame includes samples 9 through 12. The framelbl function skips samples 13 and 14.

• The third frame includes the sample 15 and gets completed with missing-name values. Since lblName is 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 = 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.

Customized Partition of Label Sequence into Frames

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

Label Sequence Partition from ROI Table

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:

• 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 flbl with <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 = 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.

Joint Partition of Signal and Label Sequence Data

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")

Numeric Label Framing for Signal Features

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

x — Input label sequence

categorical vector | string array | numeric array | logical matrix | table

Input signal, specified as a categorical vector, string array, numeric array, logical matrix, or table.

• If x is a string array, numeric array or logical matrix, framelbl returns an fl-by-N_F matrix flbl, where N_F is the number of frames.

• If x is a logical matrix with P columns, framelbl interprets each column as a mask with true elements marking regions of interest (ROI) for each of P different categories, "1", "2", ..., "P", and converts the logical matrix into a categorical label sequence. Each row of the matrix is an observation and each column of the matrix corresponds to a category. The framelbl function treats a logical row vector as a single observation and a logical column vector as a single category. If there are multiple categories in overlapping regions of interest, the function resolves the ambiguity by giving the highest priority to category "1" and the lowest priority to category "P". Finally, framelbl breaks the label sequence into equal-length frames.

• If x is a table representing ROIs, this ROI table must contain two variables. The first variable is a two-column matrix such that each row defines the limits of a region of interest. The second variable contains the label values of the regions, specified as a categorical vector or a string array. framelbl converts the ROI table into a categorical or string sequence depending of the type specified for the label values. If there are overlapping regions of interest with different label values in the ROI table, framelbl gives precedence to the label that appears first in lexicographic order. Finally, framelbl divides the label sequence into frames.

Example: ["current" "past" "past" "current" "pass"].

Example: logical([0 0 1 0 1 0]').

Example: table([2 12; 7 16; 3 8],["U" "S" "S"]').

Note

If x is either an ROI table or a logical matrix, unlabeled regions are labeled with missing values. For label values of categorical and string types, missing values are <undefined> and <missing>, respectively.

Data Types: categorical | string | table | double | single | logical | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

fl — Frame length

positive integer scalar

Frame length, specified in samples as a positive integer scalar. fl must be smaller than or equal to the length of input x.

Example: fl = 5.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: framelbl("p",5,SignalLength=12,InputLabelMode="attribute",IncompleteFrameRule="padwithmissing") partitions a 12-sample label sequence formed with the string "p" into frames of length 5 using the "attribute" input label mode and the "padwithmissing" incomplete frame rule as name-value pair arguments.

InputLabelMode — Input label mode

"mask" (default) | "attribute"

Input label mode, specified as either "mask" or "attribute".

• "mask" — framelbl assumes that each element in the label sequence corresponds to a signal sample.

• "attribute" — framelbl assumes that the input x corresponds to all samples in the data sequence. In this case, the input must be a categorical, string, or numeric scalar and framelbl returns an fl-by-N_F matrix flbl with all entries equal to x, where N_F is the number of frames. A logical 1 corresponds to a label category "1" and a logical 0 corresponds to an <undefined> label.

Data Types: char | string

SignalLength — Signal length

positive integer scalar

Length of the signal associated to the input label sequence, specified as a positive integer scalar. SignalLength must be greater than the frame length fl.

If InputLabelMode is:

• "attribute" — You must specify SignalLength.

• "mask" — SignalLength can be specified only if x is an ROI table. Then:

  • If SignalLength falls within the specified ROI limits, the function ignores the regions beyond SignalLength.

  • If SignalLength exceeds the maximum ROI limit, the function pads x with <missing> values.

  • If SignalLength is not specified, the function infers SignalLength from the input ROI table and sets it to the maximum index in the ROI limit matrix.

SampleRate — Sample rate

positive scalar

Sample rate of the signal associated to the input label sequence, specified as a positive scalar. SampleRate can be specified only if x is an ROI table.

• If SampleRate is specified, framelbl assumes that the table contains region limits in seconds. Prior to performing framing operations, framelbl converts time values to sample indices, rounding to the nearest integer.

• If SampleRate is not specified, all region limits must be specified as positive integer indices.

Data Types: single | double

Categories — List of category names

string array

List of category names, specified as a string array. Categories can be specified only if x is a logical matrix.

• The framelbl function interprets the ith column of x as a binary mask corresponding to the ith category name in Categories.

• If x is a logical matrix and Categories is not specified, framelbl sets categories to the string array ["1" "2" ... "P"].

• For other non-numeric values of x, the value of Categories is directly inferred from x.

Data Types: string

ConsolidationMethod — Frame labeling consolidation method

"none" (default) | "mode" | "max" | "median" | "mean" | "priority"

Frame labeling consolidation method, specified as either "none", "mode", "max", "median", "mean", or "priority". ConsolidationMethod specifies the method to consolidate all the label values in a frame into a single value to assign as the label of the frame. In this case, the output label sequence flbl becomes a vector of frame labels. framelbl performs the label consolidation depending of the specified value of ConsolidationMethod:

• "none" — framelbl does not consolidate labels.

• "mode" — framelbl assigns the most frequently occurring label value in the frame (the mode) as the frame label.

• "max" — framelbl assigns the maximum label value in the frame as the frame label.

• "median" — framelbl assigns the median of label values in the frame as the frame label.

• "mean" — framelbl averages the label values in a frame and specifies the average as the frame label.

• "priority" — framelbl uses the priority list given in PriorityList to consolidate label values. If the first element of the priority list is not present, the function specifies as frame label the first value in the priority list of which there is at least one instance in the frame.

Note

You can set ConsolidationMethod to certain values based on the input type of x:

• categorical or string — ConsolidationMethod can be only "mode" or "priority". This rule applies if you explicitly define x as a categorical sequence or a string array, or implicitly, by an ROI table or a logical matrix. For ordinal categorical inputs, ConsolidationMethod can also be set to "median" or "max".

• numeric — ConsolidationMethod can take any value except "priority".

Data Types: char | string

PriorityList — Category priority list

categorical array | string array | numeric array

Category priority list, specified as a categorical array, a string array, or a numeric array. PriorityList specifies a vector of unique categorical or string elements, or index of unique labels, ordered by the priority with which they should be treated when regions with different label values overlap or when consolidating frames that contain different label values.

• PriorityList must contain or point to all unique label values.

• framelbl prioritizes label values following the order of the elements in PriorityList. The first value in PriorityList has the highest priority.

• You can set a value for PriorityList only when x is an ROI table or a logical array, or when you set ConsolidationMethod to "priority".

• If x is an ordinal categorical vector and ConsolidationMethod is "priority", PriorityList overrides the mathematical ordering of x.

• If you do not specify PriorityList, framelbl assigns a value by default. If x is of type logical, PriorityList gets it value from Categories. Otherwise, PriorityList defaults to a lexicographically ordered list of label values from x.

Data Types: categorical | string | double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

OverlapLength — Overlap length

0 (default) | nonnegative integer scalar

Overlap length, specified as a nonnegative integer scalar. OverlapLength is the number of overlap samples between adjoining frames. OverlapLength must be nonnegative, smaller than the frame length, and applies only when UnderlapLength is not specified.

UnderlapLength — Underlap length

0 (default) | nonnegative integer scalar

Underlap length, specified as a nonnegative integer scalar. UnderlapLength is the number of samples to be skipped after each frame, thus reducing the frame rate. UnderlapLength must be nonnegative and applies only when OverlapLength is not specified.

InitialCondition — Array of initial conditions

[] (default) | categorical vector | string array | numeric array | logical matrix | table

Array of initial conditions, specified as a categorical vector, string array, numeric array, logical matrix, or table. InitialCondition specifies an initial condition that is stacked on top of the input label sequence x.

• InitialCondition must be in such shape that it can be concatenated with x.

• InitialCondition must have the same data type as x.

• If InputLabelMode is set to "attribute", InitialCondition must be empty.

• If x is an ROI table, the initial condition must also be an ROI table whose ROI limits do not overlap with the ROI limits in the input ROI table.

Example: framelbl(["S" "S" "N" "N" "S"],3,InitialCondition=["IC" "IC"]) partitions a 5-sample string vector into frames with a length of three samples. The initial condition is also a string vector.

Example: framelbl([1 1 0 1 0 0 0],5,InitialCondition=[0 0 1]) partitions a 7-sample logical vector into frames with a length of five samples. The initial condition is also a logical vector.

Data Types: categorical | string | table | double | single | logical | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

InitialIndex — Initial index

1 (default) | positive integer scalar

Initial index, specified as a positive integer scalar. InitialIndex indicates the index of the first element from which the framing operation starts. Equivalently, InitialIndex-1 is the number of initial data samples in x to discard.

IncompleteFrameRule — Incomplete frame rule

"drop" (default) | "padwithmissing"

Incomplete frame rule, specified as either "drop" or "padwithmissing". IncompleteFrameRule specifies the rule to handle incomplete frames when the input does not have enough remaining samples to fill up the last frame. If you set IncompleteFrameRule to:

• "drop" — framelbl drops the incomplete frame.

• "padwithmissing" — framelbl pads the last frame with missing values. Missing values are any of the following:

  • <undefined> — For label values of type categorical.

  • <missing> — For label values of type string.

  • <false> — For label values of type logical.

  • <NaN> — For label values of a numeric type.

Data Types: char | string

Output Arguments

flbl — Framed label sequence

vector | matrix

Framed label sequence, returned as a vector or a matrix.

fnlcond — Final condition array

logical vector | table

Final condition array, returned as a vector.

• If the overlap length is specified, then fnlcond contains the last OverlapLength samples of the last complete frame and any samples that might remain from the incomplete frame, if there is one.

• If the underlap length is specified, then fnlcond contains only the remaining samples in the incomplete frame, if there are any. The final condition array has the same dimensions as the input label sequence. The final condition output can be used as the initial condition input for a subsequent framing operation in a sequence of consecutive framing operations. This allows the desired overlap to be maintained from one frame to the next.

• When IncompleteFrameRule is set to "padwithmissing", or InputLabelMode is set to "attibute", then fnlcond is empty.

fnlidx — Final index output

positive integer scalar

Final index output, returned as a positive integer scalar.

• If the overlap length OverlapLength is specified, fnlidx is 1.

• When you set IncompleteFrameRule to "padwithmissing" or InputLabelMode to "attribute", then fnlidx is 1.

• fnlidx-1 indicates the difference between the total number of points to skip between frames and the number of points in x that were available to be skipped after filling the last frame. You can use the final index output as the initial index for a subsequent framing operation, thus maintaining the desired underlap from frame to frame.

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