renamecats

Rename categories in categorical array

Syntax

B = renamecats(A,newnames)

B = renamecats(A,oldnames,newnames)

Description

B = renamecats(A,newnames) renames categories in a categorical array. By default, renamecats renames all categories. Elements of B use the new category names.

B = renamecats(A,oldnames,newnames) renames only the categories specified by oldnames.

Examples

Rename All Categories

Create a categorical array that has abbreviations for New England state names.

A = categorical(["MA";"ME";"CT";"VT";"ME";"NH";"VT";"MA";"NH";"CT";"RI"])

A = 11×1 categorical
     MA 
     ME 
     CT 
     VT 
     ME 
     NH 
     VT 
     MA 
     NH 
     CT 
     RI 

Display the categories of A.

categories(A)

ans = 6×1 cell
    {'CT'}
    {'MA'}
    {'ME'}
    {'NH'}
    {'RI'}
    {'VT'}

Rename the categories to full state names instead of abbreviations.

newnames = ["Connecticut" "Massachusetts" "Maine" "New Hampshire" "Rhode Island" "Vermont"];
B = renamecats(A,newnames)

B = 11×1 categorical
     Massachusetts 
     Maine 
     Connecticut 
     Vermont 
     Maine 
     New Hampshire 
     Vermont 
     Massachusetts 
     New Hampshire 
     Connecticut 
     Rhode Island 

Display the categories of B.

categories(B)

ans = 6×1 cell
    {'Connecticut'  }
    {'Massachusetts'}
    {'Maine'        }
    {'New Hampshire'}
    {'Rhode Island' }
    {'Vermont'      }

Rename One Category

Create a categorical array.

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

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

Display its categories.

categories(A)

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

Change the category name purple to violet.

B = renamecats(A,"purple","violet")

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

Display the new categories. Note that when violet replaced purple it did not change the order of the categories. They are no longer in alphabetical order.

categories(B)

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

Input Arguments

A — Input array

categorical array

input array, specified as a categorical array.

newnames — New category names

string array | character vector | cell array of character vectors

New category names, specified as a string array, character vector, or cell array of character vectors. The new category names must be unique, and must not duplicate any existing names.

oldnames — Old category names

string array | character vector | cell array of character vectors

Old category names, specified as a string array, character vector, or cell array of character vectors.

Output Arguments

B — Output array with renamed categories

categorical array

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

Tips

• Renaming categories does not change their positions in categories(B). Use reordercats to change the category ordering. For example, you can use B = reordercats(B,sort(categories(B))) to put the categories in alphabetical order.

Extended Capabilities

Tall Arrays

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

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

Version History

Introduced in R2013b