# topkrows

Top rows in sorted order

## Syntax

``B = topkrows(X,k)``
``B = topkrows(X,k,col)``
``B = topkrows(___,direction)``
``B = topkrows(___,'ComparisonMethod',method)``
``[B,I] = topkrows(X,___)``
``B = topkrows(T,k)``
``B = topkrows(T,k,vars)``
``B = topkrows(T,k,vars,direction)``
``B = topkrows(___,'ComparisonMethod',method)``
``[B,I] = topkrows(T,___)``

## Description

example

````B = topkrows(X,k)` returns the first `k` rows in array `X` sorted in descending order (for numeric data) or reverse alphabetical order (for text data). `topkrows` sorts based on the elements in the first column. When the first column contains elements of equal value, `topkrows` sorts according to the elements in the next column and repeats this behavior for succeeding equal values.```

example

````B = topkrows(X,k,col)` sorts the results by the columns specified by `col`. Use this syntax to perform multiple column sorts in succession. For example, `topkrows(X,k,5)` sorts the rows of `X` in descending order based on the elements in the fifth column. `topkrows(X,k,[4 6])` first sorts the rows in descending order by the elements in the fourth column, and then it sorts based on the elements in the sixth column to break ties.```

example

````B = topkrows(___,direction)` specifies the direction of the sorting using any of the previous syntaxes. `direction` can be `'ascend'`, `'descend'`, or a cell array containing those values.For example, `topkrows(A,2,[2 3],{'ascend' 'descend'})` gets the top 2 rows by first sorting rows in ascending order by the elements in column 2. Then, it sorts the rows with equal entries in column 2 in descending order by the elements in column 3.```

example

````B = topkrows(___,'ComparisonMethod',method)` specifies how to compare complex numbers. The comparison method can be `'auto'`, `'real'`, or `'abs'`.```
````[B,I] = topkrows(X,___)` also returns an index vector `I` that describes the order of the selected rows such that `B = X(I,:)`.```

example

````B = topkrows(T,k)` returns the first `k` rows in table or timetable `T`, in sorted order. Table rows are in descending sorted order by all of their variables, and timetable rows are in descending sorted order by time.```

example

````B = topkrows(T,k,vars)` sorts the results by the variables specified by `vars`. Use this syntax to sort with multiple variables in succession. For example, `topkrows(T,k,{'Var1','Var2'})` first sorts the rows of `T` based on the elements in `Var1`, and then it sorts by the elements in `Var2`.```
````B = topkrows(T,k,vars,direction)` specifies the direction of the sorting. For example, use `'ascend'` to sort `T` in ascending order.```
````B = topkrows(___,'ComparisonMethod',method)` specifies how to compare complex numbers. The comparison method can be `'auto'`, `'real'`, or `'abs'`.```
````[B,I] = topkrows(T,___)` also returns an index vector `I` that describes the order of the selected rows such that `B = T(I,:)`.```

## Examples

collapse all

Sort the rows of a matrix using different sorting orders and view the top rows.

Create a 20-by-5 matrix of random integers between 1 and 10.

```rng default % for reproducibility X = randi(10,20,5);```

Sort the rows of `X` in descending order and return the top 4 rows. By default, `topkrows` sorts using the first column of the matrix. For any rows that have equal elements in a particular column, the sorting is based on the column immediately to the right.

`TA = topkrows(X,4)`
```TA = 4×5 10 10 8 7 6 10 7 8 2 4 10 4 4 3 5 10 3 7 9 6 ```

When called with three input arguments, `topkrows` bases the sort entirely on the column specified in the third argument. This means that rows with equal values in the specified column remain in their original order. Sort `X` in descending order using the values in the third column and return the top 5 rows.

`TB = topkrows(X,5,3)`
```TB = 5×5 5 7 10 2 6 2 9 8 6 6 10 10 8 7 6 10 7 8 2 4 10 2 8 3 6 ```

Sort `X` using both the third and fourth columns. In this case, `topkrows` sorts the rows by column 3. Then, for any rows with equal values in column 3, it sorts by column 4.

`TC = topkrows(X,5,[3 4])`
```TC = 5×5 5 7 10 2 6 10 10 8 7 6 2 9 8 6 6 10 2 8 3 6 10 7 8 2 4 ```

Sort a matrix using several columns with different sorting directions.

