Main Content

timeseries2timetable

Convert timeseries objects to timetable

Since R2021b

collapse all in page

Syntax

TT = timeseries2timetable(ts)
TT = timeseries2timetable(ts1,...,tsN)

Description

TT = timeseries2timetable(ts) converts timeseries objects to a timetable.

  • If ts is a timeseries object, then TT is a timetable with one variable.

  • If ts is an array of timeseries objects, then TT is a timetable with as many variables as there are timeseries objects in ts. All of the timeseries objects in ts must have the same sample times.

  • If any timeseries object has events, then the function converts the events to an event table and attaches the event table to TT. Duplicate events result in duplicate rows in the event table. (since R2024b)

example

TT = timeseries2timetable(ts1,...,tsN) converts the timeseries objects ts1,...,tsN to a timetable. The number of variables in TT matches the number of inputs. All of the timeseries objects ts1,...,tsN must have the same sample times.

example

Examples

collapse all

Open Live Script

Create a timeseries object that has five random numbers, sampled at 10-second intervals.

ts = timeseries(rand(5,1),[0 10 20 30 40])
  timeseries

  Common Properties:
            Name: 'unnamed'
            Time: [5x1 double]
        TimeInfo: tsdata.timemetadata
            Data: [5x1 double]
        DataInfo: tsdata.datametadata

Display the times and data in ts.

ts.Time
ans = 5×1

     0
    10
    20
    30
    40


ts.Data
ans = 5×1

    0.8147
    0.9058
    0.1270
    0.9134
    0.6324

Convert ts to a timetable.

TT = timeseries2timetable(ts)
TT=5×1 timetable
     Time      Data  
    ______    _______

    0 sec     0.81472
    10 sec    0.90579
    20 sec    0.12699
    30 sec    0.91338
    40 sec    0.63236
Open Live Script

Create an array of timeseries objects. Use the same vector of sample times, but give the time series different names. Create different arrays of data values by using the rand function.

ts1 = timeseries(rand(5,1),[0 10 20 30 40],"Name","Series_1");
ts2 = timeseries(rand(5,1),[0 10 20 30 40],"Name","Series_2");
ts3 = timeseries(rand(5,1),[0 10 20 30 40],"Name","Series_3");
ts = [ts1 ts2 ts3]
  1x3 timeseries array with properties:

    Events
    Name
    UserData
    Data
    DataInfo
    Time
    TimeInfo
    Quality
    QualityInfo
    IsTimeFirst
    TreatNaNasMissing
    Length

Combine the data from all the timeseries objects into one timetable. Each time series in the array contributes a variable to the timetable.

TT = timeseries2timetable(ts)
TT=5×3 timetable
     Time     Series_1    Series_2    Series_3
    ______    ________    ________    ________

    0 sec     0.81472     0.09754     0.15761 
    10 sec    0.90579      0.2785     0.97059 
    20 sec    0.12699     0.54688     0.95717 
    30 sec    0.91338     0.95751     0.48538 
    40 sec    0.63236     0.96489     0.80028
Open Live Script

Convert multiple timeseries objects to a timetable.

ts1 = timeseries(rand(5,1),[0 10 20 30 40],"Name","Series_1");
ts2 = timeseries(rand(5,1),[0 10 20 30 40],"Name","Series_2");
ts3 = timeseries(rand(5,1),[0 10 20 30 40],"Name","Series_3");
TT = timeseries2timetable(ts1,ts2,ts3)
TT=5×3 timetable
     Time     Series_1    Series_2    Series_3
    ______    ________    ________    ________

    0 sec     0.81472     0.09754     0.15761 
    10 sec    0.90579      0.2785     0.97059 
    20 sec    0.12699     0.54688     0.95717 
    30 sec    0.91338     0.95751     0.48538 
    40 sec    0.63236     0.96489     0.80028
Open Live Script

Load three timeseries objects that have vehicle traffic data for three city intersections.

load trafficCounts.mat count1 count2 count3

Display the properties of the first timeseries object. The properties store the traffic data, the times at which the data was collected, and two events. The events are tsdata.event objects.

count1
  timeseries

  Common Properties:
            Name: 'Intersection1'
            Time: [15x1 double]
        TimeInfo: tsdata.timemetadata
            Data: [15x1 double]
        DataInfo: tsdata.datametadata
          Events: [1x2 tsdata.event]

Display the first event attached to count1.

count1.Events(1)
    EventData: []
         Name: 'AMCommute'
         Time: 8
        Units: 'hours'
    StartDate: ''

Display the second event. The events label the times of the morning and evening commutes. 

count1.Events(2)
    EventData: []
         Name: 'PMCommute'
         Time: 18
        Units: 'hours'
    StartDate: ''

Plot the data from the three timeseries objects. To create a tiled chart layout for displaying the time series in subplots, use the tiledlayout function. The chart displays red dots to mark the events associated with the three time series.

tiledlayout(3,1)
nexttile
plot(count1)
nexttile
plot(count2)
nexttile
plot(count3)

