array2timetable

Convert homogeneous array to timetable

collapse all in page

Syntax

TT = array2timetable(X,'RowTimes',rowTimes)

TT = array2timetable(X,'SampleRate',Fs)

TT = array2timetable(X,'TimeStep',dt)

TT = array2timetable(___,'StartTime',t0)

TT = array2timetable(___,'VariableNames',varNames)

Description

example

TT = array2timetable(X,'RowTimes',rowTimes) converts X and rowTimes to a timetable. X is an M-by-N array and rowTimes is an M-by-1 vector of datetime or duration values. Each column of X becomes a variable of TT. The time values in rowTimes label the rows of the timetable. TT is an M-by-N timetable.

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

example

TT = array2timetable(X,'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 = array2timetable(X,'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 = array2timetable(___,'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

TT = array2timetable(___,'VariableNames',varNames) specifies the names of the variables in the output timetable. You can use this syntax with any of the input arguments of the previous syntaxes.

Examples

collapse all

Convert Array to Timetable

Open Live Script

Convert an array to a timetable. Add a vector of durations as the row times.

X = rand(5,3);
Time = seconds(1:5);
TT = array2timetable(X,'RowTimes',Time)

TT=5×3 timetable
    Time       X1         X2         X3   
    _____    _______    _______    _______

    1 sec    0.81472    0.09754    0.15761
    2 sec    0.90579     0.2785    0.97059
    3 sec    0.12699    0.54688    0.95717
    4 sec    0.91338    0.95751    0.48538
    5 sec    0.63236    0.96489    0.80028

Return the size of the timetable. TT contains five rows and three variables. The set of row times is a table property. The row times are not contained in a table variable.

size(TT)

ans = 1×2

     5     3

Specify Sample Rate

Open Live Script

Specify a sample rate of 500 Hz, and convert an array to a timetable.

X = rand(5,3);
TT = array2timetable(X,'SampleRate',500)

TT=5×3 timetable
      Time         X1         X2         X3   
    _________    _______    _______    _______

    0 sec        0.81472    0.09754    0.15761
    0.002 sec    0.90579     0.2785    0.97059
    0.004 sec    0.12699    0.54688    0.95717
    0.006 sec    0.91338    0.95751    0.48538
    0.008 sec    0.63236    0.96489    0.80028

Specify Time Step

Open Live Script

Specify a time step of 0.5 seconds, and convert an array to a timetable.

X = rand(5,3);
TT = array2timetable(X,'TimeStep',seconds(0.5))

TT=5×3 timetable
     Time        X1         X2         X3   
    _______    _______    _______    _______

    0 sec      0.81472    0.09754    0.15761
    0.5 sec    0.90579     0.2785    0.97059
    1 sec      0.12699    0.54688    0.95717
    1.5 sec    0.91338    0.95751    0.48538
    2 sec      0.63236    0.96489    0.80028

Specify Start Time

Open Live Script

Specify a time step of 15 seconds, and a start time of 5 minutes.

X = rand(5,3);
TT = array2timetable(X,'TimeStep',seconds(15),'StartTime',minutes(5))

TT=5×3 timetable
      Time        X1         X2         X3   
    ________    _______    _______    _______

    5 min       0.81472    0.09754    0.15761
    5.25 min    0.90579     0.2785    0.97059
    5.5 min     0.12699    0.54688    0.95717
    5.75 min    0.91338    0.95751    0.48538
    6 min       0.63236    0.96489    0.80028

Specify Variable Names

Open Live Script

Convert an array to a timetable. Specify the row times as a datetime vector. Specify names for the timetable variables.

X = randi([70 90],5,3);
Time = datetime(2016,7,1:5);
varNames = {'Temp1','Temp2','Temp3'};
TT = array2timetable(X,'RowTimes',Time,'VariableNames',varNames)

TT=5×3 timetable
       Time        Temp1    Temp2    Temp3
    ___________    _____    _____    _____

    01-Jul-2016     87       72       73  
    02-Jul-2016     89       75       90  
    03-Jul-2016     72       81       90  
    04-Jul-2016     89       90       80  
    05-Jul-2016     83       90       86

Input Arguments

collapse all

`X` — Input matrix
matrix

Input matrix.

`rowTimes` — Times associated with rows of timetable
datetime vector | duration vector

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

`varNames` — Names of variables
cell array of character vectors | string array

Names of the variables in the output timetable, specified as a cell array of character vectors or a string array. The number of names in varNames must equal the number of variables.

Variable names can have any Unicode^® characters, including spaces and non-ASCII characters.

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 section of timetable.

Tips

In certain cases, you can call array2timetable with a syntax that specifies a regular time step between row times, and yet array2timetable 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);
X = [1:3]';
TT = array2timetable(X,'TimeStep',tstep,'StartTime',stime)

TT =

  3×1 timetable

       Time        X
    ___________    _

    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

Variable names can contain leading and trailing whitespace characters

Behavior changed in R2019b

Table and timetable variable names with leading or trailing whitespace characters are not modified.

In previous releases, leading and trailing whitespace characters were deleted from variable names when you specified them using the 'VariableNames' name-value pair argument, or assigned them to the VariableNames property.

To manually remove such characters, first use the strtrim function on the names, then assign them as variable names to the table or timetable.

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

In generated code, you must specify the 'VariableNames' name-value pair argument when using this function.
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).

Documentation

array2timetable

Syntax

Description

Examples

Convert Array to Timetable

Specify Sample Rate

Specify Time Step

Specify Start Time

Specify Variable Names

Input Arguments

`X` — Input matrix
matrix

`rowTimes` — Times associated with rows of 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

`varNames` — Names of variables
cell array of character vectors | string array

Output Arguments

`TT` — Output timetable
timetable

Tips

Compatibility Considerations

Variable names can contain leading and trailing whitespace characters

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

See Also

Topics

MATLAB Documentation

Support

Documentation

array2timetable

Syntax

Description

Examples

Convert Array to Timetable

Specify Sample Rate

Specify Time Step

Specify Start Time

Specify Variable Names

Input Arguments

X — Input matrix matrix

rowTimes — Times associated with rows of 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

varNames — Names of variables cell array of character vectors | string array

Output Arguments

TT — Output timetable timetable

Tips

Compatibility Considerations

Variable names can contain leading and trailing whitespace characters

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

See Also

Topics

MATLAB Documentation

Support

`X` — Input matrix
matrix

`rowTimes` — Times associated with rows of 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

`varNames` — Names of variables
cell array of character vectors | string array

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