timetable

Methods

⌂ timetable

Method Reference: timetable.topkrows

timetable: ttB = topkrows (ttA, k)
timetable: ttB = topkrows (ttA, k, vars)
timetable: ttB = topkrows (ttA, k, vars, direction)
timetable: ttB = topkrows (…, Name, Value)
timetable: [ttB, index] = topkrows (…)

The top k rows of a timetable, in sorted order.

ttB = topkrows (ttA, k) returns the k rows with the latest row times, latest first. This is where it parts company with head, which takes the first rows as they are stored: topkrows ranks them.

ttB = topkrows (ttA, k, vars) ranks by one or more variables instead, named, indexed by number, selected by a logical vector or picked out by a vartype. The row dimension name may be used to rank by the row times explicitly. A numeric index counts the variables, and its sign is read the other way round from sortrows: a positive index ranks downwards.

ttB = topkrows (…, direction) sorts as 'ascend' or 'descend', the latter being the default and what makes these the top rows rather than the bottom ones.

Missing keys rank last however the sort runs, which is the one place topkrows differs from sortrows beyond its direction. 'MissingPlacement' overrides that, and 'ComparisonMethod' applies to numeric variables as usual.

Asking for more rows than there are returns all of them, still ranked, and a k of zero returns none.

[ttB, index] = topkrows (…) also returns the rows chosen, so that ttA(index,:) is ttB.

The time step is read afresh from the row times that are kept, so the default ranking of a regular timetable steps backwards.

See also: head, sortrows, timetable

Source Code: timetable

topkrows returns the rows with the latest times, latest first. This is where it parts company with head, which takes the first rows as they happen to be stored rather than ranking them.

 t0 = datetime (2024, 1, 1);
 Depth = [30; 10; 40; 20];
 TT = timetable (Depth, 'RowTimes', t0 + hours ([2 0 3 1])')
TT =
  4x1 timetable

            Time            Depth    
    ____________________    _____    

    01-Jan-2024 02:00:00       30    
    01-Jan-2024 00:00:00       10    
    01-Jan-2024 03:00:00       40    
    01-Jan-2024 01:00:00       20
 topkrows (TT, 2)
ans =
  2x1 timetable

            Time            Depth    
    ____________________    _____    

    01-Jan-2024 03:00:00       40    
    01-Jan-2024 02:00:00       30
 head (TT, 2)
            Time            Depth    
    ____________________    _____    

    01-Jan-2024 02:00:00       30    
    01-Jan-2024 00:00:00       10

Name a variable to rank by that instead, and a direction to take the bottom rows rather than the top. A numeric index counts the variables, and its sign reads the other way round from sortrows: positive ranks downwards.

 t0 = datetime (2024, 1, 1);
 Depth = [12; 45; 23; 8];
 Site = categorical ({'N'; 'S'; 'N'; 'S'});
 TT = timetable (Depth, Site, 'RowTimes', t0 + hours (0:3)');
 topkrows (TT, 2, 'Depth')
ans =
  2x2 timetable

            Time            Depth    Site    
    ____________________    _____    ____    

    01-Jan-2024 01:00:00       45       S    
    01-Jan-2024 02:00:00       23       N
 topkrows (TT, 2, 'Depth', 'ascend')
ans =
  2x2 timetable

            Time            Depth    Site    
    ____________________    _____    ____    

    01-Jan-2024 03:00:00        8       S    
    01-Jan-2024 00:00:00       12       N

Missing keys rank last whichever way the sort runs, which is the one place topkrows differs from sortrows beyond its direction.

 t0 = datetime (2024, 1, 1);
 TT = timetable ([1; 2; NaN; 4], 'RowTimes', t0 + hours (0:3)', ...
                 'VariableNames', {'Reading'});
 topkrows (TT, 4, 'Reading').Reading
ans =

     4
     2
     1
   NaN
 sortrows (TT, 'Reading', 'descend').Reading
ans =

   NaN
     4
     2
     1