catmask

Get categorical sequence mask

Since R2020b

Syntax

seq = catmask(msk)

seq = catmask(msk,len)

seq = catmask(___,'OverlapAction',action)

seq = catmask(___,'OverlapAction','prioritizeByList','PriorityList',idxlist)

[seq,numroi,cats] = catmask(___)

Description

seq = catmask(msk) returns a categorical sequence mask, seq, based on the source and properties in msk.

seq = catmask(msk,len) specifies the length of seq.

seq = catmask(___,'OverlapAction',action) specifies how signalMask deals with regions having different category values that overlap.

seq = catmask(___,'OverlapAction','prioritizeByList','PriorityList',idxlist) specifies the order in which msk categories are prioritized when regions with different category values overlap.

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

Examples

Categorical Mask with Specified Length

Consider a region-of-interest (ROI) table mask with four regions of interest spanning samples numbered from 2 to 30. Specify the category labels as A and B. Use the mask to create a signalMask object.

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

m = signalMask(roiTbl);

Extract a categorical mask from the object specifying a sequence length of 35. Samples beyond the 30th are returned as <undefined>.

catSeq = catmask(m,35);

catSeq(max(roiTbl.Var1(end)):end)

ans = 6x1 categorical
     A 
     <undefined> 
     <undefined> 
     <undefined> 
     <undefined> 
     <undefined> 

Extract the categorical mask again, but now specify a sequence length of 8. Samples beyond the eighth are removed.

catSeq = catmask(m,8)

catSeq = 8x1 categorical
     <undefined> 
     A 
     A 
     A 
     A 
     <undefined> 
     B 
     B 

Categorical Mask from Overlapping Binary Sequences

Consider an 18-by-2 mask of binary sequences. Use the mask to create a signalMask object. Label the categories with A and B, in that order.

binSeqs = logical([ ...
    0 0 1 1 1 0 0 1 1 0 0 0 1 1 1 1 0 1;
    1 1 0 0 0 1 1 1 1 0 1 1 0 1 0 1 1 0]');

m = signalMask(binSeqs);
m.Categories = ["A" "B"];

Extract a categorical mask from the object. To treat overlap between the categories, assign samples shared by the two categories to the first one in the list, A.

seqA = catmask(m,'OverlapAction','PrioritizeByList');
seqA(binSeqs(:,1) & binSeqs(:,2))

ans = 4x1 categorical
     A 
     A 
     A 
     A 

Extract the categorical mask again, but now treat overlap between the categories by assigning the shared samples to B with an explicit priority list.

seqB = catmask(m,'OverlapAction','PrioritizeByList', ...
    'PriorityList',[2 1]);
seqB(binSeqs(:,1) & binSeqs(:,2))

ans = 4x1 categorical
     B 
     B 
     B 
     B 

Treat the overlap by removing regions with fewer than three samples. Display the modified binary-sequence mask that results.

m.MinLength = 3;
binmask(m)'

ans = 2x18 logical array

   0   0   1   1   1   0   0   0   0   0   0   0   1   1   1   1   0   0
   0   0   0   0   0   1   1   1   1   0   0   0   0   0   0   0   0   0

The formerly shared samples are assigned to the categories of the regions that remain.

seqM = catmask(m);
seqM(binSeqs(:,1) & binSeqs(:,2))

ans = 4x1 categorical
     B 
     B 
     A 
     A 

Input Arguments

msk — Signal mask

signalMask object

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.

len — Output sequence length

integer scalar

Output sequence length, specified as an integer scalar. Regions beyond len are ignored. The output categorical sequence seq is padded with <missing> 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.

When RightExtension is nonzero and SourceType is 'categoricalSequence' or 'binarySequences', catmask 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.

As a last step, catmask manages overlap based on the value set for 'OverlapAction', if that argument is specified.

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

action — Way to deal with overlap

'error' (default) | 'prioritizeByList'

Way to deal with overlap, specified as 'error' or 'prioritizeByList'.

• 'error' — catmask throws an error if there are overlaps between regions with different categories.

• 'prioritizeByList' — catmask uses the priority list specified in idxlist to deal with overlaps between regions with different categories. The first category in the list has the highest priority, and all its samples are kept in cases of overlap. The second category in the list follows, and its samples are kept in overlap cases not previously resolved.

  If idxlist is not specified, catmask prioritizes categories in the same order as they appear in the Categories property of msk.

Data Types: char | string

idxlist — Category priorities in cases of overlap

msk Categories list (default) | vector of integers

Category priorities in cases of overlap, specified as a vector of integers. The indices in idxlist correspond to entries in the Categories of msk and are ordered by the priority with which they should be treated when regions with different category values overlap. idxlist must contain indices for all the elements in Categories. The first category in the list has the highest priority. This means that when regions with different categories overlap, all the values of the highest priority are kept. Then the values with the next highest priority are kept in the remaining nonoverlapping samples, and so on.

If idxlist is not specified, catmask prioritizes categories in the same order as they appear in the Categories property of msk.

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

Output Arguments

seq — Categorical sequence mask

categorical array

Categorical sequence mask, returned as a categorical array. Samples in seq that do not belong to a region of interest and have no label value are set to missing categorical values, displayed as <undefined>. For more information, see categorical.

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

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

numroi — Number of regions

vector of integers

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

cats — Category list

vector of strings

Category list, returned as a vector of strings.

Version History

Introduced in R2020b