issortedrows

Determine if matrix or table rows are sorted

Description

example

TF = issortedrows(A) returns the logical scalar 1 (true) when the elements of the first column of a matrix A are listed in ascending order. Otherwise, issortedrows returns 0 (false). When the first column has consecutive repeated elements, issortedrows determines whether the next column is in ascending order, and repeats this behavior for succeeding equal values.

example

TF = issortedrows(A,column) returns 1 when A is sorted based on the columns specified in the vector column. For example, issortedrows(A,[4 6]) first checks if the fourth column of A is in ascending order, then checks if the sixth column is in ascending order to break ties.

example

TF = issortedrows(___,direction) returns 1 when the first column of A is in the order specified by direction for any of the previous syntaxes. For example, issortedrows(A,'monotonic') checks if the first column of A is in ascending or descending order. direction can also be a cell array of character vectors representing multiple directions for each column being checked. For example, issortedrows(A,[2 3],{'ascend' 'descend'}) checks if the second column of A is in ascending order, then checks if the third column is in descending order to break ties.

example

TF = issortedrows(___,Name,Value) specifies additional parameters for checking sort order. For example, issortedrows(A,'ComparisonMethod','abs') checks if the elements in the first column of A are sorted by magnitude.

example

TF = issortedrows(tblA) checks if the rows of a table are in ascending order based on the elements in the first variable. If elements in the first variable are repeated, then issortedrows checks the elements in the second variable, and so on.

If tblA is a timetable, then issortedrows checks if the rows of tblA are in ascending order based on its row times. Row times of a timetable label the rows along the first dimension of the timetable.

example

TF = issortedrows(tblA,'RowNames') checks if the rows of a table are in ascending order based on its row names. Row names of a table label the rows along the first dimension of the table.

This syntax is not supported when tblA is a timetable.

example

TF = issortedrows(tblA,rowDimName) checks if the rows of a table are sorted by row labels rowDimName along the first dimension.

• If tblA is a table, then the labels are row names.

• If tblA is a timetable, then the labels are row times.

example

TF = issortedrows(tblA,vars) checks if the rows of a table are in ascending order based on the elements in variables vars. For example, if Age and Weight are variables of tblA, then issortedrows(tblA,{'Age','Weight'}) checks if the rows are in ascending order by age, then by weight to break ties.

• If tblA is a table with row names, then vars can include the row names.

• If tblA is a timetable, then vars can include the row times.

example

TF = issortedrows(___,direction) checks if a table is sorted in the order specified by direction for any of the previous table syntaxes. direction can be a single sort order such as 'descend' or 'monotonic', which is applied to each specified variable, row name, or row time. direction can also be a cell array whose elements contain different sort orders for each specified variable, row name, or row time that issortedrows operates on.

example

TF = issortedrows(___,Name,Value) specifies additional parameters for sorting tables. For example, issortedrows(tblA,'Var1','MissingPlacement','first') checks that missing elements in Var1, such as NaN or NaT, are placed at the beginning of the table.

Examples

collapse all

Create a matrix and determine if its rows are in ascending order based on the values in the first column. Since the first column has a repeated element, sortrows looks to the second column to determine whether the matrix rows are sorted.

A = [1 2 9; 1 5 8; 4 0 7]
A = 3×3

1     2     9
1     5     8
4     0     7

TF = issortedrows(A)
TF = logical
1

Determine if the rows of A are in ascending order based on the values in the third column.

TF = issortedrows(A,3)
TF = logical
0

Determine if the rows of A are in descending order based on the values in the third column.

TF = issortedrows(A,3,'descend')
TF = logical
1

Create a matrix containing complex numbers, and determine if its rows are in ascending order based on the real parts of the elements in the first column. Since the elements in the first column have equal real parts, issortedrows then checks the imaginary parts to break the tie.

A = [1+i 2i; 1+2i 3+4i]
A = 2×2 complex

1.0000 + 1.0000i   0.0000 + 2.0000i
1.0000 + 2.0000i   3.0000 + 4.0000i

TF = issortedrows(A,'ComparisonMethod','real')
TF = logical
1

For a table that describes patient information for five people, determine how the rows of the table are sorted.

Create a table with four variables, and determine if the rows of the table are in ascending order based on age. Since the age variable contains a repeated element, issortedrows then checks the next column (Height) to break the tie.

LastName = {'Sweet';'Jacobson';'Wang';'Joiner';'Berger'};
Age = [38;38;40;43;49];
Height = [69;71;64;67;64];
Weight = [176;163;131;133;119];
BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];

tblA = table(Age,Height,Weight,BloodPressure,'RowNames',LastName)
tblA=5×4 table
Age    Height    Weight    BloodPressure
___    ______    ______    _____________

Sweet       38       69       176       124     93
Jacobson    38       71       163       109     77
Wang        40       64       131       125     83
Joiner      43       67       133       117     75
Berger      49       64       119       122     80

TF = issortedrows(tblA)
TF = logical
1

Check if the table rows are sorted by last name, which are the row names for tblA.

TF = issortedrows(tblA,'RowNames')
TF = logical
0

