table2timetable

Convert table to timetable

Syntax

TT = table2timetable(T)
TT = table2timetable(T,'RowTimes',timeVarName)
TT = table2timetable(T,'RowTimes',rowTimes)
TT = table2timetable(T,'SampleRate',Fs)
TT = table2timetable(T,'TimeStep',dt)
TT = table2timetable(___,'StartTime',t0)

Description

example

TT = table2timetable(T) converts the table T to a timetable. The first datetime or duration variable in T becomes the vector of row times of TT. The remaining variables of T become the variables of TT.

  • If T is an M-by-N table without row names, then TT is an M-by-(N-1) timetable.

  • If T is an M-by-N table with row names, then table2timetable assigns the row names of T to a variable of TT. As a result, TT is an M-by-N timetable.

For more information on creating and using timetables, see Timetables.

To create a timetable from data in a text or spreadsheet file, first use the readtable function to read the data to a table. Then convert the table to a timetable with table2timetable.

example

TT = table2timetable(T,'RowTimes',timeVarName) assigns the table variable timeVarName as the vector of row times of the output timetable. timeVarName can be the name of any variable in T that contains datetime or duration values. The remaining variables of T become the variables of TT.

example

TT = table2timetable(T,'RowTimes',rowTimes) assigns the vector rowTimes as the vector of row times of the output timetable. All of the variables of T become variables of TT.

example

