Categories &

Functions List

Class Definition: eventfilter

datatypes: eventfilter

Subscript into a timetable by what was happening rather than by when.

A utility class that builds a condition against the variables of the event table attached to a timetable, and selects the rows the matching events cover. The condition picks out events; the rows follow from them.

 
 ef = eventfilter (tt);
 tt(ef.EventLabels == "rain", :)

An event covers the times from its own onwards and stops short of its end, and an event with neither a length nor an end covers only a row at exactly its own time. Rows covered by more than one matching event are selected once: a filter answers which rows, not how often.

Time names the event’s own time, not the row’s, so ef.Time > d selects the rows of the events that began after d.

See also: eventtable, timerange, withtol, timetable

Source Code: eventfilter

The eventfilter class offers the following public methods:

eventfilter: ef = eventfilter (tt)
eventfilter: ef = eventfilter (eventLabels)

ef = eventfilter (tt) creates a filter that may be written against the variables of the event table attached to the timetable tt, together with Time, the events’ own times. tt must have an event table attached, since the names come from it.

ef = eventfilter (eventLabels) creates a filter that matches the events carrying any of the given labels, without a timetable to take the names from. It is a whole condition already and needs no comparison written against it.

A filter is used as a row subscript, and selects the rows the matching events cover. Conditions combine with & and |; ~ is not supported, an event filter having no complement worth the name.

See also: eventtable, timerange, timetable

An event filter selects the rows of a timetable by what was happening, rather than by the clock. The condition picks out events; the rows the matching events cover follow from them.

 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));
 EF = eventfilter (TT);
 TT(EF.EventLabels == "rain", :)
ans =
  2x1 timetable

            Time            Depth    
    ____________________    _____    

    01-Mar-2024 01:00:00       45    
    01-Mar-2024 02:00:00       23

Conditions combine with & and |, and Time names the event's time rather than the row's.

 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 ([1; 2]));
 EF = eventfilter (TT);
 TT(EF.EventLabels == "hail" & EF.EventLengths > hours (1), :)
ans =
  2x1 timetable

            Time            Depth    
    ____________________    _____    

    01-Mar-2024 02:00:00       23    
    01-Mar-2024 03:00:00       31

A filter made from labels alone is a whole condition already, and needs no timetable to be written against.

 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"]);
 TT(eventfilter ("hail"), :)
ans =
  1x1 timetable

            Time            Depth    
    ____________________    _____    

    01-Mar-2024 02:00:00       23

timerange takes two event filters as bounds, running from the start of one event to the start of the other and stopping short of it.

 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"]);
 EF = eventfilter (TT);
 TT(timerange (EF.EventLabels == "rain", EF.EventLabels == "snow"), :)
ans =
  2x1 timetable

            Time            Depth    
    ____________________    _____    

    01-Mar-2024 01:00:00       45    
    01-Mar-2024 02:00:00       23
eventfilter: names = properties (ef)

They are the variables of the event table the filter came from, together with Time. A filter made from a list of labels carries none, having been given no event table to read them from.

eventfilter: ix = rowIndices (ef, tt)

eventfilter: t = eventTimes (ef, tt)

The times come back in the order the event table holds them. It is what a timerange reads when an event filter is given as one of its bounds.