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 = 1×6 categorical
     red      blue      blue      blue      red      blue 

Display the categories.

categories(A)

ans = 4×1 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: 1×6 categorical

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

Remove the unused categories.

B = removecats(A)

B = 1×6 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 = 2×1 cell
    {'blue'}
    {'red' }

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

summary(B)

B: 1×6 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 = 1×6 categorical
     plane      car      train      car      plane      car 

Display its categories.

categories(A)

ans = 3×1 cell
    {'car'  }
    {'plane'}
    {'train'}

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

B = removecats(A,"car")

B = 1×6 categorical
     plane      <undefined>      train      <undefined>      plane      <undefined> 

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

categories(B)

ans = 2×1 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 = 1×6 categorical
     Y      Yes      N      No      Yes      Y 

categories(C)

ans = 4×1 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 = 1×6 categorical
     <undefined>      <undefined>      N      No      <undefined>      <undefined> 

categories(C)

ans = 2×1 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.

Output Arguments

B — Output array without removed categories

categorical array

Output array without removed categories, returned as a categorical array.

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

GPU Code Generation

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

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment

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

The removecats 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 removecats function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2013b