addcats

Add categories to categorical array

Syntax

B = addcats(A,newcats)

B = addcats(A,newcats,Before=catname)

B = addcats(A,newcats,After=catname)

Description

B = addcats(A,newcats) adds categories to a categorical array. By default, addcats adds the new categories to the end of the set of categories, as shown by the output of categories(A). It does not add new elements. The output categorical array B does not contain elements that belong to any of the new categories until you assign such elements to B.

If A is an ordinal categorical array, you must specify the Before or After name-value argument.

B = addcats(A,newcats,Before=catname) adds categories before the specified category.

B = addcats(A,newcats,After=catname) adds categories after the specified category.

Examples

Add Categories

Create a categorical array.

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

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

Display the categories of the array.

categories(A)

ans = 2×1 cell
    {'blue'}
    {'red' }

Add the categories, green and black, to the end of the set of categories. The new array has the same elements but it has more categories.

B = addcats(A,["green" "black"])

B = 1×6 categorical
     red      blue      red      blue      red      blue 

categories(B)

ans = 4×1 cell
    {'blue' }
    {'red'  }
    {'green'}
    {'black'}

Add Category Before First Category

Create an ordinal categorical array.

A = categorical(["medium" "large"; "small" "xlarge"; "large" "medium"], ...
                ["small" "medium" "large" "xlarge"], ...
                Ordinal=true)

A = 3×2 categorical
     medium      large  
     small       xlarge 
     large       medium 

Display the categories. Because A is ordinal, the categories have the mathematical ordering small < medium < large < xlarge.

categories(A)

ans = 4×1 cell
    {'small' }
    {'medium'}
    {'large' }
    {'xlarge'}

Add the category xsmall before small. Then display the categories of the new array. Its categories have the mathematical ordering xsmall < small < medium < large < xlarge.

B = addcats(A,"xsmall",Before="small");
categories(B)

ans = 5×1 cell
    {'xsmall'}
    {'small' }
    {'medium'}
    {'large' }
    {'xlarge'}

Input Arguments

A — Input array

categorical array

Input array, specified as a categorical array.

newcats — New categories

string array | character vector | cell array of character vectors

New categories, specified as a string array, character vector, or cell array of character vectors.

catname — Name of category

string scalar | character vector

Name of a category, specified as a string scalar or character vector.

Output Arguments

B — Output array with added categories

categorical array

Output array with added categories, returned as a categorical array.

Extended Capabilities

Tall Arrays

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

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

Version History

Introduced in R2013b