Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

topkrows

Top rows in sorted order

Syntax

T = topkrows(X,k)
T = topkrows(X,k,col)
T = topkrows(X,k,col,direction)
T = topkrows(TT,k)
T = topkrows(TT,k,vars)
T = topkrows(TT,k,vars,direction)

Description

example

T = topkrows(X,k) returns the first k rows in tall array X sorted in descending order (for numeric data) or reverse alphabetical order (for text data).

example

T = topkrows(X,k,col) returns the first k rows in tall array X sorted in descending order by the columns specified by col. Use this syntax to perform multiple column sorts in succession.

example

T = topkrows(X,k,col,direction) specifies the direction of the sorting. For example, use 'ascend' to sort X in ascending order.

example

T = topkrows(TT,k) returns the first k rows in tall table or tall timetable TT 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

T = topkrows(TT,k,vars) returns the first k rows in tall table or tall timetable TT sorted by the variables specified by vars.

example

T = topkrows(TT,k,vars,direction) specifies the direction of the sorting. For example, use 'ascend' to sort TT in ascending order.

Examples

collapse all

Sort the rows of a tall matrix using different sorting orders, return the top rows, and view the results.

Create a 100-by-5 matrix of random integers. Convert the in-memory array into a tall array.

X = randi(20,100,5);
TX = tall(X)
TX =

  100×5 tall double matrix

    17     4    13     2     9
    19    16     8    14     2
     3     7    17     1    12
    19    11    11     2    10
    13     4     8    11    14
     2    13    19     2    14
     6     6    18    17    13
    11    14    12    17     1
    :     :     :     :      :
    :     :     :     :      :

Sort the rows of TX in descending order and return the top 15 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. Collect the values into memory to view the complete results.

TA = topkrows(TX,15)
TA =

  15×5 tall double matrix

    20    15    12     3     7
    20    14    13    15     2
    20    11     9    10    14
    20     9     9     3    13
    20     7    14     4     7
    20     5    10    20     9
    20     3     6     8    13
    20     2     7    11    14
    :      :     :    :     :
    :      :     :    :     :
T1 = gather(TA)
Evaluating tall expression using the Local MATLAB Session:

Evaluation completed in 0 sec
T1 = 

    20    15    12     3     7
    20    14    13    15     2
    20    11     9    10    14
    20     9     9     3    13
    20     7    14     4     7
    20     5    10    20     9
    20     3     6     8    13
    20     2     7    11    14
    19    20     4    17     7
    19    16     8    14     2

When called with three input arguments, topkrows bases the sort entirely on the column specified in the third argument.

Sort TX in descending order using the values in the third column, and return the top 20 rows. Collect the values into memory to view the complete results.

TB = topkrows(TX,20,3)
TB =

  20×5 tall double matrix

    16    18    20     8     6
     6     9    20     7    19
     5     3    20     4     1
    12    11    20     9    17
     2    13    19     2    14
     1    20    19     8     9
    14    17    19     2     4
     4     9    19     6     7
     :     :    :      :     :
     :     :    :      :     :
T2 = gather(TB)
Evaluating tall expression using the Local MATLAB Session:

Evaluation completed in 0 sec
T2 = 

    16    18    20     8     6
     6     9    20     7    19
     5     3    20     4     1
    12    11    20     9    17
     2    13    19     2    14
     1    20    19     8     9
    14    17    19     2     4
     4     9    19     6     7
    11     5    19    18    10
     7     4    19     3    12

If you sort using only one column, then rows that have equal values in the specified column remain in their original order.

Specify two columns to sort by; for example, columns 3 and 4. Collect the values into memory to view the complete results.

TC = topkrows(TX,20,[3 4])
TC =

  20×5 tall double matrix

    12    11    20     9    17
    16    18    20     8     6
     6     9    20     7    19
     5     3    20     4     1
    11     5    19    18    10
    19    14    19    17     5
     1    20    19     8     9
     4     9    19     6     7
     :     :    :      :     :
     :     :    :      :     :
T3 = gather(TC)
Evaluating tall expression using the Local MATLAB Session:

Evaluation completed in 0 sec
T3 = 

    12    11    20     9    17
    16    18    20     8     6
     6     9    20     7    19
     5     3    20     4     1
    11     5    19    18    10
    19    14    19    17     5
     1    20    19     8     9
     4     9    19     6     7
     7     4    19     3    12
     2    13    19     2    14

topkrows sorts by column 3, and then for any rows with equal values in column 3, sorts by column 4.

Sort a tall matrix using several columns with different sorting directions.

Create a 100-by-5 matrix of random integers. Convert the in-memory array into a tall array.

X = randi(10,100,5);
TX = tall(X)
TX =

  100×5 tall double matrix

     9     2     7     1     5
    10     8     4     7     1
     2     4     9     1     6
    10     6     6     1     5
     7     2     4     6     7
     1     7    10     1     7
     3     3     9     9     7
     6     7     6     9     1
     :     :     :     :     :
     :     :     :     :     :

Sort TX using the first three columns and return the top 12 rows. Specify the sorting direction for each column. Collect the values into memory to view the compete results.

T = topkrows(TX,12,1:3,{'descend','ascend','ascend'})
T =

  12×5 tall double matrix

    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
    :      :     :     :     :
    :      :     :     :     :
