mergecats

Merge categories in categorical array

Syntax

B = mergecats(A,oldcats)

B = mergecats(A,oldcats,newcat)

Description

B = mergecats(A,oldcats) merges two or more categories of a categorical array into one category. By default, mergecats merges all the categories listed in oldcats into a new category with the same name as oldcats(1). If an element of A belongs to a category listed in oldcats, then the corresponding element of B belongs to oldcats(1).

B = mergecats(A,oldcats,newcat) merges all the categories listed in oldcats into a single new category that has the name specified by newcat.

Examples

Merge Categories into One Category

Create a categorical array that has categories for various colors.

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

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

Display the categories of A. The three categories are in alphabetical order.

categories(A)

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

Merge the categories red and pink into the category red. Specify red first in oldcats to use it as the merged category. mergecats replaces the value pink with red.

oldcats = ["red" "pink"];
B = mergecats(A,oldcats)

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

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

categories(B)

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

Merge Categories Out of Order

Create a categorical array that has categories for various items of clothing.

A = categorical(["shirt" "pants" "shoes" "shirt" "dress" "belt"])

A = 1×6 categorical
     shirt      pants      shoes      shirt      dress      belt 

Display the categories of A. If you do not specify an order, then the categories are in alphabetical order.

categories(A)

ans = 5×1 cell
    {'belt' }
    {'dress'}
    {'pants'}
    {'shirt'}
    {'shoes'}

Merge the categories belt and shoes into a new category called other. The value other replaces all instances of belt and shoes.

B = mergecats(A,["belt" "shoes"],"other")

B = 1×6 categorical
     shirt      pants      other      shirt      dress      other 

Display the categories of B. The new array has four categories and the order is no longer alphabetical. other appears in place of belt because it is the first category that it replaces.

categories(B)

ans = 4×1 cell
    {'other'}
    {'dress'}
    {'pants'}
    {'shirt'}

Merge Categories of Ordinal Categorical Array

Create an ordinal categorical array.

A = categorical([1 2 3 2 1],1:3,["poor" "fair" "good"],Ordinal=true)

A = 1×5 categorical
     poor      fair      good      fair      poor 

Display the categories of A. The categories have the mathematical ordering poor < fair < good.

categories(A)

ans = 3×1 cell
    {'poor'}
    {'fair'}
    {'good'}

Merge all fair or poor values into a new category called bad. Because A is ordinal, the categories to be merged must be consecutive. If they are not consecutive, then mergecats cannot create a new set of categories that have a mathematical ordering.

B = mergecats(A,["fair" "poor"],"bad")

B = 1×5 categorical
     bad      bad      good      bad      bad 

Display the categories of B. The new array has two categories with the mathematical ordering: bad < good.

categories(B)

ans = 2×1 cell
    {'bad' }
    {'good'}

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" "Yeah" "N" "No" "Nope"])

C = 1×6 categorical
     Y      Yes      Yeah      N      No      Nope 

categories(C)

ans = 6×1 cell
    {'N'   }
    {'No'  }
    {'Nope'}
    {'Y'   }
    {'Yeah'}
    {'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.

Merge all categories whose names start with Y into one category named yes. Then merge all the categories whose names start with N into one category named no. As a result, values that have the same meaning are all in the same category. Now, C has only two categories.

C = mergecats(C,"Y" + wildcardPattern,"yes");
C = mergecats(C,"N" + wildcardPattern,"no")

C = 1×6 categorical
     yes      yes      yes      no      no      no 

categories(C)

ans = 2×1 cell
    {'no' }
    {'yes'}

Input Arguments

A — Input array

categorical array

Input array, specified as a categorical array.

oldcats — Categories to merge

string array | cell array of character vectors | pattern scalar

Categories to merge, specified as a string array, cell array of character vectors, or pattern scalar.

• If A is ordinal, then oldcats must specify a subset of categories that are consecutive. If they are not consecutive, then mergecats cannot create a new set of categories that has a mathematical ordering.

• If A is nonordinal, then oldcats can specify any subset of categories.

newcat — New category

string scalar | character vector

New category, specified as a string scalar or a character vector.

Output Arguments

B — Output array with merged categories

categorical array

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

Extended Capabilities

Tall Arrays

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

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

Version History

Introduced in R2013b