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 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, 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 Tables.
You can read data from a file into a table using the readtimetable function, or convert variables to timetables using the
array2timetable or table2timetable 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(
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 positive 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 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 specifies the data types of the variables.
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 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 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 |
| 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 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 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 the VariableNames property of the
timetable.
Variable names can have any Unicode® characters, including spaces and non-ASCII characters.
'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
timetableName.Properties.PropertyNamePropertyNameTT 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.
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.
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.
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.DimensionNamesans = 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.Propertiesans =
TimetableProperties with properties:
Description: ''
UserData: []
DimensionNames: {'Date' 'WeatherData'}
VariableNames: {'Var1' 'Var2' 'Var3'}
VariableDescriptions: {}
VariableUnits: {}
VariableContinuity: []
RowTimes: [3x1 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: 3x1 datetime
Values:
Min 18-Dec-2015
Median 19-Dec-2015
Max 20-Dec-2015
TimeStep 24:00:00
Variables:
Temp: 3x1 double
Values:
Min 37.3
Median 39.1
Max 42.3
Pressure: 3x1 double
Values:
Min 29.9
Median 30.03
Max 30.1
WindSpeed: 3x1 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.Propertiesans =
TimetableProperties with properties:
Description: ''
UserData: @(x)(5.0/9.0).*(x-32)
DimensionNames: {'Time' 'Variables'}
VariableNames: {'Temp' 'Pressure' 'WindSpeed'}
VariableDescriptions: {}
VariableUnits: {}
VariableContinuity: []
RowTimes: [3x1 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 a timetable.
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 timetable.
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 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: [3x1 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 37.3 13.4 {'N' }
11-Apr-2018 39.1 6.5 {'SE'}
12-Apr-2018 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: [5x1 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, 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.
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: 3x1 datetime
Values:
Min 18-Dec-2015
Median 19-Dec-2015
Max 20-Dec-2015
TimeStep 24:00:00
Variables:
Temp: 3x1 double
Properties:
Description: Temperature (external)
Values:
Min 37.3
Median 39.1
Max 42.3
Pressure: 3x1 double
Properties:
Description: Pressure in Hg
Values:
Min 29.9
Median 30.03
Max 30.1
WindSpeed: 3x1 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: 3x1 datetime
Values:
Min 18-Dec-2015
Median 19-Dec-2015
Max 20-Dec-2015
TimeStep 24:00:00
Variables:
Temp: 3x1 double
Properties:
Units: degrees F
Values:
Min 37.3
Median 39.1
Max 42.3
Pressure: 3x1 double
Properties:
Units: mm Hg
Values:
Min 29.9
Median 30.03
Max 30.1
WindSpeed: 3x1 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.Propertiesans =
TimetableProperties with properties:
Description: ''
UserData: []
DimensionNames: {'Time' 'Variables'}
VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'}
VariableDescriptions: {}
VariableUnits: {}
VariableContinuity: [continuous event event]
RowTimes: [3x1 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
timetableName.Properties.CustomProperties.PropertyNamePropertyNameaddprop.
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
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.Propertiesans =
TimetableProperties with properties:
Description: ''
UserData: []
DimensionNames: {'Time' 'Variables'}
VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'}
VariableDescriptions: {}
VariableUnits: {}
VariableContinuity: []
RowTimes: [3x1 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: [3x1 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.Propertiesans =
TimetableProperties with properties:
Description: ''
UserData: []
DimensionNames: {'Time' 'Variables'}
VariableNames: {'Temperature' 'WindSpeed' 'WindDirection'}
VariableDescriptions: {}
VariableUnits: {}
VariableContinuity: []
RowTimes: [3x1 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.Propertiesans =
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
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.Dataans = 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 Nth 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
____________________ ____ ____ _________
17-Aug-2020 15:25:22 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
____________________ ___________ _________ _________
17-Aug-2020 15:25:22 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
____________________ ___________ _________ _________
17-Aug-2020 15:25:22 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
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
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.
In certain cases, you can call timetable with a syntax
that specifies a regular time step between row times, and yet
timetable 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 row times that are leap seconds. This table specifies the row time values and time steps that can produce irregular timetables 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 row time occurring between 1:00 a.m. and 2:00 a.m. on a day shifting from DST to standard time (when row times are specified as datetime values whose time zone observes DST). | Number of calendar days or months. |
Any row time that is a leap second (when row times are specified as
datetime values whose time zone is the | Time step specified in any calendar unit (days, weeks, months, quarters, or years). |
Behavior changed in R2019b
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.
'SamplingRate' is not recommendedNot 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.
Usage notes and limitations:
The 'SampleRate', 'TimeStep', and
'StartTime' name-value pairs 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 with tall(ds).
The default behavior is to use the first datetime or duration
variable in the data for the row times. To specify the row times
yourself, use the RowTimes datastore property to
specify a tall datetime or a tall duration 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, and vartype 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.
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).
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 | rmprop | summary | table | table2timetable | timeseries | timetable2table | uitable
You have a modified version of this example. Do you want to open this example with your edits?