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

Thread-Based Environment

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

This 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™.

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