Main Content

signalMask

Modify and convert signal masks and extract signal regions of interest

Since R2020b

expand all in page

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,Name,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.

example

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

Input Arguments

expand all

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

expand all

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

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

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

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

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

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

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

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

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

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

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

binmaskGet matrix of binary sequences mask
catmaskGet categorical sequence mask
extractsigroiExtract regions of interest based on signal mask
plotsigroiPlot signal regions based on signal mask
roimaskGet ROI table mask

Examples

collapse all

Open Live Script

Load a speech signal sampled at Fs=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

Figure contains an axes object. The axes object with title Number of changepoints = 5 Total log weighted dispersion = -4405.482 contains 2 objects of type line.

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)

Figure contains an axes object. The axes object with xlabel Seconds contains 6 objects of type line.

More About

expand all

Version History

Introduced in R2020b

See Also

Apps

Functions

Objects

Topics