Main Content

binmask

Get matrix of binary sequences mask

Since R2020b

Description

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

seqs = binmask(msk,len) specifies the lengths of the sequences in seqs.

example

[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 18 samples.

binSeqs = binmask(m,18)'
binSeqs = 3x18 logical array

   0   1   1   1   1   0   0   0   0   0   0   0   0   0   0   0   1   1
   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   1   1   1   1

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 16 samples.

m.RightShortening = 1;
m.LeftExtension = 2;

binSeqsShort = binmask(m,16)'
binSeqsShort = 3x16 logical array

   1   1   1   1   0   0   0   0   0   0   0   0   0   0   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   1   1   1   1

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.

For more information about the length of the output, see Region Limit Modification.

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.

  • If SourceType is 'categoricalSequence' or 'binarySequences' and len is not specified, then seqs has the same length as the source mask sequence.

  • If SourceType is 'roiTable', then len must be specified.

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