clip

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 = -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.

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 | one-row table

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

scalar | vector | matrix | multidimensional array | one-row table

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)

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 names	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)

Version History

Introduced in R2024a