Main Content

eventtable

Event table

Since R2023a

expand all in page

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

ET = eventtable(eventTimes)
ET = eventtable(TT)
ET = eventtable(___,Name=Value)

Description

ET = eventtable(eventTimes) creates an event table from event times. The input is a datetime or duration 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) 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) 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 or duration vector.

Input timetable.

Name-Value Arguments

Specify optional pairs of arguments as Name1=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, or timetable. 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 vector cause as the source of the event labels in ET.

Lengths of time that events last, specified as a duration or calendarDuration 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 or calendarDuration 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 the EventEnds or the EventEndsVariable arguments.

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

Times at which events end, specified as a datetime or duration 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 specify EventEnds 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 the EventLengths 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 in ET.

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 for datetime, duration, calendarDuration, table, or timetable.

  • If you specify a logical array, then it must have one true value that specifies one variable of TT.

  • If you specify a pattern scalar, then the name of the first variable of TT that it matches becomes the value of EventLabelsVariable.

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 one true value that specifies one variable of TT.

  • If you specify a pattern scalar, then the name of the first variable of TT that it matches becomes the value of EventLengthsVariable.

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 or calendarDuration values.

  • If the event times of the event table are datetime values, then the event lengths in the variable specified by EventLengthsVariable can be either duration or calendarDuration values.

  • If the event times of the event table are duration values, then the event lengths in the variable specified by EventLengthsVariable can be only duration values.

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

Example: ET = eventtable(TT,EventLengthsVariable="EventDurations") creates an event table from timetable TT and specifies variable EventDurations 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 one true value that specifies one variable of TT.

  • If you specify a pattern scalar, then the name of the first variable of TT that it matches becomes the value of EventEndsVariable.

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 or duration 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 are datetime values, then you must specify EventEndsVariable as a variable that is a datetime vector.

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

Example: ET = eventtable(TT,EventEndsVariable="EndTimes") creates an event table from timetable TT and specifies variable EndTimes 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 for datetime, duration, calendarDuration, table, or timetable.

  • If you specify this property as a logical array, then it must have one true 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 the EventLabelsVariable 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 of EventLengthsVariable.

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 or calendarDuration values.

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

  • If the event times of the event table are duration values, then the variable specified by this property can be only a duration vector.

Example: ET.Properties.EventLengthsVariable="EventDurations" sets the EventLengthsVariable property of event table ET and specifies variable EventDurations in ET 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 one true 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 of EventEndsVariable.

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 or duration 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 a datetime vector.

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

Examples

collapse all

Open Live Script

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 = 4x1 eventtable
  Event Labels Variable: EventLabels
  Event Lengths Variable: <instantaneous>

       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 = 4x2 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
Open Live Script

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 = head(ET,5)
ETdisplay = 5x5 eventtable
  Event Labels Variable: <unset>
  Event Lengths Variable: <instantaneous>

       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 = 5x5 eventtable
  Event Labels Variable: Cause
  Event Lengths Variable: <instantaneous>

       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 = 5x5 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"
Open Live Script

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
                  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 = 4x1 eventtable
  Event Labels Variable: EventLabels
  Event Lengths Variable: <instantaneous>

       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 = 4x2 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
               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


weatherData(EF,:)
ans=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

Version History

Introduced in R2023a

expand all

See Also

| | |

Topics