TT = table2timetable(T,'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.

example

TT = table2timetable(T,'TimeStep',dt) uses the time step 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.

example

TT = table2timetable(___,'StartTime',t0) specifies start time t0, instead of zero seconds, as the first row time. You can use this syntax when you create a regular timetable using either the 'SampleRate' or 'TimeStep' name-value pair arguments from either of the previous two syntaxes.

Examples

collapse all

Convert a table that contains dates and times to a timetable.

Read power outage data from the file outages.csv to a table. The table contains both outage and restoration times.

T = readtable('outages.csv');
T(1:5,:)
ans=5×6 table
      Region          OutageTime        Loss     Customers     RestorationTime           Cause      
    ___________    ________________    ______    __________    ________________    _________________

    'SouthWest'    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    'winter storm'   
    'SouthEast'    2003-01-23 00:49    530.14    2.1204e+05                 NaT    'winter storm'   
    'SouthEast'    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    'winter storm'   
    'West'         2004-04-06 05:44    434.81    3.4037e+05    2004-04-06 06:10    'equipment fault'
    'MidWest'      2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    'severe storm'   

Convert the table to a timetable. The first variable with times, OutageTime, becomes the time vector of TT.

TT = table2timetable(T);
TT(1:5,:)
ans=5×6 timetable
       OutageTime         Region        Loss     Customers     RestorationTime           Cause      
    ________________    ___________    ______    __________    ________________    _________________

    2002-02-01 12:18    'SouthWest'    458.98    1.8202e+06    2002-02-07 16:50    'winter storm'   
    2003-01-23 00:49    'SouthEast'    530.14    2.1204e+05                 NaT    'winter storm'   
    2003-02-07 21:15    'SouthEast'     289.4    1.4294e+05    2003-02-17 08:14    'winter storm'   
    2004-04-06 05:44    'West'         434.81    3.4037e+05    2004-04-06 06:10    'equipment fault'
    2002-03-16 06:18    'MidWest'      186.44    2.1275e+05    2002-03-18 23:23    'severe storm'   

Index into TT using row times from its time vector. You can treat the row times as labels that specify rows.

TT('2003-02-07 21:15',:)
ans=1×6 timetable
       OutageTime         Region       Loss     Customers     RestorationTime         Cause     
    ________________    ___________    _____    __________    ________________    ______________

    2003-02-07 21:15    'SouthEast'    289.4    1.4294e+05    2003-02-17 08:14    'winter storm'

Calculate the duration of power outages. Use dot syntax to extract the row times as a vector.

TT.OutageDuration = TT.RestorationTime - TT.OutageTime;
TT(1:5,:)
ans=5×7 timetable
       OutageTime         Region        Loss     Customers     RestorationTime           Cause          OutageDuration
    ________________    ___________    ______    __________    ________________    _________________    ______________

    2002-02-01 12:18    'SouthWest'    458.98    1.8202e+06    2002-02-07 16:50    'winter storm'         148:32:00   
    2003-01-23 00:49    'SouthEast'    530.14    2.1204e+05                 NaT    'winter storm'               NaN   
    2003-02-07 21:15    'SouthEast'     289.4    1.4294e+05    2003-02-17 08:14    'winter storm'         226:59:00   
    2004-04-06 05:44    'West'         434.81    3.4037e+05    2004-04-06 06:10    'equipment fault'       00:26:00   
    2002-03-16 06:18    'MidWest'      186.44    2.1275e+05    2002-03-18 23:23    'severe storm'          65:05:00   

Convert a table to a timetable and specify the table variable that becomes the time vector of the timetable.

Read power outage data from the file outages.csv to a table. The table contains both outage and restoration times.

T = readtable('outages.csv');
T(1:5,:)
ans=5×6 table
      Region          OutageTime        Loss     Customers     RestorationTime           Cause      
    ___________    ________________    ______    __________    ________________    _________________

    'SouthWest'    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    'winter storm'   
    'SouthEast'    2003-01-23 00:49    530.14    2.1204e+05                 NaT    'winter storm'   
    'SouthEast'    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    'winter storm'   
    'West'         2004-04-06 05:44    434.81    3.4037e+05    2004-04-06 06:10    'equipment fault'
    'MidWest'      2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    'severe storm'   

Convert the table to a timetable. Specify the second variable with dates and times, RestorationTime, as the time vector of the timetable.

TT = table2timetable(T,'RowTimes','RestorationTime');
TT(1:5,:)
ans=5×6 timetable
    RestorationTime       Region          OutageTime        Loss     Customers           Cause      
    ________________    ___________    ________________    ______    __________    _________________

    2002-02-07 16:50    'SouthWest'    2002-02-01 12:18    458.98    1.8202e+06    'winter storm'   
    NaT                 'SouthEast'    2003-01-23 00:49    530.14    2.1204e+05    'winter storm'   
    2003-02-17 08:14    'SouthEast'    2003-02-07 21:15     289.4    1.4294e+05    'winter storm'   
    2004-04-06 06:10    'West'         2004-04-06 05:44    434.81    3.4037e+05    'equipment fault'
    2002-03-18 23:23    'MidWest'      2002-03-16 06:18    186.44    2.1275e+05    'severe storm'   

Convert a table to a timetable by adding a separate time vector that contains the row times. All the table variables become variables of the timetable.

Reading1 = [98;97.5;97.9;98.1;97.9];
Reading2 = [120;111;119;117;116];
T = table(Reading1,Reading2)
T=5×2 table
    Reading1    Reading2
    ________    ________

        98        120   
      97.5        111   
      97.9        119   
      98.1        117   
      97.9        116   

Time = [seconds(1):seconds(1):seconds(5)];
TT = table2timetable(T,'RowTimes',Time)
TT=5×3 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   

Create a table.

Reading1 = [98;97.5;97.9;98.1;97.9];
Reading2 = [120;111;119;117;116];
T = table(Reading1,Reading2)
T=5×2 table
    Reading1    Reading2
    ________    ________

        98        120   
      97.5        111   
      97.9        119   
      98.1        117   
      97.9        116   

Specify a sample rate of 500 Hz. Convert T to a timetable using that sample rate and a starting row time of zero seconds.

TT = table2timetable(T,'SampleRate',500)
TT=5×3 timetable
      Time       Reading1    Reading2
    _________    ________    ________

    0 sec            98        120   
    0.002 sec      97.5        111   
    0.004 sec      97.9        119   
    0.006 sec      98.1        117   
    0.008 sec      97.9        116   

Create a table.

Reading1 = [98;97.5;97.9;98.1;97.9];
Reading2 = [120;111;119;117;116];
T = table(Reading1,Reading2)
T=5×2 table
    Reading1    Reading2
    ________    ________

        98        120   
      97.5        111   
      97.9        119   
      98.1        117   
      97.9        116   

Specify a time step of ten seconds, using the seconds function. Convert T to a timetable using that sampling rate and a starting row time of zero seconds.

TT = table2timetable(T,'TimeStep',seconds(10))
TT=5×3 timetable
      Time      Reading1    Reading2
    ________    ________    ________

    00:00:00        98        120   
    00:00:10      97.5        111   
    00:00:20      97.9        119   
    00:00:30      98.1        117   
    00:00:40      97.9        116   

Create a table.

Reading1 = [98;97.5;97.9;98.1;97.9];
Reading2 = [120;111;119;117;116];
T = table(Reading1,Reading2)
T=5×2 table
    Reading1    Reading2
    ________    ________

        98        120   
      97.5        111   
      97.9        119   
      98.1        117   
      97.9        116   

Convert it to a timetable by specifying a time step of ten seconds and a start time of 5 seconds.

dt = seconds(10);
t0 = seconds(5);
TT = table2timetable(T,'TimeStep',dt,'StartTime',t0)
TT=5×3 timetable
     Time     Reading1    Reading2
    ______    ________    ________

    5 sec         98        120   
    15 sec      97.5        111   
    25 sec      97.9        119   
    35 sec      98.1        117   
    45 sec      97.9        116   

Input Arguments

collapse all

Input table.

Name of a variable from the input table, specified as a character vector or a string scalar.

Row times assigned to the output timetable, specified as a datetime vector or a duration vector. The number of elements of rowTimes must equal the number of rows of the input table. The time values in rowTimes do not need to be unique, sorted, or regular.

Sample rate, specified as a positive numeric scalar. Fs specifies the number of samples per second (Hz).

Time step, specified as a datetime scalar or duration scalar.

Data Types: datetime | duration | calendarDuration

Start time, specified as a datetime scalar or duration scalar.

  • If t0 is a datetime value, then the row times of TT are datetime values.

  • If t0 is a duration, then the row times are durations.

If the time step dt is a calendar duration value, then t0 must be a datetime value.

Data Types: datetime | duration

Output Arguments

collapse all

Output timetable. The timetable can store metadata such as descriptions, variable units, variable names, and row times. For more information, see the Properties sections of timetable.

Tips

  • In certain cases, you can call table2timetable with a syntax that specifies a regular time step between row times, and yet table2timetable 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);
    T = table([1:3]');
    TT = table2timetable(T,'TimeStep',tstep,'StartTime',stime)
    
    TT =
    
      3×1 timetable
    
           Time        Var1
        ___________    ____
    
        31-Jan-2019     1  
        28-Feb-2019     2  
        31-Mar-2019     3  
    
    

    In addition, 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 UTCLeapSecond time zone)

    Time step specified in any calendar unit (days, weeks, months, quarters, or years)

Compatibility Considerations

expand all

Not recommended starting in R2018b

Extended Capabilities

Introduced in R2016b