table2timetable

Convert table to timetable

collapse all in page

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 Table to Timetable

Open Live Script

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×5 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×5 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×6 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

Specify Table Variable as Row Times

Open Live Script

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×5 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 Table with Separate Time Vector

Open Live Script

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

Specify Sample Rate

Open Live Script

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

Specify Time Step

Open Live Script

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

Specify Start Time

Open Live Script

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

`T` — Input table
table

Input table.

`timeVarName` — Name of variable from input table
character vector | string scalar

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

`rowTimes` — Row times assigned to output timetable
datetime vector | duration vector

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.

`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
datetime scalar | duration scalar

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

Data Types: datetime | duration | calendarDuration

`t0` — Start time
datetime scalar | duration scalar

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

`TT` — Output timetable
timetable

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

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

expand all

`'SamplingRate'` is not recommended

Not recommended starting in R2018b

The 'SamplingRate' name-value pair argument is not recommended. Use 'SampleRate' instead. The corresponding timetable property is also named SampleRate.

For backward compatibility, you still can specify 'SamplingRate' as the name of the name-value pair. However, the value is assigned to the SampleRate property.

Extended Capabilities

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

This function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

If you specify regular row times by using the 'SampleRate', 'TimeStep', or 'StartTime' name-value pair argument, then the value must be a constant at compile time for the row times to be regular. Otherwise, the row times are considered to be irregular in generated code.

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

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Documentation

table2timetable

Syntax

Description

Examples

Convert Table to Timetable

Specify Table Variable as Row Times

Convert Table with Separate Time Vector

Specify Sample Rate

Specify Time Step

Specify Start Time

Input Arguments

`T` — Input table
table

`timeVarName` — Name of variable from input table
character vector | string scalar

`rowTimes` — Row times assigned to output timetable
datetime vector | duration vector

`Fs` — Sample rate
positive numeric scalar

`dt` — Time step
datetime scalar | duration scalar

`t0` — Start time
datetime scalar | duration scalar

Output Arguments

`TT` — Output timetable
timetable

Tips

Compatibility Considerations

`'SamplingRate'` is not recommended

Extended Capabilities

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

See Also

Topics

MATLAB Documentation

Support

Documentation

table2timetable

Syntax

Description

Examples

Convert Table to Timetable

Specify Table Variable as Row Times

Convert Table with Separate Time Vector

Specify Sample Rate

Specify Time Step

Specify Start Time

Input Arguments

T — Input table table

timeVarName — Name of variable from input table character vector | string scalar

rowTimes — Row times assigned to output timetable datetime vector | duration vector

Fs — Sample rate positive numeric scalar

dt — Time step datetime scalar | duration scalar

t0 — Start time datetime scalar | duration scalar

Output Arguments

TT — Output timetable timetable

Tips

Compatibility Considerations

'SamplingRate' is not recommended

Extended Capabilities

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

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Distributed Arrays Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

See Also

Topics

MATLAB Documentation

Support

`T` — Input table
table

`timeVarName` — Name of variable from input table
character vector | string scalar

`rowTimes` — Row times assigned to output timetable
datetime vector | duration vector

`Fs` — Sample rate
positive numeric scalar

`dt` — Time step
datetime scalar | duration scalar

`t0` — Start time
datetime scalar | duration scalar

`TT` — Output timetable
timetable

`'SamplingRate'` is not recommended

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.