extractevents

Extract event table from subset of timetable data

Since R2023a

Syntax

ET = extractevents(TT,rows)

ET = extractevents(TT,labels)

ET = extractevents(___,Name=Value)

[ET,TT2] = extractevents(___)

Description

The extractevents function extracts data from a timetable to create an event table. An event table is a timetable of events. For more information on event tables, see eventtable.

When you attach an event table to a timetable, it enables you to find and label rows in the timetable that occur during events. To attach an event table to a timetable, assign it to the Events property of the timetable.

ET = extractevents(TT,rows) creates an event table using row times from the specified rows of the input timetable. The output event table has event times but no variables.

ET = extractevents(TT,labels) creates an event table using the row times from the input timetable and attaches event labels in labels. The labels input argument must be a categorical vector. The number of elements in labels must be the same as the number of rows of the input timetable. The category names in labels become event labels in a variable of the output event table.

If any row of labels has a missing value, then the corresponding row time of TT is not included in the output event table. In a categorical array, missing values are elements that belong to an undefined category. You can use missing values in labels to exclude rows of the input timetable from the output event table.

ET = extractevents(___,Name=Value) specifies event labels, event lengths, event end times, or data variables 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.

[ET,TT2] = extractevents(___) also returns a modified copy of the input timetable. The output timetable does not include input timetable variables that you specify as the variables containing event labels, event lengths, event end times, or event data, unless you also specify the PreserveEventVariables name-value argument as true.

Examples

Extract Event Table from Timetable

Import a timetable from a file. Then extract an event table using row times from the timetable rows that you specify. You can also specify additional information such as event labels.

To import a timetable from a comma-separated values (CSV) file, use the readtimetable function. The first column that has dates or times is the source of the row times of the timetable.

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

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

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

To create an event table from TT, use the extractevents function. You can specify rows of the timetable using row times, row numbers, logical values, or timerange or withtol subscripts.

Extract the first five rows of the input timetable as an event table. The output event table has five event times, which are equal to the row times of the first five rows of the timetable. The event table has no variables because this extractevents call specifies only rows.

ET = extractevents(TT,1:5)

ET =

  5x0 empty eventtable

  Event Labels Variable: <unset>
  Event Lengths Variable: <instantaneous>

         OutageTime     
    ____________________

    01-Feb-2002 12:18:00
    23-Jan-2003 00:49:00
    07-Feb-2003 21:15:00
    06-Apr-2004 05:44:00
    16-Mar-2002 06:18:00

Add event labels as a variable of the event table. Specify the source of event labels for the output event table as the Cause variable of the input timetable.

ET = extractevents(TT,1:5,EventLabelsVariable="Cause")

ET = 5x1 eventtable
  Event Labels Variable: Cause
  Event Lengths Variable: <instantaneous>

         OutageTime               Cause      
    ____________________    _________________

    01-Feb-2002 12:18:00    "winter storm"   
    23-Jan-2003 00:49:00    "winter storm"   
    07-Feb-2003 21:15:00    "winter storm"   
    06-Apr-2004 05:44:00    "equipment fault"
    16-Mar-2002 06:18:00    "severe storm"   

Extract Events Within Time Range

Create an event table from the rows of a timetable that are within a time range.

Import a timetable from a CSV file.

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

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

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

Create a time range that covers the first six months of the year 2002.

TR = timerange("2002-01-01","2002-06-30")

TR = 
	timetable timerange subscript:

		Select timetable rows with times in the half-open interval:
		[01-Jan-2002 00:00:00, 30-Jun-2002 00:00:00)

Extract an event table from the timetable rows that fall within the specified time range. Specify the source of the event labels as the Cause variable of the input timetable.

ET = extractevents(TT,TR,EventLabelsVariable="Cause")

