clip

R2026b

Clip data to range

Since R2024a

Syntax

C = clip(X,lower,upper)

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

Description

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.

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

Clip Vector

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

Clip Matrix Columns

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

Clip Matrix Rows

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

Specify Only Upper Bound

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 = -4:4;
C = clip(X,-Inf,0)

C = 1×9

    -4    -3    -2    -1     0     0     0     0     0

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

Clip Table Variables

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

X — Input data

scalar | vector | matrix | multidimensional array | table | timetable

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 — Lower bound

scalar | vector | matrix | multidimensional array | table | timetable

Lower bound for the clipped data, specified as a scalar, vector, matrix, multidimensional array, table, or timetable.

Input Data Type	Bound Behavior	How to Specify lower
Array	Same lower bound for all elements of X	Scalar
Array	Different lower bound for each column of X	Row vector
Array	Different lower bound for each row of X	Column vector
Array	Same bound for all elements of X	Array of the same size as X
Table or timetable	Same lower bound for all elements of X	Scalar
Table or timetable	Different lower bound for each variable of X	One-row table or timetable with variables from X
Table or timetable	Different lower bound for each element of X	Table or timetable with the same variable names and number of rows as X

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

upper — Upper bound

scalar | vector | matrix | multidimensional array | table | timetable

Upper bound for the clipped data, specified as a scalar, vector, matrix, multidimensional array, table, or timetable.

Input Data Type	Bound Behavior	How to Specify upper
Array	Same upper bound for all elements of X	Scalar
Array	Different upper bound for each column of X	Row vector
Array	Different upper bound for each row of X	Column vector
Array	Same upper for all elements of X	Array of the same size as X
Table or timetable	Same upper bound for all elements of X	Scalar
Table or timetable	Different upper bound for each variable of X	One-row table or timetable with variables from X
Table or timetable	Different upper bound for each element of X	Table or timetable with the same variable names and number of rows as X

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)

DataVariables — Table variables to operate on

table variable name | scalar | vector | cell array | pattern | function handle | table vartype subscript

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 Scheme	Values to Specify	Examples
Variable name	A string scalar 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 (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	A vartype subscript that selects variables of a specified type	vartype("numeric") — All the variables containing numeric values

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

ReplaceValues — Replace values indicator

true or 1 (default) | false or 0

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)

Output Arguments

C — Clipped data

scalar | vector | matrix | multidimensional array | table | timetable

Clipped data, returned as a scalar, vector, matrix, multidimensional array, table, or timetable. The size and data type of the clipped data are the same as the input data.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• For code generation, all inputs must be numeric or logical data types.

• Name-value arguments are not supported for code generation.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Version History

Introduced in R2024a

R2026a: Code generation support

You can generate C/C++ code for the clip function.