topkrows

Top rows in sorted order

Syntax

B = topkrows(X,k)

B = topkrows(X,k,col)

B = topkrows(X,___,direction)

B = topkrows(X,___,'ComparisonMethod',method)

[B,I] = topkrows(X,___)

B = topkrows(T,k)

B = topkrows(T,k,vars)

B = topkrows(T,k,vars,direction)

B = topkrows(T,k,vars,___,'ComparisonMethod',method)

[B,I] = topkrows(T,___)

Description

Array Data

B = topkrows(X,k) sorts the rows in X and returns the top k rows of the sorted data. The rows are 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.

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.

B = topkrows(X,___,direction) specifies the direction of the sorting using any of the previous syntaxes.

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.

B = topkrows(X,___,'ComparisonMethod',method) specifies how to compare complex numbers in X. 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,:).

Table Data

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.

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(T,k,vars,___,'ComparisonMethod',method) specifies how to compare complex numbers in T.

[B,I] = topkrows(T,___) also returns an index vector I that describes the order of the selected rows such that B = T(I,:).

Examples

Sort Rows of Matrix

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

Specify Sorting Directions for Matrix Columns

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 Table

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,Smoker,Height,SelfAssessedHealthStatus)

T=100×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    38     true        71             Excellent        
    43     false       69             Fair             
    38     false       64             Good             
    40     false       67             Fair             
    49     false       64             Good             
    46     false       68             Good             
    33     true        64             Good             
    40     false       68             Good             
    28     false       68             Excellent        
    31     false       66             Excellent        
    45     false       68             Excellent        
    42     false       66             Poor             
    25     false       71             Poor             
    39     true        72             Excellent        
    36     false       65             Good             
    48     true        71             Good             
      ⋮

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 Smoker variable is subsorted to break ties with age.

• The Height variable breaks ties with smoker status.

• The SelfAssessedHealthStatus variable breaks ties with height.

TA = topkrows(T,10)

TA=10×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    50     true        72             Excellent        
    50     false       68             Good             
    49     true        68             Poor             
    49     true        63             Good             
    49     false       70             Fair             
    49     false       64             Good             
    48     true        71             Good             
    48     true        64             Excellent        
    48     false       71             Good             
    48     false       66             Excellent        

Find the top 10 rows containing the youngest nonsmokers by sorting on the Smoker variable and subsorting on the Age variable.

TB = topkrows(T,10,["Smoker" "Age"],"ascend")

TB=10×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    25     false       71             Poor             
    25     false       70             Poor             
    25     false       63             Good             
    25     false       64             Excellent        
    25     false       66             Good             
    28     false       68             Excellent        
    28     false       65             Good             
    28     false       66             Good             
    29     false       63             Excellent        
    29     false       68             Excellent        

Find the top 10 oldest nonsmokers by changing the sorting direction of the Age variable to "descend".

TB = topkrows(T,10,["Smoker" "Age"],["ascend" "descend"])

TB=10×4 table
    Age    Smoker    Height    SelfAssessedHealthStatus
    ___    ______    ______    ________________________

    50     false       68             Good             
    49     false       64             Good             
    49     false       70             Fair             
    48     false       65             Excellent        
    48     false       66             Excellent        
    48     false       64             Good             
    48     false       71             Good             
    48     false       66             Excellent        
    48     false       66             Fair             
    47     false       70             Excellent        

Sort Complex Numbers

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

X — Input array

array

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

T — Input table

table | timetable

Input table, specified as a table or timetable.

Data Types: table | timetable

k — Number of rows to return

nonnegative scalar integer

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.

col — Columns to sort by

positive scalar integer | vector of positive integers

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.

vars — Variables to sort by

scalar | vector | variable name | string array | cell array of character vectors | pattern scalar | 'RowNames'

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

Option	Example	Description
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.

direction — Sorting direction

'descend' (default) | 'ascend' | string array | cell array of character vectors

Sorting direction, specified as either 'descend', 'ascend', or a string array or cell array of character vectors 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.

method — Comparison method for numeric input

'auto' (default) | 'real' | 'abs'

Comparison method for numeric input, 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).

Output Arguments

B — Requested rows

array | table | timetable

Requested rows, returned as an array, table, or timetable. B is the same type as the input data.

I — Row indices

column vector

Row indices, returned as a column 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.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The topkrows function supports tall arrays with the following usage notes and limitations:

• The ComparisonMethod name-value argument is not supported.

• The RowNames option for tables is not supported.

For more information, see Tall Arrays.

C/C++ Code Generation

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

Usage notes and limitations:

• The following types are not supported: cell, table, categorical, duration, and datetime.

• For fixed size compilation, the value of k must be constant.

• The vars input argument does not support pattern expressions.

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.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The topkrows function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

The topkrows function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2016b

R2025a: Improved performance when returning a large number of rows for numeric or logical data

The topkrows function shows improved performance for numeric data, including complex data, and logical data when k is at least 2048 and is at least 20% of the total number of rows.

For example, this code returns the top 5000 rows from a numeric matrix containing 10,000 rows in descending order, primarily based on the first column. The code is about 2x faster than in the previous release.

function timingTest
A = rand(1e4,10);
for i = 1:120
    T = topkrows(A,5000);
end
end

The approximate execution times are:

R2024b: 0.14 s

R2025a: 0.07 s

The code was timed on a Windows^® 11, AMD EPYC™ 74F3 24-Core Processor @ 3.19 GHz test system using the timeit function.

timeit(@timingTest)

R2017b: Behavior change with tall arrays

Some behaviors of topkrows operating on tall arrays have changed:

• topkrows places NaN, NaT, and other missing values at the end of a descending sort. In previous releases topkrows placed missing values at the beginning of a descending sort.

• topkrows no longer accepts tall cell arrays containing only scalar numeric values as inputs. Use cell2mat to convert the tall cell array of scalar numeric values into a tall matrix before using topkrows.