eventtable - Event table - MATLAB (original) (raw)

Description

To find and label events in a timetable, attach an event table to it. An event table is a timetable of events. An event consists of an event time (when something happened), often an event length or event end time (how long it happened), often an event label (what happened), and sometimes additional information about the event. When you attach an event table to a timetable, it enables you to find and label rows in the timetable that occur during events.

You can treat the event times of an event table exactly the way you treat the row times of a timetable. Also, you can call timetable functions on event tables. However, event tables are designed to be attached to timetables. To attach an event table to a timetable, assign it to the Events property of the timetable.

Timetable with attached event table

Creation

To create an event table, you can extract a subset of the data contained in a timetable by using the extractevents function.

Alternatively, you can use the eventtable function described below. Create an event table from input vectors or from an input timetable. With an input timetable,eventtable returns the entire input timetable as an event table.

When you create an event table, you can specify that it has either_instantaneous_ events or interval events.

Instantaneous events happen at event times.
Interval events happen during intervals that start at event times and include all times up to, but not including, the times at the end of the events. In other words, event time intervals are always half-open intervals that are open on the right.

Syntax

Description

ET = eventtable([eventTimes](#mw%5F397194aa-5e4e-4694-90db-2a6c8cf59a22)) creates an event table from event times. The input is a datetime orduration vector whose values specify the event times of the event table. The output is an event table with event times and a variable that has default event labels.

example

ET = eventtable([TT](#mw%5Fca076d67-b9e9-4376-9358-845e1f8da9ef)) creates an event table from the input timetable. The row times of the timetable become the event times of the event table. The variables of the timetable become the variables of the event table.

example

ET = eventtable(___,[Name=Value](#namevaluepairarguments)) also specifies event labels, event lengths, or event end times using one or more name-value arguments in addition to the input arguments in previous syntaxes.

Event lengths and event end times are mutually exclusive. You can specify event lengths or event end times, but not both.

Input Arguments

expand all

Input event times, specified as a datetime orduration vector.

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: ET = eventtable(TT,EventLabelsVariable="Var1") creates an event table from an input timetable.

Example: ET = eventtable(eventTimes,EventLabels=cause) creates an event table from input arrays.

Input Time Vector or Timetable

expand all

Event labels, specified as a scalar or vector. The scalar or vector can have any data type except for datetime, duration,calendarDuration, table, ortimetable. If this argument is a vector, then it must have the same number of elements as the input time vector or timetable.

Example: ET = eventtable(eventTimes,EventLabels=cause) creates an event table from vector eventTimes and specifies vectorcause as the source of the event labels inET.

Lengths of time that events last, specified as a duration orcalendarDuration scalar or vector. If this argument is a vector, then it must have the same number of elements as the input time vector or timetable.

Events with lengths are interval events. An event with a length starts at an event time and includes all times up to, but not including, the time at the end of the event length.

If the event times of the event table are datetime values, then the event lengths can be either duration orcalendarDuration values.
If the event times of the event table are duration values, then the event lengths can be only duration values.

If you specify this name-value argument, then you cannot specify either theEventEnds or the EventEndsVariable arguments.

Example: ET = eventtable(eventTimes,EventLengths=eventDurations) creates an event table from vector eventTimes and specifies vectoreventDurations as the source of the event lengths inET.

Times at which events end, specified as a datetime orduration scalar or vector. If this argument is a vector, then it must have the same number of elements as the input time vector or timetable. Also, the data type of this argument must match the data type of the input time vector or the vector of row times of the input timetable. For example, if the input time vector is a datetime vector, then you must specifyEventEnds as a datetime vector.

Events with ends are interval events. An event with an end starts at an event time and includes all times up to, but not including, the time specified by the event end.

If you specify this name-value argument, then you cannot specify either theEventLengths or the EventLengthsVariable arguments.

Example: ET = eventtable(eventTimes,EventEnds=endTimes) creates an event table from vector eventTimes and specifies vector endTimes as the source of the end times of the events inET.

Input Timetable Only

expand all

Variable of TT that has event labels, specified as a string scalar, character vector, integer, logical array, or pattern scalar. The event labels can have any data type except fordatetime, duration,calendarDuration, table, ortimetable.

If you specify a logical array, then it must have onetrue value that specifies one variable ofTT.
If you specify a pattern scalar, then the name of the first variable of TT that it matches becomes the value ofEventLabelsVariable.

Example: ET = eventtable(TT,EventLabelsVariable="Var1") creates an event table from timetable TT and specifies the variable named Var1 in TT as the source of the event labels in ET.

Variable of TT that has event lengths, specified as a string scalar, character vector, integer, logical array, or pattern scalar.

If you specify a logical array, then it must have onetrue value that specifies one variable ofTT.
If you specify a pattern scalar, then the name of the first variable of TT that it matches becomes the value ofEventLengthsVariable.

Events with lengths are interval events. An event with a length starts at an event time and includes all times up to, but not including, the time at the end of the event length.

The event lengths must be duration orcalendarDuration values.

If the event times of the event table are datetime values, then the event lengths in the variable specified byEventLengthsVariable can be eitherduration or calendarDuration values.
If the event times of the event table are duration values, then the event lengths in the variable specified byEventLengthsVariable can be onlyduration values.

If you specify this name-value argument, then you cannot specify either theEventEnds or the EventEndsVariable argument.

Example: ET = eventtable(TT,EventLengthsVariable="EventDurations") creates an event table from timetable TT and specifies variableEventDurations in TT as the source of the event lengths in ET.

Variable that has event ends, specified as a string scalar, character vector, integer, logical array, or pattern scalar.

If you specify a logical array, then it must have onetrue value that specifies one variable ofTT.
If you specify a pattern scalar, then the name of the first variable of TT that it matches becomes the value ofEventEndsVariable.

Events with ends are interval events. An event with an end starts at an event time and includes all times up to, but not including, the time specified by the event end.

The event ends must be datetime orduration values. Also, the event ends and the event times must have the same data type. For example, if the input timetable has row times that aredatetime values, then you must specifyEventEndsVariable as a variable that is adatetime vector.

If you specify this name-value argument, then you cannot specify either theEventLengths or the EventLengthsVariable argument.

Example: ET = eventtable(TT,EventEndsVariable="EndTimes") creates an event table from timetable TT and specifies variableEndTimes in TT as the source of the end times of the events in ET.

Properties

expand all

An event table is a type of timetable. Therefore, it has Timetable Properties. However, an event table also has these properties of its own that name the event table variables that have event labels, the lengths of time that events last, or the end times of events.

Variable of the event table that has event labels, specified as a string scalar, character vector, integer, logical array, or pattern scalar. The event labels contained by the variable can have any data type except fordatetime, duration,calendarDuration, table, ortimetable.

If you specify this property as a logical array, then it must have onetrue value that specifies one variable.
If you specify this property as a pattern scalar, then the name of the first variable that it matches determines the event labels.

Example: ET.Properties.EventLabelsVariable="Cause" sets theEventLabelsVariable property of event table ET and specifies variable Cause in ET as the event labels.

Variable of the event table that has event lengths, specified as a string scalar, character vector, integer, logical array, or pattern scalar.

If you specify a logical array, then it must have one true value that specifies one variable.
If you specify a pattern scalar, then the name of the first variable that it matches becomes the value ofEventLengthsVariable.

Events with lengths are interval events. An event with a length starts at an event time and includes all times up to, but not including, the time at the end of the event length.

The event lengths contained by the variable must be duration orcalendarDuration values.

If the event times of the event table are datetime values, then the variable specified by this property can be either aduration or calendarDuration vector.
If the event times of the event table are duration values, then the variable specified by this property can be only aduration vector.

Example: ET.Properties.EventLengthsVariable="EventDurations" sets the EventLengthsVariable property of event tableET and specifies variable EventDurations inET as the event lengths.

Variable of the event table that has event ends, specified as a string scalar, character vector, integer, logical array, or pattern scalar.

If you specify this property as a logical array, then it must have onetrue value that specifies one variable.
If you specify this property as a pattern scalar, then the name of the first variable that it matches becomes the value ofEventEndsVariable.

Events with ends are interval events. An event with an end starts at an event time and includes all times up to, but not including, the time specified by the event end.

The event ends contained by the variable must be datetime orduration values. Also, the event ends and the event times must have the same data type. For example, if the event times are datetime values, then the variable specified by this property can be only adatetime vector.

Example: ET.Properties.EventEndsVariable="EndTimes" sets theEventEndsVariable property of event table ET and specifies variable EndTimes in ET as the source of the end times of the events.

Examples

collapse all

Create an event table using a vector of dates in November 2022 as the source of the event times. If you do not provide any other input arguments, eventtable provides default event labels.

Event tables have properties that identify which event table variables have event labels, event lengths, or event end times. If there are no event lengths or event end times, then the events are instantaneous.

Time = datetime(2022,11,[3 5 10 14]); ET = eventtable(Time)

ET = 4×1 eventtable Event Labels Variable: EventLabels Event Lengths Variable:

   Time        EventLabels
___________    ___________

03-Nov-2022     "Event 1" 
05-Nov-2022     "Event 2" 
10-Nov-2022     "Event 3" 
14-Nov-2022     "Event 4"

To specify event labels, event lengths, or event end times, use name-value arguments. For example, create an event table that also has event labels and lengths that you specify as vectors. If you specify the inputs as row vectors, eventtable reorients them as column vectors before adding them as event table variables.

labels = ["Hail","Rain","Snow","Rain"]; lengths = hours([1.2 36 18 20]); ET = eventtable(Time,EventLabels=labels,EventLengths=lengths)

ET = 4×2 eventtable Event Labels Variable: EventLabels Event Lengths Variable: EventLengths

   Time        EventLabels    EventLengths
___________    ___________    ____________

03-Nov-2022      "Hail"          1.2 hr   
05-Nov-2022      "Rain"           36 hr   
10-Nov-2022      "Snow"           18 hr   
14-Nov-2022      "Rain"           20 hr

First, create a timetable. To import a timetable from a comma-separated values (CSV) file, use the readtimetable function.

TT = readtimetable("outages.csv",TextType="string")

TT=1468×5 timetable OutageTime Region Loss Customers RestorationTime Cause
________________ ___________ ______ __________ ________________ _________________

2002-02-01 12:18    "SouthWest"    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"   
2003-01-23 00:49    "SouthEast"    530.14    2.1204e+05                 NaT    "winter storm"   
2003-02-07 21:15    "SouthEast"     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"   
2004-04-06 05:44    "West"         434.81    3.4037e+05    2004-04-06 06:10    "equipment fault"
2002-03-16 06:18    "MidWest"      186.44    2.1275e+05    2002-03-18 23:23    "severe storm"   
2003-06-18 02:49    "West"              0             0    2003-06-18 10:54    "attack"         
2004-06-20 14:39    "West"         231.29           NaN    2004-06-20 19:16    "equipment fault"
2002-06-06 19:28    "West"         311.86           NaN    2002-06-07 00:51    "equipment fault"
2003-07-16 16:23    "NorthEast"    239.93         49434    2003-07-17 01:12    "fire"           
2004-09-27 11:09    "MidWest"      286.72         66104    2004-09-27 16:37    "equipment fault"
2004-09-05 17:48    "SouthEast"    73.387         36073    2004-09-05 20:46    "equipment fault"
2004-05-21 21:45    "West"         159.99           NaN    2004-05-22 04:23    "equipment fault"
2002-09-01 18:22    "SouthEast"    95.917         36759    2002-09-01 19:12    "severe storm"   
2003-09-27 07:32    "SouthEast"       NaN    3.5517e+05    2003-10-04 07:02    "severe storm"   
2003-11-12 06:12    "West"         254.09    9.2429e+05    2003-11-17 02:04    "winter storm"   
2004-09-18 05:54    "NorthEast"         0             0                 NaT    "equipment fault"
  ⋮

To create an event table from a timetable, use the eventtable function. When you create an event table from a timetable, the event table and the timetable have the same size and the same variables. But when you create an event table with this eventtable syntax, it has no event labels, and the events are instantaneous.

ET = eventtable(TT); whos ET TT

Name Size Bytes Class Attributes

ET 1468x5 236604 eventtable
TT 1468x5 236601 timetable

Display the first five rows of the event table by using the head function.

ETdisplay = 5×5 eventtable Event Labels Variable: Event Lengths Variable:

   OutageTime         Region        Loss     Customers     RestorationTime           Cause      
________________    ___________    ______    __________    ________________    _________________

2002-02-01 12:18    "SouthWest"    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"   
2003-01-23 00:49    "SouthEast"    530.14    2.1204e+05                 NaT    "winter storm"   
2003-02-07 21:15    "SouthEast"     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"   
2004-04-06 05:44    "West"         434.81    3.4037e+05    2004-04-06 06:10    "equipment fault"
2002-03-16 06:18    "MidWest"      186.44    2.1275e+05    2002-03-18 23:23    "severe storm"

Event tables have the same properties as timetables. But they also have properties for the event table variables that can specify event labels, event lengths, and event end times. For example, to specify that the Cause variable of the event table has the event labels, assign the name of that variable to the EventLabelsVariable property. Display the first five rows of the event table.

ET.Properties.EventLabelsVariable = "Cause"; ETdisplay = head(ET,5)

ETdisplay = 5×5 eventtable Event Labels Variable: Cause Event Lengths Variable:

   OutageTime         Region        Loss     Customers     RestorationTime           Cause      
________________    ___________    ______    __________    ________________    _________________

2002-02-01 12:18    "SouthWest"    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"   
2003-01-23 00:49    "SouthEast"    530.14    2.1204e+05                 NaT    "winter storm"   
2003-02-07 21:15    "SouthEast"     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"   
2004-04-06 05:44    "West"         434.81    3.4037e+05    2004-04-06 06:10    "equipment fault"
2002-03-16 06:18    "MidWest"      186.44    2.1275e+05    2002-03-18 23:23    "severe storm"

You can also specify properties using name-value arguments when you use the eventtable function. For example, specify event labels and event end times using name-value arguments. Display the first five rows.

ET = eventtable(TT,EventLabelsVariable="Cause",EventEndsVariable="RestorationTime"); ETdisplay = head(ET,5)

ETdisplay = 5×5 eventtable Event Labels Variable: Cause Event Ends Variable: RestorationTime

   OutageTime         Region        Loss     Customers     RestorationTime           Cause      
________________    ___________    ______    __________    ________________    _________________

2002-02-01 12:18    "SouthWest"    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"   
2003-01-23 00:49    "SouthEast"    530.14    2.1204e+05                 NaT    "winter storm"   
2003-02-07 21:15    "SouthEast"     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"   
2004-04-06 05:44    "West"         434.81    3.4037e+05    2004-04-06 06:10    "equipment fault"
2002-03-16 06:18    "MidWest"      186.44    2.1275e+05    2002-03-18 23:23    "severe storm"

To attach an event table to a timetable, assign it to the Events property of the timetable. When a timetable has an attached event table, you can use the event table to display event labels or to filter timetable rows by events.

First, import a timetable from a sample MAT-file. Display the timetable, which has a list of weather conditions over a span of two weeks in November 2022.

load weatherEvents.mat weatherData 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

Next, attach an event table to the timetable. You can accomplish this task in two ways. The first way is to create a time vector and assign it to the Events property of the timetable. This action converts the time vector to an event table with default event labels. This event table becomes a property of the timetable. When you display the timetable, you can see the event labels that occur at the times listed in the event table.

Time = datetime(2022,11,[3 5 10 14]); weatherData.Properties.Events = Time

weatherData=15×2 timetable with 4 events Time Temperature Humidity ___________ ___________ ________

           01-Nov-2022        36            45   
           02-Nov-2022        31            76   
Event 1    03-Nov-2022        37            43   
           04-Nov-2022        36            46   
Event 2    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   
Event 3    10-Nov-2022        30            58   
           11-Nov-2022        39            54   
           12-Nov-2022        34            58   
           13-Nov-2022        31            73   
Event 4    14-Nov-2022        40            78   
           15-Nov-2022        34            66

Display the event table that was created and attached to the timetable.

ET = weatherData.Properties.Events

ET = 4×1 eventtable Event Labels Variable: EventLabels Event Lengths Variable:

   Time        EventLabels
___________    ___________

03-Nov-2022     "Event 1" 
05-Nov-2022     "Event 2" 
10-Nov-2022     "Event 3" 
14-Nov-2022     "Event 4"

The second way is to explicitly create an event table and assign it to the Events property. In this example, use eventtable to create an event table with event times, event labels, and event lengths that you specify. This event table has a list of storms that occurred in November 2022 and their durations.

Time = datetime(2022,11,[3 5 10 14]); labels = ["Hail","Rain","Snow","Rain"]; lengths = hours([1.2 36 18 20]); weatherEvents = eventtable(Time,EventLabels=labels,EventLengths=lengths)

weatherEvents = 4×2 eventtable Event Labels Variable: EventLabels Event Lengths Variable: EventLengths

   Time        EventLabels    EventLengths
___________    ___________    ____________

03-Nov-2022      "Hail"          1.2 hr   
05-Nov-2022      "Rain"           36 hr   
10-Nov-2022      "Snow"           18 hr   
14-Nov-2022      "Rain"           20 hr

Attach the event table to the timetable. The event table becomes a property of the timetable. When you display the timetable, you can also see the event labels. When an event has an event length that spans multiple rows in the timetable, the event label appears next to each row in the span. The first Rain event spans 36 hours, so that label appears next to the two rows in that time period.

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

After you attach an event table to a timetable, you can use the eventfilter and syncevents functions to operate on the timetable.

For example, create an event filter that matches rows of weatherData that occur during events. Then subscript into the timetable using the event filter as a row subscript.

EF = eventfilter(weatherData)

EF = eventfilter with no constraints and no selected variables

<unconstrained>

VariableNames: Time, EventLabels, EventLengths

ans=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

Version History

Introduced in R2023a

expand all

You can perform calculations directly on event tables without extracting their data. In R2023a, you cannot perform direct calculations on event tables, though you can perform direct calculations on tables and timetables.

For more information, see Rules for Table and Timetable Mathematics.