# extractsigroi

Extract regions of interest based on signal mask

Since R2020b

## Syntax

``sigroi = extractsigroi(msk,x)``
``sigroi = extractsigroi(msk,x,Name,Value)``
``[sigroi,limits] = extractsigroi(___)``
``[sigroi,limits,numroi,cats] = extractsigroi(___)``

## Description

example

````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.```
````[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 `i`th, `j`th, `k`th, 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