Figure contains 3 axes objects. Axes object 1 with title Time Series Plot:Intersection1, xlabel Time (hours), ylabel Intersection1 contains 2 objects of type line. One or more of the lines displays its values using only markers Axes object 2 with title Time Series Plot:Intersection2, xlabel Time (hours), ylabel Intersection2 contains 2 objects of type line. One or more of the lines displays its values using only markers Axes object 3 with title Time Series Plot:Intersection3, xlabel Time (hours), ylabel Intersection3 contains 2 objects of type line. One or more of the lines displays its values using only markers

Convert the three timeseries objects to one timetable. Set the format of the row times to the hh:mm format. The events happen at the same times in the three time series, so the timetable has three event labels at both 08:00 and 18:00.

TT = timeseries2timetable(count1,count2,count3);
TT.Time.Format = "hh:mm"
TT=15×3 timetable
                  Time     Intersection1    Intersection2    Intersection3
                  _____    _____________    _____________    _____________

                  06:00          38               46               76     
                  07:00          61              132              186     
    <3 events>    08:00          75              135              180     
                  09:00          38               88              115     
                  10:00          28               36               55     
                  11:00          12               12               14     
                  12:00          18               27               30     
                  13:00          18               19               29     
                  14:00          17               15               18     
                  15:00          19               36               48     
                  16:00          32               47               10     
                  17:00          42               65               92     
    <3 events>    18:00          57               66              151     
                  19:00          44               55               90     
                  20:00         114              145              257

The conversion also converts the event objects to an event table. The event table is attached to the timetable. The event table shows that it has three identical events at two times.

TT.Properties.Events
ans = 6x1 eventtable
  Event Labels Variable: EventLabels
  Event Lengths Variable: <instantaneous>

    Time     EventLabels
    _____    ___________

    8 hr     "AMCommute"
    8 hr     "AMCommute"
    8 hr     "AMCommute"
    18 hr    "PMCommute"
    18 hr    "PMCommute"
    18 hr    "PMCommute"

You can clean an event table that has repeated events. One approach is to use the unique function.

ET = TT.Properties.Events;
ET = unique(ET)
ET = 2x1 eventtable
  Event Labels Variable: EventLabels
  Event Lengths Variable: <instantaneous>

    Time     EventLabels
    _____    ___________

    8 hr     "AMCommute"
    18 hr    "PMCommute"

Attach the cleaned event table to the timetable. Display the timetable.

TT.Properties.Events = ET
TT=15×3 timetable
                 Time     Intersection1    Intersection2    Intersection3
                 _____    _____________    _____________    _____________

                 06:00          38               46               76     
                 07:00          61              132              186     
    AMCommute    08:00          75              135              180     
                 09:00          38               88              115     
                 10:00          28               36               55     
                 11:00          12               12               14     
                 12:00          18               27               30     
                 13:00          18               19               29     
                 14:00          17               15               18     
                 15:00          19               36               48     
                 16:00          32               47               10     
                 17:00          42               65               92     
    PMCommute    18:00          57               66              151     
                 19:00          44               55               90     
                 20:00         114              145              257

Create a chart of the traffic data in the timetable. First create a new figure window so that you do not reuse subplots that were created by tiledlayout. Then, to plot data from the timetable, use stackedplot. The stackedplot function plots each timetable variable in a subplot and displays vertical black lines at the times that events occur.

figure
stackedplot(TT)

Figure contains an object of type stackedplot.

Input Arguments

collapse all

Input time series, specified as an array of timeseries objects.

This function uses some of the properties of ts to either assign data or set properties in the timetable. For each timeseries property, the table describes the result in the output timetable.

Input timeseries Property

Result in Output Timetable

Name

Specifies the name of the corresponding timetable variable.

If Name is 'unnamed' (the default value), then the corresponding variable name is 'Data' (or 'Data_1', 'Data_2', and so on, when multiple time series have 'unnamed' as their names).

Data

Specifies the data assigned to the corresponding timetable variable.

DataInfo.Units

Sets the VariableUnits property of the corresponding timetable variable.

DataInfo.Interpolation

Sets the VariableContinuity property of the corresponding timetable variable.

Time

Converts sample times to row times of the timetable. The vector of row times is either a duration or datetime vector, depending on the information in the Time and TimeInfo properties of the input.

TimeInfo.Units

Specifies units for row times. If the vector of timetable row times is a duration vector, then TimeInfo.Units also determines its format.

TimeInfo.Format

Sets the format for row times.

TimeInfo.StartDate

Sets the StartTime property of the timetable.

TimeInfo.Increment

Sets the TimeStep property of the timetable.

TimeInfo.Start

Calculates the offset from TimeInfo.StartDate to specify the StartTime property of the timetable.

IsTimeFirst

Determines if the data needs to be reoriented.

UserData

Specifies the data assigned to the UserData property of the timetable.

Events

Converts events to entries in an event table and attaches the event table to the timetable. (since R2024b)

Duplicate events from the input time series result in duplicate rows in the event table.

Quality

Warns.

QualityInfo

Warns if timeseries object has a Quality property.

Version History

Introduced in R2021b

expand all

See Also

| | | |

Topics