MathWorks Machine Translation
The automated translation of this page is provided by a general purpose third party translator tool.
MathWorks does not warrant, and disclaims all liability for, the accuracy, suitability, or fitness for purpose of the translation.
Timetable array with time-stamped rows and variables of different types
timetable
is a type of table that associates a time with
each row. Like tables, timetables can store column-oriented data variables that have
different data types and sizes as long as they have the same number of rows. In
addition, timetables provide time-specific functions to align, combine, and perform
calculations with time-stamped data in one or more timetables.
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. To index into a timetable, use smooth parentheses
()
to return a subtable or curly braces {}
to
extract the contents. You can reference variables and the vector of row times using
names. For more information on indexing, see Select Timetable Data by Row Time and Variable Type
and Access Data in a Table.
To create a timetable from a table or an array, use the table2timetable
or array2timetable
functions. Alternatively, you can use the
timetable
function described below.
When you use the timetable
function, you can specify a vector of
row times, or create row times using a sample rate or time step. Also, you can create a
timetable with preallocated space for variables whose values are filled in later.
TT = timetable(rowTimes,var1,...,varN)
TT = timetable(var1,...,varN,'RowTimes',rowTimes)
TT = timetable(var1,...,varN,'SampleRate',Fs)
TT = timetable(var1,...,varN,'TimeStep',dt)
TT = timetable('Size',sz,'VariableTypes',varTypes,'RowTimes',rowTimes)
TT = timetable('Size',sz,'VariableTypes',varTypes,'SampleRate',Fs)
TT = timetable('Size',sz,'VariableTypes',varTypes,'TimeStep',dt)
TT = timetable(___,Name,Value)
TT = timetable(
creates a timetable from the input data variables
rowTimes
,var1,...,varN
)var1,...,varN
and the time vector
rowTimes
. The data variables can be 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(
creates a timetable using the sample rate var1,...,varN
,'SampleRate',Fs
)Fs
to calculate
regularly spaced row times. Fs
is a positive numeric
scalar that specifies the number of samples per second (Hz). The first row
time is zero seconds.
TT = timetable(
creates a timetable using the time step var1,...,varN
,'TimeStep',dt
)dt
to calculate
regularly spaced row times. dt
is a duration or calendar
duration value that specifies the length of time between consecutive row
times. The first row time is zero seconds.
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
is a cell array of character vectors
specifying data types. The number of times in rowTimes
must equal sz[1]
.
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.
var1,...,varN
— Input variablesInput variables, specified as arrays with the same number of rows. The input variables can be of 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 timetableTimes associated with rows of a timetable, specified as a datetime
vector or a 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.
Data Types: datetime
| duration
sz
— Size of preallocated timetableSize 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 variablesData 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 |
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 rateSample rate, specified as a positive numeric scalar.
Fs
specifies the number of samples per second
(Hz).
dt
— Time stepTime step, specified as a duration scalar.
If you specify dt
as a calendar duration, and you
specify the 'StartTime'
name-value pair argument,
then the value of 'StartTime'
must be a datetime
scalar.
Data Types: duration
| calendarDuration
Specify optional
comma-separated pairs of Name,Value
arguments. Name
is
the argument name and Value
is the corresponding value.
Name
must appear inside quotes. You can specify several name and value
pair arguments in any order as Name1,Value1,...,NameN,ValueN
.
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 namesVariable names, specified as the comma-separated pair consisting
of 'VariableNames'
and a cell array of character
vectors or a string array. The number of names in the array must
equal the number of table variables.
'StartTime'
— Start timeStart time, specified as the comma-separated pair consisting of
'StartTime'
and 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
of TT
are datetime values.
If the start time is a duration, then the row times are durations.
If the time step dt
is a calendar
duration value, then the start time must be a datetime
value.
Data Types: datetime
| duration
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 provides 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 variable using the syntax TT.Var1
, accessing the
values in an array.
DimensionNames
— Dimension names{'Time','Variables'}
(default) | two-element cell array of character vectors | two-element string arrayDimension names, specified as a two-element cell array of character vectors or two-element string array.
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.
If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.
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 = 1×2 cell array
{'Time'} {'Variables'}
Access the row times using the first dimension name.
TT.Time
ans = 3×1 datetime array
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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3×1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: 1d CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
Description
— Timetable description''
(default) | character vector | string scalarTimetable 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.
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)
Description: Weather Data from December 2015 RowTimes: Time: 3×1 datetime Values: Min 18-Dec-2015 Median 19-Dec-2015 Max 20-Dec-2015 TimeStep 24:00:00 Variables: Temp: 3×1 double Values: Min 37.3 Median 39.1 Max 42.3 Pressure: 3×1 double Values: Min 29.9 Median 30.03 Max 30.1 WindSpeed: 3×1 double Values: Min 6.5 Median 7.3 Max 13.4
UserData
— Additional timetable information[]
(default) | arrayAdditional timetable information, specified as an array. You can attach data of any kind to a timetable using this property.
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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3×1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: 1d CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
RowTimes
— Row timesRow times, specified as a datetime vector or duration vector. There
must be a row time for every row of the timetable. However, a timetable
can have row times that are duplicates, out of order, or
NaT
or NaN
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 table.
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 = 1×2 cell array
{'Time'} {'Variables'}
TT.Time
ans = 3×1 datetime array
01-Jan-2017
02-Jan-2017
03-Jan-2017
StartTime
— Start time of row timesStart 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, then the row times of
TT
are datetime values.
If the start time is a duration, then the row times are durations.
If the time step is a calendar duration, then the start time must be a datetime value.
If the timetable is empty, then the start time is
NaN
.
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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3×1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN 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 00:00:00 37.3 13.4 'N'
11-Apr-2018 00:00:00 39.1 6.5 'SE'
12-Apr-2018 00:00:00 42.3 7.3 'NW'
SampleRate
— Sample rateSample rate, specified as a positive 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
.
TimeStep
— Time stepTime step, specified as a duration scalar.
If you specify the time step as a calendar duration (for example, calendar months), then the vector of row times must be a datetime vector.
If you specify the time step as a duration (for example, seconds), then the vector of row times either can be a datetime or duration vector.
If the row times are not regular, or the timetable is empty, then the
time step is NaN
.
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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [5×1 duration] StartTime: 0 sec SampleRate: 100 TimeStep: 0.01 sec 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
Data Types: duration
| calendarDuration
VariableNames
— Variable namesVariable names, specified as a cell array of character vectors or a
string array, with names that are nonempty and distinct. Variable names
must be valid MATLAB® identifiers. You can determine valid variable names using
the function isvarname
.
MATLAB removes any leading or trailing whitespace from the
character vectors. The number of character vectors must equal the number
of variables.
If you do not specify variable names, or you specify invalid
identifiers, then MATLAB uses a cell array of N
character
vectors of the form {'Var1' ...
'Var
where
N
'}N
is the number of variables.
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 timetable data.
If you specify this property using a string array, then it is converted and stored as a cell array of character vectors.
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
VariableDescriptions
— Variable descriptions{}
(default) | cell array of character vectors | string arrayVariable 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.
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)
RowTimes: Time: 3×1 datetime Values: Min 18-Dec-2015 Median 19-Dec-2015 Max 20-Dec-2015 TimeStep 24:00:00 Variables: Temp: 3×1 double Properties: Description: Temperature (external) Values: Min 37.3 Median 39.1 Max 42.3 Pressure: 3×1 double Properties: Description: Pressure in Hg Values: Min 29.9 Median 30.03 Max 30.1 WindSpeed: 3×1 double Properties: Description: Wind speed at sensor 123 Values: Min 6.5 Median 7.3 Max 13.4
VariableUnits
— Variable units{}
(default) | cell array of character vectors | string arrayVariable 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.
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)
RowTimes: Time: 3×1 datetime Values: Min 18-Dec-2015 Median 19-Dec-2015 Max 20-Dec-2015 TimeStep 24:00:00 Variables: Temp: 3×1 double Properties: Units: degrees F Values: Min 37.3 Median 39.1 Max 42.3 Pressure: 3×1 double Properties: Units: mm Hg Values: Min 29.9 Median 30.03 Max 30.1 WindSpeed: 3×1 double Properties: Units: mph Values: Min 6.5 Median 7.3 Max 13.4
VariableContinuity
— Status as continuous or discrete variables[]
(default) | cell array of character vectors | string arrayStatus 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 as NaN
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 as NaN
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.
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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [continuous event event] RowTimes: [3×1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: 1d CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
CustomProperties
— Customized metadata of timetable and its variablesCustomProperties
objectCustomized 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 using
PropertyName
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
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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3×1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN 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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3×1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN 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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [3×1 datetime] StartTime: 18-Dec-2015 SampleRate: NaN TimeStep: NaN Custom Properties (access using t.Properties.CustomProperties.<name>): Instruments: ["thermometer" "anemometer" "wind vane"]
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'} VariableDescriptions: {} VariableUnits: {} VariableContinuity: [] RowTimes: [6x1 datetime] StartTime: 18-Dec-2015 08:00:00 SampleRate: 2.7778e-04 TimeStep: 01:00:00 CustomProperties: No custom properties are set. Use addprop and rmprop to modify CustomProperties.
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 array
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
⋮
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
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
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
Create a regular timetable using a time step of 0.01 seconds. You must specify the time step as a duration or calendar duration 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
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
____________________ ____ ____ _________
27-Aug-2018 13:37:10 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
____________________ ___________ _________ _________
27-Aug-2018 13:37:10 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
____________________ ___________ _________ _________
27-Aug-2018 13:37:10 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.
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
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 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
Use single quotes for these input names:
'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.
For a list of functions that accept or return timetables, see Timetables.
Not recommended starting in R2018b
The 'SamplingRate'
name-value pair argument is not recommended.
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 pair. However,
the value is assigned to the SampleRate
property.
This function fully supports tall arrays with these usage notes.
Creation. There are several ways to create a tall timetable:
Convert an existing tall table using table2timetable
.
ds = datastore('data/folder/path.csv'); tt = tall(ds); TT = table2timetable(tt);
tt
for the row times. To specify the
row times yourself, use the 'RowTimes'
name-value
pair to specify either a tall datetime or a tall duration vector of
row times.TT = table2timetable(tt,'RowTimes',rowTimes)
Convert an existing tall array using
array2timetable
.
Manually construct a tall timetable from the variables
in a tall table using the timetable
constructor.
ds = datastore('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
and withtol
functions are supported for
indexing into tall timetables. The vartype
function is not supported.
Supported Functions. These functions support tall timetables.
For more information, see Tall Arrays.
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'}
)
All data variables must be distributed.
For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).
addprop
| array2timetable
| isvarname
| rmprop
| summary
| table
| table2timetable
| timetable2table
| uitable
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.
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: .
Select web siteYou can also select a web site from the following list:
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.