timetable
Tables for time series data, with timestamped rows and variables of different types
Description
timetable
is a type of table that associates a time with
each row for use with time series data. Like tables, timetables store column-oriented
data variables that can have different data types and sizes as long as they have the
same number of rows. In addition, there are time-specific functions to align, combine,
and perform calculations with timestamped data in one or more timetables, such as the
retime
and synchronize
functions.
The row times of a timetable are datetime
or
duration
values that label the rows. You can index into a
timetable by row time and variable. For more information on indexing, see Select Times in Timetable
and Access Data in Tables.
To find and label events in a timetable, attach
an event table to it. Event tables list the times at which events occur, along with
event labels and other information about events. For more information, see eventtable
. (since R2023a)
Creation
To create a timetable, you can read data from a file into a table using the readtimetable
function, or you can convert variables having other data
types.
To convert:
An array, use the
array2timetable
function.A table, use the
table2timetable
function.A
timeseries
object, use thetimeseries2timetable
function.
Simulink® users can extract data from a
Simulink.SimulationData.Dataset
object by using the extractTimetable
(Simulink) function.
Alternatively, you can use the timetable
function described
below. Create a timetable from input arrays or preallocate space for variables whose
values are filled in later. To specify the row times, you can either use an input vector
of row times or create the row times by using a sample rate or time step.
Syntax
Description
Combine Existing Variables
TT = timetable(
creates a timetable from the input data variables
rowTimes
,var1,...,varN
)var1,...,varN
and the time vector
rowTimes
. The data variables can have different sizes
and data types as long as they have the same number of rows.
rowTimes
must be a datetime
or
duration
vector, also with the same number of
rows.
TT = timetable(
specifies var1,...,varN
,'RowTimes',rowTimes
)rowTimes
as the source of the row times of
TT
. When you use this syntax, the name of the row
times vector of TT
is always Time
,
even when rowTimes
is a workspace variable with a
different name.
TT = timetable(
uses the sample rate var1,...,varN
,'SampleRate',Fs
)Fs
to calculate regularly spaced row
times. Fs
is a numeric scalar that specifies the number
of samples per second (Hz). The first row time is zero seconds.
TT = timetable(
uses the time step var1,...,varN
,'TimeStep',dt
)dt
to calculate regularly spaced row
times. dt
is a duration
or
calendarDuration
value that specifies the length of
time between consecutive row times. The first row time is zero
seconds.
Preallocate Space
TT = timetable('Size',
creates a timetable and preallocates space for the variables that have data
types you specify. sz
,'VariableTypes',varTypes
,'RowTimes',rowTimes
)sz
is a two-element numeric array,
where sz(1)
specifies the number of rows and
sz(2)
specifies the number of variables.
varTypes
specifies the data types of the variables.
The number of times in rowTimes
must equal
sz(1)
.
Set Names or Start Time
TT = timetable(___,
specifies additional input arguments using one or more name-value pair
arguments. For example, you can specify variable names using the
Name,Value
)'VariableNames'
name-value pair. You also can specify
a start time using the 'StartTime'
name-value pair with a
sample rate or time step. You can use this syntax with any of the input
arguments of the previous syntaxes.
Input Arguments
var1,...,varN
— Input variables
arrays
Input variables, specified as arrays with the same number of rows. The input variables can have different sizes and different data types, as long as they have the same number of rows.
Common input variables are numeric arrays, logical arrays, string arrays, structure arrays, and cell arrays.
Input variables also can be objects that are arrays. Such an array
must support indexing of the form
var(index1,...,indexN)
, where
index1
is a numeric or logical vector that
corresponds to rows of the variable var
. In addition,
the array must implement both a vertcat
method and a
size
method with a dim
argument.
rowTimes
— Times associated with rows of timetable
datetime
vector | duration
vector
Times associated with rows of a timetable, specified as a
datetime
vector or duration
vector. Each time labels a row in the output timetable,
TT
. The time values in
rowTimes
do not need to be unique, sorted, or
regular.
sz
— Size of preallocated timetable
two-element numeric vector
Size of the preallocated timetable, specified as a two-element numeric
vector. The first element of sz
specifies the number
of rows, and the second element specifies the number of timetable
variables.
varTypes
— Data types of preallocated variables
cell array of character vectors | string array
Data types of the preallocated variables, specified as a cell array of character vectors or a
string array. The number of types specified by varTypes
must equal
the number of variables specified by the second element of sz
.
varTypes
can contain the names of any data types, including the names shown in the table.
Data Type Name | Initial Value in Each Element |
---|---|
| Double- or single-precision |
| Double- or single-precision
|
| Signed 8-, 16-, 32-, or 64-bit integer |
| Unsigned 8-, 16-, 32-, or 64-bit integer |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Scalar structure with no fields |
| Table with no variables |
| Timetable with no variables and |
For any other data type, the initial value is the value used by that type or class to "in-fill" unassigned elements of an array.
If you specify 'char'
as a data type, then timetable
preallocates the corresponding variable as a cell array of character vectors, not as a character array. Best practice is to avoid creating table or timetable variables that are character arrays. When working with text data in a table or a timetable, consider using a string array or a categorical array.
Fs
— Sample rate
numeric scalar
Sample rate, specified as a numeric scalar. Fs
specifies the number of samples per second (Hz).
dt
— Time step
duration
scalar | calendarDuration
scalar
Time step, specified as a duration
scalar or
calendarDuration
scalar.
If you specify dt
as a
calendarDuration
value, and you specify the
'StartTime'
name-value pair argument, then the
value of 'StartTime'
must be a
datetime
scalar.
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example:
TT =
timetable(rowTimes,T,W,'VariableNames',{'Temperature','WindSpeed'})
creates a timetable from input arrays T
and
W
, and names the corresponding timetable variables
Temperature
and
WindSpeed
.
VariableNames
— Variable names
cell array of character vectors | string array
Variable names, specified as a cell array of character vectors or a string array whose elements are nonempty and distinct.
The number of names in the array must equal the number of timetable variables.
The
timetable
function also stores the variable names in theVariableNames
property of the timetable.Variable names can have any Unicode® characters, including spaces and non-ASCII characters.
DimensionNames
— Dimension names
two-element cell array of character vectors | two-element string array
Since R2021a
Dimension names, specified as a two-element cell array of character vectors or two-element string array whose elements are nonempty and distinct.
The
timetable
function also stores the dimension names in theDimensionNames
property of the timetable.Dimension names can have any Unicode characters, including spaces and non-ASCII characters.
Before R2021a, you can specify dimension names only by setting the
DimensionNames
property.
StartTime
— Start time
datetime
scalar |
duration
scalar
Start time, specified as a datetime
scalar or
duration
scalar. The start time is also the
row time of the first row of the timetable.
You can specify 'StartTime'
only when you also
specify the 'SampleRate'
or
'TimeStep'
name-value pair argument.
If the start time is a
datetime
value, then the row times ofTT
aredatetime
values.If the start time is a
duration
value, then the row times are durations.If the time step
dt
is acalendarDuration
value, then the start time must be adatetime
value.
Properties
Access Timetable Metadata Properties
A timetable contains metadata properties that describe the timetable, its row times,
and its variables. Access these properties using the syntax
,
where timetableName
.Properties.PropertyName
is the name of a
property. For example, you can access the names of the variables in the timetable
PropertyName
TT
through the TT.Properties.VariableNames
property.
You can return a summary of the metadata properties using the syntax
.timetableName
.Properties
Timetables provide metadata access through the Properties
property
because you can access timetable data directly using dot syntax. For example, if
timetable TT
has a variable named Var1
, then you
can access the values in the variable by using the syntax
TT.Var1
.
Timetable Metadata
DimensionNames
— Dimension names
{'Time','Variables'}
(default) | two-element cell array of character vectors | two-element string array
Dimension names, specified as a two-element cell array of character vectors or two-element string array, whose elements are nonempty and distinct.
Dimension names can have any Unicode characters, including spaces and non-ASCII characters.
If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.
You can access timetable data using the two dimension names.
If you use dot syntax and the first dimension name, then you can access the row times as a vector.
If you use dot syntax and the second dimension name, then the data from all the variables are concatenated together in one array, as though you had indexed into the timetable using
{:,:}
syntax.
Example
Create a timetable and display its dimension names. You can access row times and data using dimension names with dot syntax.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]); TT.Properties.DimensionNames
ans = 1x2 cell
{'Time'} {'Variables'}
Access the row times using the first dimension name.
TT.Time
ans = 3x1 datetime
18-Dec-2015
19-Dec-2015
20-Dec-2015
Access the data using the second dimension name. This syntax is equivalent to TT{:,:,}
.
TT.Variables
ans = 3×3
37.3000 30.1000 13.4000
39.1000 30.0300 6.5000
42.3000 29.9000 7.3000
Modify the names of its dimensions using the Properties.DimensionNames
property. Having changed the dimension names, you can access the row times and data using the syntaxes TT.Date
and TT.WeatherData
respectively.
TT.Properties.DimensionNames = {'Date','WeatherData'}; TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Date' 'WeatherData'} VariableNames: {'Var1' 'Var2' 'Var3'} VariableTypes: ["double" "double" "double"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3x1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: 1d Events: [] CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Description
— Timetable description
''
(default) | character vector | string scalar
Timetable description, specified as a character vector or string
scalar. This description is visible when using the
summary
function.
If you specify this property using a string scalar, then it is converted and stored as a character vector.
Example
Create a timetable. Modify the variable names and the description of the timetable. Display a summary of the result.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]); TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'}; TT.Properties.Description = 'Weather Data from December 2015'; summary(TT)
TT: 3x3 timetable Description: Weather Data from December 2015 Row Times: Time: datetime Variables: Temp: double Pressure: double WindSpeed: double Statistics for applicable variables and row times: NumMissing Min Median Max Mean Std Time 0 18-Dec-2015 19-Dec-2015 20-Dec-2015 19-Dec-2015 24:00:00 Temp 0 37.3000 39.1000 42.3000 39.5667 2.5325 Pressure 0 29.9000 30.0300 30.1000 30.0100 0.1015 WindSpeed 0 6.5000 7.3000 13.4000 9.0667 3.7740
UserData
— Additional timetable information
[]
(default) | array
Additional timetable information, specified as an array. You can attach data of any kind to a timetable using this property.
Example
Create a timetable. Modify the variable names. Attach an anonymous function as a piece of user data that is associated with the timetable.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]); TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'}; Fahrenheit2Celsius = @(x) (5.0/9.0).*(x - 32); TT.Properties.UserData = Fahrenheit2Celsius; TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: @(x)(5.0/9.0).*(x-32) DimensionNames: {'Time' 'Variables'} VariableNames: {'Temp' 'Pressure' 'WindSpeed'} VariableTypes: ["double" "double" "double"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3x1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: 1d Events: [] CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Row Times Metadata
RowTimes
— Row times
datetime
vector | duration
vector
Row times, specified as a datetime
vector or
duration
vector.
There must be a row time for every row of a timetable.
A timetable can have row times that are duplicates, out of order, or
NaT
orNaN
values.The row times are visible when you view the timetable. Furthermore, you can use the row times within parentheses or curly braces to access the timetable data.
Another way to access the row times is to use dot syntax and the name of the first dimension of the timetable.
Example
Create a timetable. Then replace its row times using the Properties.RowTimes
property.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3])
TT=3×3 timetable
Time Var1 Var2 Var3
___________ ____ _____ ____
18-Dec-2015 37.3 30.1 13.4
19-Dec-2015 39.1 30.03 6.5
20-Dec-2015 42.3 29.9 7.3
Dates = datetime(2017,1,1:3); TT.Properties.RowTimes = Dates
TT=3×3 timetable
Time Var1 Var2 Var3
___________ ____ _____ ____
01-Jan-2017 37.3 30.1 13.4
02-Jan-2017 39.1 30.03 6.5
03-Jan-2017 42.3 29.9 7.3
Another way to access the row times is by using dot syntax with the name of the first dimension of the timetable.
TT.Properties.DimensionNames
ans = 1x2 cell
{'Time'} {'Variables'}
TT.Time
ans = 3x1 datetime
01-Jan-2017
02-Jan-2017
03-Jan-2017
StartTime
— Start time of row times
datetime
scalar | duration
scalar
Start time of the row times, specified as a
datetime
scalar or duration
scalar. The start time is equal to the row time for the first row of the
timetable, and has the same data type.
If the start time is a
datetime
value, then the row times ofTT
aredatetime
values.If the start time is a
duration
value, then the row times are durations.If the time step is a
calendarDuration
value, then the start time must be adatetime
value.
If the timetable is empty, then the start time is
NaN
.
Example
Create a timetable. In this timetable, the time step between consecutive rows is not the same, so the timetable is irregular.
TT = timetable(datetime({'2015-12-18';'2015-12-20';'2015-12-21'}), ... [37.3;39.1;42.3],[13.4;6.5;7.3],{'N';'SE';'NW'}); TT.Properties.VariableNames = {'Temperature','WindSpeed','WindDirection'}
TT=3×3 timetable
Time Temperature WindSpeed WindDirection
___________ ___________ _________ _____________
18-Dec-2015 37.3 13.4 {'N' }
20-Dec-2015 39.1 6.5 {'SE'}
21-Dec-2015 42.3 7.3 {'NW'}
Display its properties. The value of the StartTime
property is equal to the first row time. Whether a timetable is regular or irregular, it always has a start time, unless it is empty.
TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Time' 'Variables'} VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'} VariableTypes: ["double" "double" "cell"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3x1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN Events: [] CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Modify the StartTime
property. Note that all the row times have new values. For each row time, the change in value is equal to the difference between the original value of the first row time and the new start time.
TT.Properties.StartTime = datetime('2018-04-09')
TT=3×3 timetable
Time Temperature WindSpeed WindDirection
___________ ___________ _________ _____________
09-Apr-2018 37.3 13.4 {'N' }
11-Apr-2018 39.1 6.5 {'SE'}
12-Apr-2018 42.3 7.3 {'NW'}
SampleRate
— Sample rate
numeric scalar
Sample rate, specified as a numeric scalar. The sample rate is the number of samples per second (Hz).
If the row times are not regular, or the timetable is empty, then the
sample rate is NaN
.
Example
Create a regular timetable. In this timetable, the row times are durations, created using the same sample rate.
Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'SampleRate',100)
TT=5×1 timetable
Time Intensity
________ _________
0 sec 100
0.01 sec 98.7
0.02 sec 95.2
0.03 sec 101.4
0.04 sec 99.1
Display its properties. The SampleRate
property stores the sample rate in Hz.
TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Time' 'Variables'} VariableNames: {'Intensity'} VariableTypes: "double" VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [5x1 duration] StartTime: 0 sec SampleRate: 100 TimeStep: 0.01 sec Events: [] CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Modify the SampleRate
property. The start time is the same, but all the other row times are different because the sample rate is smaller. However, the variable Intensity
remains the same.
TT.Properties.SampleRate = 25
TT=5×1 timetable
Time Intensity
________ _________
0 sec 100
0.04 sec 98.7
0.08 sec 95.2
0.12 sec 101.4
0.16 sec 99.1
TimeStep
— Time step
duration
scalar | calendarDuration
scalar
Time step, specified as a duration
scalar or
calendarDuration
scalar.
If you specify the time step as a
calendarDuration
value (for example, calendar months), then the vector of row times must be adatetime
vector.If you specify the time step as a
duration
value (for example, seconds), then the vector of row times either can be adatetime
orduration
vector.
If the row times are not regular, or the timetable is empty, then the
time step is NaN
.
Example
Create a regular timetable. In this timetable, the row times are durations, created using the same time step.
Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.01))
TT=5×1 timetable
Time Intensity
________ _________
0 sec 100
0.01 sec 98.7
0.02 sec 95.2
0.03 sec 101.4
0.04 sec 99.1
Display its properties. The TimeStep
property stores the time step as a duration.
TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Time' 'Variables'} VariableNames: {'Intensity'} VariableTypes: "double" VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [5x1 duration] StartTime: 0 sec SampleRate: 100 TimeStep: 0.01 sec Events: [] CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Modify the TimeStep
property. The start time is the same, but all the other row times are different because the time step is larger. However, the variable Intensity
remains the same.
TT.Properties.TimeStep = seconds(0.04)
TT=5×1 timetable
Time Intensity
________ _________
0 sec 100
0.04 sec 98.7
0.08 sec 95.2
0.12 sec 101.4
0.16 sec 99.1
Events
— Events
event table | datetime
vector | duration
vector
Since R2023a
Events, specified as an event table, a datetime
vector, or a duration
vector. Event tables list the
times at which events occur, labels that describe the events, and
sometimes other information about the events. To find and label
timetable rows that occur during events, attach events to the timetable
by assignment to the Events
property.
If you assign a datetime
or
duration
vector, then the assignment converts the
vector to an event table with default labels and assigns that event
table to the Events
property.
The row times of the timetable and the event times associated with
events must have the same data type. For example, you cannot attach a
duration
vector, or an event table whose event
times are duration
values, to a timetable whose row
times are datetime
values.
For more information about event tables, see eventtable
.
Variable Metadata
VariableNames
— Variable names
cell array of character vectors | string array
Variable names, specified as a cell array of character vectors or a string array, whose elements are nonempty and distinct. The number of names must equal the number of variables.
Variable names can have any Unicode characters, including spaces and non-ASCII characters.
The variable names are visible when viewing the timetable and when using the
summary
function. Furthermore, you can use the variable names within parentheses, within curly braces, or with dot indexing to access table data.If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.
Example
Create a timetable with default variable names. Then modify the names using the Properties.VariableNames
property.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3])
TT=3×3 timetable
Time Var1 Var2 Var3
___________ ____ _____ ____
18-Dec-2015 37.3 30.1 13.4
19-Dec-2015 39.1 30.03 6.5
20-Dec-2015 42.3 29.9 7.3
TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'}
TT=3×3 timetable
Time Temp Pressure WindSpeed
___________ ____ ________ _________
18-Dec-2015 37.3 30.1 13.4
19-Dec-2015 39.1 30.03 6.5
20-Dec-2015 42.3 29.9 7.3
A fundamental way to display and modify variables is to access them by name using dot syntax.
TT.Temp
ans = 3×1
37.3000
39.1000
42.3000
TT.Pressure(3) = 30
TT=3×3 timetable
Time Temp Pressure WindSpeed
___________ ____ ________ _________
18-Dec-2015 37.3 30.1 13.4
19-Dec-2015 39.1 30.03 6.5
20-Dec-2015 42.3 30 7.3
VariableTypes
— Variable data types
string array | cell array of character vectors
Since R2024b
Variable data types, specified as a string array or a cell array of character vectors.
Example
Create a timetable.
TT = timetable(datetime(["2015-12-18";"2015-12-19";"2015-12-20"]), ... [37.3;39.1;42.3],[13.4;6.5;7.3],["N";"SE";"NW"],[1;0;1]); TT.Properties.VariableNames = ["Temperature" "WindSpeed" "WindDirection" "ExtremeWarning"]
TT=3×4 timetable
Time Temperature WindSpeed WindDirection ExtremeWarning
___________ ___________ _________ _____________ ______________
18-Dec-2015 37.3 13.4 "N" 1
19-Dec-2015 39.1 6.5 "SE" 0
20-Dec-2015 42.3 7.3 "NW" 1
Display the data types of the variables of the timetable.
TT.Properties.VariableTypes
ans = 1x4 string
"double" "double" "string" "double"
You can also use the property to convert the data types of the timetable variables. For example, convert WindDirection
to a categorical array and ExtremeWarning
to a logical array.
TT.Properties.VariableTypes = ["double" "double" "categorical" "logical"]
TT=3×4 timetable
Time Temperature WindSpeed WindDirection ExtremeWarning
___________ ___________ _________ _____________ ______________
18-Dec-2015 37.3 13.4 N true
19-Dec-2015 39.1 6.5 SE false
20-Dec-2015 42.3 7.3 NW true
VariableDescriptions
— Variable descriptions
{}
(default) | cell array of character vectors | string array
Variable descriptions, specified as a cell array of character vectors or a string array. This property can be an empty cell array, which is the default. If the array is not empty, then it must contain as many elements as there are variables. You can specify an individual empty character vector or empty string for a variable that does not have a description.
The variable descriptions are visible when using the
summary
function.If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.
Example
Create a timetable. Modify the variable names and descriptions. Display a summary of the result.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]); TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'}; TT.Properties.VariableDescriptions = {'Temperature (external)', ... 'Pressure in Hg', ... 'Wind speed at sensor 123'}; summary(TT)
TT: 3x3 timetable Row Times: Time: datetime Variables: Temp: double (Temperature (external)) Pressure: double (Pressure in Hg) WindSpeed: double (Wind speed at sensor 123) Statistics for applicable variables and row times: NumMissing Min Median Max Mean Std Time 0 18-Dec-2015 19-Dec-2015 20-Dec-2015 19-Dec-2015 24:00:00 Temp 0 37.3000 39.1000 42.3000 39.5667 2.5325 Pressure 0 29.9000 30.0300 30.1000 30.0100 0.1015 WindSpeed 0 6.5000 7.3000 13.4000 9.0667 3.7740
VariableUnits
— Variable units
{}
(default) | cell array of character vectors | string array
Variable units, specified as a cell array of character vectors or a string array. This property can be an empty cell array, which is the default. If the array is not empty, then it must contain as many elements as there are variables. You can specify an individual empty character vector or empty string for a variable that does not have units.
The variable units are visible when using the
summary
function.If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.
Example
Create a timetable. Modify the variable names and units. Display a summary of the result.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]); TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'}; TT.Properties.VariableUnits = {'degrees F','mm Hg','mph'}; summary(TT)
TT: 3x3 timetable Row Times: Time: datetime Variables: Temp: double (degrees F) Pressure: double (mm Hg) WindSpeed: double (mph) Statistics for applicable variables and row times: NumMissing Min Median Max Mean Std Time 0 18-Dec-2015 19-Dec-2015 20-Dec-2015 19-Dec-2015 24:00:00 Temp 0 37.3000 39.1000 42.3000 39.5667 2.5325 Pressure 0 29.9000 30.0300 30.1000 30.0100 0.1015 WindSpeed 0 6.5000 7.3000 13.4000 9.0667 3.7740
VariableContinuity
— Status as continuous or discrete variables
[]
(default) | cell array of character vectors | string array
Status as continuous or discrete variables, specified as a cell array
of character vectors or a string array. This property can be an empty
array, which is the default. If the array is not empty, then it must
contain as many elements as there are variables. Each element can be
either 'unset'
, 'continuous'
,
'step'
, or 'event'
.
The values in VariableContinuity
affect how the
retime
or synchronize
functions work. If you specify VariableContinuity
and
call retime
or synchronize
,
then you do not need to specify a method. Instead,
retime
and synchronize
fill in the output timetable variables using the following default
methods:
'unset'
— Fill in values using missing data indicator for that type (such asNaN
for numeric variables).'continuous'
— Fill in values using linear interpolation.'step'
— Fill in values using previous value.'event'
— Fill in values using missing data indicator for that type (such asNaN
for numeric variables).
If you do specify a method as an input argument to
retime
or synchronize
,
then that method overrides the values you specify in
VariableContinuity
.
For more information on using the
VariableContinuity
property, see Retime and Synchronize Timetable Variables Using Different Methods.
Example
Create a timetable. Specify a matlab.tabular.Continuity
value for each variable.
TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ... [37.3;39.1;42.3],[13.4;6.5;7.3],{'N';'SE';'NW'}); TT.Properties.VariableNames = {'Temperature','WindSpeed','WindDirection'}; TT.Properties.VariableContinuity = {'continuous','event','event'}; TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Time' 'Variables'} VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'} VariableTypes: ["double" "double" "cell"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [continuous event event] RowTimes: [3x1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: 1d Events: [] CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Custom Metadata
CustomProperties
— Customized metadata of timetable and its variables
CustomProperties
object
Customized metadata of a timetable and its variables, specified as a
CustomProperties
object.
The CustomProperties
object is a container for
customized metadata that you can add to a timetable. By default,
CustomProperties
has zero properties. Each
property you add to CustomProperties
can contain
either table metadata or variable metadata. If a property contains
variable metadata, then its value must be an array, and the number of
elements in the array must equal the number of timetable
variables.
To add properties for customized metadata to a timetable, use the
addprop
function.To access or modify customized metadata, use the syntax
. In this syntax,timetableName
.Properties.CustomProperties.PropertyName
is the name you chose when you added that property usingPropertyName
addprop
.To remove properties, use the
rmprop
function.
Note: You can add or remove only properties for customized metadata using
addprop
and rmprop
. You
cannot add or remove properties of the
object.timetableName
.Properties
Example
Create a timetable containing weather data.
TT = timetable(datetime({'2015-12-18';'2015-12-20';'2015-12-21'}), ... [37.3;39.1;42.3],[13.4;6.5;7.3],{'N';'SE';'NW'}); TT.Properties.VariableNames = {'Temperature','WindSpeed','WindDirection'}
TT=3×3 timetable
Time Temperature WindSpeed WindDirection
___________ ___________ _________ _____________
18-Dec-2015 37.3 13.4 {'N' }
20-Dec-2015 39.1 6.5 {'SE'}
21-Dec-2015 42.3 7.3 {'NW'}
To describe the instruments that measured these data, and the name of an output file, add customized metadata using the addprop
function. The Instruments
property has variable metadata that apply to the variables of TT
. The OutputFile
property has table metadata.
TT = addprop(TT,{'Instruments','OutputFile'},{'variable','table'}); TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Time' 'Variables'} VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'} VariableTypes: ["double" "double" "cell"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3x1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN Events: [] Custom Properties (access using t.Properties.CustomProperties.<name>): OutputFile: [] Instruments: []
Assign values to the customized metadata using dot syntax. When you assign an array of text values to customized metadata, the best practice is to use a string array, not a cell array of character vectors. If a property of CustomProperties
is a cell array of character vectors, then there is no mechanism to prevent you from later assigning nontext values as elements of the cell array.
TT.Properties.CustomProperties.Instruments = ["thermometer","anemometer","wind vane"]; TT.Properties.CustomProperties.OutputFile = 'weatherReadings.csv'; TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Time' 'Variables'} VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'} VariableTypes: ["double" "double" "cell"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3x1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN Events: [] Custom Properties (access using t.Properties.CustomProperties.<name>): OutputFile: 'weatherReadings.csv' Instruments: ["thermometer" "anemometer" "wind vane"]
Remove the OutputFile
property from TT
.
TT = rmprop(TT,'OutputFile');
TT.Properties
ans = TimetableProperties with properties: Description: '' UserData: [] DimensionNames: {'Time' 'Variables'} VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'} VariableTypes: ["double" "double" "cell"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3x1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN Events: [] Custom Properties (access using t.Properties.CustomProperties.<name>): Instruments: ["thermometer" "anemometer" "wind vane"]
Examples
Store and Synchronize Related Data Variables in Timetable
Store data about weather conditions measured at different times in a timetable. Aside from storage, timetables provide functions to synchronize data to times that you specify. Also, you can annotate the timetable to describe your work and the variables of the timetable.
Create a timetable from workspace variables. The values in MeasurementTime
become the row times of the timetable. All the other input arguments become the timetable variables. When you use this syntax, the names of the row times vector and the variables of TT
are the names of the corresponding input arguments.
MeasurementTime = datetime({'2015-12-18 08:03:05';'2015-12-18 10:03:17';'2015-12-18 12:03:13'}); Temp = [37.3;39.1;42.3]; Pressure = [30.1;30.03;29.9]; WindSpeed = [13.4;6.5;7.3]; TT = timetable(MeasurementTime,Temp,Pressure,WindSpeed)
TT=3×3 timetable
MeasurementTime Temp Pressure WindSpeed
____________________ ____ ________ _________
18-Dec-2015 08:03:05 37.3 30.1 13.4
18-Dec-2015 10:03:17 39.1 30.03 6.5
18-Dec-2015 12:03:13 42.3 29.9 7.3
Synchronize the weather data to regular times with an hourly time step. Adjust the data to the new times using linear interpolation.
TT2 = retime(TT,'hourly','linear')
TT2=6×3 timetable
MeasurementTime Temp Pressure WindSpeed
____________________ ______ ________ _________
18-Dec-2015 08:00:00 37.254 30.102 13.577
18-Dec-2015 09:00:00 38.152 30.067 10.133
18-Dec-2015 10:00:00 39.051 30.032 6.6885
18-Dec-2015 11:00:00 40.613 29.969 6.8783
18-Dec-2015 12:00:00 42.214 29.903 7.2785
18-Dec-2015 13:00:00 43.815 29.838 7.6788
Since the row times of the output are not the measured times, rename the vector of row times. This vector is also the name of the first dimension of the timetable.
TT2.Properties.DimensionNames{1} = 'InterpolatedTimes'
TT2=6×3 timetable
InterpolatedTimes Temp Pressure WindSpeed
____________________ ______ ________ _________
18-Dec-2015 08:00:00 37.254 30.102 13.577
18-Dec-2015 09:00:00 38.152 30.067 10.133
18-Dec-2015 10:00:00 39.051 30.032 6.6885
18-Dec-2015 11:00:00 40.613 29.969 6.8783
18-Dec-2015 12:00:00 42.214 29.903 7.2785
18-Dec-2015 13:00:00 43.815 29.838 7.6788
Annotate TT2
with a description. You can annotate TT2
and its variables using metadata accessed through TT2.Properties
.
TT2.Properties.Description = 'Weather data, interpolated to regular hourly times';
TT2.Properties
ans = TimetableProperties with properties: Description: 'Weather data, interpolated to regular hourly times' UserData: [] DimensionNames: {'InterpolatedTimes' 'Variables'} VariableNames: {'Temp' 'Pressure' 'WindSpeed'} VariableTypes: ["double" "double" "double"] VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [6x1 datetime] StartTime: 18-Dec-2015 08:00:00 SampleRate: 2.7778e-04 TimeStep: 01:00:00 Events: [] CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Access Row Times and Variable Data
You can use dot syntax to access the row times of a timetable. Also, you can access individual variables using dot syntax, or all the data in a timetable using its second dimension name.
Load a timetable from the MAT-file outdoors
. Display the first three rows.
load outdoors
outdoors(1:3,:)
ans=3×3 timetable
Time Humidity TemperatureF PressureHg
___________________ ________ ____________ __________
2015-11-15 00:00:24 49 51.3 29.61
2015-11-15 01:30:24 48.9 51.5 29.61
2015-11-15 03:00:24 48.9 51.5 29.61
Access the row times using the name of the row times vector. This name is also the name of the first dimension of the timetable. outdoors
stores the row times as a datetime
vector. Display the first three times.
outdoors.Time(1:3)
ans = 3x1 datetime
2015-11-15 00:00:24
2015-11-15 01:30:24
2015-11-15 03:00:24
Access the temperatures as a numeric vector, using its variable name.
outdoors.TemperatureF(1:3)
ans = 3×1
51.3000
51.5000
51.5000
Access all the timetable data as a matrix, using the syntax outdoors.Variables
. This syntax uses the second dimension name of the timetable, and is equivalent to accessing all the contents using curly brace indexing, outdoors{:,:}
. However, the matrix does not include row times, because the vector of row times is timetable metadata, not a variable. If the timetable data cannot be concatenated into a matrix, then an error message is raised.
outdoors.Variables
ans = 51×3
49.0000 51.3000 29.6100
48.9000 51.5000 29.6100
48.9000 51.5000 29.6100
48.8000 51.5000 29.6100
48.7000 51.5000 29.6000
48.8000 51.5000 29.6000
49.0000 51.5000 29.6000
49.1000 51.3000 29.6000
49.1000 51.3000 29.6100
49.1000 51.5000 29.6100
⋮
Rename the second dimension of outdoors
. If you change the name, then you can use the new name to access the data.
outdoors.Properties.DimensionNames{2} = 'Data';
outdoors.Data
ans = 51×3
49.0000 51.3000 29.6100
48.9000 51.5000 29.6100
48.9000 51.5000 29.6100
48.8000 51.5000 29.6100
48.7000 51.5000 29.6000
48.8000 51.5000 29.6000
49.0000 51.5000 29.6000
49.1000 51.3000 29.6000
49.1000 51.3000 29.6100
49.1000 51.5000 29.6100
⋮
Specify Time Vector
Create a timetable using the 'RowTimes'
name-value pair argument. Note that the name of the row times vector of TT
is Time
, not MeasurementTime
. When you use this syntax, the name of the row times vector is always Time
.
MeasurementTime = datetime({'2015-12-18 08:03:05';'2015-12-18 10:03:17';'2015-12-18 12:03:13'}); Temp = [37.3;39.1;42.3]; Pressure = [29.4;29.6;30.0]; Precip = [0.1;0.9;0.0]; StormDuration = [hours(1);hours(2);NaN]; TT = timetable(Temp,Pressure,Precip,StormDuration,'RowTimes',MeasurementTime)
TT=3×4 timetable
Time Temp Pressure Precip StormDuration
____________________ ____ ________ ______ _____________
18-Dec-2015 08:03:05 37.3 29.4 0.1 1 hr
18-Dec-2015 10:03:17 39.1 29.6 0.9 2 hr
18-Dec-2015 12:03:13 42.3 30 0 NaN hr
Default Names
Create a timetable. If there are input arguments that are not workspace variables, then the timetable
function assigns default names to the corresponding row times vector and the variables of the timetable. For example, if you transpose some input arguments to make them column vectors, then those input arguments are not workspace variables. The default names are Time
for the vector of row times, and VarN
for the N
th timetable variable.
T = hours(1:3); Temp = [37.3;39.1;42.3]; P = [29.4 29.6 30]; TT = timetable(T',Temp,P')
TT=3×2 timetable
Time Temp Var2
____ ____ ____
1 hr 37.3 29.4
2 hr 39.1 29.6
3 hr 42.3 30
Specify Sample Rate
Create a regular timetable using a sample rate of 100 Hz.
Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'SampleRate',100)
TT=5×1 timetable
Time Intensity
________ _________
0 sec 100
0.01 sec 98.7
0.02 sec 95.2
0.03 sec 101.4
0.04 sec 99.1
Create a timetable with 30 seconds as the first row time. To specify a start time, use the 'StartTime'
name-value pair argument.
TT = timetable(Intensity,'SampleRate',100,'StartTime',seconds(30))
TT=5×1 timetable
Time Intensity
_________ _________
30 sec 100
30.01 sec 98.7
30.02 sec 95.2
30.03 sec 101.4
30.04 sec 99.1
Specify Time Step
Create a regular timetable using a time step of 0.01 seconds. You must specify the time step as a duration
or calendarDuration
value.
Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.01))
TT=5×1 timetable
Time Intensity
________ _________
0 sec 100
0.01 sec 98.7
0.02 sec 95.2
0.03 sec 101.4
0.04 sec 99.1
Create a timetable with 30 seconds as the first row time. To specify a start time, use the 'StartTime'
name-value pair argument.
TT = timetable(Intensity,'TimeStep',seconds(0.01),'StartTime',seconds(30))
TT=5×1 timetable
Time Intensity
_________ _________
30 sec 100
30.01 sec 98.7
30.02 sec 95.2
30.03 sec 101.4
30.04 sec 99.1
Specify Size and Variable Types
Preallocate a table by specifying its size and the data types of the variables. The timetable
function fills the variables with default values that are appropriate for the data types you specify. It also gives the variables default names.
T = [datetime('now') datetime(2017,11,1:3)]; sz = [4 3]; varTypes = {'double','double','string'}; TT = timetable('Size',sz,'VariableTypes',varTypes,'RowTimes',T)
TT=4×3 timetable
Time Var1 Var2 Var3
____________________ ____ ____ _________
20-Jul-2024 14:05:30 0 0 <missing>
01-Nov-2017 00:00:00 0 0 <missing>
02-Nov-2017 00:00:00 0 0 <missing>
03-Nov-2017 00:00:00 0 0 <missing>
To specify names for the variables, use the 'VariableNames'
name-value pair argument.
varNames = {'Temperature','WindSpeed','Station'}; TT = timetable('Size',sz,'VariableTypes',varTypes,'RowTimes',T,'VariableNames',varNames)
TT=4×3 timetable
Time Temperature WindSpeed Station
____________________ ___________ _________ _________
20-Jul-2024 14:05:30 0 0 <missing>
01-Nov-2017 00:00:00 0 0 <missing>
02-Nov-2017 00:00:00 0 0 <missing>
03-Nov-2017 00:00:00 0 0 <missing>
Add a row of data to TT
. Preallocation can be a useful technique when your code adds one row of data, or a few rows of data, at a time. Instead of growing the timetable every time you add a row, you can fill in table variables that already have room for your data. You can encapsulate a row of data values in a cell array, and assign it to a row of the timetable.
Subscript into a row by its time and assign a row of data values. You also can subscripting into rows and variables by number. However, subscripting into a timetable by time is a useful technique.
TT(datetime(2017,11,2),:) = {48.2,13.33,"S1"}
TT=4×3 timetable
Time Temperature WindSpeed Station
____________________ ___________ _________ _________
20-Jul-2024 14:05:30 0 0 <missing>
01-Nov-2017 00:00:00 0 0 <missing>
02-Nov-2017 00:00:00 48.2 13.33 "S1"
03-Nov-2017 00:00:00 0 0 <missing>
You can encapsulate a row of data values in a cell array. When you assign a row from a cell array, the assignment converts the cell array into a timetable row.
Preallocate Timetable Using Sample Rate
Specify a sample rate of 1000 Hz and preallocate a timetable. You also can specify a start time.
sz = [4 3]; varTypes = {'uint64','double','duration'}; TT = timetable('Size',sz,'VariableTypes',varTypes,'SampleRate',1000,'StartTime',seconds(15))
TT=4×3 timetable
Time Var1 Var2 Var3
__________ ____ ____ ________
15 sec 0 0 00:00:00
15.001 sec 0 0 00:00:00
15.002 sec 0 0 00:00:00
15.003 sec 0 0 00:00:00
Index into the third row, by specifying its time, and add a row of data.
TT(seconds(15.002),:) = {50,1.37,minutes(76)}
TT=4×3 timetable
Time Var1 Var2 Var3
__________ ____ ____ ________
15 sec 0 0 00:00:00
15.001 sec 0 0 00:00:00
15.002 sec 50 1.37 01:16:00
15.003 sec 0 0 00:00:00
Preallocate Timetable Using Time Step
Specify a time step, and names for the variables.
sz = [3 2]; varTypes = {'double','double'}; TT = timetable('Size',sz,'VariableTypes',varTypes,'TimeStep',seconds(0.1),'VariableNames',{'Intensity','Distance'})
TT=3×2 timetable
Time Intensity Distance
_______ _________ ________
0 sec 0 0
0.1 sec 0 0
0.2 sec 0 0
Index into the second row, by specifying its time, and add a row of data.
TT(seconds(0.1),:) = {93.6,11.27}
TT=3×2 timetable
Time Intensity Distance
_______ _________ ________
0 sec 0 0
0.1 sec 93.6 11.27
0.2 sec 0 0
Create Timetable and Specify Variable Names
Create a timetable and specify the names of the timetable variables. The vector of row times is a duration
vector, whose units are seconds.
Time = seconds(1:5)'; TT = timetable(Time,[98;97.5;97.9;98.1;97.9],[120;111;119;117;116],... 'VariableNames',{'Reading1','Reading2'})
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
Starting in R2019b you can specify timetable variable names that are not valid MATLAB® identifiers. Such variable names can include spaces, non-ASCII characters, and can have any character as the leading character.
For example, use dates as the names of the timetable variables that contain the readings.
TT = timetable(Time,[98;97.5;97.9;98.1;97.9],[120;111;119;117;116],... 'VariableNames',{'29-May-2019','30-May-2019'})
TT=5×2 timetable
Time 29-May-2019 30-May-2019
_____ ___________ ___________
1 sec 98 120
2 sec 97.5 111
3 sec 97.9 119
4 sec 98.1 117
5 sec 97.9 116
To use dot notation when the name is not a valid identifier, include parentheses and quotation marks.
TT.('29-May-2019')
ans = 5×1
98.0000
97.5000
97.9000
98.1000
97.9000
Limitations
Use single quotes for these input names:
'DimensionNames'
(since R2021a)'RowTimes'
'SampleRate'
'Size'
'StartTime'
'TimeStep'
'VariableTypes'
'VariableNames'
To avoid confusion with variable inputs, do not use double-quoted string scalars (such as
"RowTimes"
) for these names.
Tips
For a list of functions that accept or return timetables, see Timetables.
In certain cases, you can call
timetable
with a syntax that specifies a regular time step between row times, and yettimetable
returns an irregular timetable. This result occurs when you specify the time step using a calendar unit of time and there is a row time that introduces an irregular step. For example, if you create a timetable with a time step of one calendar month, starting on January 31, 2019, then it is irregular with respect to months.stime = datetime(2019,1,31); tstep = calmonths(1); TT = timetable('Size',[3 1],'VariableTypes',{'double'},... 'TimeStep',tstep,'StartTime',stime)
TT = 3×1 timetable Time Var1 ___________ ____ 31-Jan-2019 0 28-Feb-2019 0 31-Mar-2019 0
There are other cases where irregularities are due to shifts from Daylight Saving Time (DST) or to
datetime
values that are leap seconds. This table specifies the dates, times, and time steps that can produce irregular results unexpectedly.Row Time Value
Time Step
Start time specified as the 29th, 30th, or 31st day of the month.
Number of calendar months or quarters.
Start time specified as February 29.
Number of calendar years.
Any datetime
value occurring between 1:00 a.m. and 2:00 a.m. on a day shifting from DST to standard time (when such values have a time zone that observes DST).Number of calendar days or months. Any
datetime
value that is a leap second (when the time zone for such values is theUTCLeapSeconds
time zone). For the list of leap seconds, seeleapseconds
.Time step specified in any calendar unit (days, weeks, months, quarters, or years).
Extended Capabilities
Tall Arrays
Calculate with arrays that have more rows than fit in memory.
The
timetable
function supports tall arrays with the following usage
notes and limitations:
The
SampleRate
,TimeStep
,StartTime
,Events
, andVariableTypes
properties are not supported.Creation. There are several ways to create a tall timetable:
Specify the
OutputType
property of the underlying datastore as'timetable'
so that read operations on the datastore return timetables. Then, convert the datastore into a tall array withtall(ds)
.The default behavior is to use the first
datetime
orduration
variable in the data for the row times. To specify the row times yourself, use theRowTimes
datastore property to specify a talldatetime
or a tallduration
vector of row times.Convert an existing tall table using
table2timetable
.Convert an existing tall array using
array2timetable
.Manually construct a tall timetable from the variables in a tall table using the
timetable
constructor.ds = tabularTextDatastore('data/folder/path.csv'); tt = tall(ds); TT = timetable(rowTimes, tt.Var1, tt.Var2, ...)
Convert an in-memory timetable into a tall timetable using the syntax
TT = tall(tt)
.
Indexing. The
timerange
,withtol
, andvartype
functions are supported for indexing into tall timetables.Supported Functions. The Extended Capabilities section at the bottom of each reference page indicates whether that function supports tall arrays, and if so, whether there are any limitations when using the function with tall timetables.
For more information, see Tall Arrays.
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
Starting in R2020a, you can use timetables in MATLAB® code intended for code generation. For more information, see Code Generation for Timetables (MATLAB Coder) and Timetable Limitations for Code Generation (MATLAB Coder).
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.
Usage notes and limitations:
Only these syntaxes are supported:
TT = timetable(
rowTimes
,var1,...,varN
)TT = timetable(
var1,...,varN
,'RowTimes',rowTimes
)TT = timetable(___,
'VariableNames'
,{'name1',...,'nameN'}
)TT = timetable(___,
'DimensionNames'
,{'dim1','dim2'}
)All data variables must be distributed.
The
'SampleRate'
,'TimeStep'
, and'StartTime'
name-value arguments are not supported.The
Events
property is not supported.
For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).
Version History
Introduced in R2016bR2024b: VariableTypes
property of tables and timetables specifies the data types of their variables
The VariableTypes
property of tables and timetables specifies the data
types of their variables.
R2023a: Perform calculations directly on tables and timetables without extracting their data
You can now perform calculations directly on tables and timetables without extracting their data. All the variables in your tables and timetables must have data types that support calculations. You can also perform operations where one operand is a table or timetable and the other is a numeric or logical array. Previously, all calculations required you to extract data from your tables and timetables by indexing into them.
For more information, see Direct Calculations on Tables and Timetables and Rules for Table and Timetable Mathematics.
R2023a: Find and label events in timetables using attached event tables
To find and label events in a timetable, attach an event table to it. An event table is a timetable of events. An event consists of an event time (when something happened), often an event length or event end time (how long it happened), often an event label (what happened), and sometimes additional information about the event. Event tables are designed to be attached to timetables. When you attach an event table to a timetable, you can find or label rows in the timetable that occur during events.
MATLAB provides these functions to create event tables from input data, filter timetable rows on event times, and synchronize events to timetables:
R2023a: Improved performance when subscripting with times or with withtol
subscript
timetable
subscripting when subscripting with times or with a
withtol
subscript is significantly faster in R2023a than in
R2022b.
For example, when you use a vector of 100
datetime
values to subscript into a timetable that has 107 rows, performance in R2023a is about 114x faster than in R2022b.function timingTest() rng default % 10^7 rows N = 10000000; rowtimes = datetime(2023,1,1,0,0,0:N-1); rowtimes.Format = rowtimes.Format + ".SSS"; tt = timetable(rand(N,1),RowTimes=rowtimes); % 100 values chosen in steps of 10 n = 1000; t = datetime(2023,1,1,0,0,0:10:n-1); tic tt2 = tt(t,:); toc end
The approximate execution times are:
R2022b: 9.10 s
R2023a: 0.08 s
Similarly, when you use a vector of 100
duration
values to subscript into a timetable that has 107 rows, performance in R2023a is about 14x faster than in R2022b.function timingTest() rng default % 10^7 rows N = 10000000; rowtimes = seconds(0:N-1); tt = timetable(rand(N,1),RowTimes=rowtimes); % 100 values chosen in steps of 10 n = 1000; t = seconds(0:10:n-1); tic tt2 = tt(t,:); toc end
The approximate execution times are:
R2022b: 1.29 s
R2023a: 0.09 s
When you use a
withtol
subscript with a timetable that has 107 rows, performance in R2023a is about 44x faster than in R2022b.function timingTest() rng default % 10^7 rows N = 10000000; rowtimes = seconds(0:N-1); tt = timetable(rand(N,1),RowTimes=rowtimes); % 100 values chosen in steps of 10 n = 1000; t = seconds(0:10:n-1); tt.Time = tt.Time + .1*seconds(rand(N,1)); wt = withtol(t,seconds(.1)); tic tt2 = tt(wt,:); toc end
The approximate execution times are:
R2022b: 3.92 s
R2023a: 0.09 s
The code was timed on a Windows® 10, AMD® EPYC 74F3 24-Core Processor @ 3.19 GHz test system by calling each
version of the timingTest
function.
R2021a: 'SamplingRate'
will be removed
The 'SamplingRate'
name-value argument will be removed in a future
release. Use 'SampleRate'
instead. The corresponding timetable property
is also named SampleRate
.
For backward compatibility, you still can specify 'SamplingRate'
as the
name of the name-value argument. However, the value is assigned to the
SampleRate
property.
R2019b: Variable names can contain leading and trailing whitespace characters
Table and timetable variable names with leading or trailing whitespace characters are not modified.
In previous releases, leading and trailing whitespace characters were deleted from variable names when you specified them using the 'VariableNames'
name-value pair argument, or assigned them to the VariableNames
property.
To manually remove such characters, first use the strtrim
function on the names,
then assign them as variable names to the table or timetable.
See Also
array2timetable
| table2timetable
| summary
| uitable
| timetable2table
| timeseries
| timeseries2timetable
| extractTimetable
(Simulink) | table
| retime
| synchronize
Topics
- Represent Dates and Times in MATLAB
- Create Timetables
- Clean Timetable with Missing, Duplicate, or Nonuniform Times
- Resample and Aggregate Data in Timetable
- Calculations When Tables Have Both Numeric and Nonnumeric Data
- Grouped Calculations in Tables and Timetables
- Add Event Table from External Data to Timetable
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)