categorical

Methods

⌂ categorical

Method Reference: categorical.categorical

categorical: C = categorical (A)
categorical: C = categorical (A, valueset)
categorical: C = categorical (A, valueset, catnames)
categorical: C = categorical (…, Name, Value)

Create a new array of categorical values.

C = categorical (A) creates a categorical array C from the input array A, which can be numeric, logical, datetime, duration, string, or cell array of character vectors. Input A can also be another categorical array. The categories in C the sorted unique values from the input array A. When the input array is string or cell array of character vectors, any leading or trailing white spaces are removed. Missing values in the input array correspond to <undefined> elements in the created categorical array. By default, there is no category for undefined values in the output array.

C = categorical (A, valueset) creates a categorical array from input A with the categories specified in valueset, which must be a vector of unique values. The data type of input array A and valueset must be the same, unless they are string or cell arrays of character vectors, in which case they can be used interchangeably. Similarly to input array A any leading or trailing white spaces are removed, if valueset is a string or cell array of character vectors.

C = categorical (A, valueset, catnames) creates a categorical array from input A with the categories specified in valueset and named after the corresponding values in catnames, which must be specified either as a string array or a cell array of character vectors. If omitted, categorical uses the cellstring representation of valueset to name the specified category names. catnames must not contain any missing values, it may have duplicate names, and it must have the same number of elements as valueset.

C = categorical (…, Name, Value) further specifies additional parameters for creating categorical array C.

  • "Ordinal" must be a logical scalar specifying that the categories in C have a numeric ordering relationship. By default, it is false and categorical creates a non-ordinal array. The elements of unordered categorical arrays can only be compared for equality. Any other relational operator cannot be used. Setting "Ordinal" to true results in a categorical array with mathematically ordered categories. The ordering goes from smallest to largest according to the order in valueset or the order of appearance in input array A, when valueset is not specified, in which case the unique values in A are not sorted in order to set the categories. Ordinal categorical arrays allow for relational operators such as >=, >, <=, <, as well as statistical operations such as min, max, and median.
  • "Protected" must be a logical scalar specifying that the categories in C are protected. By default, it is false for unordered categorical arrays and it is always true for ordinal categorical arrays. Setting "Protected" to true prevents from assigning new values that do not correspond to existing categories. When false, assigning new values to the array automatically updates the categories. Hence, categorical arrays with different sets of categories can be combined/merged into a new array with set operations.

See also: categories, discretize, iscategorical

Source Code: categorical

Example: 1

categorical stores discrete labels compactly: each value becomes an index into a shared list of categories. Starting from repeated text labels ...

 sizes = {'M'; 'S'; 'L'; 'M'; 'S'; 'L'; 'M'}
sizes =
  7x1 cell array

    {'M'}    
    {'S'}    
    {'L'}    
    {'M'}    
    {'S'}    
    {'L'}    
    {'M'}

... the categories are detected automatically — the sorted unique values.

 C = categorical (sizes)
C =
  7x1 categorical array

    M    
    S    
    L    
    M    
    S    
    L    
    M
 categories (C)
ans =
  3x1 cell array

    {'L'}    
    {'M'}    
    {'S'}

Example: 2

Supply a valueset with 'Ordinal', true to impose a meaningful order, so the values compare with < and >, not only ==.

 raw = {'M'; 'S'; 'L'; 'M'}
raw =
  4x1 cell array

    {'M'}    
    {'S'}    
    {'L'}    
    {'M'}
 C = categorical (raw, {'S', 'M', 'L'}, 'Ordinal', true)
C =
  4x1 categorical array

    M    
    S    
    L    
    M

Ordering questions now make sense.

 C >= 'M'
ans =

  1
  0
  1
  1

Example: 3

A third argument renames the categories as you build; empty labels become the special <undefined> element.

 codes = {'1'; '2'; ''; '1'}
codes =
  4x1 cell array

    {'1'     }    
    {'2'     }    
    {0x0 char}    
    {'1'     }
 C = categorical (codes, {'1', '2'}, {'low', 'high'})
C =
  4x1 categorical array

    low            
    high           
    <undefined>    
    low