Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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 can store column-oriented data variables that have different data types and sizes, as long as they have the same number of rows. In addition, timetables provide time-specific functions to align, combine, and perform calculations with one or more timetables.

The row times of a timetable are datetime or duration values that label the rows. You can index into a timetable by row time and variable. To index into a timetable, use smooth parentheses () to return a subtable or curly braces {} to extract the contents. You can reference variables and the vector of row times using names. For more information on indexing, see Select Timetable Data by Row Time and Variable Type and Access Data in a Table.

Creation

To create a timetable from a table or an array, use the table2timetable or array2timetable functions. Alternatively, you can use the timetable function described below.

Syntax

TT = timetable(rowTimes,var1,...,varN)
TT = timetable(var1,...,varN,'RowTimes',rowTimes)
TT = timetable(___,'VariableNames',{varName1,...,varNameN})

Description

example

TT = timetable(rowTimes,var1,...,varN) creates a timetable from the input data variables var1,...,varN and the time vector rowTimes. The data variables can be different sizes and data types as long as they have the same number of rows. rowTimes must be a datetime or duration vector, also with the same number of rows.

example

TT = timetable(var1,...,varN,'RowTimes',rowTimes) creates a timetable from the input data variables var1,...,varN and the time vector rowTimes.

example

TT = timetable(___,'VariableNames',{varName1,...,varNameN}) creates a timetable and assigns the variables the names varName1,...,varNameN. The variable names must be unique, valid MATLAB® identifiers in a cell array. You can use this syntax with any of the input arguments of the previous syntaxes.

Input Arguments

expand all

Input variables, specified as arrays with the same number of rows. The input variables can be of different sizes and different data types, as long as they have the same number of rows.

Common input variables are numeric arrays, logical arrays, string arrays, structure arrays, or 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.

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

Properties

expand all

Access properties using the form timetableName.Properties.PropertyName. For example, create a timetable and rename its variables using the VariableNames property.

Time = seconds([5;10]);
TT = timetable(Time,[10;20],{'M';'F'});
TT.Properties.VariableNames = {'Age','Gender'}

Return a summary of all properties using timetableName.Properties.

TT.Properties

You also can concatenate all the timetable variables into an array using timetableName.Variables. This syntax returns the same array as the timetableName{:,:} syntax.

Timetable Metadata

Variable names, specified as a cell array of character vectors that are nonempty and distinct. Variable names must be valid MATLAB variable names. The number of character vectors must equal the number of variables. MATLAB removes any leading or trailing white space from the character vectors.

If valid MATLAB identifiers are not available for use as variable names, MATLAB uses a cell array of N character vectors of the form {'Var1' ... 'VarN'} where N is the number of variables. You can determine valid MATLAB variable names using the function isvarname.

The variable names are visible when viewing the timetable and when using the summary function. Furthermore, you can use the variable names within parentheses, within curly braces, or with dot indexing to access timetable data.

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 =

  3x3 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 =

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

Row times, specified as a datetime vector or duration vector. There must be a row time for every row of the timetable. However, a timetable can have row times that are duplicates, out of order, or NaT or NaN values.

The row times are visible when you view the timetable. Furthermore, you can use the row times within parentheses or curly braces to access the timetable data.

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 =

  3x3 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 =

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

Dimension names, specified as a two-element cell array of character vectors.

Example

Create a timetable. Modify the names of its dimensions using the Properties.DimensionNames property. The first dimension is the name of the vector of row times.

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 = {'Date' 'WeatherData'};
TT.Properties
ans = 

  struct with fields:

             Description: ''
                UserData: []
          DimensionNames: {'Date'  'WeatherData'}
           VariableNames: {'Var1'  'Var2'  'Var3'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3x1 datetime]

Timetable description, specified as a character vector. This description is visible when using the summary function.

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       

Variable descriptions, specified as a cell array of character vectors. This property can be an empty cell array, which is the default. If the cell array is not empty, the number of character vectors must equal the number of variables. You can specify an individual empty character vector within the cell array for a variable that does not have a description.

The variable descriptions are visible when using the summary function.

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

        Description:  Temperature (external)
        Values:

            Min       37.3  
            Median    39.1  
            Max       42.3  

    Pressure: 3x1 double

        Description:  Pressure in Hg
        Values:

            Min        29.9     
            Median    30.03     
            Max        30.1     

    WindSpeed: 3x1 double

        Description:  Wind speed at sensor 123
        Values:

            Min        6.5       
            Median     7.3       
            Max       13.4       

Variable units, specified as a cell array of character vectors. This property can be an empty cell array, which is the default. If the cell array is not empty, the number of character vectors must equal the number of variables. You can specify an individual empty character vector within the cell array for a variable that does not have units.

The variable units are visible when using the summary function.

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

        Units:  degrees F
        Values:

            Min       37.3  
            Median    39.1  
            Max       42.3  

    Pressure: 3x1 double

        Units:  mm Hg
        Values:

            Min        29.9     
            Median    30.03     
            Max        30.1     

    WindSpeed: 3x1 double

        Units:  mph
        Values:

            Min        6.5       
            Median     7.3       
            Max       13.4       

Status as continuous or discrete variables, specified as a cell array of character vectors. This property can be an empty array, which is the default. If the array is not empty, then the number of elements must equal the number of variables. The values that you specify can be either 'unset', 'continuous', 'step', or 'event'.

If you specify VariableContinuity and call the retime or synchronize functions, 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 = 

  struct with fields:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temperature'  'WindSpeed'  'WindDirection'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: [continuous    event    event]
                RowTimes: [3×1 datetime]

Additional timetable information, specified as a variable containing information in any data type.

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 = 

  struct with fields:

             Description: ''
                UserData: @(x)(5.0/9.0).*(x-32)
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temp'  'Pressure'  'WindSpeed'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3x1 datetime]

Examples

expand all

Create a timetable from workspace variables that contain times as well as temperature, pressure, and wind speed and direction measurements. The values in Time become the row times of the timetable. All the other workspace variables become the timetable variables.

Time = 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];
WindDirection = categorical({'NW';'N';'NW'});
TT = timetable(Time,Temp,Pressure,WindSpeed,WindDirection)
TT=3x4 timetable
            Time            Temp    Pressure    WindSpeed    WindDirection
    ____________________    ____    ________    _________    _____________

    18-Dec-2015 08:03:05    37.3     30.1       13.4         NW           
    18-Dec-2015 10:03:17    39.1    30.03        6.5         N            
    18-Dec-2015 12:03:13    42.3     29.9        7.3         NW           

Create a timetable from workspace variables that contain dates as well as temperature, pressure, and precipitation readings, and the durations of storms on those dates. Specify Date as the vector of row times.

Date = datetime({'2015-12-18';'2015-12-18';'2015-12-18'});
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',Date)
TT=3x4 timetable
        Time       Temp    Pressure    Precip    StormDuration
    ___________    ____    ________    ______    _____________

    18-Dec-2015    37.3    29.4        0.1         1 hr       
    18-Dec-2015    39.1    29.6        0.9         2 hr       
    18-Dec-2015    42.3      30          0       NaN hr       

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=5x2 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     

Tips

  • For a list of functions that accept or return timetables, see Timetables.

Extended Capabilities

Introduced in R2016b

Was this topic helpful?