ET = 12x1 eventtable
  Event Labels Variable: Cause
  Event Lengths Variable: <instantaneous>

         OutageTime               Cause       
    ____________________    __________________

    01-Feb-2002 12:18:00    "winter storm"    
    16-Mar-2002 06:18:00    "severe storm"    
    06-Jun-2002 19:28:00    "equipment fault" 
    26-Mar-2002 01:59:00    "winter storm"    
    20-Apr-2002 16:46:00    "unknown"         
    18-May-2002 11:04:00    "unknown"         
    20-May-2002 10:57:00    "unknown"         
    05-Mar-2002 17:53:00    "wind"            
    27-May-2002 09:44:00    "wind"            
    08-May-2002 20:34:00    "thunder storm"   
    02-Jun-2002 16:11:00    "energy emergency"
    17-Jun-2002 23:01:00    "thunder storm"   

Extract Events from Rows That Meet Condition

Extract an event table from rows of a timetable that meet a condition. When you extract the events, also specify event end times that make the events into interval events.

Import a timetable from a CSV file. The timetable lists a series of power outages. The data includes number of customers affected by the power outages as well as the times when the power outages begin and the times when power is restored.

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

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

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

Extract an event table from the timetable rows for power outages that affected more than 1,500,000 customers. Label the events as "High Customer Impact". Also include event end times in the event table by specifying their source as the RestorationTime variable of the input timetable.

ET = extractevents(TT,TT.Customers > 1.5e6, ...
                   EventLabels="High Customer Impact", ...
                   EventEndsVariable="RestorationTime")

ET = 14x2 eventtable
  Event Labels Variable: EventLabels
  Event Ends Variable: RestorationTime

         OutageTime           RestorationTime            EventLabels      
    ____________________    ____________________    ______________________

    01-Feb-2002 12:18:00    07-Feb-2002 16:50:00    "High Customer Impact"
    10-Dec-2002 10:45:00    11-Dec-2002 18:06:00    "High Customer Impact"
    20-May-2002 10:57:00    21-May-2002 15:22:00    "High Customer Impact"
    20-Sep-2004 12:37:00    02-Oct-2004 06:00:00    "High Customer Impact"
    15-Aug-2003 19:06:00    16-Aug-2003 05:13:00    "High Customer Impact"
    13-Sep-2004 11:51:00    15-Sep-2004 23:41:00    "High Customer Impact"
    21-Oct-2006 00:12:00    21-Oct-2006 12:38:00    "High Customer Impact"
    28-Dec-2006 14:04:00    04-Jan-2007 14:26:00    "High Customer Impact"
    16-Jul-2006 00:05:00    27-Jul-2006 14:42:00    "High Customer Impact"
    01-Jan-2006 11:54:00    11-Jan-2006 01:21:00    "High Customer Impact"
    07-Sep-2008 23:35:00    19-Sep-2008 17:19:00    "High Customer Impact"
    24-Jan-2010 18:47:00    30-Jan-2010 01:43:00    "High Customer Impact"
    17-May-2010 09:10:00    18-May-2010 22:43:00    "High Customer Impact"
    05-Jul-2010 21:07:00    09-Jul-2010 03:33:00    "High Customer Impact"

Attach the event table to the timetable. When you display the timetable, you can see event labels from the event table at the timetable rows whose row times match event times.

TT.Properties.Events = ET

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

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

Return Event Table and Modified Timetable

When you use extractevents to create an event table from a timetable, you can attach the event table to the original timetable. But you can also attach it to the modified copy of the timetable that is returned as the second output of extractevents. The modified copy of the timetable does not include the input timetable variables that were used as variables in the event table.

Import a timetable from a CSV file. Display the first five rows.

TT = readtimetable("outages.csv",TextType="string");
TTdisplay = head(TT,5)

TTdisplay=5×5 timetable
         OutageTime           Region        Loss     Customers       RestorationTime             Cause      
    ____________________    ___________    ______    __________    ____________________    _________________

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