T12 = gather(T)
Evaluating tall expression using the Local MATLAB Session:

Evaluation completed in 0 sec
T12 = 

    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 text in a tall cell array of character vectors.

Create a tall cell array using the UniqueCarrier text data in the airlinesmall.csv data set.

ds = datastore('airlinesmall.csv','SelectedVariableNames','UniqueCarrier');
tt = tall(ds);
A = tt.UniqueCarrier
A =

  M×1 tall cell array

    'PS'
    'PS'
    'PS'
    'PS'
    'PS'
    'PS'
    'PS'
    'PS'
    :
    :

Sort the rows of C and return the top 10 rows. Collect the values into memory to view the results.

b = topkrows(A,10)
b =

  M×1 tall cell array

    ?
    ?
    ?
    :
    :
B = gather(b)
Evaluating tall expression using the Local MATLAB Session:

- Pass 1 of 1: Completed in 0 sec

Evaluation completed in 0 sec
B = 10×1 cell array
    'YV'
    'YV'
    'YV'
    'YV'
    'YV'
    'YV'
    'YV'
    'YV'
    'YV'
    'YV'

By default topkrows sorts in reverse alphabetical order. Specify ascend as the fourth input to sort in alphabetical order.

c = topkrows(A,10,1,'ascend')
c =

  M×1 tall cell array

    ?
    ?
    ?
    :
    :
C = gather(c)
Evaluating tall expression using the Local MATLAB Session:

- Pass 1 of 1: Completed in 0 sec

Evaluation completed in 0 sec
C = 10×1 cell array
    '9E'
    '9E'
    '9E'
    '9E'
    '9E'
    '9E'
    '9E'
    '9E'
    '9E'
    '9E'

Sort rows of heterogeneous data in a tall table.

Create a tall table for the airlinesmall.csv data set. Select the Year, Month, and UniqueCarrier variables as the variables of interest.

ds = datastore('airlinesmall.csv','SelectedVariableNames',...
    {'Year','Month','UniqueCarrier'});
tt = tall(ds)
tt =

  M×3 tall table

    Year    Month    UniqueCarrier
    ____    _____    _____________

    1987    10       'PS'         
    1987    10       'PS'         
    1987    10       'PS'         
    1987    10       'PS'         
    1987    10       'PS'         
    1987    10       'PS'         
    1987    10       'PS'         
    1987    10       'PS'         
    :       :        :
    :       :        :

Sort the table rows in descending order and return the top 15 rows. Collect the values into memory to view the results.

T = topkrows(tt,15)
T =

  M×3 tall table

    Year    Month    UniqueCarrier
    ____    _____    _____________

    ?       ?        ?            
    ?       ?        ?            
    ?       ?        ?            
    :       :        :
    :       :        :
top15 = gather(T)
Evaluating tall expression using the Local MATLAB Session:

- Pass 1 of 1: Completed in 0 sec

Evaluation completed in 0 sec
top15 = 15×3 table
    Year    Month    UniqueCarrier
    ____    _____    _____________

    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         
    2008    12       'YV'         

Sort the table rows using an alphabetical sort of the UniqueCarrier variable.

T2 = topkrows(tt,10,'UniqueCarrier','ascend')
T2 =

  M×3 tall table

    Year    Month    UniqueCarrier
    ____    _____    _____________

    ?       ?        ?            
    ?       ?        ?            
    ?       ?        ?            
    :       :        :
    :       :        :
top10 = gather(T2)
Evaluating tall expression using the Local MATLAB Session:

- Pass 1 of 1: Completed in 0 sec

Evaluation completed in 0 sec
top10 = 10×3 table
    Year    Month    UniqueCarrier
    ____    _____    _____________

    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         
    2007    1        '9E'         

Input Arguments

collapse all

Input array, specified as a tall array. The underlying data type of X can be numeric, logical, char, string, cell, datetime, or duration.

  • If X contains NaN or NaT values, then topkrows places them on the high end of the sort (as if they were large numbers).

  • If X contains complex numbers, then topkrows sorts them by magnitude and, where magnitudes are equal, further sorts by phase angle on the interval [−π, π].

  • If X is a cell array, then it must contain either all numeric values or all character vectors.

Complex Number Support: Yes

Input table, specified as a tall table or tall timetable.

Number of rows to return, specified as a positive scalar integer.

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

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

Variables to sort by, specified as a positive integer, a vector of positive integers, a logical vector, a variable name, or a cell array containing one or more variable names.

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

Example: T = topkrows(X,k,'Year') sorts using the Year variable.

Sorting direction, specified as either 'descend', 'ascend', or a cell array that specifies 'descend' or 'ascend' for each sorting column specified by col or vars.

Output Arguments

collapse all

Requested rows, returned as an unevaluated tall array of the same size and underlying class as X or TT. To calculate T and bring it into memory, use gather(T). For more information, see Deferred Evaluation of Tall Arrays.

Algorithms

topkrows does not do a full sort of the input data. Instead, the algorithm retrieves the top few rows from each partition of data using local sorts. These intermediate results, which are significantly smaller than the original data, are then combined and fully sorted to produce the final result.

Introduced in R2016b

Was this topic helpful?