syncevents

Add and synchronize variables from attached event table to timetable

Since R2023a

Syntax

TT2 = syncevents(TT)

TT2 = syncevents(TT,defaultLabel)

TT2 = syncevents(___,EventDataVariables=vars)

Description

TT2 = syncevents(TT) adds the variables from the attached event table to the main timetable and synchronizes them. The new variables of the timetable have values from the corresponding variables of the event table in the timetable rows that occur during events. The new variables have missing values in the timetable rows without events.

• If the attached events table has an event labels variable, then syncevents adds the variable to the timetable. This new timetable variable also has missing values in the rows without events.

• If the attached events table has an event lengths or event end times variable, then syncevents does not add the variable to the timetable. These event table variables are indicated by the EventLengthsVariable and the EventEndsVariable properties of the attached event table.

• If the events have lengths or end times, then it is possible for events to overlap. If events overlap, then syncevents creates duplicate rows in the output timetable for those events. In that case, the output timetable is irregular even if the input timetable is regular.

TT2 = syncevents(TT,defaultLabel) specifies defaultLabel as the event label for timetable rows without events instead of using missing values.

TT2 = syncevents(___,EventDataVariables=vars) adds only the event table variables specified by vars as new variables in TT2.

Examples

Synchronize Events to Timetable

When a timetable has an attached event table, you can use the syncevents function to synchronize events from the event table to the timetable.

First, load a timetable and an event table from a sample MAT-file. Then display the timetable. It has data for weather conditions spanning two weeks.

load weatherEvents.mat
weatherData

weatherData=15×2 timetable
       Time        Temperature    Humidity
    ___________    ___________    ________

    01-Nov-2022        36            45   
    02-Nov-2022        31            76   
    03-Nov-2022        37            43   
    04-Nov-2022        36            46   
    05-Nov-2022        38            72   
    06-Nov-2022        32            54   
    07-Nov-2022        35            50   
    08-Nov-2022        34            45   
    09-Nov-2022        32            72   
    10-Nov-2022        30            58   
    11-Nov-2022        39            54   
    12-Nov-2022        34            58   
    13-Nov-2022        31            73   
    14-Nov-2022        40            78   
    15-Nov-2022        34            66   

Display the event table. It has event times, event labels, event lengths, and precipitation measurements for weather events that occurred during that two-week span. In this event table, the EventType variable contains the event labels.

weatherEvents

weatherEvents = 4x3 eventtable
  Event Labels Variable: EventType
  Event Lengths Variable: EventLength

       Time        EventType    EventLength    Precipitation (mm)
    ___________    _________    ___________    __________________

    03-Nov-2022      Hail         1.2 hr              12.7       
    05-Nov-2022      Rain          36 hr             114.3       
    10-Nov-2022      Snow          18 hr              25.4       
    14-Nov-2022      Rain          20 hr             177.8       

Attach the event table to the timetable.

weatherData.Properties.Events = weatherEvents

weatherData=15×2 timetable
               Time        Temperature    Humidity
            ___________    ___________    ________

            01-Nov-2022        36            45   
            02-Nov-2022        31            76   
    Hail    03-Nov-2022        37            43   
            04-Nov-2022        36            46   
    Rain    05-Nov-2022        38            72   
    Rain    06-Nov-2022        32            54   
            07-Nov-2022        35            50   
            08-Nov-2022        34            45   
            09-Nov-2022        32            72   
    Snow    10-Nov-2022        30            58   
            11-Nov-2022        39            54   
            12-Nov-2022        34            58   
            13-Nov-2022        31            73   
    Rain    14-Nov-2022        40            78   
            15-Nov-2022        34            66   

To synchronize the events from the attached event table to the timetable, use syncevents. The output timetable has a new variable with event labels in the rows whose row times match event times. The syncevents function inserts missing values in the new variables where the row times do not match any events. In this example, the missing values in EventType are <undefined> categorical values because EventType is a categorical variable. The missing values are NaNs in the precipitation data.

weatherData = syncevents(weatherData)

weatherData=15×4 timetable
               Time        Temperature    Humidity     EventType     Precipitation (mm)
            ___________    ___________    ________    ___________    __________________

            01-Nov-2022        36            45       <undefined>            NaN       
            02-Nov-2022        31            76       <undefined>            NaN       
    Hail    03-Nov-2022        37            43       Hail                  12.7       
            04-Nov-2022        36            46       <undefined>            NaN       
    Rain    05-Nov-2022        38            72       Rain                 114.3       
    Rain    06-Nov-2022        32            54       Rain                 114.3       
            07-Nov-2022        35            50       <undefined>            NaN       
            08-Nov-2022        34            45       <undefined>            NaN       
            09-Nov-2022        32            72       <undefined>            NaN       
    Snow    10-Nov-2022        30            58       Snow                  25.4       
            11-Nov-2022        39            54       <undefined>            NaN       
            12-Nov-2022        34            58       <undefined>            NaN       
            13-Nov-2022        31            73       <undefined>            NaN       
    Rain    14-Nov-2022        40            78       Rain                 177.8       
            15-Nov-2022        34            66       <undefined>            NaN       

Specify Label for Rows Without Events

When you synchronize events to a timetable, you can specify a label for the rows that do not correspond to any events. You can use the new label instead of missing values to mark such rows.