Then extract an event table from the timetable. Extract the timetable rows where the cause of the outage does not contain the word "storm". Specify the timetable variables that have the event labels and the event end times. The output event table includes these two variables. The second output is a copy of TT that does not include the RestorationTime or Cause variables. You might not need to keep these variables in the output timetable because you have copies of them in the event table.

[ET,TTcopy] = extractevents(TT,~contains(TT.Cause,"storm"), ...
                            EventLabelsVariable="Cause", ...
                            EventEndsVariable="RestorationTime");
ETdisplay = head(ET,5)

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

         OutageTime           RestorationTime             Cause      
    ____________________    ____________________    _________________

    06-Apr-2004 05:44:00    06-Apr-2004 06:10:00    "equipment fault"
    18-Jun-2003 02:49:00    18-Jun-2003 10:54:00    "attack"         
    20-Jun-2004 14:39:00    20-Jun-2004 19:16:00    "equipment fault"
    06-Jun-2002 19:28:00    07-Jun-2002 00:51:00    "equipment fault"
    16-Jul-2003 16:23:00    17-Jul-2003 01:12:00    "fire"           

TTcopydisplay = head(TTcopy,5)

TTcopydisplay=5×3 timetable
         OutageTime           Region        Loss     Customers 
    ____________________    ___________    ______    __________

    01-Feb-2002 12:18:00    "SouthWest"    458.98    1.8202e+06
    23-Jan-2003 00:49:00    "SouthEast"    530.14    2.1204e+05
    07-Feb-2003 21:15:00    "SouthEast"     289.4    1.4294e+05
    06-Apr-2004 05:44:00    "West"         434.81    3.4037e+05
    16-Mar-2002 06:18:00    "MidWest"      186.44    2.1275e+05

To specify timetable variables that become event data variables in the output event table, specify the EventDataVariables name-value argument.

[ET,TTcopy] = extractevents(TT,~contains(TT.Cause,"storm") ,...
                            EventLabelsVariable="Cause", ...
                            EventEndsVariable="RestorationTime", ...
                            EventDataVariables="Region");
ETdisplay = head(ET,5)

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

         OutageTime           RestorationTime             Cause            Region   
    ____________________    ____________________    _________________    ___________

    06-Apr-2004 05:44:00    06-Apr-2004 06:10:00    "equipment fault"    "West"     
    18-Jun-2003 02:49:00    18-Jun-2003 10:54:00    "attack"             "West"     
    20-Jun-2004 14:39:00    20-Jun-2004 19:16:00    "equipment fault"    "West"     
    06-Jun-2002 19:28:00    07-Jun-2002 00:51:00    "equipment fault"    "West"     
    16-Jul-2003 16:23:00    17-Jul-2003 01:12:00    "fire"               "NorthEast"

TTcopydisplay = head(TTcopy,5)

TTcopydisplay=5×2 timetable
         OutageTime          Loss     Customers 
    ____________________    ______    __________

    01-Feb-2002 12:18:00    458.98    1.8202e+06
    23-Jan-2003 00:49:00    530.14    2.1204e+05
    07-Feb-2003 21:15:00     289.4    1.4294e+05
    06-Apr-2004 05:44:00    434.81    3.4037e+05
    16-Mar-2002 06:18:00    186.44    2.1275e+05

To attach the event table to the modified copy of the timetable, assign it to the Events property of the timetable.

TTcopy.Properties.Events = ET;
TTcopydisplay = head(TTcopy,5)

TTcopydisplay=5×2 timetable
                            OutageTime          Loss     Customers 
                       ____________________    ______    __________

                       01-Feb-2002 12:18:00    458.98    1.8202e+06
                       23-Jan-2003 00:49:00    530.14    2.1204e+05
                       07-Feb-2003 21:15:00     289.4    1.4294e+05
    equipment fault    06-Apr-2004 05:44:00    434.81    3.4037e+05
                       16-Mar-2002 06:18:00    186.44    2.1275e+05

Input Arguments

TT — Input timetable

timetable

Input timetable.

rows — Rows of input timetable

