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

TT = table2timetable(T) converts the input table 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, use the readtimetable function.

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

example

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` — Variable from input table
character vector | string scalar | numeric index

Variable from the input table, specified as a character vector, string scalar, or numeric index.

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

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

`dt` — Time step
duration scalar | calendar duration scalar

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

Data Types: 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 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).

Extended Capabilities

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

The table2timetable function supports tall arrays with the following usage notes and limitations:

The 'SampleRate', 'TimeStep', and 'StartTime' name-value arguments are not supported.

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 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.
If the input table has a nonempty value for the UserData property, then the output does not include it. The UserData property of the output timetable is always empty.

For more information, see Code Generation for Timetables (MATLAB Coder) and Timetable Limitations for Code Generation (MATLAB Coder).

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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

Usage notes and limitations:

The 'SampleRate', 'TimeStep', and 'StartTime' name-value arguments are not supported.

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

Version History

Introduced in R2016b

expand all

R2021a: `'SamplingRate'` will be removed

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.

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` — Variable from input table
character vector | string scalar | numeric index

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

`Fs` — Sample rate
numeric scalar

`dt` — Time step
duration scalar | calendar duration scalar

`t0` — Start time
datetime scalar | duration scalar

Output Arguments

`TT` — Output timetable
timetable

Tips

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

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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

Version History

R2021a: `'SamplingRate'` will be removed

See Also

Topics

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 — Variable from input table character vector | string scalar | numeric index

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

Fs — Sample rate numeric scalar

dt — Time step duration scalar | calendar duration scalar

t0 — Start time datetime scalar | duration scalar

Output Arguments

TT — Output timetable timetable

Tips

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

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

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

Version History

R2021a: 'SamplingRate' will be removed

See Also

Topics

`T` — Input table
table

`timeVarName` — Variable from input table
character vector | string scalar | numeric index

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

`Fs` — Sample rate
numeric scalar

`dt` — Time step
duration scalar | calendar duration scalar

`t0` — Start time
datetime scalar | duration scalar

`TT` — Output timetable
timetable

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

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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

R2021a: `'SamplingRate'` will be removed