Create Timetables - MATLAB & Simulink (original) (raw)
Main Content
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
timetablefunction. - 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, andtimeseries2timetablefunctions. - Read a timetable from a file by using the
readtimetablefunction. - 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.Datasetobjects 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 =
3×0 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.80028When 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=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
timeseriesobject, then the output is a timetable with one variable. - If the input is an array of
timeseriesobjects, 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]
1×3 timeseries array with properties:
Events
Name
UserData
Data
DataInfo
Time
TimeInfo
Quality
QualityInfo
IsTimeFirst
TreatNaNasMissing
LengthTT = 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
table2timetablefunction.