datetime vector | duration vector | numeric vector | logical vector | timerange subscript | withtol subscript

Rows of the input timetable, specified as a datetime, duration, numeric, or logical vector, or as a timerange or withtol subscript.

labels — Event labels

categorical vector

Event labels, specified as a categorical vector. The number of elements in the labels input argument must be the same as the number of rows of the input timetable. The category names in labels become event labels in a variable of the output event table. The event table has a row for every row time in the input timetable, except for any row where labels has a missing value.

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 = extractevents(TT,TT.Var1 > 10,EventLabels="High") extracts timetable rows where TT.Var1 is greater than 10 and returns them as an event table with High event labels.

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 rows input argument.

Example: ET = extractevents(TT,rows,EventLabels=cause) creates an event table from timetable TT and specifies vector cause as the source of the event labels in ET.

EventLabelsVariable — Variable of input timetable that has event labels

string scalar | character vector | integer | logical array | pattern scalar

Variable of the input timetable 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 the input timetable.

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

Example: ET = extractevents(TT,rows,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.

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 rows input argument.

• If the row times of the input timetable are datetime values, then the event lengths can be either duration or calendarDuration values.

• If the row times of the input timetable 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 = extractevents(TT,rows,EventLengths=eventDurations) creates an event table from timetable TT and specifies vector eventDurations as the source of the event lengths in ET.

EventLengthsVariable — Variable of input timetable that has event lengths

string scalar | character vector | integer | logical array | pattern scalar

Variable of the input timetable 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 the input timetable.

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

The event lengths must be duration or calendarDuration values.

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

• If the row times of the input timetable 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 = extractevents(TT,rows,EventLengthsVariable="EventDurations") creates an event table from timetable TT and specifies the variable named "EventDurations" in TT 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 rows input argument. Also, the data type of this argument must match the data type of the vector of row times of the input timetable. For example, if the timetable row times are datetime values, then you must specify EventEnds as a datetime vector.

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

Example: ET = extractevents(TT,rows,EventEnds=endTimes) creates an event table from timetable TT and specifies vector endTimes as the source of the end times of the events in ET.

EventEndsVariable — Variable of input timetable that has event ends

string scalar | character vector | integer | logical array | pattern scalar

Variable of the input timetable 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 the input timetable.

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

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 = extractevents(TT,rows,EventEndsVariable="EndTimes") creates an event table from timetable TT and specifies the variable named "EndTimes" in TT as the source of the end times of the events in ET.

EventDataVariables — Variables of input timetable that become variables of output event table

string array | character vector | integer array | logical array | pattern scalar

Variables of the input timetable that become variables of the output event table, specified as a string array, character vector, integer array, logical array, or pattern scalar. These variables do not label events or specify their ends or durations. They are data variables that extractevents copies to the output event table.

• If you specify a logical array, then it must have a true value for every variable that is copied to the event table.

• If you specify a pattern scalar, then EventDataVariables is an array of the timetable variable names that match the pattern.

Example: ET = extractevents(TT,rows,EventDataVariables=["Var1","Var2","Var3"]) creates an event table from timetable TT and specifies that the variables named "Var1", "Var2", and "Var3" in TT become variables in the output event table ET.

PreserveEventVariables — Preserve data variables in second output

false or 0 (default) | true or 1

Preserve data variables in the second output, specified as a numeric or logical 1 (true) or 0 (false).

Example: [ET,TT2] = extractevents(TT,rows,EventDataVariables=["Var1","Var2","Var3"],PreserveEventVariables=true) specifies that the variables named "Var1", "Var2", and "Var3" are data variables in ET and are preserved in TT2.

Output Arguments

ET — Event table

event table

Event table.

TT2 — Modified copy of input timetable

timetable

Modified copy of the input timetable, returned as a timetable.

The copy does not include input timetable variables that you specify using the EventDataVariables name-value argument, unless you also specify the PreserveEventVariables argument as true.

Version History

Introduced in R2023a