signalMask

Modify and convert signal masks and extract signal regions of interest

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

Syntax

msk = signalMask(src)

msk = signalMask(src,PropertyName,Value)

Description

msk = signalMask(src) creates a signal mask for the input data source src. A mask defines the locations of regions of interest of a signal together with the label or category values for each region.

msk = signalMask(src,PropertyName,Value) sets Properties using name-value arguments. You can specify multiple name-value arguments. Enclose each property name in quotes.

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, see categorical.

• When src is a P-column matrix of binary sequences, each column is interpreted as a signal mask with true 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 the Categories 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

Read-only: "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

Read-only: 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 $$F_s=7418Hz$$. 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:

1. Extends regions to the left or right based on LeftExtension and RightExtension.

2. Shortens regions from the left or right based on LeftShortening and RightShortening.

3. 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.

4. Removes short regions based on MinLength.

Version History

Introduced in R2020b