timetable

Methods

⌂ timetable

Method Reference: timetable.extractevents

timetable: et = extractevents (tt, rows)
timetable: et = extractevents (tt, labels)
timetable: et = extractevents (…, Name, Value)
timetable: [et, tt2] = extractevents (…)

Build an event table out of the rows of a timetable.

et = extractevents (tt, rows) returns an eventtable whose events happen at the times of the rows rows picks out. rows is any row subscript a timetable accepts: row numbers, a logical vector, row times, a timerange, a withtol or a colon. The events come out in the order the subscript names them and a row named twice gives two events; with no option saying otherwise the event table carries no variables at all and designates nothing.

et = extractevents (tt, labels) takes a categorical vector with one element per row of tt and makes an event of every row whose label is not missing, labelled by it. Consecutive rows sharing a label are not gathered into one interval: each row is its own instantaneous event.

[et, tt2] = extractevents (…) also returns tt2, a copy of tt without the variables the event table took from it. Only variables named by 'EventDataVariables' or by one of the three '…Variable' options are taken, so a call that names none leaves tt2 exactly as tt was.

The following Name-Value options are supported:

NameValue
'EventLabels'A scalar, labelling every event alike, or one value per event. Added as a variable named EventLabels.
'EventLabelsVariable'The name of a variable of tt holding the labels. It keeps its own name in the event table and leaves tt2.
'EventLengths'A duration or calendarDuration, scalar or one per event, added as a variable named EventLengths.
'EventLengthsVariable'The name of a variable of tt holding the lengths, which must be a duration or calendarDuration column.
'EventEnds'Scalar or one per event, of the same type as the row times, added as a variable named EventEnds.
'EventEndsVariable'The name of a variable of tt holding the end times, which must be a datetime or duration column.
'EventDataVariables'Variables of tt to carry into the event table as event data. Each keeps its own name.
'PreserveEventVariables'A logical scalar. When true the variables the event table took stay in tt2 as well. It says what to do with variables that were named, so it requires at least one option that names some.

Source Code: timetable

Lengths and ends are mutually exclusive, however they are given, and so are labels given as values and labels named as a variable. Neither labels option may be combined with the labels form, which carries its own.

See also: eventtable, syncevents, timetable

Source Code: timetable

extractevents builds an event table out of a timetable's own rows. Given a row subscript it takes the times and nothing else.

 t0 = datetime (2024, 3, 1);
 TT = timetable ([12; 45; 23; 31], 'RowTimes', t0 + hours (0:3)', ...
                 'VariableNames', {'Depth'});
 extractevents (TT, [2; 4])
ans =
  2x0 empty eventtable

            Time            
    ____________________    

    01-Mar-2024 01:00:00    
    01-Mar-2024 03:00:00

Given a categorical with one element per row, every row whose label is not missing becomes an event labelled by it. Consecutive rows sharing a label are not gathered into one interval: each row is its own instantaneous event.

 t0 = datetime (2024, 3, 1);
 TT = timetable ([12; 45; 23; 31], 'RowTimes', t0 + hours (0:3)', ...
                 'VariableNames', {'Depth'});
 phase = categorical ({'dry'; 'dry'; ''; 'wet'});
 extractevents (TT, phase)
ans =
  3x1 eventtable

            Time            EventLabels    
    ____________________    ___________    

    01-Mar-2024 00:00:00            dry    
    01-Mar-2024 01:00:00            dry    
    01-Mar-2024 03:00:00            wet

Options say what else the event table carries. A value given as EventLengths becomes a variable of that name; a variable of the timetable named by EventDataVariables keeps its own.

 t0 = datetime (2024, 3, 1);
 TT = timetable ([12; 45; 23; 31], 'RowTimes', t0 + hours (0:3)', ...
                 'VariableNames', {'Depth'});
 extractevents (TT, [2; 4], 'EventLabels', ["rain"; "snow"], ...
                'EventLengths', hours ([1; 2]), ...
                'EventDataVariables', {'Depth'})
ans =
  2x3 eventtable

            Time            EventLabels    EventLengths    Depth    
    ____________________    ___________    ____________    _____    

    01-Mar-2024 01:00:00    {'rain'   }            1 hr       45    
    01-Mar-2024 03:00:00    {'snow'   }            2 hr       31

A second output returns the timetable without the variables the event table took from it. Only a variable that was named is taken, so a call that names none leaves it as it was.

 t0 = datetime (2024, 3, 1);
 TT = timetable ([12; 45; 23; 31], ["a"; "b"; "c"; "d"], ...
                 'RowTimes', t0 + hours (0:3)', ...
                 'VariableNames', {'Depth', 'Tag'});
 [ET, TT2] = extractevents (TT, [2; 4], 'EventLabelsVariable', 'Tag');
 TT2.Properties.VariableNames
ans =
  1x1 cell array

    {'Depth'}