Main Content

extractsigroi

Extract regions of interest based on signal mask

Since R2020b

Description

sigroi = extractsigroi(msk,x) extracts regions of interest of the input signal vector x based on the source and properties in msk.

example

sigroi = extractsigroi(msk,x,Name,Value) specifies additional options using name-value arguments. You can choose to concatenate extracted regions and select the number of regions to extract per category.

example

[sigroi,limits] = extractsigroi(___) returns an array with the locations of the extracted region endpoints.

[sigroi,limits,numroi,cats] = extractsigroi(___) also returns numroi, a vector containing the number of regions found for each of the categories listed in cats.

Examples

collapse all

Consider a region-of-interest (ROI) table with three regions labeled A and two regions labeled B. Use the table to create a signalMask object.

roiTbl = table([2 5; 7 10; 12 13; 15 25; 28 30],["A","B","A","B","A"]');

m = signalMask(roiTbl);

Generate an array with prime numbers smaller than 150. Use the signalMask object to extract the primes specified in the ROI table. Display the first set of A primes and the first set of B primes.

prm = primes(150);

rgs = extractsigroi(m,prm);

AB = [rgs{1}{1} rgs{2}{1}]
AB = 4×2

     3    17
     5    19
     7    23
    11    29

Repeat the operation, but now concatenate the regions of interest for each category. Display the first six A primes and the last six B primes.

rgs = extractsigroi(m,prm,'ConcatenateRegions',true);

AB = [rgs{1}(1:6) rgs{2}(end-5:end)]
AB = 6×2

     3    71
     5    73
     7    79
    11    83
    37    89
    41    97

Repeat the operation, but now ignore regions with two samples or less. Display the first six A primes and the last six B primes.

m.MinLength = 3;

rgs = extractsigroi(m,prm,'ConcatenateRegions',true);

AB = [rgs{1}(1:6) rgs{2}(end-5:end)]
AB = 6×2

     3    71
     5    73
     7    79
    11    83
   107    89
   109    97

Input Arguments

collapse all

Signal mask, specified as a signalMask object.

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.

Input signal, specified as a vector.

Example: chirp(0:1/1e3:1,25,1,50) specifies a chirp sampled at 1 kHz.

Data Types: single | double
Complex Number Support: Yes

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'ConcatenateRegions',true,'SelectedRegions',[2 4] specifies that the function extract the second and fourth regions of each category and concatenate them.

Option to concatenate extracted signal regions, specified as a logical value.

  • If this argument is set to false, then each cell of sigroi is a cell array corresponding to an individual signal region.

  • If this argument is set to true, then each cell of sigroi is a vector of concatenated extracted signal regions for each category contained in msk.

Data Types: logical

Regions selected for extraction, specified as a vector of integers.

  • If this argument is set to 1, then extractsigroi extracts only the first region of each category and returns it in sigroi.

  • If this argument is set to [i j k ...], then extractsigroi extracts the ith, jth, kth, and successive regions of each category and returns them in sigroi.

The function ignores indices larger than the number of regions present for a given category.

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

Output Arguments

collapse all

Signal regions of interest, returned as a cell array. Each cell of sigroi contains a cell array with the signal regions extracted for each category in msk.

  • If ConcatenateRegions is set to false, then each cell of sigroi is a cell array corresponding to an individual signal region.

  • If ConcatenateRegions is set to true, then each cell of sigroi is a vector of concatenated extracted signal regions for each category contained in msk.

Extracted region limits, returned as a cell array of two-column matrices. If msk specifies a SampleRate, the region limits are expressed in seconds. If msk does not specify a sample rate, the region limits are integers corresponding to signal sample indices.

Number of regions found for each of the categories in cats, returned as a vector of integers.

Category list, returned as a vector of strings.

Version History

Introduced in R2020b