eventfilter
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(
creates an event
filter that matches any event whose event label is equal to one of the labels specified by
eventLabels
)eventLabels
.
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
and
withtol
, or with functions such as
containsrange
.
EF = eventfilter(
creates an event filter
from an event table that is attached to the input timetable TT
)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 Event Filter
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("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
weatherEvents = 4x3 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
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
Time Temperature Humidity
___________ ___________ ________
Rain 05-Nov-2022 38 72
Rain 06-Nov-2022 32 54
Rain 14-Nov-2022 40 78
Create Event Filter from Attached Event Table
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
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
weatherEvents = 4x3 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
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 Where Event Data Meets Condition
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
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 = 4x3 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 hr VariableNames: Time, EventType, EventLength, Precipitation (mm)
Select rows of weatherData
for rain events that lasted less than 24 hours.
weatherData(rainLessThan24,:)
ans=1×2 timetable
Time Temperature Humidity
___________ ___________ ________
Rain 14-Nov-2022 40 78
Select Rows Using Time Range or Tolerance
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
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"
Select rows of the timetable that occur between the events by using TR
as a row subscript.
betweenEvents = weatherData(TR,:)
betweenEvents=8×2 timetable
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
aroundEvents = weatherData(WT,:)
aroundEvents=7×2 timetable
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
Determine if Row Times Match Time Ranges
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
returns1
when 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
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"
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)
tf = logical
1
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)
tf = logical
1
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)
tf = logical
0
Input Arguments
eventLabels
— Labels for matching events
scalar | vector
Event labels, specified as a scalar or vector. The scalar or vector can have any
data type except for datetime
, duration
,
calendarDuration
, table
, or
timetable
.
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.
TT
— Input timetable
timetable
Input timetable. TT
must have an event table attached to its
Events
property. In other words,
TT.Properties.Events
must contain an event table.
Version History
Introduced in R2023a
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)