signalMask
Modify and convert signal masks and extract signal regions of interest
Since R2020b
Description
Use signalMask
to store the locations of regions of interest of
a signal together with the label or category values for each region.
Using signalMask
, you can:
Represent a signal mask as a table, a categorical sequence, or a matrix of binary sequences.
Modify regions of interest by extending or shortening their duration, merge same-category regions that are sufficiently close, or remove regions that are not long enough.
Extract signal regions of interest from a signal vector.
Plot a signal with color-coded regions of interest.
Creation
Description
creates a signal mask for the input data source msk
= signalMask(src
)src
. A
mask defines the locations of regions of interest of a signal
together with the label or category values for each region.
sets Properties using name-value
arguments. You can specify multiple name-value arguments. Enclose each property name in
quotes.msk
= signalMask(src
,Name,Value
)
Input Arguments
src
— Input data source
table | categorical vector sequence | matrix of binary sequences
Input data source, specified as a region-of-interest (ROI) table, a categorical vector sequence, or a matrix of binary sequences.
When
src
is an ROI table, it must contain two variables:The first variable is a two-column matrix. Each row of the matrix contains the beginning and end limits of a signal region of interest.
If
SampleRate
is specified,signalMask
interprets the limits as time values expressed in seconds.If
SampleRate
is not specified,signalMask
interprets the limits as sample indices. If the matrix elements are not integers,signalMask
rounds their values to the nearest integer greater than zero.
The second variable contains the region labels, specified as a categorical array or a string array.
When
src
is a categorical vector sequence, groups of contiguous same-value category elements indicate a signal region of interest labeled with that particular category. Elements that belong to no category (and hence have no label value) should be specified as the missing categorical, displayed as<undefined>
. For more information, seecategorical
.When
src
is a P-column matrix of binary sequences, each column is interpreted as a signal mask withtrue
elements marking regions of interest for each of P different categories, labeled with integers from 1 to P. If you prefer, you can specify a list of P category names using theCategories
property.
Example: signalMask(table([2 4;6 7],["male" "female"]'))
specifies a signal mask with a three-sample male
region and a
two-sample female
region.
Example: signalMask(categorical(["" "male" "male" "male" "" "female"
"female" ""]',["male" "female"]))
specifies a signal mask with a
three-sample male
region and a two-sample female
region.
Example: signalMask([0 1 1 1 0 0 0 0;0 0 0 0 0 1 1
0]','Categories',["male" "female"])
specifies a signal mask with a
three-sample male
region and a two-sample female
region.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
| char
| string
| table
| categorical
Properties
SourceType
— Type of input source
"roiTable"
| "categoricalSequence"
| "binarySequences"
This property is read-only.
Type of input source, returned as "roiTable"
,
"categoricalSequence"
, or "binarySequences"
.
This property is inferred from src
and cannot be set.
Example: signalMask(table([2 4;6 7],["male" "female"]'))
has
SourceType
returned as
"roiTable"
.
Example: signalMask(categorical(["" "male" "male" "male" "" "female"
"female" ""]',["male" "female"]))
has SourceType
returned as "categoricalSequence"
.
Example: signalMask([0 1 1 1 0 0 0 0;0 0 0 0 0 1 1 0]','Categories',["male"
"female"])
has SourceType
returned as
"binarySequences"
.
Data Types: string
SampleRate
— Sample rate value
positive numeric scalar
This property is read-only.
Sample rate value, returned as a positive numeric scalar. If
src
is specified as an ROI table, signalMask
assumes that the table contains region limits expressed in seconds. If you omit this
property, the object treats all region limits as sample indices.
Data Types: single
| double
Categories
— Category names
string vector | cell array of character vectors
Category names, specified as a string vector or a cell array of character vectors.
This property can be set only when src
is a matrix of binary
sequences. For all other input src
types,
signalMask
infers category names directly from
src
and this property is read-only. The vector has a number of
elements equal to the number of columns of src
, and its
ith category corresponds to the ith column of
src
. If src
has P columns
and this property is not specified, signalMask
sets the category names
to ["1" "2" ... "P"]
.
Data Types: string
| char
SpecifySelectedCategories
— Option to select a subset of categories
false
(default) | true
Option to select a subset of categories, specified as a logical value. If this
property is set to false
after creating the mask, then all categories
in Categories
are selected. SpecifySelectedCategories
can only be used on an existing object and cannot be specified as a name-value
argument.
Data Types: logical
SelectedCategories
— Indices of selected categories
vector of integer index values
Indices of selected categories, specified as a vector of integer index values
pointing to category elements in Categories
. Categories not listed in this property are filtered out from
the mask input when calling the object functions of signalMask
. The
category indices must be sorted in ascending order. This property applies only when
SpecifySelectedCategories
is true
.
SelectedCategories
can only be used on an existing object and
cannot be specified as a name-value argument.
Example: Given a set of categories ["woman" "girl" "man" "boy"]
,
specifying SelectedCategories
as [1 2 4]
selects
["woman" "girl" "boy"]
and filters out the rest.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
LeftExtension
— Number of samples to extend regions to the left
0
(default) | positive integer
Number of samples to extend regions to the left, specified as a positive integer. The number of extended samples is truncated when the beginning of the sequence is reached. For more information, see Region Limit Modification.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
RightExtension
— Number of samples to extend regions to the right
0
(default) | positive integer
Number of samples to extend regions to the right, specified as a positive integer. For more information, see Region Limit Modification.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
LeftShortening
— Number of samples to shorten regions from the left
0
(default) | positive integer
Number of samples to shorten regions from the left, specified as a positive integer.
signalMask
removes regions that are shortened by a number of samples
equal to or greater than their length. For more information, see Region Limit Modification.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
RightShortening
— Number of samples to shorten regions from the right
0
(default) | positive integer
Number of samples to shorten regions from the right, specified as a positive
integer. signalMask
removes regions that are shortened by a number of
samples equal to or greater than their length. For more information, see Region Limit Modification.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
MergeDistance
— Distance between regions to be merged
0
(default) | positive integer
Distance between regions to be merged, specified as a positive integer. When this
property is specified, signalMask
merges regions of the same category
that are separated by the specified number of samples or less. For more information, see
Region Limit Modification.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
MinLength
— Minimum length of regions to keep
1
(default) | positive integer
Minimum length of regions to keep, specified as a positive integer. When this
property is specified, signalMask
removes regions shorter than the
specified number of samples. For more information, see Region Limit Modification.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Object Functions
binmask | Get matrix of binary sequences mask |
catmask | Get categorical sequence mask |
extractsigroi | Extract regions of interest based on signal mask |
plotsigroi | Plot signal regions based on signal mask |
roimask | Get ROI table mask |
Examples
Regions of Interest in Audio File
Load a speech signal sampled at . The file contains a recording of a female voice saying the word "MATLAB®."
load mtlb
t = (0:length(mtlb)-1)/Fs;
Discern the vowels and consonants in the word by finding the points at which the variance of the signal changes significantly. Limit the number of changepoints to five.
q = findchangepts(mtlb,"Statistic","rms","MaxNumChanges",5);
Plot the signal and display the changepoints.
findchangepts(mtlb,"Statistic","rms","MaxNumChanges",5) axis tight
Define regions of interest that correspond to each letter in the word.
roitable = t([[1;q] [q;length(mtlb)]]);
Assign region labels and preserve their order.
x = ["M" "A" "T" "L" "A" "B"]'; y = unique(x,"stable"); c = categorical(x,y);
Create a signal mask for the regions of interest and corresponding labels. Shorten each region by one sample from the right to avoid contiguity. Display the region-of-interest table mask.
src = table(roitable,c); msk = signalMask(src,"SampleRate",Fs,"RightShortening",1); roimask(msk)
ans=6×2 table
roitable c
___________________ _
0 0.017525 M
0.01766 0.10461 A
0.10475 0.22162 T
0.22176 0.33675 L
0.33688 0.46535 A
0.46549 0.53909 B
Introduce gaps in the signal where the letter "A"
is vocalized.
m = mtlb;
seq = catmask(msk,length(mtlb));
m(seq == "A") = NaN;
Reconstruct the signal using an autoregressive process. Extract each region of interest from the reconstructed signal.
p = fillgaps(m); w = extractsigroi(msk,p);
To play the sound with a pause after each region, uncomment these lines:
% for k = 1:length(w) % sound(cell2mat(w{k}),Fs) % pause(0.5) % end
Plot the reconstructed signal and visualize the regions of interest.
figure plotsigroi(msk,p)
More About
Region Limit Modification
You can use signalMask
to modify regions of interest
by extending or shortening their duration, merge same-category regions that are sufficiently
close, or remove regions that are not long enough.
signalMask
first converts the region limits of src
to a matrix
and, depending on the specified Properties, modifies the limits in
this order:
Extends regions to the left or right based on
LeftExtension
andRightExtension
.Shortens regions from the left or right based on
LeftShortening
andRightShortening
.Merges close-enough regions based on
MergeDistance
.signalMask
always merges contiguous, overlapping, or repeated regions. Think of these regions as being separated by zero samples, or a negative number of samples.Removes short regions based on
MinLength
.
Version History
Introduced in R2020b
See Also
Apps
Functions
binmask2sigroi
|extendsigroi
|extractsigroi
|mergesigroi
|removesigroi
|shortensigroi
|sigroi2binmask
|categorical
Objects
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
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)