topkrows

Top rows in sorted order

collapse all in page

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

Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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 integertopkrows(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 integerstopkrows(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 vectortopkrows(T,k,[true false true])Specifies one or more variables to sort by using values of true or false.
variable nametopkrows(T,k,'Var3')Specifies the sorting variable as one of the variable names listed in T.Properties.VariableNames.
cell arraytopkrows(T,k,{'Var1 'Var3'})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.

Compatibility Considerations

expand all

Behavior changed in R2017b

Extended Capabilities

See Also

| | | | |

Introduced in R2016b

MATLAB Documentation

Support