Create Timetables

Open Live Script

A timetable is a type of table that associates a time with each row. Like tables, timetables store column-oriented data variables that have the same number of rows. Timetables store their row times as vectors of datetime or duration values. In addition, timetables support time-specific functions to align, combine, and perform calculations with timestamped data in one or more timetables.

In MATLAB®, you can create timetables and assign data to them in several ways.

Create a timetable from a vector of row times and data arrays by using the timetable function.
Add variables to an existing timetable by using dot notation.
Assign variables to an empty timetable.
Preallocate a timetable and fill in its data later.
Convert variables to timetables by using the array2timetable, table2timetable, and timeseries2timetable functions.
Read a timetable from a file by using the readtimetable function.
Use the Import Tool to import your data as a table. Then convert it by using table2timetable.
For Simulink® users: Extract timetables from Simulink.SimulationData.Dataset objects by using the extractTimetable (Simulink) function.

The way you choose depends on the nature of your data and how you plan to use timetables in your code.

Create Timetables from Input Arrays

You can create a timetable from a vector of row times and data arrays by using the timetable function. For example, create a timetable that contains weather conditions at various times.

First, create a vector of row times. This vector can be a datetime or duration vector. Then create data arrays with temperature, pressure, precipitation, and storm duration readings.

MeasurementTime = datetime(["2023-12-18 08:03:05"; "2023-12-18 10:03:17"; "2023-12-18 12:03:13"]);
Temperature = [37.3; 39.1; 42.3];
Pressure = [29.4; 29.6; 30.0];
Precipitation = [0.1; 0.9; 0.0];
StormDuration = [hours(1); hours(2); NaN];

Now create a timetable as a container for the data. The timetable function uses the input argument variable names as the timetable variable names. Also, the first input argument provides the name of the vector of row times. The vector of row times is not a timetable variable. Rather, the row times are metadata that label the rows, just as the variable names are metadata that label the variables. So, the resulting timetable is a 3-by-4 timetable.

weather = timetable(MeasurementTime,Temperature,Pressure,Precipitation,StormDuration)

weather=3×4 timetable
      MeasurementTime       Temperature    Pressure    Precipitation    StormDuration
    ____________________    ___________    ________    _____________    _____________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr    
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr    
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr

You can also specify the vector of row times by using the RowTimes name-value argument. When you use this name-value argument, timetable uses Time as the name of the vector of row times.

weather = timetable(Temperature,Pressure,Precipitation,StormDuration,RowTimes=MeasurementTime)

weather=3×4 timetable
            Time            Temperature    Pressure    Precipitation    StormDuration
    ____________________    ___________    ________    _____________    _____________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr    
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr    
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr

Add Variable to Timetable Using Dot Notation

Once you have created a timetable, you can add a new variable at any time by using dot notation. Dot notation refers to timetable variables by name, such as T.varname, where T is the timetable and varname is the variable name.

For example, add an array of wind speeds to weather.

w = [15; 27; 22.8];
weather.WindSpeed = w

weather=3×5 timetable
            Time            Temperature    Pressure    Precipitation    StormDuration    WindSpeed
    ____________________    ___________    ________    _____________    _____________    _________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr            15   
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr            27   
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr          22.8

Add Variables to Empty Timetable

Another way to create a timetable is to start with an empty timetable of just row times and then add variables to it. For example, create another version of the timetable of weather conditions. But this time, add variables using dot notation.

First, create an empty timetable by calling timetable with only a vector of row times. The result is an empty timetable because it has no variables.

weather2 = timetable(MeasurementTime)

weather2 =

  3x0 empty timetable

      MeasurementTime   
    ____________________

    18-Dec-2023 08:03:05
    18-Dec-2023 10:03:17
    18-Dec-2023 12:03:13

(While you can call timetable with no arguments at all, the result is an empty timetable that also has no row times. The resulting 0-by-0 timetable is of little use because adding row times to it is less efficient than simply creating an empty timetable with a vector of row times.)

Add variables to the empty timetable by using dot notation. Timetable variable names do not have to match array names from the workspace, as shown by the assignment to the WindSpeed variable.

weather2.Temperature = Temperature;
weather2.Pressure = Pressure;
weather2.Precipitation = Precipitation;
weather2.StormDuration = StormDuration;
weather2.WindSpeed = w

weather2=3×5 timetable
      MeasurementTime       Temperature    Pressure    Precipitation    StormDuration    WindSpeed
    ____________________    ___________    ________    _____________    _____________    _________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr            15   
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr            27   
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr          22.8

Preallocate Timetable

