countcats

Count occurrences of categorical array elements by category

Syntax

B = countcats(A)

B = countcats(A,dim)

Description

B = countcats(A) returns the number of elements in each category of a categorical array. The counts are in the same order as the categories listed by the categories function.

• If A is a vector, then countcats returns the number of elements in each category.

• If A is a matrix, then countcats treats the columns of A as vectors and returns the category counts for each column of A.

• If A is a multidimensional array, then countcats acts along the first array dimension whose size does not equal 1.

To display a summary of a categorical array that shows both category names and the number of elements in each category, use the summary function.

B = countcats(A,dim) returns the category counts along dimension dim.

For example, you can return the category counts of each row in a categorical array using countcats(A,2).

Examples

Return Number of Elements in Each Category

Create a categorical array.

A = categorical(["red" "blue" "green" "blue" "red"],["red" "green" "blue"])

A = 1×5 categorical
     red      blue      green      blue      red 

It has three categories, red, green, and blue.

categories(A)

ans = 3×1 cell
    {'red'  }
    {'green'}
    {'blue' }

Find the number of elements in each category of A.

• The first element in B corresponds to the first category of A, which is red.

• The second element in B corresponds to the second category of A, which is green.

• The third element of B corresponds to the third category of A, which is blue.

B = countcats(A)

B = 1×3

     2     1     2

You can see the same result by using the summary function.

summary(A)

A: 1×5 categorical

     red      green      blue      <undefined> 
     2        1          2         0           

Category Counts of Each Column in Array

Create a 3-by-2 categorical array.

valueset = 1:3;
catnames = ["red" "green" "blue"];
A = categorical([1 3; 2 1; 3 1],valueset,catnames)

A = 3×2 categorical
     red        blue 
     green      red  
     blue       red  

It has three categories, red, green, and blue.

categories(A)

ans = 3×1 cell
    {'red'  }
    {'green'}
    {'blue' }

Find the category counts of each column in A. The counts are in the same order as the categories listed by the categories function.

• The value red occurs once in the first column of A and twice in the second column.

• The value green occurs once in the first column of A, and it does not occur in the second column.

• The value blue occurs once in the first column of A and once in the second column.

B = countcats(A)

B = 3×2

     1     2
     1     0
     1     1

You can see the same result by using the summary function.

summary(A)

A: 3×2 categorical

     red              1      2 
     green            1      0 
     blue             1      1 
     <undefined>      0      0 

Category Counts of Each Row in Array

Create a 3-by-2 categorical array.

valueset = 1:3;
catnames = ["red" "green" "blue"];
A = categorical([1 3; 2 1; 3 1],valueset,catnames)

A = 3×2 categorical
     red        blue 
     green      red  
     blue       red  

It has three categories, red, green, and blue.

categories(A)

ans = 3×1 cell
    {'red'  }
    {'green'}
    {'blue' }

Find the category counts of A along the second dimension. The counts are in the same order as the categories listed by the categories function.

• The value red occurs once in the first row of A, once in the second row, and once in the third row.

• The value green occurs in only one element. It occurs in the second row of A.

• The value blue occurs once in the first row of A and once in the third row.

B = countcats(A,2)

B = 3×3

     1     0     1
     1     1     0
     1     0     1

You can see the same result by using the summary function.

summary(A,2)

A: 3×2 categorical

     red      green      blue      <undefined> 
     1        0          1         0           
     1        1          0         0           
     1        0          1         0           

Category Counts of Array Containing Undefined Elements

The countcats function does not return the number of undefined elements in a categorical array.

Create a 6-by-1 categorical array.

valueset = 1:3;
catnames = ["red" "green" "blue"];
A = categorical([1;3;2;1;3;1],valueset,catnames)

A = 6×1 categorical
     red 
     blue 
     green 
     red 
     blue 
     red 

Remove the blue category. A has two categories, red and green. Elements of A that belonged to the blue category are now undefined.

A = removecats(A,"blue")

A = 6×1 categorical
     red 
     <undefined> 
     green 
     red 
     <undefined> 
     red 

Find the number of elements in each category of A.

• The value red occurs three times in A.

• The value green occurs once in A.

• countcats does not return the number of undefined elements.

B = countcats(A)

B = 2×1

     3
     1

To view the number of undefined elements as well as the number of elements in each category of A, use the summary function.

summary(A)

A: 6×1 categorical

     red              3 
     green            1 
     <undefined>      2 

Input Arguments

A — Input array

categorical array

Input array, specified as a categorical array.

dim — Dimension to operate along

positive integer scalar

Dimension to operate along, specified as a positive integer scalar. If you do not specify the dimension, then the default is the first array dimension whose size does not equal 1.

Consider a two-dimensional categorical array, A.

If dim = 1, then countcats(A,1) returns the category counts for each column of A.

If dim = 2, then countcats(A,2) returns the category counts for each row of A.

If dim is greater than ndims(A), then countcats(A) returns an array the same size as A for each category. countcats returns 1 for elements in the corresponding category and 0 otherwise.

Output Arguments

B — Number of elements in each category

numeric array

Number of elements in each category, returned as a numeric array.

Tips

• To find the number of undefined elements in a categorical array, you must use summary or isundefined.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The countcats function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The countcats function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

The countcats function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2013b