Check if the table rows are in ascending order by age, then in descending order by weight.

TF = issortedrows(tblA,{'Age','Weight'},{'ascend','descend'})
TF = logical
1

Create a timetable, and check that the rows of the timetable are in ascending order based on the row times. Also check that missing elements are placed last.

Time = [seconds(1:3) NaN NaN]';
TT = timetable(Time,[98;97.5;97.9;98.1;99.9],[120;111;119;117;112],...
'VariableNames',{'Temperature','Distance'})
TT=5×2 timetable
Time      Temperature    Distance
_______    ___________    ________

1 sec           98          120
2 sec         97.5          111
3 sec         97.9          119
NaN sec       98.1          117
NaN sec       99.9          112

TF = issortedrows(TT,'Time','MissingPlacement','last')
TF = logical
1

Input Arguments

collapse all

Input array, specified as a column vector or matrix.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | categorical | datetime | duration
Complex Number Support: Yes

Column sorting vector, specified as a nonzero integer scalar or a vector of nonzero integers. Each specified integer value indicates a column to check for sort order. Negative integers indicate that the sort order is descending.

Sorting direction, specified as one of the following:

• 'ascend' (default) — Checks if data is in ascending order. Data can contain consecutive repeated elements.

• 'descend' — Checks if data is in descending order. Data can contain consecutive repeated elements.

• 'monotonic' — Checks if data is in descending or ascending order. Data can contain consecutive repeated elements.

• 'strictascend' — Checks if data is in strictly ascending order. Data cannot contain duplicate or missing elements.

• 'strictdescend' — Checks if data is in strictly descending order. Data cannot contain duplicate or missing elements.

• 'strictmonotonic' — Checks if data is in strictly descending or strictly ascending order. Data cannot contain duplicate or missing elements.

direction can also be a cell array containing a list of these character vectors, where each element in the list corresponds to a column of A. For example, issortedrows(A,[2 4],{'ascend' 'descend'}) first checks if the rows of A are in ascending order based on the second column. Then, to break ties, issortedrows checks if the rows are in descending order based on the fourth column.

If column is specified, then the number of elements in the cell array must match the length of column. When column is not specified, the cell array must contain an element for every column of A, or a single element that is applied to all columns.

Data Types: char | cell

Input table, specified as a table or a timetable. Each variable in tblA must be a valid input to sort or sortrows.

Data Types: table | timetable

Name of the first dimension of the input table or timetable, specified as a character vector.

• If tblA is a table with row names, then rowDimName is the name of the first dimension of the table. By default, the name of the first dimension is 'Row'. Dimension names are a property of tables. You can access the dimension names of tblA using tblA.Properties.DimensionNames.

• If tblA is a timetable, then rowDimName is the name of the vector of row times. You can specify its name when you create a timetable, such as Time or Date. You can also access the dimension names using tblA.Properties.DimensionNames.

Example: If a table T has row names, and you changed the name of the first dimension using T.Properties.DimensionName{1} = 'Name', then issortedrows(T,'Name') checks if the table is sorted by row names.

Example: If a timetable TT has a time vector named Date, then issortedrows(TT,'Date') checks if the timetable is sorted by the dates and times that Date contains.

Data Types: char

Sorting variables, specified as a scalar integer, a vector of integers, a variable name, a cell array of variable names, or a logical vector. vars indicates the table variables to sort by.

If an element of vars is a positive integer, then issortedrows checks if the rows in the corresponding variable in tblA are in ascending order. If an element of vars is a negative integer, then issortedrows checks if the rows in the corresponding variable in tblA are in descending order.

Example: issortedrows(tblA,{'Height','Weight'}) checks if the rows of tblA are in ascending order, first by the variable Height, then by the variable Weight to break ties.

Example: issortedrows(tblA,[1 4]) first checks if the table rows are in ascending order based on the first variable, then breaks ties by checking if the rows are in ascending order based on the fourth variable.

Example: issortedrows(TT,{'Time','X'}) checks if the row times of a timetable are in ascending order, then breaks ties by checking if the rows are in ascending order based on the table variable 'X'.

Data Types: double | single | char | cell | logical

Name-Value Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: issortedrows(A,'MissingPlacement','last')

Placement of missing values (NaN, NaT, <undefined>, and missing) specified as the comma-separated pair consisting of 'MissingPlacement' and one of the following:

• 'auto' — Missing elements are required to be placed last for ascending order and first for descending order to return 1.

• 'first' — Missing elements are required to be placed first to return 1.

• 'last' — Missing elements are required to be placed last to return 1.

Element comparison method, specified as the comma-separated pair consisting of 'ComparisonMethod' and one of the following:

• 'auto' — Check if the rows of A are sorted by real(A) when A is real, and check if the rows of A are sorted by abs(A) when A is complex.

• 'real' — Check if the rows of A are sorted by real(A) when A is real or complex. If a column has elements with consecutive equal real parts, then check imag(A) to break ties.

• 'abs' — Check if the rows of A are sorted by abs(A) when A is real or complex. If a column has elements with consecutive equal magnitude, then check angle(A) in the interval (-π,π] to break ties.