Documentation

This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

라이선스가 부여된 사용자만 번역 문서를 볼 수 있습니다. 번역 문서를 보려면 로그인하십시오.

categorical

Create categorical array

Use `categorical` to create a categorical array from data with values from a finite set of discrete categories. To group numeric data into categories, use `discretize`.

Syntax

• ``B = categorical(A)``
example
• ``B = categorical(A,valueset)``
example
• ``B = categorical(A,valueset,catnames)``
example
• ``B = categorical(A,___,Name,Value)``
example

Description

example

````B = categorical(A)` creates a categorical array from the array, `A`. The categories of `B` are the sorted unique values from `A`.For more information on creating and using categorical arrays, see Categorical Arrays.```

example

````B = categorical(A,valueset)` creates one category for each value in `valueset`. The categories of `B` are in the same order as the values of `valueset`.You can use `valueset` to include categories for values not present in `A`. Conversely, if `A` contains any values not present in `valueset`, the corresponding elements of `B` are undefined.```

example

````B = categorical(A,valueset,catnames)` names the categories in `B` by matching the category values in `valueset` with the names in `catnames`.```

example

````B = categorical(A,___,Name,Value)` creates a categorical array with additional options specified by one or more `Name,Value` pair arguments. You can include any of the input arguments in previous syntaxes.For example, you can specify that the categories have a mathematical ordering.```

Examples

collapse all

Convert a cell array of character vectors to a categorical array.

Create a cell array of character vectors.

```A = {'r' 'b' 'g'; 'g' 'r' 'b'; 'b' 'r' 'g'} ```
```A = 3×3 cell array 'r' 'b' 'g' 'g' 'r' 'b' 'b' 'r' 'g' ```

`A` is a 3-by-3 cell array containing three unique values.

Convert the cell array of character vectors, `A`, to a categorical array, `B`.

```B = categorical(A) ```
```B = r b g g r b b r g ```

The contents of `B` match the contents of `A`.

Display the categories of `B`.

```categories(B) ```
```ans = 3×1 cell array 'b' 'g' 'r' ```

The categories of `B` are the unique values from `A` in alphabetical order.

Convert a cell array of character vectors, `A`, to a categorical array. Specify a list of categories that includes values that are not present in `A`.

Create a cell array of character vectors.

```A = {'republican' 'democrat'; 'democrat' 'democrat'; 'democrat' 'republican'} ```
```A = 3×2 cell array 'republican' 'democrat' 'democrat' 'democrat' 'democrat' 'republican' ```

`A` is a 3-by-2 cell array containing two unique values.

Convert the cell array of character vectors, `A`, to a categorical array, `B` and include a category for `independent`.

```valueset = {'democrat' 'republican' 'independent'}; B = categorical(A,valueset) ```
```B = republican democrat democrat democrat democrat republican ```

The contents of `B` match the contents of `A`.

Display the categories of `B`.

```categories(B) ```
```ans = 3×1 cell array 'democrat' 'republican' 'independent' ```

The categories of `B` are in the same order as the values specified in `valueset`.

Create a cell array of character vectors.

```A = {'r' 'b' 'g'; 'g' 'r' 'b'; 'b' 'r' 'g'} ```
```A = 3×3 cell array 'r' 'b' 'g' 'g' 'r' 'b' 'b' 'r' 'g' ```

`A` is a 3-by-3 cell array containing three unique values.

Convert the cell array of character vectors, `A`, to a categorical array, `B`, and specify category names.

```B = categorical(A,{'r' 'g' 'b'},{'red' 'green' 'blue'}) ```
```B = red blue green green red blue blue red green ```

`B` uses the specified category names for the contents from `A`.

Display the categories of `B`.

```categories(B) ```
```ans = 3×1 cell array 'red' 'green' 'blue' ```

The categories of `B` are in the order they were specified.

Starting in R2016b, you can create string arrays using the `string` function. Convert a string array to a categorical array and then change its category names.

```str = string({'plane','jet','plane','helicopter','jet'}) ```
```str = 1×5 string array "plane" "jet" "plane" "helicopter" "jet" ```
```C = categorical(str) ```
```C = plane jet plane helicopter jet ```

Specify new category names. When you convert a string array, `valueset` can be either a string array or a cell array of character vectors. However, when you specify new category names, you must specify `catnames` as a cell array of character vectors.

```valueset = string({'plane','jet','helicopter'}) ```
```valueset = 1×3 string array "plane" "jet" "helicopter" ```
```catnames = {'PLN','JET','HEL'} ```
```catnames = 1×3 cell array 'PLN' 'JET' 'HEL' ```

Display the category with new category names.

```C = categorical(str,valueset,catnames) ```
```C = PLN JET PLN HEL JET ```

Convert a string array with missing elements to a categorical array. Where the string array contains a missing value, the categorical array contains an undefined value.

