# Create Timetables

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.

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=5×2 table
________    ________

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
_____    ________    ________

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

To read tabular data 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=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:

1. Preview your data and import it as a table.

2. Convert the imported table by using the table2timetable function.