# clip

Clip data to range

Since R2024a

## Syntax

``C = clip(X,lower,upper)``
``C = clip(X,lower,upper,Name=Value)``

## Description

example

````C = clip(X,lower,upper)` clips the values in array `X` to the range `[lower,upper]` by replacing values less than `lower` with `lower` and values greater than `upper` with `upper`. The returned clipped data and the input data have the same size and data type.```

example

````C = clip(X,lower,upper,Name=Value)` specifies additional parameters for clipping using one or more name-value arguments. Name-value arguments are supported only for tabular input data. For example, `clip(X,lower,upper,DataVariables=datavars)` clips values in table variables specified by `datavars`.```

## Examples

collapse all

Clip the values in a vector of data to the range [3, 6]. The resulting vector contains values within the specified bounds, where all values less than 3 are replaced with 3, and all values greater than 6 are replaced with 6.

```X = 1:7; C = clip(X,3,6)```
```C = 1×7 3 3 3 4 5 6 6 ```

Create a 7-by-4 numeric matrix.

```col = [1:7]'; X = repmat(col,1,4)```
```X = 7×4 1 1 1 1 2 2 2 2 3 3 3 3 4 4 4 4 5 5 5 5 6 6 6 6 7 7 7 7 ```

Clip the values in each column of the matrix. Each element in the lower bound, specified as a row vector, sets the minimum allowed value for the corresponding column of the input data. The upper bound, specified as a scalar, sets the maximum allowed value for all columns of the input data.

```lower = [1 2 3 4]; upper = 6; C = clip(X,lower,upper)```
```C = 7×4 1 2 3 4 2 2 3 4 3 3 3 4 4 4 4 4 5 5 5 5 6 6 6 6 6 6 6 6 ```

Create a 4-by-7 numeric matrix.

```row = 1:7; X = repmat(row,4,1)```
```X = 4×7 1 2 3 4 5 6 7 1 2 3 4 5 6 7 1 2 3 4 5 6 7 1 2 3 4 5 6 7 ```

Clip the values in each row of the matrix. Each element of the lower bound, specified as a column vector, sets the minimum allowed value for the corresponding row of the input data. The upper bound, specified as a scalar, sets the maximum allowed value for all rows of the input data.

```lower = [1; 2; 3; 4]; upper = 6; C = clip(X,lower,upper)```
```C = 4×7 1 2 3 4 5 6 6 2 2 3 4 5 6 6 3 3 3 4 5 6 6 4 4 4 4 5 6 6 ```

Clip the values in a vector of data to a maximum value of 0. To clip only to an upper bound, specify the lower bound as `-Inf`. This value indicates that there is no lower bound, and `clip` replaces any values exceeding the upper bound with the upper bound value.

```X = -6:6; C = clip(X,-Inf,0)```
```C = 1×13 -6 -5 -4 -3 -2 -1 0 0 0 0 0 0 0 ```

Alternatively, to clip only to a lower bound, specify the upper bound as `Inf`.

Create a table with three variables of different data types.

```num = rand(6,1); num2 = single(rand(6,1)); dt = datetime(2016:2021,1,1)'; T = table(num,num2,dt)```
```T=6×3 table num num2 dt _______ _______ ___________ 0.81472 0.2785 01-Jan-2016 0.90579 0.54688 01-Jan-2017 0.12699 0.95751 01-Jan-2018 0.91338 0.96489 01-Jan-2019 0.63236 0.15761 01-Jan-2020 0.09754 0.97059 01-Jan-2021 ```

Specify the bounds for variables of different data types in one-row tables.

`lower = table(0.2,single(0.1),datetime(2018,1,1),VariableNames=["num" "num2" "dt"])`
```lower=1×3 table num num2 dt ___ ____ ___________ 0.2 0.1 01-Jan-2018 ```
`upper = table(0.9,Inf,datetime(2020,1,1),VariableNames=["num" "num2" "dt"])`
```upper=1×3 table num num2 dt ___ ____ ___________ 0.9 Inf 01-Jan-2020 ```

Clip the `num` and `dt` values in the table, and append the input table variables with table variables containing clipped data.

