table

Methods

⌂ table

Method Reference: table.topkrows

table: tblB = topkrows (tblA, k)
table: tblB = topkrows (tblA, k, 'RowNames')
table: tblB = topkrows (tblA, k, rowDimName)
table: tblB = topkrows (tblA, k, vars)
table: tblB = topkrows (tblA, k, …, direction)
table: tblB = topkrows (…, Name, Value)
table: [tblB, index] = topkrows (…)

Return the top rows of a table.

tblB = topkrows (tblA, k) returns the top k rows from table tblA sorted in descending order based on all of its variables. If elements in the first variable are repeated, then topkrows sorts by the elements in the second variable, and so on.

tblB = topkrows (tblA, k, 'RowNames') returns the top k rows from table tblA sorted according to its row names. If tblA does not have row names, i.e. tblA.Properties.RowNames is empty, then it returns tblA.

tblB = topkrows (tblA, k, rowDimName) also returns the top k rows from table tblA sorted along its first dimension, rowDimName, which is the equivalent to the previous syntax, i.e. according to its row names. If tblA does not have row names, i.e. tblA.Properties.RowNames is empty, then it returns tblA. For this syntax to work, rowDimName must match the first element in tblA.Properties.DimensionNames, otherwise rowDimName is considered a variable name, as in the following syntax.

tblB = topkrows (tblA, k, vars) returns the top k rows from table tblA sorted by the elements in the variables specified by vars, which can be a character vector (for a single variable) or a cell array of character vectors or a string array (specifying a single or multiple variables). If tblA has row names, then vars can include the row names. Alternatively, vars can be a logical vector or a numeric vector of real integers indexing the desired variables. Unlike sortrows, positive integers specify a descending order, whereas negative integers specify an ascending order for the referenced variables, consistent with the descending default of topkrows. You can also index all available variables in tblA by passing a semicolon character argument. This Octave-specific syntax facilitates the use of the direction input argument when no particular variable needs to be selected to sort on. Additionally, vars can be a vartype object used to create a subscript that selects variables of a specified type.

tblB = topkrows (tblA, k, …, direction) returns the top k rows from table tblA sorted in the order specified by direction for any of the previous syntaxes. direction can be 'ascend' or 'descend', which is applied to all specified variables or row names that sortrows operates on. direction can also be a cell array of character vectors, whose elements are 'ascend' and 'descend', where each element corresponds to the specified variables and/or row names used for sorting the table. The order specified by direction always takes precedence over the order defined by a numerical vector of integers in vars. direction must always be the 3rd input argument. If you want to omit passing selected variables and allow sortrows to work on consecutive variables until all ties are resolved, then you can leave the second input argument empty, as in sortrows (tblA, {[]}, direction) or pass a colon argument for vars as in sortrows (tblA, {':'}, direction).

tblB = topkrows (…, k, Name, Value) returns the top k rows from table tblA sorted with any of the previous syntaxes and further specified by additional parameters for sorting rows of a table with the following Name-Value paired arguments.

  • 'MissingPlacement' specifies the placement of missing values with one of the following options: 'auto' places the missing elements at the bottom for ascending order and at the top for descending order; 'first' places missing elements at the top; 'last' places missing elements at the bottom.
  • 'ComparisonMethod' specifies the element comparison method with one of the following options: 'auto' sorts rows using the real part for real numbers and the magnitude for complex numbers; 'real' sorts rows using the real part for both real and complex numbers; 'abs' sorts rows using the magnitude for both real and complex numbers. For complex numbers with equal magnitude, the phase angle in the interval (-π, π] is further used to break ties.

[tblB, index] = topkrows (…) also returns an index vector such that tblB = tblA(index,:).

Source Code: table

Example: 1

topkrows returns the top k rows by a sort key without sorting the whole table — like sortrows followed by head, but stated in one call. The default direction is descending, so the largest values come first.

 LastName = {'Sanchez'; 'Johnson'; 'Li'; 'Diaz'; 'Brown'};
 Age = [38; 43; 38; 40; 49];
 T = table (Age, 'RowNames', LastName)
T =
  5x1 table

               Age    
               ___    

    Sanchez     38    
    Johnson     43    
    Li          38    
    Diaz        40    
    Brown       49
 topkrows (T, 3, 'Age')
ans =
  3x1 table

               Age    
               ___    

    Brown       49    
    Johnson     43    
    Diaz        40

Add a direction to take the smallest instead, and capture the index of the selected rows in the original table.

 [B, idx] = topkrows (T, 2, 'Age', 'ascend');
 B
B =
  2x1 table

               Age    
               ___    

    Sanchez     38    
    Li          38
 idx
idx =

   1
   3