Create a 100-by-5 matrix of random integers between 1 and 10.

```rng default % for reproducibility X = randi(10,100,5);```

Sort `X` using the first three columns and return the top 10 rows. Specify a sorting direction for each column using a cell array.

`TA = topkrows(X,10,1:3,{'descend','ascend','ascend'})`
```TA = 10×5 10 1 4 6 7 10 1 8 5 1 10 2 3 4 7 10 3 5 10 5 10 4 7 2 4 10 5 5 2 7 10 5 5 6 7 10 6 5 5 7 10 6 6 1 5 10 7 7 8 1 ```

Sort rows of heterogeneous data in a table.

Create a table from the `patients.mat` data set, which includes basic health information for a group of patients. Include the patients age, gender, height, and their self-assessed health status in the table. Make the `SelfAssessedHealthStatus` variable an ordinal categorical array.

```load patients vals = {'Poor','Fair','Good','Excellent'}; SelfAssessedHealthStatus = categorical(SelfAssessedHealthStatus,vals,'Ordinal',true); T = table(Age,Gender,Height,SelfAssessedHealthStatus);```

Find the top 10 rows when the table is sorted in descending order. The result is sorted by the first variable, `Age`, in descending order. The remaining columns are subsorted to break ties:

• The `Gender` variable is subsorted to break ties with age.

• The `Height` variable breaks ties with gender.

• The `SelfAssessedHealthStatus` variable breaks ties with height.

`TA = topkrows(T,10)`
```TA=10×4 table Age Gender Height SelfAssessedHealthStatus ___ __________ ______ ________________________ 50 {'Male' } 72 Excellent 50 {'Male' } 68 Good 49 {'Male' } 70 Fair 49 {'Male' } 68 Poor 49 {'Female'} 64 Good 49 {'Female'} 63 Good 48 {'Male' } 71 Good 48 {'Male' } 71 Good 48 {'Male' } 66 Fair 48 {'Female'} 66 Excellent ```

Find the top 10 rows containing the youngest women by sorting on the `Gender` variable and subsorting on the `Age` variable.

`TB = topkrows(T,10,{'Gender','Age'},'ascend')`
```TB=10×4 table Age Gender Height SelfAssessedHealthStatus ___ __________ ______ ________________________ 25 {'Female'} 63 Good 25 {'Female'} 64 Excellent 27 {'Female'} 69 Fair 28 {'Female'} 65 Good 28 {'Female'} 65 Good 28 {'Female'} 66 Good 29 {'Female'} 63 Excellent 29 {'Female'} 68 Excellent 29 {'Female'} 64 Good 30 {'Female'} 67 Excellent ```

Find the top 10 oldest women by changing the sorting direction of the `Age` variable to `'descend'`.

`TB = topkrows(T,10,{'Gender','Age'},{'ascend','descend'})`
```TB=10×4 table Age Gender Height SelfAssessedHealthStatus ___ __________ ______ ________________________ 49 {'Female'} 64 Good 49 {'Female'} 63 Good 48 {'Female'} 65 Excellent 48 {'Female'} 66 Excellent 48 {'Female'} 64 Excellent 48 {'Female'} 64 Good 48 {'Female'} 66 Excellent 47 {'Female'} 66 Excellent 46 {'Female'} 68 Good 45 {'Female'} 68 Excellent ```

Sort a matrix of complex numbers by absolute value and then by real part.

Create a 100-by-2 matrix of random complex numbers.

```valRange = [-10 10]; X = randi(valRange,100,2) + 1i*randi(valRange,100,2);```

Find the top 10 rows of the matrix. By default, `topkrows` compares the complex numbers by absolute value.

`TA = topkrows(X,10)`
```TA = 10×2 complex -10.0000 + 9.0000i 10.0000 - 2.0000i -8.0000 + 9.0000i 2.0000 - 8.0000i 9.0000 + 8.0000i 4.0000 + 7.0000i -6.0000 +10.0000i -8.0000 - 7.0000i 6.0000 -10.0000i -1.0000 - 5.0000i 6.0000 -10.0000i 0.0000 + 5.0000i -7.0000 + 9.0000i -2.0000 - 5.0000i 9.0000 - 7.0000i 10.0000 + 7.0000i 9.0000 - 7.0000i 6.0000 + 6.0000i -9.0000 - 7.0000i 9.0000 + 9.0000i ```

