# Work with Protected Categorical Arrays

This example shows how to work with a categorical array with protected categories.

When you create a categorical array with the `categorical`

function, you have the option of specifying whether or not the categories are protected. Ordinal categorical arrays always have protected categories, but you also can create a nonordinal categorical array that is protected using the `Protected`

name-value argument.

When you assign values that are not members of a category, the array updates automatically so that its list of categories includes the new values. Similarly, you can combine (nonordinal) categorical arrays that have different categories. The categories in the result include the categories from both arrays.

When you assign new values to a *protected* categorical array, the values must belong to one of the existing categories. Similarly, you can only combine protected arrays that have the same categories.

If you want to combine two nonordinal categorical arrays that have protected categories, they must have the same categories, but the order does not matter. The resulting categorical array uses the category order from the first array.

If you want to combine two ordinal categorical array (that always have protected categories), they must have the same categories, including their order.

To add new categories to the array, you must use the `addcats`

function.

### Create Ordinal Categorical Array

Create a categorical array containing the sizes of 10 objects. Use the category names `small`

, `medium`

, and `large`

for the values `"S"`

, `"M"`

, and `"L"`

.

A = categorical(["M";"L";"S";"S";"M";"L";"M";"L";"M";"S"], ... ["S" "M" "L"], ... ["small" "medium" "large"], ... "Ordinal",true)

`A = `*10x1 categorical*
medium
large
small
small
medium
large
medium
large
medium
small

Display the categories of `A`

.

categories(A)

`ans = `*3x1 cell*
{'small' }
{'medium'}
{'large' }

### Verify That Categories Are Protected

When you create an ordinal categorical array, the categories are always protected.

Use the `isprotected`

function to verify that the categories of A are protected.

tf = isprotected(A)

`tf = `*logical*
1

The categories of `A`

are protected.

### Assign Value in New Category

If you try to assign a new value that does not belong to one of the existing categories, then MATLAB® returns an error. For example, you cannot assign the value `"xlarge"`

to the categorical array, as in the expression `A(2) = "xlarge"`

, because `xlarge`

is not a category of `A`

. Instead, MATLAB returns the error:

Error using () (line 57) Cannot add a new category 'xlarge' to this categorical array because its categories are protected. Use ADDCATS to add the new category.

To add a new category for `xlarge`

, use the `addcats`

function. Because `A`

is ordinal you must specify the order for the new category.

A = addcats(A,"xlarge",After="large");

Now, assign a value for `"xlarge"`

, because it has an existing category.

`A(2) = "xlarge"`

`A = `*10x1 categorical*
medium
xlarge
small
small
medium
large
medium
large
medium
small

`A`

is now a 10-by-1 categorical array with four categories, such that `small < medium < large < xlarge`

.

### Combine Two Ordinal Categorical Arrays

Create another ordinal categorical array, `B`

, containing the sizes of five items.

B = categorical([2;1;1;2;2],1:2,["xsmall" "small"],Ordinal=true)

`B = `*5x1 categorical*
small
xsmall
xsmall
small
small

`B`

is a 5-by-1 categorical array with two categories such that `xsmall < small`

.

To combine two ordinal categorical arrays (which always have protected categories), they must have the same categories and the categories must be in the same order.

Add the category `xsmall`

to `A`

before the category `small`

.

A = addcats(A,"xsmall",Before="small"); categories(A)

`ans = `*5x1 cell*
{'xsmall'}
{'small' }
{'medium'}
{'large' }
{'xlarge'}

Add the categories `medium`

, `large`

, and `xlarge`

to `B`

after the category `small`

.

B = addcats(B,["medium" "large" "xlarge"],After="small"); categories(B)

`ans = `*5x1 cell*
{'xsmall'}
{'small' }
{'medium'}
{'large' }
{'xlarge'}

The categories of `A`

and `B`

are now the same including their order.

Vertically concatenate `A`

and `B`

.

C = [A;B]

`C = `*15x1 categorical*
medium
xlarge
small
small
medium
large
medium
large
medium
small
small
xsmall
xsmall
small
small

The values from `B`

are appended to the values from `A`

.

List the categories of `C`

.

categories(C)

`ans = `*5x1 cell*
{'xsmall'}
{'small' }
{'medium'}
{'large' }
{'xlarge'}

`C`

is a 16-by-1 ordinal categorical array with five categories, such that `xsmall < small < medium < large < xlarge`

.

## See Also

`categorical`

| `categories`

| `summary`

| `isprotected`

| `isordinal`

| `addcats`

## Related Examples

- Create Categorical Arrays
- Convert Text in Table Variables to Categorical
- Access Data Using Categorical Arrays
- Combine Categorical Arrays
- Produce All Combinations of Categories from Two Categorical Arrays