Documentation

# nominal

(Not Recommended) Arrays for nominal data

The `nominal` and `ordinal` array data types are not recommended. To represent ordered and unordered discrete, nonnumeric data, use the Categorical Arrays (MATLAB) data type instead.

## Description

Nominal data are discrete, nonnumeric values that do not have a natural ordering. `nominal` array objects provide efficient storage and convenient manipulation of such data, while also maintaining meaningful labels for the values.

You can manipulate `nominal` arrays like ordinary numeric arrays, by subscripting, concatenating, and reshaping. Use `nominal` arrays as grouping variables when the elements indicate the group to which an observation belongs.

## Creation

### Syntax

``B = nominal(X)``
``B = nominal(X,labels)``
``B = nominal(X,labels,levels)``
``B = nominal(X,labels,[],edges)``

### Description

````B = nominal(X)` creates a nominal array `B` from the array `X`. `nominal` creates the levels of `B` from the sorted unique values in `X`, and creates default labels for the levels.```

example

````B = nominal(X,labels)` labels the levels in `B` according to `labels`.```
````B = nominal(X,labels,levels)` creates a nominal array with possible levels defined by `levels`.```
````B = nominal(X,labels,[],edges)` creates a nominal array by binning the numeric array `X` with bin edges given by the numeric vector `edges`.```

### Input Arguments

expand all

Input array to convert to `nominal`, specified as a numeric, logical, character, string, or categorical array, or a cell array of character vectors. The levels of the resulting `nominal` array correspond to the sorted unique values in `X`.

Labels for the discrete levels, specified as a character array, string array, or cell array of character vectors. By default, `nominal` assigns labels to the levels in `B` in order of the sorted unique values in `X`.

You can include duplicate labels in `labels` to merge multiple values in `X` into a single level in `B`.

Data Types: `char` | `string` | `cell`

Possible nominal levels for the output `nominal` array, specified as a vector whose values can be compared to those in `X` using the equality operator. `nominal` assigns labels to each level from the corresponding elements of `labels`. If `X` contains any values not present in `levels`, the levels of the corresponding elements of `B` are undefined.

Bin edges used to create the nominal array by binning a numeric array, specified as a numeric vector. The uppermost bin includes values equal to the rightmost edge. `nominal` assigns labels to each level in the resulting nominal array from the corresponding elements of `labels`. When you specify the `edges` input argument, it must have one more element than `labels`.

### Output Arguments

expand all

Nominal array, returned as a `nominal` array object.

By default, an element of `B` is undefined if the corresponding element of `X` is `NaN` (when `X` is numeric), an empty character vector (when `X` is a character), an empty or missing string (when `X` is a string), or undefined (when `X` is categorical). `nominal` treats such elements as undefined or missing and does not include entries for them among the possible levels. To create an explicit level for such elements instead of treating them as undefined, use the `levels` input argument and include `NaN`, the empty character vector, the empty or missing string, or an undefined element.

## Properties

expand all

This property is read-only.

Level labels, specified as a cell array of character vectors. Access labels using `getlabels`.

Data Types: `cell`

This property is read-only.

Label for undefined levels, specified as `'<undefined>'`. You can find undefined elements in categorical arrays by using `isundefined`.

## Object Functions

 `addlevels` (Not Recommended) Add levels to nominal or ordinal arrays `droplevels` (Not Recommended) Drop levels from a nominal or ordinal array `getlabels` (Not Recommended) Access nominal or ordinal array labels `getlevels` (Not Recommended) Access nominal or ordinal array levels `islevel` (Not Recommended) Determine if levels are in nominal or ordinal array `levelcounts` (Not Recommended) Element counts by level of a nominal or ordinal array `mergelevels` (Not Recommended) Merge levels of nominal or ordinal arrays `reorderlevels` (Not Recommended) Reorder levels of nominal or ordinal arrays `setlabels` (Not Recommended) Assign labels to levels of nominal or ordinal arrays

The following is a partial list of the many other MATLAB® array functions you can use with nominal arrays. For a complete list, see Other MATLAB Functions Supporting Nominal and Ordinal Arrays.

 `double` Double-precision arrays `histogram` Histogram plot `isequal` Determine array equality `isundefined` Find undefined elements in categorical array `pie` Pie chart `summary` Print summary of table, timetable, or categorical array `times` Multiplication

## Examples

collapse all

Create nominal arrays from a cell array of character vectors and from integer data. Provide explicit labels.

Create a nominal array from a cell array of character vectors with values `'r'`, `'g'`, and `'b'`. Label these levels `'red'`, `'green'`, and `'blue'`, respectively. `nominal` assigns the labels according to the sorted (alphabetical) order of the elements in `X`.

`X = {'r' 'b' 'g';'g' 'r' 'b';'b' 'r' 'g'}`
```X = 3x3 cell array {'r'} {'b'} {'g'} {'g'} {'r'} {'b'} {'b'} {'r'} {'g'} ```
```labels = {'blue','green','red'}; B = nominal(X,labels)```
```B = 3x3 nominal array red blue green green red blue blue red green ```

Create a nominal array from integer data with values 1 to 4, merging odd and even values into two nominal levels with the labels `'odd'` and `'even'`. Merge the values by duplicating the labels.

`X = randi([1 4],5,2)`
```X = 5×2 4 1 4 2 1 3 4 4 3 4 ```
```labels = {'odd','even','odd','even'}; B = nominal(X,labels)```
```B = 5x2 nominal array even odd even even odd odd even even odd even ```

Create a nominal array from data in a cell array.

```X = {'r','b','g';'g','r','b';'b','r','g'}; labels = {'blue','green','red'}; colors = nominal(X,labels)```
```colors = 3x3 nominal array red blue green green red blue blue red green ```

Identify the elements in `colors` that are members of the level `'red'`. A value of `1` in the resulting array indicates that the corresponding element of `colors` is a member of `'red'`.

`colors == 'red'`
```ans = 3x3 logical array 1 0 0 0 1 0 0 1 0 ```

Identify the elements in `colors` that are members of either the level `'red'` or `'blue'`.

`ismember(colors,{'red','blue'})`
```ans = 3x3 logical array 1 1 0 0 1 1 1 1 0 ```

Merge the elements of the `'red'` and `'blue'` levels into a new level labeled `'purple'`.

`colors = mergelevels(colors,{'red','blue'},'purple')`
```colors = 3x3 nominal array purple purple green green purple purple purple purple green ```

Display the levels of `colors`.

`getlevels(colors)`
```ans = 1x2 nominal array purple green ```

Summarize the number of elements in each level. By default, `summary` returns counts for each column of the input array.

`summary(colors)`
``` purple 2 3 1 green 1 0 2 ```

Create a pie chart for the data in `colors`.

`pie(colors)` 