Find the top 10 rows of the matrix using only the real part of the complex numbers by specifying the `'ComparisonMethod'` name-value pair.

`TB = topkrows(X,10,'ComparisonMethod','real')`
```TB = 10×2 complex 10.0000 + 4.0000i -3.0000 - 7.0000i 10.0000 + 3.0000i 4.0000 + 5.0000i 10.0000 + 2.0000i 5.0000 - 7.0000i 10.0000 - 1.0000i -1.0000 - 8.0000i 10.0000 - 1.0000i -6.0000 +10.0000i 10.0000 - 4.0000i -9.0000 + 0.0000i 10.0000 - 5.0000i -8.0000 - 3.0000i 9.0000 + 8.0000i 4.0000 + 7.0000i 9.0000 + 5.0000i -10.0000 + 0.0000i 9.0000 + 1.0000i 1.0000 - 9.0000i ```

## Input Arguments

collapse all

Input array, specified as a numeric, logical, character, string, categorical, datetime, or duration array.

• If `X` is a nonordinal categorical array, then `topkrows` sorts the elements in descending order based on the order of the categories returned by `categories(X)`.

• If `X` contains `NaN`, `NaT`, or other missing values, then `topkrows` places the missing values at the end of a descending sort.

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

Input table, specified as a table or timetable.

Data Types: `table` | `timetable`

Number of rows to return, specified as a nonnegative scalar integer. If `k` is greater than the number of rows in `X`, then `topkrows` returns all of the rows in `X`.

Columns to sort by, specified as a positive scalar integer or a vector of positive integers.

Example: `B = topkrows(X,100,[1 3])` sorts over the first and third columns before returning the top 100 rows.

Variables to sort by, specified as one of the options in this table.

OptionExampleDescription
positive integer`topkrows(T,k,3)`The integer `n` specifies the index of the variable to sort by as returned by `T.Properties.VariableNames{n}`.
vector of positive integers`topkrows(T,k,[1 3])`The vector `[n1 n2 …]` specifies the indices of several variables to sort by as returned by ```T.Properties.VariableNames{[n1 n2 …]}```.
logical vector```topkrows(T,k,[true false true])```Specifies one or more variables to sort by using values of `true` or `false`.
variable name`topkrows(T,k,"Var3")`Specifies the sorting variable as one of the variable names listed in `T.Properties.VariableNames`.
string array`topkrows(T,k,["Var1","Var3"])`Specifies several sorting variables selected from `T.Properties.VariableNames`.
cell array of character vectors`topkrows(T,k,{'Var1','Var3'})`Specifies several sorting variables selected from `T.Properties.VariableNames`.
`pattern` scalar```topkrows(T,k,"V" + wildcardPattern)```Specifies several sorting variables selected from `T.Properties.VariableNames`.
`'RowNames'``topkrows(T,k,'RowNames')`For tables only. This option sorts the results by the row names.

Example: `B = topkrows(X,k,[1 3])` sorts over the first and third columns.

Example: `B = topkrows(X,k,"Year")` sorts using the `Year` variable.

Sorting direction, specified as either `'descend'`, `'ascend'`, or a cell array that specifies some combination of these values.

If `direction` is a cell array, then it must contain `'descend'` or `'ascend'` for each sorting column specified by `col` or `vars`. If you do not specify `col` or `vars`, then the cell array must contain `'descend'` or `'ascend'` for each column in `X` or variable in `T`.

Comparison method for complex numbers, specified as one of these values:

• `'auto'` — (default) Compares real numbers according to `'real'` and complex numbers according to `'abs'`.

• `'real'` — Compares numbers by real part `real(A)`. Numbers with equal real part are subsorted by imaginary part `imag(A)`.

• `'abs'` — Compares numbers by absolute value `abs(A)`. Numbers with equal magnitude are subsorted by phase angle `angle(A)`.

This option does not support nonnumeric input data (`datetime`, `duration`, `string`, and so on).

## Output Arguments

collapse all

Requested rows, returned as an array of the same class as `X` or `T`.

Row indices, returned as a vector. `I` describes the order of the selected rows such that `B = X(I,:)` or `B = T(I,:)`.

## Tips

• `topkrows` does not do a full sort of the input data, so it is generally faster than `sort` and `sortrows` when the number of requested rows is small.

## Version History

Introduced in R2016b

expand all