array2timetable - Convert homogeneous array to timetable - MATLAB (original) (raw)

Convert homogeneous array to timetable

Syntax

Description

[TT](#bvdhisw-TT) = array2timetable([X](#bvdhisw-X),'RowTimes',[rowTimes](#d126e55563)) converts an input array to a timetable. The input array X is anM-by-N array and the vectorrowTimes 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 anM-by-N timetable.

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

example

[TT](#bvdhisw-TT) = array2timetable([X](#bvdhisw-X),'SampleRate',[Fs](#d126e55585)) 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](#bvdhisw-TT) = array2timetable([X](#bvdhisw-X),'TimeStep',[dt](#d126e55605)) 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](#bvdhisw-TT) = array2timetable(___,'StartTime',[t0](#d126e55631)) 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

`T` = array2timetable([X](#bvdhisw-X),[Name,Value](#namevaluepairarguments)) creates a timetable from an array, X, with additional options specified by one or more Name,Value pair arguments.

For example, you can specify variable names to include in the timetable.

example

Examples

collapse all

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.

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

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

Input matrix.

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.

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

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

Data Types: 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, thent0 must be a datetime value.

Data Types: datetime | duration

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: TT = array2timetable(X,'RowTimes',Time,'VariableNames',{'Latitude','Longitude'}) creates a timetable from input array X, with row times specified by Time, and names the corresponding timetable variablesLatitude and Longitude.

Variable names, specified as a cell array of character vectors or a string array, whose elements are nonempty and distinct. The number of variable names must equal the number of columns of the input array.

Variable names can have any Unicode® characters, including spaces and non-ASCII characters. However, a variable name cannot match any table dimension name or the reserved names 'Properties', 'RowNames', 'VariableNames', or ':'.

Since R2021a

Dimension names, specified as a two-element cell array of character vectors or two-element string array whose elements are nonempty and distinct.

Dimension names can have any Unicode characters, including spaces and non-ASCII characters. However, a dimension name cannot match any table variable name or the reserved names'Properties', 'RowNames','VariableNames', or ':'.

As an alternative, in all releases you can specify dimension names by setting theDimensionNames property of the table.

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

Tips

In certain cases, you can call array2timetable with a syntax that specifies a regular time step between row times, and yetarray2timetable 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 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

expand all

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

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

Version History

Introduced in R2016b

expand all

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

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.