`C = clip(T,lower,upper,DataVariables=["num" "dt"],ReplaceValues=0)`
```C=6×5 table num num2 dt num_clipped dt_clipped _______ _______ ___________ ___________ ___________ 0.81472 0.2785 01-Jan-2016 0.81472 01-Jan-2018 0.90579 0.54688 01-Jan-2017 0.9 01-Jan-2018 0.12699 0.95751 01-Jan-2018 0.2 01-Jan-2018 0.91338 0.96489 01-Jan-2019 0.9 01-Jan-2019 0.63236 0.15761 01-Jan-2020 0.63236 01-Jan-2020 0.09754 0.97059 01-Jan-2021 0.2 01-Jan-2020 ```

Alternatively, if you specify the bounds as one-row tables containing only the bounds for `num` and `dt`, you do not need to specify the `DataVariables` name-value argument.

## Input Arguments

collapse all

Input data, specified as a scalar, vector, matrix, multidimensional array, table, or timetable.

`clip` ignores missing values in `X`.

Data Types: `double` | `single` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `logical` | `categorical` | `datetime` | `duration` | `table` | `timetable`

Lower bound for the clipped data, specified as a scalar, vector, matrix, multidimensional array, or one-row table. `lower` must be less than or equal to the upper bound and have a size that is compatible with the input data. For more information, see Compatible Array Sizes for Basic Operations.

Use the same lower bound for all elements of `X` by specifying `lower` as a scalar. Use different lower bounds for each column or row in `X` by specifying `lower` as a row or column vector, respectively.

For tabular input data, when the table variables to operate on have different data types, specify the lower bound as a one-row table. The variable names of the one-row table must be the same as the names of the table variables to operate on.

To clip only to a lower bound, specify the upper bound as `Inf`.

Upper bound for the clipped data, specified as a scalar, vector, matrix, multidimensional array, or one-row table. `upper` must be greater than or equal to the lower bound and have a size that is compatible with the input data. For more information, see Compatible Array Sizes for Basic Operations.

Use the same upper bound for all elements of `X` by specifying `upper` as a scalar. Use different upper bounds for each column or row in `X` by specifying `upper` as a row or column vector, respectively.

For tabular input data, when the table variables to operate on have different data types, specify the upper bound as a one-row table. The variable names of the one-row table must be the same as the names of the table variables to operate on.

To clip only to an upper bound, specify the lower bound as `-Inf`.

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: `clip(X,lower,upper,ReplaceValues=false)`

Table variables to operate on, specified as one of the options in this table. The `DataVariables` value indicates which variables of the input table or timetable to clip.

`DataVariables` is supported only for table and timetable input data.

Other variables in the table not specified by `DataVariables` pass through to the output without being operated on. If you do not specify `DataVariables`, `clip` operates on all variables in `X`.

Indexing SchemeExamples

Variable names:

• A string or character vector

• A string array or cell array of character vectors

• A `pattern` object

• `"A"` or `'A'` — A variable named `A`

• `["A" "B"]` or `{'A','B'}` — Two variables named `A` and `B`

• `"Var"+digitsPattern(1)` — Variables named `"Var"` followed by a single digit

Variable index:

• An index number that refers to the location of a variable in the table

• A vector of numbers

• A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing `0` or `false` values.

• `3` — The third variable from the table

• `[2 3]` — The second and third variables from the table

• `[false false true]` — The third variable

Function handle:

• A function handle that takes a table variable as input and returns a logical scalar

• `@isnumeric` — All the variables containing numeric values

Variable type:

• `vartype("numeric")` — All the variables containing numeric values

Example: ```clip(X,lower,upper,DataVariables=["Var1" "Var2" "Var4"])```

Replace values indicator, specified as one of these numeric or logical values when `X` is a table or timetable:

• `true` or `1` — Replace input table variables with table variables containing clipped data.

• `false` or `0` — Append all table variables that were operated on to the input table. The appended variables contain clipped data.

`ReplaceValues` is supported only for table and timetable input data.

Example: `clip(X,lower,upper,ReplaceValues=false)`

## Version History

Introduced in R2024a