```str = string({'jet','plane','helicopter'}); str(5) = 'plane'; str ```
```str = 1×5 string array "jet" "plane" "helicopter" <missing> "plane" ```
```C = categorical(str) ```
```C = jet plane helicopter <undefined> plane ```

Create a 2-by-3 numeric array.

```A = gallery('integerdata',3,[2,3],3) ```
```A = 2 1 2 1 1 3 ```

`A` contains the values `1`, `2`, and `3`.

Convert the numeric array, `A`, to a categorical array. Use the values `1`, `2`, and `3` to define the categories `car`, `bus`, and `bike`, respectively.

```valueset = 1:3; catnames = {'car' 'bus' 'bike'}; B = categorical(A,valueset,catnames) ```
```B = bus car bus car car bike ```

`categorical` maps the numeric values in `valueset` to the category names in `catnames`.

The 2-by-3 categorical array, `B`, is not ordinal. Therefore, you can only compare the values in `B` for equality. To compare the values in `B` using relational operators, such as less than and greater than, you must include the `'Ordinal',true` name-value pair argument.

Create a 5-by-2 numeric array.

```A = gallery('integerdata',3,[5,2],1) ```
```A = 3 2 3 3 3 2 2 1 3 2 ```

`A` contains the values `1`, `2`, and `3`.

Convert the numeric array, `A`, to an ordinal categorical array where 1, 2, and 3 represent child, adult, and senior respectively.

```valueset = [1:3]; catnames = {'child' 'adult' 'senior'}; B = categorical(A,valueset,catnames,'Ordinal',true) ```
```B = senior adult senior senior senior adult adult child senior adult ```

Since `B` is ordinal, the categories of `B` have a mathematical ordering, `child < adult < senior`.

Use the `discretize` function (instead of `categorical`) to bin 100 random numbers into three categories.

```x = rand(100,1); y = discretize(x,[0 .25 .75 1],'categorical',{'small','medium','large'}); summary(y) ```
``` small 22 medium 46 large 32 ```

Input Arguments

collapse all

Input array, specified as a numeric array, logical array, categorical array, string array, or cell array of character vectors.

`categorical` removes leading and trailing spaces from input values that are strings or character vectors.

If `A` contains missing values, the corresponding element of `B` is `<undefined>`. Missing values are `NaN` for numeric arrays, the missing string (`<missing>`) or the empty string (`string('')`) for string arrays, the empty character vector (`''`) for cell arrays of character vectors, and `<undefined>` for categorical arrays. `B` does not have a category for undefined values. To create an explicit category for missing or undefined values, you must include the desired category name in `catnames`, and `NaN`, `<missing>`, the empty string, the empty character vector, or `<undefined>` in `valueset`.

In addition to an array, `A` can be an object with the following class methods:

• `unique`

• `eq`

Values to define categories, specified as a vector of unique values. The data type of `valueset` and the data type of `A` must be the same, except when `A` is a string array. In that case, `valueset` either can be a string array or a cell array of character vectors.

`categorical` removes leading and trailing spaces from elements of `valueset` that are strings or character vectors.

Category names, specified as a cell array of character vectors. If you do not specify the `catnames` input argument, `categorical` uses the values in `valueset` as category names.

To merge multiple distinct values in `A` into a single category in `B`, include duplicate names corresponding to those values.

Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `'Ordinal',true` specifies that the categories have a mathematical ordering

collapse all

Mathematical ordering indicator, specified as the comma-separated pair consisting of `'Ordinal'` and either `false`, `true`, `0`, or `1`.

 `false` `categorical` creates a categorical array that is not ordinal. This is the default behavior.The categories of `B` have no mathematical ordering. Therefore, you can only compare the values in `B` for equality. `true` `categorical` creates an ordinal categorical array.The categories of `B` have a mathematical ordering, such that the first category specified is the smallest and the last category is the largest. You can compare the values in `B` using relational operators, such as less than and greater than, in addition to comparing the values for equality.

Category protection indicator specified as the comma-separated pair consisting of `'Protected'` and either `false`, `true`, `0`, or `1`. The categories of ordinal categorical arrays are always protected. The default value is `true` when you specify `'Ordinal',true` and false otherwise.

 `false` When you assign new values to `B`, the categories update automatically. Therefore, you can combine (nonordinal) categorical arrays that have different categories. The categories can update accordingly to include the categories from both arrays. `true` When you assign new values to `B`, the values must belong to one of the existing categories. Therefore, you can only combine arrays that have the same categories. To add new categories to `B`, you must use the function `addcats`.

collapse all

Tall Array Support

This function supports tall arrays with the limitation:

With the syntax `C = categorical(data)`, the order of categories is undefined. Use `valueset` and `categoryNames` to enforce the order.