If you know the sizes and data types of the data that you want to store in a timetable, but you plan to assign the data later, preallocating space in the timetable and then assigning values to empty rows can be more efficient.

For example, to preallocate space for a 4-by-3 timetable that contains time, temperature, and wind speed readings at different stations, use the timetable function. You must supply row times so that you can subscript into the timetable by row times. But instead of supplying input data arrays, specify the sizes and data types of the timetable variables. To give them names, specify the VariableNames name-value argument. Preallocation fills timetable variables with default values that are appropriate for their data types.

d = datetime(2023,6,1:4)';
sz = [4 3];
varTypes = ["double","double","string"];
varNames = ["Temperature","WindSpeed","Station"];
TT = timetable(Size=sz, ...
               VariableTypes=varTypes, ...
               RowTimes=d, ...
               VariableNames=varNames)

TT=4×3 timetable
       Time        Temperature    WindSpeed     Station 
    ___________    ___________    _________    _________

    01-Jun-2023         0             0        <missing>
    02-Jun-2023         0             0        <missing>
    03-Jun-2023         0             0        <missing>
    04-Jun-2023         0             0        <missing>

You can assign data to one row at a time. Specify the row of data values as a cell array.

TT(datetime("2023-06-01"),:) = {48.2,13.33,"S1"}

TT=4×3 timetable
       Time        Temperature    WindSpeed     Station 
    ___________    ___________    _________    _________

    01-Jun-2023       48.2          13.33      "S1"     
    02-Jun-2023          0              0      <missing>
    03-Jun-2023          0              0      <missing>
    04-Jun-2023          0              0      <missing>

Instead of supplying row times from a vector when you preallocate a timetable, you can specify a sample rate or time step for creating the necessary row times. By default, the row times of such a timetable start with 0 seconds. For example, preallocate a 3-by-2 timetable whose row times have a time step of 0.1 second by using the TimeStep name-value argument.

TT = timetable(Size=[3 2], ...
               VariableTypes=["double","double"], ...
               TimeStep=seconds(0.1))

TT=3×2 timetable
     Time      Var1    Var2
    _______    ____    ____

    0 sec       0       0  
    0.1 sec     0       0  
    0.2 sec     0       0

To preallocate a timetable whose first row has a row time that is not 0 seconds, specify the StartTime name-value argument. The value of StartTime can be a datetime or duration scalar. When you specify StartTime, you must also specify either SampleRate or TimeStep to set the sample rate or time step. For example, preallocate a timetable using a sample rate of 1000 Hz that starts at 15 seconds.

TT = timetable(Size=[3 3], ...
               VariableTypes=["uint64","double","double"], ...
               SampleRate=1000, ...
               StartTime=seconds(15))

TT=3×3 timetable
       Time       Var1    Var2    Var3
    __________    ____    ____    ____

    15 sec         0       0       0  
    15.001 sec     0       0       0  
    15.002 sec     0       0       0

Convert Variables to Timetables

Another way to create a timetable is by converting an array or a table.

For example, convert an array to a timetable by using the array2timetable function. Specify a start time and sample rate to add row times.

X = rand(5,3);
TT = array2timetable(X,StartTime=seconds(10),SampleRate=500)

TT=5×3 timetable
       Time         X1         X2         X3   
    __________    _______    _______    _______

    10 sec        0.81472    0.09754    0.15761
    10.002 sec    0.90579     0.2785    0.97059
    10.004 sec    0.12699    0.54688    0.95717
    10.006 sec    0.91338    0.95751    0.48538
    10.008 sec    0.63236    0.96489    0.80028

When you use array2timetable, you can specify a sample rate or a time step with or without a start time. Or you can specify a vector of row times.

Similarly, you can convert a table to a timetable by using the table2timetable function. For example, create a table and then add row times to it.

Reading1 = [98; 97.5; 97.9; 98.1; 97.9];
Reading2 = [120; 111; 119; 117; 116];
T = table(Reading1,Reading2)

T=5×2 table
    Reading1    Reading2
    ________    ________

        98        120   
      97.5        111   
      97.9        119   
      98.1        117   
      97.9        116

Time = seconds(1:1:5);
TT = table2timetable(T,RowTimes=Time)

TT=5×2 timetable
    Time     Reading1    Reading2
    _____    ________    ________

    1 sec        98        120   
    2 sec      97.5        111   
    3 sec      97.9        119   
    4 sec      98.1        117   
    5 sec      97.9        116

With table2timetable, you can specify a vector of row times, or you can specify a sample rate or a time step with or without a start time.

