timetable

Timetable array with time-stamped rows and variables of different types

Description

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 Times in Timetable and Access Data in Tables.

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 the timeseries2timetable 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

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)

Description

Combine Existing Variables

TT = timetable(rowTimes,var1,...,varN) creates a timetable from the input data variables 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(var1,...,varN,'RowTimes',rowTimes) specifies 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(var1,...,varN,'SampleRate',Fs) uses the sample rate 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(var1,...,varN,'TimeStep',dt) uses the time step 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',sz,'VariableTypes',varTypes,'RowTimes',rowTimes) creates a timetable and preallocates space for the variables that have data types you specify. 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('Size',sz,'VariableTypes',varTypes,'SampleRate',Fs) preallocates variables with data types and adds row times using the sample rate Fs. The first row time is zero seconds.

TT = timetable('Size',sz,'VariableTypes',varTypes,'TimeStep',dt) preallocates variables with data types and adds row times using the time step dt. The first row time is zero seconds.

Set Names or Start Time

TT = timetable(___,Name,Value) specifies additional input arguments using one or more name-value pair arguments. For example, you can specify variable names using the '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', 'single'	Double- or single-precision 0
'doublenan', 'doubleNaN', 'singlenan', 'singleNaN'	Double- or single-precision NaN
'int8', 'int16', 'int32', 'int64'	Signed 8-, 16-, 32-, or 64-bit integer 0
'uint8', 'uint16', 'uint32', 'uint64'	Unsigned 8-, 16-, 32-, or 64-bit integer 0
'logical'	0 (false)
'categorical'	<undefined> categorical value
'datetime'	NaT datetime value
'duration'	0 seconds, as a duration value
'calendarDuration'	0 days, as a calendarDuration value
'string'	"" (1-by-1 string with no characters)
'cellstr'	{''} (cell with 0-by-0 character array)
'cell'	{[]} (cell with 0-by-0 double array)
'struct'	Scalar structure with no fields
'table'	Table with no variables
'timetable'	Timetable with no variables and NaT for row times

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

positive numeric scalar

Sample rate, specified as a positive 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.

Name-Value Pair Arguments

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.

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 the VariableNames 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 the DimensionNames 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 of TT are datetime values.

• If the start time is a duration value, then the row times are durations.

• If the time step dt is a calendarDuration value, then the start time must be a datetime 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 timetableName.Properties.PropertyName, where PropertyName is the name of a property. For example, you can access the names of the variables in the timetable 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'}
    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 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)

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) | 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'}
    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.

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 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.

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 of TT are datetime 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 a datetime 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'}
    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 rate

positive numeric scalar

Sample 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.

Example

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 a datetime vector.

• If you specify the time step as a duration value (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.

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'}
    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  

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   

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)

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 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)

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 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 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.

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'}
    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.

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 timetableName.Properties.CustomProperties.PropertyName. In this syntax, PropertyName is the name you chose when you added that property using 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 timetableName.Properties object.

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'}
    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.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>):
             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'}
    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.

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

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   
    ____________________    ____    ____    _________

    01-Sep-2021 09:50: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 
    ____________________    ___________    _________    _________

    01-Sep-2021 09:50: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 
    ____________________    ___________    _________    _________

    01-Sep-2021 09:50: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 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 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 the UTCLeapSeconds time zone). For the list of leap seconds, see leapseconds.	Time step specified in any calendar unit (days, weeks, months, quarters, or years).

Compatibility Considerations

Variable names can contain leading and trailing whitespace characters

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' will be removed

Warns starting in R2021a

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.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

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:

  1. 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.

  2. Convert an existing tall table using table2timetable.

  3. Convert an existing tall array using array2timetable.

  4. 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, ...)

  5. 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.

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).

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'})

• All data variables must be distributed.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).