Get matrix of binary sequences mask

Since R2020b

## Syntax

``seqs = binmask(msk)``
``seqs = binmask(msk,len)``
``[seqs,numroi,cats] = binmask(___)``

## Description

````seqs = binmask(msk)` returns a matrix of binary sequences mask, `seqs`, based on the source and properties in `msk`.```

example

````seqs = binmask(msk,len)` specifies the lengths of the sequences in `seqs`.```
````[seqs,numroi,cats] = binmask(___)` 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 mask with four regions of interest spanning samples numbered from 2 to 19. Specify the category labels as `A`, `B`, and `C`. Use the mask to create a `signalMask` object.

```roiTbl = table([2 5; 7 10; 15 18; 17 19],["A" "B" "C" "A"]'); m = signalMask(roiTbl);```

Extract a binary sequences mask from the object. Specify a sequence length of 20 samples.

`binSeqs = binmask(m,20)'`
```binSeqs = 3x20 logical array 0 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 0 0 ```

Shorten the regions of interest by one sample from the right and extend them two samples to the left. Extract the modified mask, specifying a sequence length of 18 samples.

```m.RightShortening = 1; m.LeftExtension = 2; binSeqs = binmask(m,18)'```
```binSeqs = 3x18 logical array 1 1 1 1 0 0 0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 0 ```

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

Output sequence length, specified as an integer scalar. Regions beyond `len` are ignored. The output matrix of binary sequences `seqs` is padded with `false` values in these cases:

• `SourceType` is `'categoricalSequence'` or `'binarySequences'` and `len` is greater than the length of the source sequence.

• `SourceType` is `'roiTable'` and `len` is greater than the maximum region index.

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

## Output Arguments

collapse all

Matrix of binary sequences mask, returned as a matrix. The ith column of `seqs` contains a binary mask sequence for the ith category listed in the `SelectedCategories` property of `msk`.

When `RightExtension` is nonzero and `SourceType` is `'categoricalSequence'` or `'binarySequences'`, `binmask` extends regions possibly beyond the sequence length, applies all other modifications based on `LeftExtension`, `LeftShortening`, `RightShortening`, `MergeDistance`, and `MinLength`, and then truncates the resulting sequence to the original sequence length, or to the specified length `len`.

For more information on how the properties of `msk` affect the length of `seqs`, see Region Limit Modification.

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