However, if a table already has dates and times, then you can call table2timetable without other arguments. The function converts the first datetime or duration variable in the table to a vector of row times in the output timetable.

For example, create a table with a datetime variable. Then convert it to a timetable. While T is a 3-by-4 table, TT is a 3-by-3 timetable because MeasurementTime becomes the vector of row times in TT.

T = table(Temperature,Pressure,MeasurementTime,StormDuration)

T=3×4 table
    Temperature    Pressure      MeasurementTime       StormDuration
    ___________    ________    ____________________    _____________

       37.3          29.4      18-Dec-2023 08:03:05         1 hr    
       39.1          29.6      18-Dec-2023 10:03:17         2 hr    
       42.3            30      18-Dec-2023 12:03:13       NaN hr

TT = table2timetable(T)

TT=3×3 timetable
      MeasurementTime       Temperature    Pressure    StormDuration
    ____________________    ___________    ________    _____________

    18-Dec-2023 08:03:05       37.3          29.4           1 hr    
    18-Dec-2023 10:03:17       39.1          29.6           2 hr    
    18-Dec-2023 12:03:13       42.3            30         NaN hr

Convert `timeseries` Array to Timetable

The timeseries data type is another data type for working with time series data in MATLAB. The timetable data type is the recommended data type for working with time series data. To convert a timeseries array to a timetable, use the timeseries2timetable function.

If the input is a timeseries object, then the output is a timetable with one variable.
If the input is an array of timeseries objects, then the output is a timetable with more than one variable.

For example, create an array of timeseries objects. Convert it 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");
ts = [ts1 ts2 ts3]

  1x3 timeseries array with properties:

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

TT = timeseries2timetable(ts)

TT=5×3 timetable
     Time     Series_1    Series_2    Series_3
    ______    ________    ________    ________

    0 sec     0.14189      0.65574    0.75774 
    10 sec    0.42176     0.035712    0.74313 
    20 sec    0.91574      0.84913    0.39223 
    30 sec    0.79221      0.93399    0.65548 
    40 sec    0.95949      0.67874    0.17119

Read Timetable from File

To read tabular data such as a CSV (comma-separated values) file or an Excel® spreadsheet into a timetable, use the readtimetable function.

For example, the sample file outages.csv contains data for a set of electrical power outages. The first line of outages.csv has column names. The rest of the file has comma-separated data values for each outage. The first few lines are shown here.

Region,OutageTime,Loss,Customers,RestorationTime,Cause
SouthWest,2002-02-01 12:18,458.9772218,1820159.482,2002-02-07 16:50,winter storm
SouthEast,2003-01-23 00:49,530.1399497,212035.3001,,winter storm
SouthEast,2003-02-07 21:15,289.4035493,142938.6282,2003-02-17 08:14,winter storm
West,2004-04-06 05:44,434.8053524,340371.0338,2004-04-06 06:10,equipment fault
MidWest,2002-03-16 06:18,186.4367788,212754.055,2002-03-18 23:23,severe storm
...

To import the data from outages.csv into a timetable, use readtimetable. It reads numeric values, dates and times, and strings into variables that have appropriate data types. Here, Loss and Customers are numeric arrays. The OutageTime and RestorationTime columns of the input file are imported as datetime arrays because readtimetable recognizes the date and time formats of the text in those columns. Note that OutageTime is the first column in the input file whose values contain dates and times, so readtimetable converts it to the vector of row times in the output timetable. The outages.csv file has six columns, but readtimetable converts it to a timetable that has a vector of row times and five variables.

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

outages=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"
      ⋮

Import Tool Usage

Finally, you can interactively preview and import data from spreadsheets, delimited text files, and fixed-width text files by using the Import Tool. However, while the Import Tool can import data as a table, it cannot import data directly as a timetable.

If you do use the Import Tool, follow these steps to create a timetable:

Preview your data and import it as a table.
Convert the imported table by using the table2timetable function.

Create Timetables

Create Timetables from Input Arrays

Add Variable to Timetable Using Dot Notation

Add Variables to Empty Timetable

Preallocate Timetable

Convert Variables to Timetables

Convert `timeseries` Array to Timetable

Read Timetable from File

Import Tool Usage

See Also

Functions

Apps

Related Topics

Create Timetables

Create Timetables from Input Arrays

Add Variable to Timetable Using Dot Notation

Add Variables to Empty Timetable

Preallocate Timetable

Convert Variables to Timetables

Convert timeseries Array to Timetable

Read Timetable from File

Import Tool Usage

See Also

Functions

Apps

Related Topics

Convert `timeseries` Array to Timetable