eventtable
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.
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.
Description
ET = eventtable(
creates an event
table from event times. The input is a eventTimes
)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.
ET = eventtable(
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.TT
)
ET = eventtable(___,
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.Name=Value
)
Event lengths and event end times are mutually exclusive. You can specify event lengths or event end times, but not both.
Input Arguments
eventTimes
— Input event times
datetime
or duration
vector
Input event times, specified as a datetime
or
duration
vector.
TT
— Input timetable
timetable
Input timetable.
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.
EventLabels
— Event labels
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
. 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
.
EventLengths
— Lengths of time that events last
duration
or calendarDuration
scalar or
vector
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 eitherduration
orcalendarDuration
values.If the event times of the event table are
duration
values, then the event lengths can be onlyduration
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
.
EventEnds
— Times at which events end
datetime
or duration
scalar or
vector
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
.
EventLabelsVariable
— Variable of TT
that has event labels
string scalar | character vector | integer | logical array | pattern
scalar
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 ofTT
.If you specify a
pattern
scalar, then the name of the first variable ofTT
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
.
EventLengthsVariable
— Variable of TT
that has event lengths
string scalar | character vector | integer | logical array | pattern
scalar
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 ofTT
.If you specify a
pattern
scalar, then the name of the first variable ofTT
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
or
calendarDuration
values.
If the event times of the event table are
datetime
values, then the event lengths in the variable specified byEventLengthsVariable
can be eitherduration
orcalendarDuration
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 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
.
EventEndsVariable
— Variable of TT
that has event ends
string scalar | character vector | integer | logical array | pattern
scalar
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 ofTT
.If you specify a
pattern
scalar, then the name of the first variable ofTT
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
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
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.
EventLabelsVariable
— Variable that has event labels
string scalar | character vector | integer | logical array | pattern
scalar
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.
EventLengthsVariable
— Variable that has event lengths
string scalar | character vector | integer | logical array | pattern
scalar
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
or
calendarDuration
values.
If the event times of the event table are
datetime
values, then the variable specified by this property can be either aduration
orcalendarDuration
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 table
ET
and specifies variable EventDurations
in
ET
as the event lengths.
EventEndsVariable
— Variable that has event ends
string scalar | character vector | integer | logical array | pattern
scalar
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 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
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
Create Event Table from Vectors
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
Create Event Table from Timetable
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"
Attach Event Table to Timetable
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 R2023aR2023b: Perform calculations directly on event tables without extracting their data
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.
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)