First, load a timetable and an event table from a sample MAT-file. Display the event table. It has labels for times when hail, rain, or snow occurred.

load weatherEvents.mat
weatherEvents

weatherEvents = 4x3 eventtable
  Event Labels Variable: EventType
  Event Lengths Variable: EventLength

       Time        EventType    EventLength    Precipitation (mm)
    ___________    _________    ___________    __________________

    03-Nov-2022      Hail         1.2 hr              12.7       
    05-Nov-2022      Rain          36 hr             114.3       
    10-Nov-2022      Snow          18 hr              25.4       
    14-Nov-2022      Rain          20 hr             177.8       

Attach the event table to the timetable.

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   

Synchronize the events to the timetable using syncevents. Specify "No Storm" as the label for the rows when no hail, rain, or snow occurred. Because EventType is a categorical variable, syncevents converts the string to a new category named No Storm.

weatherData = syncevents(weatherData,"No Storm")

weatherData=15×4 timetable
               Time        Temperature    Humidity    EventType    Precipitation (mm)
            ___________    ___________    ________    _________    __________________

            01-Nov-2022        36            45       No Storm             NaN       
            02-Nov-2022        31            76       No Storm             NaN       
    Hail    03-Nov-2022        37            43       Hail                12.7       
            04-Nov-2022        36            46       No Storm             NaN       
    Rain    05-Nov-2022        38            72       Rain               114.3       
    Rain    06-Nov-2022        32            54       Rain               114.3       
            07-Nov-2022        35            50       No Storm             NaN       
            08-Nov-2022        34            45       No Storm             NaN       
            09-Nov-2022        32            72       No Storm             NaN       
    Snow    10-Nov-2022        30            58       Snow                25.4       
            11-Nov-2022        39            54       No Storm             NaN       
            12-Nov-2022        34            58       No Storm             NaN       
            13-Nov-2022        31            73       No Storm             NaN       
    Rain    14-Nov-2022        40            78       Rain               177.8       
            15-Nov-2022        34            66       No Storm             NaN       

Copy Event Data Variables to Timetable

Event tables can have event data variables that contain additional data about events. When you synchronize events to a timetable, the syncevents function copies all additional event data variables to the output timetable. You can use the EventDataVariables name-value argument to choose which event data variables to copy. For instance, you can include event lengths or event end times in the output timetable, or exclude event labels or additional event data variables.

First, load a timetable and an event table from a sample MAT-file. Display the event table.

load weatherEvents.mat
weatherEvents

weatherEvents = 4x3 eventtable
  Event Labels Variable: EventType
  Event Lengths Variable: EventLength

       Time        EventType    EventLength    Precipitation (mm)
    ___________    _________    ___________    __________________

    03-Nov-2022      Hail         1.2 hr              12.7       
    05-Nov-2022      Rain          36 hr             114.3       
    10-Nov-2022      Snow          18 hr              25.4       
    14-Nov-2022      Rain          20 hr             177.8       

Attach the event table to the timetable.

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   

Synchronize the events to the timetable. By default, syncevents does not copy event lengths or event end times to the output timetable. In this example, specify the EventLength variable as an event data variable to copy. Specify Precipitation (mm) as another event data variable. The syncevents function inserts missing values in timetable rows that do not occur during events. The timetable displays event labels even though EventType is not copied to the timetable. The event labels are still in the attached event table, so they are still displayed next to the matching timetable rows.

weatherData = syncevents(weatherData,EventDataVariables=["EventLength","Precipitation (mm)"])

weatherData=15×4 timetable
               Time        Temperature    Humidity    EventLength    Precipitation (mm)
            ___________    ___________    ________    ___________    __________________

            01-Nov-2022        36            45         NaN hr               NaN       
            02-Nov-2022        31            76         NaN hr               NaN       
    Hail    03-Nov-2022        37            43         1.2 hr              12.7       
            04-Nov-2022        36            46         NaN hr               NaN       
    Rain    05-Nov-2022        38            72          36 hr             114.3       
    Rain    06-Nov-2022        32            54          36 hr             114.3       
            07-Nov-2022        35            50         NaN hr               NaN       
            08-Nov-2022        34            45         NaN hr               NaN       
            09-Nov-2022        32            72         NaN hr               NaN       
    Snow    10-Nov-2022        30            58          18 hr              25.4       
            11-Nov-2022        39            54         NaN hr               NaN       
            12-Nov-2022        34            58         NaN hr               NaN       
            13-Nov-2022        31            73         NaN hr               NaN       
    Rain    14-Nov-2022        40            78          20 hr             177.8       
            15-Nov-2022        34            66         NaN hr               NaN       

Input Arguments

TT — Input timetable

timetable

Input timetable. TT must have an event table attached to its Events property. In other words, TT.Properties.Events must contain an event table.

defaultLabel — Label for rows without events

scalar

Label for rows without events, specified as a scalar. The data type of defaultLabel must be compatible with the data type of the EventLabelsVariable of the event table that is attached to TT.

Example: TT = syncevents(TT,"N/A") adds event labels from the event table attached to TT and adds "N/A" as the label for rows of TT that do not correspond to events.

vars — Variables to copy from attached event table

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

Variables to copy from the attached event table, specified as a string array, character vector, pattern scalar, numeric array, or logical array.

Version History

Introduced in R2023a