eventfilter - Create event filter for selecting timetable rows - MATLAB (original) (raw)
Create event filter for selecting timetable rows
Since R2023a
Syntax
Description
This function creates an event filter for selecting rows of a timetable based on the events attached to the timetable.
An event filter is a type of row filter. You can use it as a row subscript when you subscript into a timetable.
EF = eventfilter([eventLabels](#mw%5Ff6955cbe-1286-4feb-b778-c03c1050dec8)) creates an event filter that matches any event whose event label is equal to one of the labels specified byeventLabels.
To filter timetable rows with an event filter created using this syntax:
- The timetable must have an attached event table.
- The event table must specify that one of its variables is the event labels variable.
You can create more complex event filters by combining multiple filters using the& or | operators. For example,eventfilter("A") matches events with event label"A", while eventfilter("A") | eventfilter("B") matches events whose labels are either "A" or "B".
Note: You can also use event filters with timerange andwithtol, or with functions such ascontainsrange.
EF = eventfilter([TT](#mw%5Fd9430b00-d2d0-42a7-ad32-e268924c536b)) creates an event filter from an event table that is attached to the input timetable TT. The function creates the event filter using the variable names of the attached event table.
Each variable of the event table becomes a property of the event filter. To match rows where an event filter property meets a condition, use any of the relational operators:<, <=, >,>=, ==, and ~=. To combine multiple conditions, use the & or | operators.
Examples
Create an event filter. Then use the event filter to select rows of a timetable that occur during the specified event.
First, create an event filter that matches any event whose event label is "Rain".
EF = eventfilter with constraint:
<Event Labels Variable> == "Rain"Load a timetable and an event table from a sample MAT-file. The timetable has weather data for two weeks. The event table has event times, event labels, event lengths, and precipitation measurements for several weather events. Display the timetable and event table.
load weatherEvents.mat weatherData
weatherData=15×2 timetable Time Temperature Humidity ___________ ___________ ________
01-Nov-2022 36 45
02-Nov-2022 31 76
03-Nov-2022 37 43
04-Nov-2022 36 46
05-Nov-2022 38 72
06-Nov-2022 32 54
07-Nov-2022 35 50
08-Nov-2022 34 45
09-Nov-2022 32 72
10-Nov-2022 30 58
11-Nov-2022 39 54
12-Nov-2022 34 58
13-Nov-2022 31 73
14-Nov-2022 40 78
15-Nov-2022 34 66 weatherEvents = 4×3 eventtable Event Labels Variable: EventType Event Lengths Variable: EventLength
Time EventType EventLength Precipitation (mm)
___________ _________ ___________ __________________
03-Nov-2022 Hail 1.2 hr 12.7
05-Nov-2022 Rain 36 hr 114.3
10-Nov-2022 Snow 18 hr 25.4
14-Nov-2022 Rain 20 hr 177.8 Attach the event table to the timetable. When you display the timetable, you can see additional labels for the rows during which events occur.
weatherData.Properties.Events = weatherEvents
weatherData=15×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
01-Nov-2022 36 45
02-Nov-2022 31 76
Hail 03-Nov-2022 37 43
04-Nov-2022 36 46
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
07-Nov-2022 35 50
08-Nov-2022 34 45
09-Nov-2022 32 72
Snow 10-Nov-2022 30 58
11-Nov-2022 39 54
12-Nov-2022 34 58
13-Nov-2022 31 73
Rain 14-Nov-2022 40 78
15-Nov-2022 34 66 To select the rows of the timetable that correspond to times when rain occurred, use the event filter as a row subscript. The rain event that started on November 5, 2022, lasted for 36 hours. So the event filter selects the rows of weatherData whose row times are November 5 and November 6 because the event spans both dates. The event table that is attached to the original timetable is also attached to the output timetable.
rainyDays = weatherData(EF,:)
rainyDays=3×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
Rain 14-Nov-2022 40 78 Load a timetable and an event table from a sample MAT-file. Attach the event table to the timetable. Then display the timetable and event table.
load weatherEvents.mat weatherData.Properties.Events = weatherEvents
weatherData=15×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
01-Nov-2022 36 45
02-Nov-2022 31 76
Hail 03-Nov-2022 37 43
04-Nov-2022 36 46
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
07-Nov-2022 35 50
08-Nov-2022 34 45
09-Nov-2022 32 72
Snow 10-Nov-2022 30 58
11-Nov-2022 39 54
12-Nov-2022 34 58
13-Nov-2022 31 73
Rain 14-Nov-2022 40 78
15-Nov-2022 34 66 weatherEvents = 4×3 eventtable Event Labels Variable: EventType Event Lengths Variable: EventLength
Time EventType EventLength Precipitation (mm)
___________ _________ ___________ __________________
03-Nov-2022 Hail 1.2 hr 12.7
05-Nov-2022 Rain 36 hr 114.3
10-Nov-2022 Snow 18 hr 25.4
14-Nov-2022 Rain 20 hr 177.8 Create an event filter from the event table that is attached to the input timetable.
EF = eventfilter(weatherData)
EF = eventfilter with no constraints and no selected variables
<unconstrained>VariableNames: Time, EventType, EventLength, Precipitation (mm)
Use the event filter as a row subscript. The filter selects rows that occur during any event listed in the attached event table.
allEvents = weatherData(EF,:)
allEvents=5×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
Hail 03-Nov-2022 37 43
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
Snow 10-Nov-2022 30 58
Rain 14-Nov-2022 40 78 Select rows of a timetable where the data associated with events meets a condition that you specify.
First, load a timetable and an event table from a sample MAT-file. Attach the event table to the timetable.
load weatherEvents.mat weatherData.Properties.Events = weatherEvents
weatherData=15×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
01-Nov-2022 36 45
02-Nov-2022 31 76
Hail 03-Nov-2022 37 43
04-Nov-2022 36 46
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
07-Nov-2022 35 50
08-Nov-2022 34 45
09-Nov-2022 32 72
Snow 10-Nov-2022 30 58
11-Nov-2022 39 54
12-Nov-2022 34 58
13-Nov-2022 31 73
Rain 14-Nov-2022 40 78
15-Nov-2022 34 66 Display the attached event table. It has both event labels and event lengths.
weatherData.Properties.Events
ans = 4×3 eventtable Event Labels Variable: EventType Event Lengths Variable: EventLength
Time EventType EventLength Precipitation (mm)
___________ _________ ___________ __________________
03-Nov-2022 Hail 1.2 hr 12.7
05-Nov-2022 Rain 36 hr 114.3
10-Nov-2022 Snow 18 hr 25.4
14-Nov-2022 Rain 20 hr 177.8 Create an event filter from the attached event table.
EF = eventfilter(weatherData)
EF = eventfilter with no constraints and no selected variables
<unconstrained>VariableNames: Time, EventType, EventLength, Precipitation (mm)
Then create an event filter from EF for rain events that last less than 24 hours.
rainLessThan24 = EF.EventType == "Rain" & EF.EventLength < hours(24)
rainLessThan24 = eventfilter with constraints:
EventType == "Rain" & EventLength < 24 hrVariableNames: Time, EventType, EventLength, Precipitation (mm)
Select rows of weatherData for rain events that lasted less than 24 hours.
weatherData(rainLessThan24,:)
ans=1×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
Rain 14-Nov-2022 40 78 Select rows of a timetable that occur between events by specifying a timerange object whose endpoints are event filters. Then select rows that occur around events, within a time tolerance specified by a withtol object.
First, load a timetable and an event table from a sample MAT-file. Attach the event table to the timetable.
load weatherEvents.mat weatherData.Properties.Events = weatherEvents
weatherData=15×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
01-Nov-2022 36 45
02-Nov-2022 31 76
Hail 03-Nov-2022 37 43
04-Nov-2022 36 46
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
07-Nov-2022 35 50
08-Nov-2022 34 45
09-Nov-2022 32 72
Snow 10-Nov-2022 30 58
11-Nov-2022 39 54
12-Nov-2022 34 58
13-Nov-2022 31 73
Rain 14-Nov-2022 40 78
15-Nov-2022 34 66 Then create a time range that includes all times between two event filters. The first event filter specifies events labeled "Hail". The second event filter specifies events labeled "Snow".
EFstart = eventfilter("Hail"); EFend = eventfilter("Snow"); TR = timerange(EFstart,EFend,"closed")
TR = timetable timerange subscript:
Select timetable rows with event times in the closed interval:
Starting at, including: <Event Labels Variable> == "Hail"
Ending at, including: <Event Labels Variable> == "Snow"
See Select Times in Timetable.Select rows of the timetable that occur between the events by using TR as a row subscript.
betweenEvents = weatherData(TR,:)
betweenEvents=8×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
Hail 03-Nov-2022 37 43
04-Nov-2022 36 46
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
07-Nov-2022 35 50
08-Nov-2022 34 45
09-Nov-2022 32 72
Snow 10-Nov-2022 30 58 You can also select row times that occur within a specified time tolerance of an event by using the withtol function. For example, select rows that are within 24 hours of any event labeled "Rain". This subscript selects rows that occur up to 24 hours before and after each event that the event filter finds in the timetable.
WT = withtol(eventfilter("Rain"),hours(24))
WT = timetable withtol subscript:
Select timetable rows matching the following event times:
<Event Labels Variable> == "Rain"
with tolerance of +/- 24 hr
See Select Times in Timetable.aroundEvents = weatherData(WT,:)
aroundEvents=7×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
04-Nov-2022 36 46
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
07-Nov-2022 35 50
13-Nov-2022 31 73
Rain 14-Nov-2022 40 78
15-Nov-2022 34 66 Since R2023b
You can use the containsrange, overlapsrange, and withinrange functions to determine if the row times of a timetable match a time range specified by a timerange object. And you can specify a timerange object using event filters.
- containsrange returns
1when the timetable contains the entire time range. - overlapsrange returns 1 when the timetable overlaps at least a part of the time range.
- withinrange returns 1 when all of the row times of a timetable occur within the time range.
Load a timetable and an event table from a sample MAT-file. Attach the event table to the timetable.
load weatherEvents.mat weatherData.Properties.Events = weatherEvents
weatherData=15×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________
01-Nov-2022 36 45
02-Nov-2022 31 76
Hail 03-Nov-2022 37 43
04-Nov-2022 36 46
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
07-Nov-2022 35 50
08-Nov-2022 34 45
09-Nov-2022 32 72
Snow 10-Nov-2022 30 58
11-Nov-2022 39 54
12-Nov-2022 34 58
13-Nov-2022 31 73
Rain 14-Nov-2022 40 78
15-Nov-2022 34 66 Create a time range between the events labeled "Hail" and the events labeled "Snow".
EFstart = eventfilter("Hail"); EFend = eventfilter("Snow"); EFrange = timerange(EFstart,EFend,"closed")
EFrange = timetable timerange subscript:
Select timetable rows with event times in the closed interval:
Starting at, including: <Event Labels Variable> == "Hail"
Ending at, including: <Event Labels Variable> == "Snow"
See Select Times in Timetable.Call the containsrange function. It returns 1 because the range of the row times of weatherData contains the range specified by EFrange.
tf = containsrange(weatherData,EFrange)
Call the overlapsrange function. It returns 1 because the range of the row times of weatherData also overlaps the range specified by EFrange.
tf = overlapsrange(weatherData,EFrange)
Call the withinrange function. It returns 0 because weatherData has row times before the event labeled "Hail" and after the event labeled "Snow".
tf = withinrange(weatherData,EFrange)
Input Arguments
Event labels, specified as a scalar or vector. The scalar or vector can have any data type except for datetime, duration,calendarDuration, table, ortimetable.
Example: EF = eventfilter("lightning strike") creates an event filter for events that have "lightning strike" as a label.
Example: EF = eventfilter(["rain","sleet","snow"]) creates an event filter for events that have "rain", "sleet", or "snow" as a label.
Example: EF = eventfilter([1 4 5]) creates an event filter for events that have one of the specified numbers as a label.
Example: EF = eventfilter(wildcardPattern + "storm") creates an event filter for events whose labels are strings that end with"storm".
Example: EF = eventfilter(1) & eventfilter(2) creates an event filter for overlapping events. Use the event filter to select timetable rows in which events labeled 1 and events labeled 2 occur during the same times.
Input timetable. TT must have an event table attached to itsEvents property. In other words,TT.Properties.Events must contain an event table.
Version History
Introduced in R2023a