removecats

Remove categories from categorical array

Syntax

B = removecats(A)

B = removecats(A,oldcats)

Description

B = removecats(A) removes categories from a categorical array. By default, removecats removes all unused categories. The output categorical array B has the same size and values as the input A. However, B might have fewer categories.

B = removecats(A,oldcats) removes the categories specified by oldcats. The function removes categories but does not remove any elements of the array. Therefore the elements of B are undefined where the corresponding elements of A belong to any category specified by oldcats.

Examples

Remove All Unused Categories

Create a categorical array that has some unused categories. When a categorical array has an unused category, it means that no element of the array belongs to that category.

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

A = 1x6 categorical
     red      blue      blue      blue      red      blue 

Display the categories.

categories(A)

ans = 4x1 cell
    {'black'}
    {'blue' }
    {'red'  }
    {'green'}

Summarize the categorical array. The summary shows that there are no elements that belong to the categories black and green.

summary(A)

A: 1x6 categorical

     black      blue      red      green      <undefined> 
     0          4         2        0          0           

Remove the unused categories.

B = removecats(A)

B = 1x6 categorical
     red      blue      blue      blue      red      blue 

B has the same values as A.

Display the categories of B. The new categorical array has fewer categories.

categories(B)

ans = 2x1 cell
    {'blue'}
    {'red' }

Summarize B. The summary shows that it has no unused categories.

summary(B)

B: 1x6 categorical

     blue      red      <undefined> 
     4         2        0           

Remove Category and Make Corresponding Values Undefined

Create a categorical array.

A = categorical(["plane" "car" "train" "car" "plane" "car"])

A = 1x6 categorical
     plane      car      train      car      plane      car 

Display its categories.

categories(A)

ans = 3x1 cell
    {'car'  }
    {'plane'}
    {'train'}

Remove the category car. The elements that belong to that category are now undefined.

B = removecats(A,"car")

B = 1x6 categorical
     plane      <undefined>      train      <undefined>      plane      <undefined> 

Display the categories of B. It has one fewer category than A.

categories(B)

ans = 2x1 cell
    {'plane'}
    {'train'}

Specify Categories by Using Pattern

Create a categorical array. This array has many different categories that can stand for "yes" and "no".

C = categorical(["Y" "Yes" "N" "No" "Yes" "Y"])

C = 1x6 categorical
     Y      Yes      N      No      Yes      Y 

categories(C)

ans = 4x1 cell
    {'N'  }
    {'No' }
    {'Y'  }
    {'Yes'}

You can match multiple category names by using a pattern. For example, to specify category names that start with a Y, you can use a wildcard pattern. To create a wildcard pattern, use the wildcardPattern function.

Remove the categories whose names start with Y. The removecats function removes categories but does not remove any elements of the input array. Therefore elements that belonged to the categories whose names started with Y are now undefined values.

C = removecats(C,"Y"+wildcardPattern)

C = 1x6 categorical
     <undefined>      <undefined>      N      No      <undefined>      <undefined> 

categories(C)

ans = 2x1 cell
    {'N' }
    {'No'}

Input Arguments

A — Input array

categorical array

Input array, specified as a categorical array.

oldcats — Categories to remove

string array | character vector | cell array of character vectors | pattern scalar

Categories to remove, specified as a string array, character vector, cell array of character vectors, or pattern scalar. The default is all the unused categories from A.

Tips

• ~ismember(categories(A),unique(A)) returns logical 1 (true) for any unused category of A.

Extended Capabilities

Tall Arrays

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

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The oldcats input argument does not support pattern expressions.

For more information, see Code Generation for Categorical Arrays (MATLAB Coder).

Thread-Based Environment

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

This 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™.

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

Version History

Introduced in R2013b