framelbl
Syntax
Description
specifies additional options using name-value arguments.flbl
= framelbl(x
,fl
,Name=Value
)
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 inputlblName
, with the input label mode"attribute"
, and repeatsY
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 anfl
-by-NF matrixflbl
, where NF 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. Theframelbl
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 a either "mask"
or
"attribute"
.
"mask"
—framelbl
assumes that each element in the label sequence corresponds to a signal sample."attribute"
—framelbl
assumes that the inputx
corresponds to all samples in the data sequence. In this case, the input must be a categorical, string, or numeric scalar andframelbl
returns anfl
-by-NF matrixflbl
with all entries equal tox
, where NF is the number of frames. A logical1
corresponds to a label category"1"
and a logical0
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 specifySignalLength
."mask"
—SignalLength
can be specified only ifx
is an ROI table. Then:If
SignalLength
falls within the specified ROI limits, the function ignores the regions beyondSignalLength
.If
SignalLength
exceeds the maximum ROI limit, the function padsx
with<missing>
values.If
SignalLength
is not specified, the function infersSignalLength
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 ofx
as a binary mask corresponding to the ith category name inCategories
.If
x
is a logical matrix andCategories
is not specified,framelbl
sets categories to the string array["1" "2" ... "P"]
.For other non-numeric values of
x
, the value ofCategories
is directly inferred fromx
.
Data Types: string
ConsolidationMethod
— Frame labeling consolidation method
"none"
(default) | "mode"
| "max"
| "median"
| "mean"
| "priority"
Frame labeling consolidation method, specified as a 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 inPriorityList
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 definex
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 inPriorityList
. The first value inPriorityList
has the highest priority.You can set a value for
PriorityList
only whenx
is an ROI table or a logical array, or when you setConsolidationMethod
to"priority"
.If
x
is an ordinal categorical vector andConsolidationMethod
is"priority"
,PriorityList
overrides the mathematical ordering ofx
.If you do not specify
PriorityList
,framelbl
assigns a value by default. Ifx
is of typelogical
,PriorityList
gets it value fromCategories
. Otherwise,PriorityList
defaults to a lexicographically ordered list of label values fromx
.
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 withx
.InitialCondition
must have the same data type asx
.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 a 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 typecategorical
.<missing>
— For label values of typestring
.<false>
— For label values of typelogical
.<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 lastOverlapLength
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"
, orInputLabelMode
is set to"attibute"
, thenfnlcond
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
is1
.When you set
IncompleteFrameRule
to"padwithmissing"
orInputLabelMode
to"attribute"
, thenfnlidx
is 1.fnlidx-1
indicates the difference between the total number of points to skip between frames and the number of points inx
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
See Also
MATLAB コマンド
次の MATLAB コマンドに対応するリンクがクリックされました。
コマンドを MATLAB コマンド ウィンドウに入力して実行してください。Web ブラウザーは MATLAB コマンドをサポートしていません。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)