Main Content

eventfilter

Create event filter for selecting timetable rows

Since R2023a

collapse all in page

Syntax

EF = eventfilter(eventLabels)
EF = eventfilter(TT)

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) creates an event filter that matches any event whose event label is equal to one of the labels specified by 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.

example

EF = eventfilter(TT) 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.

example

Examples

collapse all

Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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 1 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

collapse all

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.

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

See Also

| | | |

Topics