# table2timetable

Convert table to timetable

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

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

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

T=5×2 table
________    ________

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

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.

T=5×2 table
________    ________

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

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.

T=5×2 table
________    ________

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

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.

T=5×2 table
________    ________

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

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

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

expand all

Warns starting in R2021a