# ordinal

(Not Recommended) Arrays for ordinal data

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

## Description

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

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

## Creation

### Syntax

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

### Description

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

example

````B = ordinal(X,labels)` labels the levels in `B` according to `labels`.```
````B = ordinal(X,labels,levels)` creates an ordinal array with possible levels defined by `levels`.```

example

````B = ordinal(X,labels,[],edges)` creates an ordinal 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 `ordinal`, specified as a numeric, logical, character, string, or categorical array, or a cell array of character vectors. The levels of the resulting `ordinal` 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, `ordinal` 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 ordinal levels for the output `ordinal` array, specified as a vector whose values can be compared to those in `X` using the equality operator. `ordinal` 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 ordinal array by binning a numeric array, specified as a numeric vector. The uppermost bin includes values equal to the rightmost edge. `ordinal` assigns labels to each level in the resulting ordinal 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

Ordinal array, returned as an `ordinal` 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). `ordinal` 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.

## 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 ordinal arrays.

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

## Examples

collapse all

Create an ordinal array from integer data, providing explicit labels.

```quality = ordinal([1 2 3 3 2 1 2 1 3],... {'low' 'medium' 'high'})```
```quality = 1x9 ordinal low medium high high medium low medium low high ```

Show that the first element is less than the second element (low is less than medium).

`quality(1) < quality(2)`
```ans = logical 1 ```

Create an ordinal array by binning values between 0 and 1 into thirds with labels `'small'`, `'medium'`, and `'large'`.

`X = rand(5,2)`
```X = 5×2 0.8147 0.0975 0.9058 0.2785 0.1270 0.5469 0.9134 0.9575 0.6324 0.9649 ```
`A = ordinal(X,{'small' 'medium' 'large'},[],[0 1/3 2/3 1])`
```A = 5x2 ordinal large small large small small medium large large medium large ```

Create an ordinal array from integer data.

`quality = ordinal([1 2 3; 3 2 1; 2 1 3],{'low' 'medium' 'high'})`
```quality = 3x3 ordinal low medium high high medium low medium low high ```

Identify the elements in `quality` that are members of a level greater than or equal to `'medium'`. A value of `1` in the resulting array indicates that the corresponding element of `quality` is a member of this level.

`quality >= 'medium'`
```ans = 3x3 logical array 0 1 1 1 1 0 1 0 1 ```

Identify the elements in `quality` that are members of either the level `'low'` or `'high'`.

`ismember(quality,{'low' 'high'})`
```ans = 3x3 logical array 1 0 1 1 0 1 0 1 1 ```

Merge the elements of the `'medium'` and `'high'` levels into a new level labeled `'ok'`.

`quality = mergelevels(quality,{'medium','high'},'ok')`
```quality = 3x3 ordinal low ok ok ok ok low ok low ok ```

Display the levels of `quality`.

`getlevels(quality)`
```ans = 1x2 ordinal low ok ```

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

`summary(quality)`
``` low 1 1 1 ok 2 2 2 ```

## Version History

Introduced in R2007a