timetable.syncevents
timetable: tt2 = syncevents (tt)
timetable: tt2 = syncevents (tt, defaultLabel)
timetable: tt2 = syncevents (…, 'EventDataVariables', vars)
Copy the attached event table’s data onto the rows it covers.
tt2 = syncevents (tt) adds the variables of the
event table attached to tt as variables of tt, each row
taking the values of the event covering its time. A row no event
covers takes missing values. tt must have an event table
attached.
An event covers the times from its own onwards and stops short of its end, so an event beginning at 02:00 and lasting two hours covers 02:00 and 03:00 but not 04:00, and an event of zero length covers nothing. An event with neither a length nor an end is an instant and covers only a row at exactly its own time.
A row covered by more than one event is repeated, once per event, which generally makes the result irregular.
By default every variable of the event table is copied except the one
holding the event lengths or ends, which describes the events rather
than what happened. 'EventDataVariables' names the variables
to copy instead, and replaces that default rather than adding to it,
so it can ask for the lengths and can leave the labels out.
tt2 = syncevents (tt, defaultLabel) gives
defaultLabel to the rows no event covers, in place of a missing
label. It reaches the labels variable alone; every other copied
variable stays missing there.
A copied variable whose name tt already uses has both of them
renamed, the timetable’s with a _tt suffix and the event
table’s with _et, so neither is lost to the other.
The result keeps the event table it was synchronised from.
See also: extractevents, eventtable, timetable
Source Code: timetable
syncevents copies the attached event table's data onto the rows its events cover. A row no event covers takes a missing value.
t0 = datetime (2024, 3, 1);
TT = timetable ([12; 45; 23; 31], 'RowTimes', t0 + hours (0:3)', ...
'VariableNames', {'Depth'});
TT.Properties.Events = eventtable (t0 + hours ([1; 3]), ...
'EventLabels', ["rain"; "snow"]);
syncevents (TT)
ans =
4x2 timetable
Time Depth EventLabels
____________________ _____ ___________
01-Mar-2024 00:00:00 12 {'' }
01-Mar-2024 01:00:00 45 {'rain' }
01-Mar-2024 02:00:00 23 {'' }
01-Mar-2024 03:00:00 31 {'snow' }
An interval event covers the rows from its own time up to but not including its end, so a two-hour event beginning at 01:00 covers 01:00 and 02:00. A default label answers for the rows left over.
t0 = datetime (2024, 3, 1);
TT = timetable ([12; 45; 23; 31], 'RowTimes', t0 + hours (0:3)', ...
'VariableNames', {'Depth'});
TT.Properties.Events = eventtable (t0 + hours (1), ...
'EventLabels', "rain", ...
'EventLengths', hours (2));
syncevents (TT, "dry")
ans =
4x2 timetable
Time Depth EventLabels
____________________ _____ ___________
01-Mar-2024 00:00:00 12 {'dry' }
01-Mar-2024 01:00:00 45 {'rain' }
01-Mar-2024 02:00:00 23 {'rain' }
01-Mar-2024 03:00:00 31 {'dry' }
A row two events both cover is repeated, once per event, which generally makes the result irregular.
t0 = datetime (2024, 3, 1);
TT = timetable ([12; 45; 23; 31], 'RowTimes', t0 + hours (0:3)', ...
'VariableNames', {'Depth'});
TT.Properties.Events = eventtable (t0 + hours ([1; 2]), ...
'EventLabels', ["rain"; "hail"], ...
'EventLengths', hours ([2; 2]));
height (syncevents (TT))
ans = 5