Documentation

This is machine translation

Mouseover text to see original. Click the button below to return to the English version of the page.

array2timetable

Convert homogeneous array to timetable

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 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×4 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 a sample rate of 500 Hz, and convert an array to a timetable.

```X = rand(5,3); TT = array2timetable(X,'SampleRate',500)```
```TT=5×4 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×4 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×4 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×4 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.

Data Types: `double` | `single` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `logical` | `char` | `string` | `categorical` | `datetime` | `duration` | `calendarDuration`
Complex Number Support: Yes

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

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.

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

In addition, 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 `UTCLeapSecond` time zone)

Time step specified in any calendar unit (days, weeks, months, quarters, or years)

Compatibility Considerations

expand all

Not recommended starting in R2018b