addcats

Add categories to categorical array

Syntax

B = addcats(A,newcats)

B = addcats(A,newcats,'Before',beforewhere)

B = addcats(A,newcats,'After',afterwhere)

Description

B = addcats(A,newcats) adds categories to the end of the category list for the input categorical array, A. The output categorical array, B, contains the same values as A. The output, B, does not contain any elements equal to the new categories until you assign values from newcats to elements in B.

If A is an ordinal categorical array, you must specify the 'Before',beforewhere or 'After',afterwhere input arguments.

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

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

Examples

Add Categories at End

Create a nonordinal categorical array.

A = categorical({'republican' 'democrat' 'republican';...
    'democrat' 'republican' 'democrat'})

A = 2x3 categorical
     republican      democrat        republican 
     democrat        republican      democrat   

Display the categories of A.

categories(A)

ans = 2x1 cell
    {'democrat'  }
    {'republican'}

A is a 2-by-3 categorical array with two categories.

Add the categories, independent and undeclared, to the end of the category list.

B = addcats(A,{'independent' 'undeclared'})

B = 2x3 categorical
     republican      democrat        republican 
     democrat        republican      democrat   

B contains the same values as A.

Display the categories of B.

categories(B)

ans = 4x1 cell
    {'democrat'   }
    {'republican' }
    {'independent'}
    {'undeclared' }

B is a 2-by-3 categorical array with four categories.

Add Categories and Specify Category to Precede

Create an ordinal categorical array.

A = categorical({'medium' 'large'; 'small' 'xlarge'; 'large' 'medium'},...
    {'small' 'medium' 'large' 'xlarge'},'Ordinal',true)

A = 3x2 categorical
     medium      large  
     small       xlarge 
     large       medium 

Display the categories of A.

categories(A)

ans = 4x1 cell
    {'small' }
    {'medium'}
    {'large' }
    {'xlarge'}

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

Add the category xsmall before small.

B = addcats(A,'xsmall','Before','small')

B = 3x2 categorical
     medium      large  
     small       xlarge 
     large       medium 

B contains the same values as A.

Display the categories of B.

categories(B)

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

The categories have the mathematical ordering xsmall < small < medium < large < xlarge.

Input Arguments

A — Categorical array

vector | matrix | multidimensional array

Categorical array, specified as a vector, matrix, or multidimensional array.

newcats — New categories

character vector | cell array of character vectors | string array

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

beforewhere — Category to precede

character vector | string scalar

Category to precede, specified as a character vector or a string scalar.

afterwhere — Category to follow

character vector | string scalar

Category to follow, specified as a character vector or a string scalar.

Extended Capabilities

Tall Arrays

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

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

C/C++ Code Generation
Generate C and C++ code using 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