timetable

时间序列数据表，具有带时间戳的行和不同类型的变量

说明

timetable 是一种特定类型的表，表中的每一行关联一个时间，这些时间与时间序列数据一起使用。与表一样，时间表存储具有不同数据类型和大小的列向数据变量，只要它们具有相同的行数即可。此外，还有特定于时间的函数，可对一个或多个时间表中的带时间戳的数据进行对齐、合并以及执行计算，例如 retime 和 synchronize 函数。

时间表的行时间是标记行的 datetime 或 duration 值。您可以按行时间和变量对时间表进行索引。有关进行索引的详细信息，请参阅在时间表中选择时间和访问表中的数据。

要查找并标记时间表中的事件，请将事件表附加到时间表。事件表列出事件发生的时间以及事件标签和其他有关事件的信息。有关详细信息，请参阅 eventtable。 (自 R2023a 起)

您可以直接对时间表执行数学运算，如 +、.* 和 mean。有关详细信息，请参阅 Direct Calculations on Tables and Timetables。 (自 R2023a 起)

创建对象

要创建时间表，可以使用 readtimetable 函数将文件中的数据读取到一个表中，也可以转换具有其他数据类型的变量。

要转换：

数组，请使用 array2timetable 函数。
表，请使用 table2timetable 函数。
timeseries 对象，请使用 timeseries2timetable 函数。

Simulink^® 用户可以使用 extractTimetable (Simulink) 函数从 Simulink.SimulationData.Dataset 对象中提取数据。

也可以使用 timetable 函数，如下所述。从输入数组创建一个时间表，或为稍后填充值的变量预分配空间。要指定行时间，可以使用行时间的输入向量，也可以使用采样率或时间步来创建行时间。

语法

TT = timetable(rowTimes,var1,...,varN)

TT = timetable(var1,...,varN,'RowTimes',rowTimes)

TT = timetable(var1,...,varN,'SampleRate',Fs)

TT = timetable(var1,...,varN,'TimeStep',dt)

TT = timetable('Size',sz,'VariableTypes',varTypes,'RowTimes',rowTimes)

TT = timetable('Size',sz,'VariableTypes',varTypes,'SampleRate',Fs)

TT = timetable('Size',sz,'VariableTypes',varTypes,'TimeStep',dt)

TT = timetable(___,Name,Value)

描述

合并现有变量

TT = timetable(rowTimes,var1,...,varN) 根据输入数据变量 var1,...,varN 和时间向量 rowTimes 创建时间表。数据变量的大小和类型可以不同，但行数必须相同。rowTimes 必须为 datetime 或 duration 向量，并且具有相同的行数。

示例

TT = timetable(var1,...,varN,'RowTimes',rowTimes) 将 rowTimes 指定为 TT 的行时间的来源。当使用此语法时，TT 的行时间向量的名称始终为 Time，即使 rowTimes 是具有不同名称的工作区变量时也是如此。

示例

TT = timetable(var1,...,varN,'SampleRate',Fs) 使用采样率 Fs 计算固定间隔的行时间。Fs 是一个数值标量，用于指定每秒采样数 (Hz)。第一个行时间是零秒。

示例

TT = timetable(var1,...,varN,'TimeStep',dt) 使用时间步 dt 计算固定间隔的行时间。dt 是一个 duration 或 calendarDuration 值，用于指定连续行时间之间的时间长度。第一个行时间是零秒。

示例

预分配空间

TT = timetable('Size',sz,'VariableTypes',varTypes,'RowTimes',rowTimes) 创建一个时间表并为具有您指定的数据类型的变量预分配空间。sz 是二元素数值数组，其中 sz(1) 指定行数，sz(2) 指定变量数。varTypes 指定变量的数据类型。rowTimes 中的时间的数量必须等于 sz(1)。

示例

TT = timetable('Size',sz,'VariableTypes',varTypes,'SampleRate',Fs) 预分配具有数据类型的变量，并使用采样率 Fs 添加行时间。第一个行时间是零秒。

示例

TT = timetable('Size',sz,'VariableTypes',varTypes,'TimeStep',dt) 预分配具有数据类型的变量，并使用时间步 dt 添加行时间。第一个行时间是零秒。

示例

设置名称或开始时间

TT = timetable(___,Name,Value) 使用一个或多个名称-值对组参量指定其他输入参量。例如，您可以使用 'VariableNames' 名称-值对组指定变量名称。您还可以使用具有采样率或时间步的 'StartTime' 名称-值对组指定开始时间。您可将此语法与上述语法中的任何输入参量一起使用。

示例

输入参量

全部展开

`var1,...,varN` — 输入变量
数组

输入变量，指定为具有相同行数的数组。输入变量的大小和数据类型可以不同，但行数必须相同。

常见的输入变量为数值数组、逻辑数组、字符串数组、结构体数组和元胞数组。

输入变量也可以是数组对象。此类数组必须支持 var(index1,...,indexN) 形式的索引，其中 index1 为与变量 var 的行对应的数值或逻辑向量。此外，该数组还必须使用 dim 参量实现 vertcat 方法和 size 方法。

`rowTimes` — 与时间表的行相关联的时间
`datetime` 向量 | `duration` 向量

与时间表的行相关联的时间，指定为 datetime 向量或 duration 向量。每个时间标记输出时间表 TT 中的一行。rowTimes 中的时间值不需要唯一、排序或有规律。

`sz` — 预分配的时间表的大小
二元素数值向量

预分配的时间表的大小，指定为二元素数值向量。sz 的第一个元素指定行数，第二个元素指定时间表变量的数量。

`varTypes` — 预分配变量的数据类型
字符向量元胞数组 | 字符串数组

预分配变量的数据类型，指定为字符向量元胞数组或字符串数组。由 varTypes 指定的类型的数量必须等于由 sz 的第二个元素指定的变量的数量。

varTypes 可以包含任何数据类型的名称，包括表中显示的名称。

数据类型名称	每个元素中的初始值
`'double'`, `'single'`	双精度或单精度 `0`
`'doublenan'`, `'doubleNaN'`, `'singlenan'`, `'singleNaN'`	双精度或单精度 `NaN`
`'int8'`, `'int16'`, `'int32'`, `'int64'`	有符号 8 位、16 位、32 位或 64 位整数 `0`
`'uint8'`, `'uint16'`, `'uint32'`, `'uint64'`	无符号 8 位、16 位、32 位或 64 位整数 `0`
`'logical'`	`0` (`false`)
`'categorical'`	`<undefined>` 分类值
`'datetime'`	`NaT` `datetime` 值
`'duration'`	`0` 秒，作为 `duration` 值
`'calendarDuration'`	`0` 天，作为 `calendarDuration` 值
`'string'`	`<missing>`（缺失字符串）
`'cellstr'`	`{''}`（具有 0×0 字符数组的元胞）
`'cell'`	`{[]}`（具有 0×0 双精度数组的元胞）
`'struct'`	没有字段的标量结构体
`'table'`	没有变量的表
`'timetable'`	没有变量的时间表，行时间为 `NaT`

对于任何其他数据类型，初始值是该类型或类用于“填充”数组的未分配元素的值。

如果将 'char' 指定为数据类型，则 timetable 会将对应的变量预分配为字符向量元胞数组，而不是字符数组。最佳做法是避免创建字符数组形式的表或时间表变量。处理表或时间表中的文本数据时，请考虑使用字符串数组或分类数组。

`Fs` — 采样率
数值标量

采样率，指定为数值标量。Fs 指定每秒采样数 (Hz)。

`dt` — 时间步
`duration` 标量 | `calendarDuration` 标量

时间步，指定为 duration 标量或 calendarDuration 标量。

如果您将 dt 指定为 calendarDuration，并指定 'StartTime' 名称-值对组参量，则 'StartTime' 的值必须是 datetime 标量。

名称-值参数

全部展开

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但对各个参量对组的顺序没有要求。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: TT = timetable(rowTimes,T,W,'VariableNames',{'Temperature','WindSpeed'}) 基于输入数组 T 和 W 创建时间表，并命名对应的时间表变量 Temperature 和 WindSpeed。

`VariableNames` — 变量名称
字符向量元胞数组 | 字符串数组

变量名称，指定为字符向量元胞数组或字符串数组，其元素为非空且不同。

数组中的名称的数量必须等于时间表变量的数量。
timetable 函数还将变量名称存储在时间表的 VariableNames 属性中。
变量名称可以包含任何 Unicode^® 字符，包括空格和非 ASCII 字符。

`DimensionNames` — 维度名称
二元素字符向量元胞数组 | 二元素字符串数组

自 R2021a 起

维度名称，指定为二元素字符向量元胞数组或二元素字符串数组，其元素为非空且不同。

timetable 函数还将维度名称存储在时间表的 DimensionNames 属性中。
维度名称可以包含任何 Unicode 字符，包括空格和非 ASCII 字符。

在 R2021a 之前，只能通过设置 DimensionNames 属性来指定维度名称。

`StartTime` — 开始时间
`datetime` 标量 | `duration` 标量

开始时间，指定为 datetime 标量或 duration 标量。开始时间也是时间表的第一行的行时间。

仅当您还指定 'SampleRate' 或 'TimeStep' 名称-值对组参量时，才能指定 'StartTime'。

如果开始时间是 datetime 值，则 TT 的行时间是 datetime 值。
如果开始时间是 duration 值，则行时间是持续时间。
如果时间步 dt 是 calendarDuration 值，则开始时间必须为 datetime 值。

属性

全部展开

访问时间表元数据属性

时间表包含描述时间表、其行时间及其变量的元数据属性。使用语法 timetableName.Properties.PropertyName 访问这些属性，其中 PropertyName 是属性的名称。例如，您可以通过 TT.Properties.VariableNames 属性访问时间表 TT 中变量的名称。

您可以使用语法 timetableName.Properties 返回元数据属性的摘要。

时间表通过 Properties 属性提供元数据访问，因为您可以使用圆点语法直接访问时间表数据。例如，如果时间表 TT 有名为 Var1 的变量，则可以使用语法 TT.Var1 访问该变量中的值。

时间表元数据

`DimensionNames` — 维度名称
`{'Time','Variables'}` (默认) | 二元素字符向量元胞数组 | 二元素字符串数组

维度名称，指定为二元素字符向量元胞数组或二元素字符串数组，其元素为非空且不同。

维度名称可以包含任何 Unicode 字符，包括空格和非 ASCII 字符。
如果使用字符串数组指定此属性，则将其转换并存储为字符向量元胞数组。

您可以使用这两个维度名称访问时间表数据。

如果使用圆点语法和第一个维度名称，则可以将行时间作为向量来访问。
如果使用圆点语法和第二个维度名称，则会将所有变量的数据串联在一个数组中，就像已使用 {:,:} 语法对时间表进行索引一样。

示例

创建时间表并显示其维度名称。您可以结合使用圆点语法和维度名称来访问行时间和数据。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]);
TT.Properties.DimensionNames

ans = 1×2 cell
    {'Time'}    {'Variables'}

使用第一个维度名称访问行时间。

TT.Time

ans = 3×1 datetime
   18-Dec-2015
   19-Dec-2015
   20-Dec-2015

使用第二个维度名称访问数据。此语法等效于 TT{:,:,}。

TT.Variables

ans = 3×3

   37.3000   30.1000   13.4000
   39.1000   30.0300    6.5000
   42.3000   29.9000    7.3000

使用 Properties.DimensionNames 属性修改其维度的名称。更改维度名称后，可以分别使用语法 TT.Date 和 TT.WeatherData 访问行时间和数据。

TT.Properties.DimensionNames = {'Date','WeatherData'};
TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Date'  'WeatherData'}
           VariableNames: {'Var1'  'Var2'  'Var3'}
           VariableTypes: ["double"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3×1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: 1d
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

`Description` — 时间表描述
`''` (默认) | 字符向量 | 字符串标量

时间表描述，指定为字符向量或字符串标量。使用 summary 函数时，此描述是可见的。

如果使用字符串标量指定此属性，则将其转换并存储为字符向量。

示例

创建一个时间表。修改变量名称和时间表的描述。显示结果摘要。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]);
TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'};
TT.Properties.Description = 'Weather Data from December 2015';
summary(TT)

TT: 3×3 timetable

Description: Weather Data from December 2015

Row Times:

    Time: datetime

Variables:

    Temp: double
    Pressure: double
    WindSpeed: double

Statistics for applicable variables and row times:

                 NumMissing          Min              Median               Max               Mean              Std     

    Time             0           18-Dec-2015        19-Dec-2015        20-Dec-2015        19-Dec-2015        24:00:00  
    Temp             0               37.3000            39.1000            42.3000            39.5667          2.5325  
    Pressure         0               29.9000            30.0300            30.1000            30.0100          0.1015  
    WindSpeed        0                6.5000             7.3000            13.4000             9.0667          3.7740

`UserData` — 其他时间表信息
`[]` (默认) | 数组

其他时间表信息，指定为数组。您可以使用此属性将任何种类的数据附加到时间表。

示例

创建一个时间表。修改变量名称。将匿名函数作为与时间表相关联的一段用户数据附加。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]);
TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'};
Fahrenheit2Celsius = @(x) (5.0/9.0).*(x - 32);
TT.Properties.UserData = Fahrenheit2Celsius;
TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: @(x)(5.0/9.0).*(x-32)
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temp'  'Pressure'  'WindSpeed'}
           VariableTypes: ["double"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3×1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: 1d
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

行时间元数据

`RowTimes` — 行时间
`datetime` 向量 | `duration` 向量

行时间，指定为 datetime 向量或 duration 向量。

时间表的每一行都必须有一个行时间。
时间表的行时间可以是重复的、无序的，还可以包含 NaT 或 NaN 值。
查看时间表时，行时间是可见的。此外，您也可以在圆括号或花括号中使用行时间来访问时间表数据。
访问行时间的另一种方法是使用圆点语法和时间表的第一个维度的名称。

示例

创建一个时间表。然后使用 Properties.RowTimes 属性替换行时间。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3])

TT=3×3 timetable
       Time        Var1    Var2     Var3
    ___________    ____    _____    ____

    18-Dec-2015    37.3     30.1    13.4
    19-Dec-2015    39.1    30.03     6.5
    20-Dec-2015    42.3     29.9     7.3

Dates = datetime(2017,1,1:3);
TT.Properties.RowTimes = Dates

TT=3×3 timetable
       Time        Var1    Var2     Var3
    ___________    ____    _____    ____

    01-Jan-2017    37.3     30.1    13.4
    02-Jan-2017    39.1    30.03     6.5
    03-Jan-2017    42.3     29.9     7.3

访问行时间的另一种方法是使用圆点语法和时间表的第一个维度的名称。

TT.Properties.DimensionNames

ans = 1×2 cell
    {'Time'}    {'Variables'}

TT.Time

ans = 3×1 datetime
   01-Jan-2017
   02-Jan-2017
   03-Jan-2017

`StartTime` — 行时间的开始时间
`datetime` 标量 | `duration` 标量

行时间的开始时间，指定为 datetime 标量或 duration 标量。开始时间等于时间表第一行的行时间，并且具有相同的数据类型。

如果开始时间是 datetime 值，则 TT 的行时间是 datetime 值。
如果开始时间是 duration 值，则行时间是持续时间。
如果时间步是 calendarDuration 值，则开始时间必须为 datetime 值。

如果时间表为空，则开始时间为 NaN。

示例

创建一个时间表。在此时间表中，连续行之间的时间步不同，因此时间表不规则。

TT = timetable(datetime({'2015-12-18';'2015-12-20';'2015-12-21'}), ...
               [37.3;39.1;42.3],[13.4;6.5;7.3],{'N';'SE';'NW'});
TT.Properties.VariableNames = {'Temperature','WindSpeed','WindDirection'}

TT=3×3 timetable
       Time        Temperature    WindSpeed    WindDirection
    ___________    ___________    _________    _____________

    18-Dec-2015       37.3          13.4          {'N' }    
    20-Dec-2015       39.1           6.5          {'SE'}    
    21-Dec-2015       42.3           7.3          {'NW'}

显示其属性。StartTime 属性的值等于第一个行时间。无论时间表是规则的还是不规则的，它始终有开始时间，除非它为空。

TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temperature'  'WindSpeed'  'WindDirection'}
           VariableTypes: ["double"    "double"    "cell"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3×1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

修改 StartTime 属性。请注意，所有行时间都有新值。对于每个行时间，值的变化等于第一个行时间的原始值与新开始时间之间的差。

TT.Properties.StartTime = datetime('2018-04-09')

TT=3×3 timetable
       Time        Temperature    WindSpeed    WindDirection
    ___________    ___________    _________    _____________

    09-Apr-2018       37.3          13.4          {'N' }    
    11-Apr-2018       39.1           6.5          {'SE'}    
    12-Apr-2018       42.3           7.3          {'NW'}

`SampleRate` — 采样率
数值标量

采样率，指定为数值标量。采样率是每秒采样数 (Hz)。

如果行时间不规则，或时间表为空，则采样率为 NaN。

示例

创建规则时间表。在此时间表中，行时间是使用相同采样率创建的持续时间。

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'SampleRate',100)

TT=5×1 timetable
      Time      Intensity
    ________    _________

    0 sec           100  
    0.01 sec       98.7  
    0.02 sec       95.2  
    0.03 sec      101.4  
    0.04 sec       99.1

显示其属性。SampleRate 属性存储以 Hz 为单位的采样率。

TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Intensity'}
           VariableTypes: "double"
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [5×1 duration]
               StartTime: 0 sec
              SampleRate: 100
                TimeStep: 0.01 sec
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

修改 SampleRate 属性。开始时间相同，但所有其他行时间都不同，因为采样率较小。但是，变量 Intensity 保持不变。

TT.Properties.SampleRate = 25

TT=5×1 timetable
      Time      Intensity
    ________    _________

    0 sec           100  
    0.04 sec       98.7  
    0.08 sec       95.2  
    0.12 sec      101.4  
    0.16 sec       99.1

`TimeStep` — 时间步
`duration` 标量 | `calendarDuration` 标量

时间步，指定为 duration 标量或 calendarDuration 标量。

如果将时间步指定为 calendarDuration 值（例如，日历月），则行时间向量必须是 datetime 向量。
如果将时间步指定为 duration 值（例如秒），则行时间向量可以是 datetime 或 duration 向量。

如果行时间不规则，或者时间表为空，则时间步为 NaN。

示例

创建规则时间表。在此时间表中，行时间是使用相同时间步创建的持续时间。

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.01))

TT=5×1 timetable
      Time      Intensity
    ________    _________

    0 sec           100  
    0.01 sec       98.7  
    0.02 sec       95.2  
    0.03 sec      101.4  
    0.04 sec       99.1

显示其属性。TimeStep 属性将时间步存储为持续时间。

TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Intensity'}
           VariableTypes: "double"
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [5×1 duration]
               StartTime: 0 sec
              SampleRate: 100
                TimeStep: 0.01 sec
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

修改 TimeStep 属性。开始时间相同，但所有其他行时间都不同，因为时间步较大。但是，变量 Intensity 保持不变。

TT.Properties.TimeStep = seconds(0.04)

TT=5×1 timetable
      Time      Intensity
    ________    _________

    0 sec           100  
    0.04 sec       98.7  
    0.08 sec       95.2  
    0.12 sec      101.4  
    0.16 sec       99.1

`Events` — 事件
事件表 | `datetime` 向量 | `duration` 向量

自 R2023a 起

事件，指定为事件表、datetime 向量或 duration 向量。事件表列出事件发生的时间、描述事件的标签，有时还列出关于事件的其他信息。要查找和标记在事件期间出现的时间表行，请通过对 Events 属性赋值将事件关联到时间表。

如果对 datetime 或 duration 向量赋值，则该赋值会将向量转换为具有默认标签的事件表，并将该事件表赋给 Events 属性。

时间表的行时间和与事件相关联的事件时间必须具有相同的数据类型。例如，无法将 duration 向量或事件时间为 duration 值的事件表关联到行时间为 datetime 值的时间表。

有关事件表的详细信息，请参阅 eventtable。

变量元数据

`VariableNames` — 变量名称
字符向量元胞数组 | 字符串数组

变量名称，指定为字符向量元胞数组或字符串数组，其元素为非空且不同。名称的数量必须等于变量数。

变量名称可以包含任何 Unicode 字符，包括空格和非 ASCII 字符。
查看时间表和使用 summary 函数时，变量名称是可见的。此外，您也可以在圆括号、花括号中使用变量名称，或者将变量名称与点索引配合使用来访问表数据。
如果使用字符串数组指定此属性，则将其转换并存储为字符向量元胞数组。

示例

创建一个使用默认变量名称的时间表。然后使用 Properties.VariableNames 属性修改这些名称。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3])

TT=3×3 timetable
       Time        Var1    Var2     Var3
    ___________    ____    _____    ____

    18-Dec-2015    37.3     30.1    13.4
    19-Dec-2015    39.1    30.03     6.5
    20-Dec-2015    42.3     29.9     7.3

TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'}

TT=3×3 timetable
       Time        Temp    Pressure    WindSpeed
    ___________    ____    ________    _________

    18-Dec-2015    37.3      30.1        13.4   
    19-Dec-2015    39.1     30.03         6.5   
    20-Dec-2015    42.3      29.9         7.3

显示和修改变量的基本方法是使用圆点语法按名称访问它们。

TT.Temp

TT.Pressure(3) = 30

TT=3×3 timetable
       Time        Temp    Pressure    WindSpeed
    ___________    ____    ________    _________

    18-Dec-2015    37.3      30.1        13.4   
    19-Dec-2015    39.1     30.03         6.5   
    20-Dec-2015    42.3        30         7.3

`VariableTypes` — 变量的数据类型
字符串数组 | 字符向量元胞数组

自 R2024b 起

变量数据类型，指定为字符串数组或字符向量元胞数组。

示例

创建一个时间表。

TT = timetable(datetime(["2015-12-18";"2015-12-19";"2015-12-20"]), ...
               [37.3;39.1;42.3],[13.4;6.5;7.3],["N";"SE";"NW"],[1;0;1]);
TT.Properties.VariableNames = ["Temperature" "WindSpeed" "WindDirection" "ExtremeWarning"]

TT=3×4 timetable
       Time        Temperature    WindSpeed    WindDirection    ExtremeWarning
    ___________    ___________    _________    _____________    ______________

    18-Dec-2015       37.3          13.4           "N"                1       
    19-Dec-2015       39.1           6.5           "SE"               0       
    20-Dec-2015       42.3           7.3           "NW"               1

显示时间表变量的数据类型。

TT.Properties.VariableTypes

ans = 1×4 string
    "double"    "double"    "string"    "double"

您还可以使用属性来转换时间表变量的数据类型。例如，将 WindDirection 转换为分类数组，将 ExtremeWarning 转换为逻辑数组。

TT.Properties.VariableTypes = ["double" "double" "categorical" "logical"]

TT=3×4 timetable
       Time        Temperature    WindSpeed    WindDirection    ExtremeWarning
    ___________    ___________    _________    _____________    ______________

    18-Dec-2015       37.3          13.4            N               true      
    19-Dec-2015       39.1           6.5            SE              false     
    20-Dec-2015       42.3           7.3            NW              true

`VariableDescriptions` — 变量描述
`{}` (默认) | 字符向量元胞数组 | 字符串数组

变量描述，指定为字符向量元胞数组或字符串数组。此属性可以为空元胞数组（默认值）。如果数组不为空，则它必须包含与变量相同数量的元素。您可以为没有描述的变量指定单独的空字符向量或空字符串。

使用 summary 函数时，变量描述是可见的。
如果使用字符串数组指定此属性，则将其转换并存储为字符向量元胞数组。

示例

创建一个时间表。修改变量名称和描述。显示结果摘要。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]);
TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'};
TT.Properties.VariableDescriptions = {'Temperature (external)', ...
                                      'Pressure in Hg', ...
                                      'Wind speed at sensor 123'};
summary(TT)

TT: 3×3 timetable

Row Times:

    Time: datetime

Variables:

    Temp: double (Temperature (external))
    Pressure: double (Pressure in Hg)
    WindSpeed: double (Wind speed at sensor 123)

Statistics for applicable variables and row times:

                 NumMissing          Min              Median               Max               Mean              Std     

    Time             0           18-Dec-2015        19-Dec-2015        20-Dec-2015        19-Dec-2015        24:00:00  
    Temp             0               37.3000            39.1000            42.3000            39.5667          2.5325  
    Pressure         0               29.9000            30.0300            30.1000            30.0100          0.1015  
    WindSpeed        0                6.5000             7.3000            13.4000             9.0667          3.7740

`VariableUnits` — 变量单位
`{}` (默认) | 字符向量元胞数组 | 字符串数组

变量单位，指定为字符向量元胞数组或字符串数组。此属性可以为空元胞数组（默认值）。如果数组不为空，则它必须包含与变量相同数量的元素。您可以为没有单位的变量指定单独的空字符向量或空字符串。

使用 summary 函数时，变量单位是可见的。
如果使用字符串数组指定此属性，则将其转换并存储为字符向量元胞数组。

示例

创建一个时间表。修改变量名称和单位。显示结果摘要。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[30.1;30.03;29.9],[13.4;6.5;7.3]);
TT.Properties.VariableNames = {'Temp','Pressure','WindSpeed'};
TT.Properties.VariableUnits = {'degrees F','mm Hg','mph'};
summary(TT)

TT: 3×3 timetable

Row Times:

    Time: datetime

Variables:

    Temp: double (degrees F)
    Pressure: double (mm Hg)
    WindSpeed: double (mph)

Statistics for applicable variables and row times:

                 NumMissing          Min              Median               Max               Mean              Std     

    Time             0           18-Dec-2015        19-Dec-2015        20-Dec-2015        19-Dec-2015        24:00:00  
    Temp             0               37.3000            39.1000            42.3000            39.5667          2.5325  
    Pressure         0               29.9000            30.0300            30.1000            30.0100          0.1015  
    WindSpeed        0                6.5000             7.3000            13.4000             9.0667          3.7740

`VariableContinuity` — 状态为连续或离散变量
`[]` (默认) | 字符向量元胞数组 | 字符串数组

状态为连续或离散变量，指定为字符向量元胞数组或字符串数组。此属性可以为空数组（默认值）。如果数组不为空，则它必须包含与变量相同数量的元素。每个元素可以是 'unset'、'continuous'、'step' 或 'event'。

VariableContinuity 中的值会影响 retime 或 synchronize 函数的工作方式。如果您指定 VariableContinuity 并调用 retime 或 synchronize，则不需要指定方法。在这种情况下，retime 和 synchronize 将使用以下默认方法填充输出时间表变量：

'unset' - 使用该类型的缺失数据指示符填充值（例如对数字变量使用 NaN）。
'continuous' - 使用线性插值方法填充值。
'step' - 使用上一个值填充值。
'event' - 使用该类型的缺失数据指示符填充值（例如对数字变量使用 NaN）。

如果您将方法指定为 retime 或 synchronize 的输入参量，则该方法将覆盖您在 VariableContinuity 中指定的值。

有关使用 VariableContinuity 属性的详细信息，请参阅使用不同的方法对时间表变量重设时间并进行同步。

示例

创建一个时间表。为每个变量指定 matlab.tabular.Continuity 值。

TT = timetable(datetime({'2015-12-18';'2015-12-19';'2015-12-20'}), ...
               [37.3;39.1;42.3],[13.4;6.5;7.3],{'N';'SE';'NW'});
TT.Properties.VariableNames = {'Temperature','WindSpeed','WindDirection'};
TT.Properties.VariableContinuity = {'continuous','event','event'};
TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temperature'  'WindSpeed'  'WindDirection'}
           VariableTypes: ["double"    "double"    "cell"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: [continuous    event    event]
                RowTimes: [3×1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: 1d
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

自定义元数据

`CustomProperties` — 时间表及其变量的自定义元数据
`CustomProperties` 对象

时间表及其变量的自定义元数据，指定为 CustomProperties 对象。

CustomProperties 对象是可以添加到时间表的自定义元数据的容器。默认情况下，CustomProperties 的属性为零。添加到 CustomProperties 的每个属性都可以包含表元数据或变量元数据。如果属性包含变量元数据，则其值必须是数组，并且数组中的元素数必须等于时间表变量的数量。

要将自定义元数据的属性添加到时间表，请使用 addprop 函数。
要访问或修改自定义元数据，请使用语法 timetableName.Properties.CustomProperties.PropertyName。在此语法中，PropertyName 是使用 addprop 添加该属性时选择的名称。
要删除属性，请使用 rmprop 函数。

注意：您只能使用 addprop 和 rmprop 为自定义元数据添加或删除属性。您不能添加或删除 timetableName.Properties 对象的属性。

示例

创建包含天气数据的时间表。

TT = timetable(datetime({'2015-12-18';'2015-12-20';'2015-12-21'}), ...
               [37.3;39.1;42.3],[13.4;6.5;7.3],{'N';'SE';'NW'});
TT.Properties.VariableNames = {'Temperature','WindSpeed','WindDirection'}

TT=3×3 timetable
       Time        Temperature    WindSpeed    WindDirection
    ___________    ___________    _________    _____________

    18-Dec-2015       37.3          13.4          {'N' }    
    20-Dec-2015       39.1           6.5          {'SE'}    
    21-Dec-2015       42.3           7.3          {'NW'}

要说明测量这些数据的仪器以及输出文件的名称，请使用 addprop 函数添加自定义元数据。Instruments 属性具有适用于 TT 变量的变量元数据。OutputFile 属性具有表元数据。

TT = addprop(TT,{'Instruments','OutputFile'},{'variable','table'});
TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temperature'  'WindSpeed'  'WindDirection'}
           VariableTypes: ["double"    "double"    "cell"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3×1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN
                  Events: []

   Custom Properties (access using t.Properties.CustomProperties.<name>):
              OutputFile: []
             Instruments: []

使用圆点语法将值赋给自定义元数据。将由文本值构成的数组赋给自定义元数据时，最佳做法是使用字符串数组，而不是字符向量元胞数组。如果 CustomProperties 的属性是字符向量元胞数组，则无法防止您以后将非文本值指定为元胞数组的元素。

TT.Properties.CustomProperties.Instruments = ["thermometer","anemometer","wind vane"];
TT.Properties.CustomProperties.OutputFile = 'weatherReadings.csv';
TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temperature'  'WindSpeed'  'WindDirection'}
           VariableTypes: ["double"    "double"    "cell"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3×1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN
                  Events: []

   Custom Properties (access using t.Properties.CustomProperties.<name>):
              OutputFile: 'weatherReadings.csv'
             Instruments: ["thermometer"    "anemometer"    "wind vane"]

从 TT 中删除 OutputFile 属性。

TT = rmprop(TT,'OutputFile');
TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Temperature'  'WindSpeed'  'WindDirection'}
           VariableTypes: ["double"    "double"    "cell"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3×1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN
                  Events: []

   Custom Properties (access using t.Properties.CustomProperties.<name>):
             Instruments: ["thermometer"    "anemometer"    "wind vane"]

示例

全部折叠

在时间表中存储和同步相关数据变量

打开实时脚本

在时间表中存储关于在不同时间测量的天气状况的数据。除存储功能外，时间表还提供将数据同步到指定时间的功能。此外，您可以对时间表进行注解以描述您的工作和时间表的变量。

基于工作区变量创建时间表。MeasurementTime 中的值成为时间表的行时间。所有其他输入参量成为时间表变量。使用此语法时，行时间向量的名称和 TT 的变量是对应输入参量的名称。

MeasurementTime = datetime({'2015-12-18 08:03:05';'2015-12-18 10:03:17';'2015-12-18 12:03:13'});
Temp = [37.3;39.1;42.3];
Pressure = [30.1;30.03;29.9];
WindSpeed = [13.4;6.5;7.3];
TT = timetable(MeasurementTime,Temp,Pressure,WindSpeed)

TT=3×3 timetable
      MeasurementTime       Temp    Pressure    WindSpeed
    ____________________    ____    ________    _________

    18-Dec-2015 08:03:05    37.3      30.1        13.4   
    18-Dec-2015 10:03:17    39.1     30.03         6.5   
    18-Dec-2015 12:03:13    42.3      29.9         7.3

以小时为时间步长度将天气数据同步到规则时间。使用线性插值将数据调整到新时间。

TT2 = retime(TT,'hourly','linear')

TT2=6×3 timetable
      MeasurementTime        Temp     Pressure    WindSpeed
    ____________________    ______    ________    _________

    18-Dec-2015 08:00:00    37.254     30.102      13.577  
    18-Dec-2015 09:00:00    38.152     30.067      10.133  
    18-Dec-2015 10:00:00    39.051     30.032      6.6885  
    18-Dec-2015 11:00:00    40.613     29.969      6.8783  
    18-Dec-2015 12:00:00    42.214     29.903      7.2785  
    18-Dec-2015 13:00:00    43.815     29.838      7.6788

由于输出的行时间不是测量的时间，请重命名行时间的向量。此向量也是时间表的第一个维度的名称。

TT2.Properties.DimensionNames{1} = 'InterpolatedTimes'

TT2=6×3 timetable
     InterpolatedTimes       Temp     Pressure    WindSpeed
    ____________________    ______    ________    _________

    18-Dec-2015 08:00:00    37.254     30.102      13.577  
    18-Dec-2015 09:00:00    38.152     30.067      10.133  
    18-Dec-2015 10:00:00    39.051     30.032      6.6885  
    18-Dec-2015 11:00:00    40.613     29.969      6.8783  
    18-Dec-2015 12:00:00    42.214     29.903      7.2785  
    18-Dec-2015 13:00:00    43.815     29.838      7.6788

用描述对 TT2 进行注解。您可以使用通过 TT2.Properties 访问的元数据来对 TT2 及其变量进行注解。

TT2.Properties.Description = 'Weather data, interpolated to regular hourly times';
TT2.Properties

ans = 
  TimetableProperties with properties:

             Description: 'Weather data, interpolated to regular hourly times'
                UserData: []
          DimensionNames: {'InterpolatedTimes'  'Variables'}
           VariableNames: {'Temp'  'Pressure'  'WindSpeed'}
           VariableTypes: ["double"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [6×1 datetime]
               StartTime: 18-Dec-2015 08:00:00
              SampleRate: 2.7778e-04
                TimeStep: 01:00:00
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

访问行时间和变量数据

打开实时脚本

您可以使用圆点语法来访问时间表的行时间。此外，您可以使用圆点语法访问各个变量，或者使用第二个维度名称访问时间表中的所有数据。

从 MAT 文件 outdoors 加载时间表。显示前三行。

load outdoors
outdoors(1:3,:)

ans=3×3 timetable
           Time            Humidity    TemperatureF    PressureHg
    ___________________    ________    ____________    __________

    2015-11-15 00:00:24        49          51.3          29.61   
    2015-11-15 01:30:24      48.9          51.5          29.61   
    2015-11-15 03:00:24      48.9          51.5          29.61

使用行时间向量的名称访问行时间。此名称也是时间表的第一个维度的名称。outdoors 将行时间存储为 datetime 向量。显示前三个时间。

outdoors.Time(1:3)

ans = 3×1 datetime
   2015-11-15 00:00:24
   2015-11-15 01:30:24
   2015-11-15 03:00:24

使用变量名称将温度作为数值向量来进行访问。

outdoors.TemperatureF(1:3)

使用语法 outdoors.Variables 将所有时间表数据作为矩阵来进行访问。此语法使用时间表的第二个维度名称，等同于使用花括号索引 outdoors{:,:} 访问所有内容。但是，矩阵不包含行时间，因为行时间向量是时间表元数据，而不是变量。如果时间表数据不能串联为一个矩阵，则会引发错误消息。

outdoors.Variables

ans = 51×3

   49.0000   51.3000   29.6100
   48.9000   51.5000   29.6100
   48.9000   51.5000   29.6100
   48.8000   51.5000   29.6100
   48.7000   51.5000   29.6000
   48.8000   51.5000   29.6000
   49.0000   51.5000   29.6000
   49.1000   51.3000   29.6000
   49.1000   51.3000   29.6100
   49.1000   51.5000   29.6100
   48.9000   51.5000   29.6100
   49.0000   51.5000   29.6100
   49.0000   51.3000   29.6100
   48.9000   51.3000   29.6000
   48.8000   51.2000   29.6100
      ⋮

重命名 outdoors 的第二个维度。如果更改名称，则可以使用新名称访问数据。

outdoors.Properties.DimensionNames{2} = 'Data';
outdoors.Data

ans = 51×3

   49.0000   51.3000   29.6100
   48.9000   51.5000   29.6100
   48.9000   51.5000   29.6100
   48.8000   51.5000   29.6100
   48.7000   51.5000   29.6000
   48.8000   51.5000   29.6000
   49.0000   51.5000   29.6000
   49.1000   51.3000   29.6000
   49.1000   51.3000   29.6100
   49.1000   51.5000   29.6100
   48.9000   51.5000   29.6100
   49.0000   51.5000   29.6100
   49.0000   51.3000   29.6100
   48.9000   51.3000   29.6000
   48.8000   51.2000   29.6100
      ⋮

指定时间向量

打开实时脚本

使用 'RowTimes' 名称-值对组参量创建时间表。请注意，TT 的行时间向量的名称是 Time，而不是 MeasurementTime。使用此语法时，行时间向量的名称始终为 Time。

MeasurementTime = datetime({'2015-12-18 08:03:05';'2015-12-18 10:03:17';'2015-12-18 12:03:13'});
Temp = [37.3;39.1;42.3];
Pressure = [29.4;29.6;30.0];
Precip = [0.1;0.9;0.0];
StormDuration = [hours(1);hours(2);NaN];
TT = timetable(Temp,Pressure,Precip,StormDuration,'RowTimes',MeasurementTime)

TT=3×4 timetable
            Time            Temp    Pressure    Precip    StormDuration
    ____________________    ____    ________    ______    _____________

    18-Dec-2015 08:03:05    37.3      29.4       0.1           1 hr    
    18-Dec-2015 10:03:17    39.1      29.6       0.9           2 hr    
    18-Dec-2015 12:03:13    42.3        30         0         NaN hr

默认名称

打开实时脚本

创建一个时间表。如果输入参量不是工作区变量，则 timetable 函数会为对应的行时间向量和时间表的变量分配默认名称。例如，如果将某些输入参量转置为列向量，则这些输入参量不是工作区变量。对于行时间向量，默认名称是 Time，对于第 N 个时间表变量，默认名称是 VarN。

T = hours(1:3);
Temp = [37.3;39.1;42.3];
P = [29.4 29.6 30];
TT = timetable(T',Temp,P')

TT=3×2 timetable
    Time    Temp    Var2
    ____    ____    ____

    1 hr    37.3    29.4
    2 hr    39.1    29.6
    3 hr    42.3      30

指定采样率

打开实时脚本

使用 100 Hz 的采样率创建规则时间表。

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'SampleRate',100)

TT=5×1 timetable
      Time      Intensity
    ________    _________

    0 sec           100  
    0.01 sec       98.7  
    0.02 sec       95.2  
    0.03 sec      101.4  
    0.04 sec       99.1

使用 30 秒作为第一个行时间创建时间表。要指定开始时间，请使用 'StartTime' 名称-值对组参量。

TT = timetable(Intensity,'SampleRate',100,'StartTime',seconds(30))

TT=5×1 timetable
      Time       Intensity
    _________    _________

    30 sec           100  
    30.01 sec       98.7  
    30.02 sec       95.2  
    30.03 sec      101.4  
    30.04 sec       99.1

指定时间步

打开实时脚本

使用 0.01 秒的时间步创建规则时间表。您必须将时间步指定为 duration 或 calendarDuration 值。

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.01))

TT=5×1 timetable
      Time      Intensity
    ________    _________

    0 sec           100  
    0.01 sec       98.7  
    0.02 sec       95.2  
    0.03 sec      101.4  
    0.04 sec       99.1

使用 30 秒作为第一个行时间创建时间表。要指定开始时间，请使用 'StartTime' 名称-值对组参量。

TT = timetable(Intensity,'TimeStep',seconds(0.01),'StartTime',seconds(30))

TT=5×1 timetable
      Time       Intensity
    _________    _________

    30 sec           100  
    30.01 sec       98.7  
    30.02 sec       95.2  
    30.03 sec      101.4  
    30.04 sec       99.1

指定大小和变量类型

打开实时脚本

通过指定表的大小和变量的数据类型来预分配一个表。timetable 函数使用适合于您指定的数据类型的默认值填充变量。它还会为变量提供默认名称。

T = [datetime('now') datetime(2017,11,1:3)];
sz = [4 3];
varTypes = {'double','double','string'};
TT = timetable('Size',sz,'VariableTypes',varTypes,'RowTimes',T)

TT=4×3 timetable
            Time            Var1    Var2      Var3   
    ____________________    ____    ____    _________

    13-Jul-2025 17:43:35     0       0      <missing>
    01-Nov-2017 00:00:00     0       0      <missing>
    02-Nov-2017 00:00:00     0       0      <missing>
    03-Nov-2017 00:00:00     0       0      <missing>

要为变量指定名称，请使用 'VariableNames' 名称-值对组参量。

varNames = {'Temperature','WindSpeed','Station'};
TT = timetable('Size',sz,'VariableTypes',varTypes,'RowTimes',T,'VariableNames',varNames)

TT=4×3 timetable
            Time            Temperature    WindSpeed     Station 
    ____________________    ___________    _________    _________

    13-Jul-2025 17:43:35         0             0        <missing>
    01-Nov-2017 00:00:00         0             0        <missing>
    02-Nov-2017 00:00:00         0             0        <missing>
    03-Nov-2017 00:00:00         0             0        <missing>

向 TT 添加一行数据。当您的代码一次性添加一行数据或几行数据时，可以使用预分配。使用预分配时，您可以填充已为数据预留空间的表变量，而不必在每次添加一行时时间表都随之增长。您可以将一行数据值封装在元胞数组中，并将其分配到时间表的一个行。

按时间通过下标对行进行索引并分配一行数据值。您也可以按数字通过下标对行和变量进行索引。但是，按时间通过下标对时间表进行索引是一种很有用的方法。

TT(datetime(2017,11,2),:) = {48.2,13.33,"S1"}

TT=4×3 timetable
            Time            Temperature    WindSpeed     Station 
    ____________________    ___________    _________    _________

    13-Jul-2025 17:43:35          0              0      <missing>
    01-Nov-2017 00:00:00          0              0      <missing>
    02-Nov-2017 00:00:00       48.2          13.33      "S1"     
    03-Nov-2017 00:00:00          0              0      <missing>

您可以将一行数据值封装在一个元胞数组中。当您从元胞数组中分配一个行时，该分配会将元胞数组转换为一个时间表行。

使用采样率预分配时间表

打开实时脚本

指定 1000 Hz 的采样率并预分配时间表。您也可以指定开始时间。

sz = [4 3];
varTypes = {'uint64','double','duration'};
TT = timetable('Size',sz,'VariableTypes',varTypes,'SampleRate',1000,'StartTime',seconds(15))

TT=4×3 timetable
       Time       Var1    Var2      Var3  
    __________    ____    ____    ________

    15 sec         0       0      00:00:00
    15.001 sec     0       0      00:00:00
    15.002 sec     0       0      00:00:00
    15.003 sec     0       0      00:00:00

通过指定第三行的时间对该行进行索引，并添加一行数据。

TT(seconds(15.002),:) = {50,1.37,minutes(76)}

TT=4×3 timetable
       Time       Var1    Var2      Var3  
    __________    ____    ____    ________

    15 sec          0        0    00:00:00
    15.001 sec      0        0    00:00:00
    15.002 sec     50     1.37    01:16:00
    15.003 sec      0        0    00:00:00

使用时间步预分配时间表

打开实时脚本

指定时间步和变量的名称。

sz = [3 2];
varTypes = {'double','double'};
TT = timetable('Size',sz,'VariableTypes',varTypes,'TimeStep',seconds(0.1),'VariableNames',{'Intensity','Distance'})

TT=3×2 timetable
     Time      Intensity    Distance
    _______    _________    ________

    0 sec          0           0    
    0.1 sec        0           0    
    0.2 sec        0           0

通过指定第二行的时间对该行进行索引，并添加一行数据。

TT(seconds(0.1),:) = {93.6,11.27}

TT=3×2 timetable
     Time      Intensity    Distance
    _______    _________    ________

    0 sec           0            0  
    0.1 sec      93.6        11.27  
    0.2 sec         0            0

创建时间表并指定变量名称

打开实时脚本

创建时间表并指定时间表变量的名称。行时间的向量是 duration 向量，其单位为秒。

Time = seconds(1:5)';
TT = timetable(Time,[98;97.5;97.9;98.1;97.9],[120;111;119;117;116],...
               'VariableNames',{'Reading1','Reading2'})

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

从 R2019b 开始，您指定的时间表变量名称可以不是有效的 MATLAB® 标识符。这种变量名称可以包括空格、非 ASCII 字符，并且可以有任何字符作为前导字符。

例如，使用日期作为包含读数的时间表变量的名称。

TT = timetable(Time,[98;97.5;97.9;98.1;97.9],[120;111;119;117;116],...
               'VariableNames',{'29-May-2019','30-May-2019'})

TT=5×2 timetable
    Time     29-May-2019    30-May-2019
    _____    ___________    ___________

    1 sec         98            120    
    2 sec       97.5            111    
    3 sec       97.9            119    
    4 sec       98.1            117    
    5 sec       97.9            116

当名称不是有效标识符时，要使用圆点表示法，需要加上括号和引号。

TT.('29-May-2019')

局限性

对下列输入名称使用单引号：
- 'DimensionNames' （从 R2021a 开始提供）
- 'RowTimes'
- 'SampleRate'
- 'Size'
- 'StartTime'
- 'TimeStep'
- 'VariableTypes'
- 'VariableNames'
为了避免与变量输入混淆，请不要对这些名称使用双引号字符串标量（如 "RowTimes"）。

提示

有关接受或返回时间表的函数列表，请参阅时间表。

在某些情况下，您可以使用指定行时间之间的规则时间步的语法来调用 timetable，而 timetable 返回不规则时间表。当您使用日历时间单位指定时间步并且存在引入不规则时间步的行时间时，就会出现这种结果。例如，如果您创建时间步为一个日历月的时间表，从 2019 年 1 月 31 日开始，则基于月份，时间步是不规则的。

stime = datetime(2019,1,31);
tstep = calmonths(1);
TT = timetable('Size',[3 1],'VariableTypes',{'double'},...
               'TimeStep',tstep,'StartTime',stime)

TT =

  3×1 timetable

       Time        Var1
    ___________    ____

    31-Jan-2019     0  
    28-Feb-2019     0  
    31-Mar-2019     0

夏令时 (DST) 的转换或闰秒的 datetime 值也会造成不规则性。下表指定可能意外产生不规则结果的日期、时间和时间步。

行时间值	时间步
开始时间，指定为一个月的第 29 天、第 30 天或第 31 天。	日历月数或季度数。
开始时间，指定为 2 月 29 日。	日历年数。
在从 DST 转换到标准时间的一天中凌晨 1:00 到 2:00 之间发生的任何 `datetime` 值（当这些值的时区遵守 DST 时）。	日历天数或月数。
闰秒的任何 `datetime` 值（当这些值的时区是 `UTCLeapSeconds` 时区时）。有关闰秒的列表，请参阅 `leapseconds`。	以任何日历单位（天、周、月、季度或年）指定的时间步。

扩展功能

全部展开

tall 数组
对行数太多而无法放入内存的数组进行计算。

timetable 函数支持 tall 数组，但存在以下使用说明和限制：

不支持 SampleRate、TimeStep、StartTime、Events 和 VariableTypes 属性。
创建。创建 tall 时间表有多种方法：
1. 将基础数据存储的 OutputType 属性指定为 'timetable'，以便对数据存储的读取操作返回时间表。然后，使用 tall(ds) 将该数据存储转换为 tall 数组。
  默认行为是对行时间使用数据中的第一个 datetime 或 duration 变量。要自行指定行时间，请使用 RowTimes 数据存储属性来指定行时间的 tall datetime 或 tall duration 向量。
2. 使用 table2timetable 转换现有 tall 表。
3. 使用 array2timetable 转换现有的 tall 数组。
4. 使用 timetable 构造函数基于 tall 表中的变量手动构建 tall 时间表。
```
ds = tabularTextDatastore('data/folder/path.csv');
tt = tall(ds);
TT = timetable(rowTimes, tt.Var1, tt.Var2, ...)
```
5. 使用语法 TT = tall(tt) 将内存时间表转换为 tall 时间表。
索引。支持使用 timerange、withtol 和 vartype 函数对 tall 时间表进行索引。
支持的函数。每个参考页底部的扩展功能部分指示该函数是否支持 tall 数组，如果支持，在该函数与 tall 时间表结合使用时是否存在任何限制。

有关详细信息，请参阅tall 数组。

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

从 R2020a 开始，您可以在用于代码生成的 MATLAB^® 代码中使用时间表。有关详细信息，请参阅时间表的代码生成 (MATLAB Coder)和代码生成的时间表限制 (MATLAB Coder)。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

用法说明和限制：

仅支持以下语法：
TT = timetable(rowTimes,var1,...,varN)
TT = timetable(var1,...,varN,'RowTimes',rowTimes)
TT = timetable(___,'VariableNames',{'name1',...,'nameN'})
TT = timetable(___,'DimensionNames',{'dim1','dim2'})
所有数据变量都必须为分布式。
不支持 'SampleRate'、'TimeStep' 和 'StartTime' 名称-值参量。
不支持 Events 属性。

有关详细信息，请参阅使用分布式数组运行 MATLAB 函数 (Parallel Computing Toolbox)。

版本历史记录

在 R2016b 中推出

全部展开

R2025a: 维度和变量名称的最大长度增加到 2048 个字符

在表和时间表中，维度和变量名称的允许的最大长度已增加到 2048 个字符。此长度与更新后的最大标识符长度匹配，您可以使用 namelengthmax 函数查询后者。

在表和时间表中使用较长的维度和变量名称可能会对性能和内存产生负面影响。

以前，表和时间表中维度和变量名称的最大长度为 63 个字符。依赖维度和变量名称不超出 63 个字符的代码可能无法按预期运行。

如果将具有长维度或变量名称的表或时间表保存到 MAT 文件，则可以将其加载到 R2025a 之前的 MATLAB 版本中。但是，较早的 MATLAB 版本会将表或时间表中的长维度和变量名称截断为 63 个字符。

R2024b: 表和时间表的 `VariableTypes` 属性指定其变量的数据类型

表和时间表的 VariableTypes 属性指定其变量的数据类型。

R2023a: 直接对表和时间表执行计算而无需提取其数据

现在，您可以直接对表和时间表执行计算而无需提取其数据。表和时间表中的所有变量都必须具有支持计算的数据类型。还可以执行其中一个操作数是表或时间表、另一个是数值或逻辑数组的运算。以前，所有计算都要求您通过对表和时间表进行索引来从其中提取数据。

有关详细信息，请参阅Direct Calculations on Tables and Timetables和Rules for Table and Timetable Mathematics。

R2023a: 使用附加的事件表查找并标记时间表中的事件

要查找并标记时间表中的事件，请将事件表附加到时间表。事件表是各个事件的时间表。一个事件包含事件时间（事件发生的时间），通常还包含事件长度或事件结束时间（事件发生的时间长度）、事件标签（发生了什么），有时还包含关于事件的其他信息。事件表设计为附加到时间表。当您将事件表附加到时间表时，您可以在时间表中查找或标记事件期间涉及的行。

MATLAB 提供以下函数，以基于输入数据创建事件表，根据事件时间过滤时间表行以及将事件与时间表同步：

R2023a: 改进了使用时间或 `withtol` 下标进行下标索引时的性能

与在 R2022b 中相比，在 R2023a 中使用时间或 withtol 下标对 timetable 进行下标索引时速度更快。

例如，当您使用一个包含 100 个 datetime 值的向量对一个包含 10⁷ 个行的时间表进行下标索引时，在 R2023a 中的性能比在 R2022b 中快 114 倍。

function timingTest()
rng default

% 10^7 rows
N = 10000000;
rowtimes = datetime(2023,1,1,0,0,0:N-1); 
rowtimes.Format = rowtimes.Format + ".SSS";
tt = timetable(rand(N,1),RowTimes=rowtimes);

% 100 values chosen in steps of 10
n = 1000;
t = datetime(2023,1,1,0,0,0:10:n-1);
    
tic
tt2 = tt(t,:);
toc
end

大致的执行时间是：

R2022b：9.10 秒

R2023a：0.08 秒

同样，当您使用一个包含 100 个 duration 值的向量对一个包含 10⁷ 个行的时间表进行下标索引时，在 R2023a 中的性能比在 R2022b 中快 14 倍。

function timingTest()
rng default

% 10^7 rows
N = 10000000;
rowtimes = seconds(0:N-1);
tt = timetable(rand(N,1),RowTimes=rowtimes);

% 100 values chosen in steps of 10
n = 1000;
t = seconds(0:10:n-1);
    
tic
tt2 = tt(t,:);
toc
end

大致的执行时间是：

R2022b：1.29 秒

R2023a：0.09 秒

当您对一个包含 10⁷ 个行的时间表使用 withtol 下标进行索引时，在 R2023a 中的性能比在 R2022b 中大约快 44 倍。

function timingTest()
rng default

% 10^7 rows
N = 10000000;
rowtimes = seconds(0:N-1);
tt = timetable(rand(N,1),RowTimes=rowtimes);

% 100 values chosen in steps of 10
n = 1000;
t = seconds(0:10:n-1);

tt.Time = tt.Time + .1*seconds(rand(N,1));
wt = withtol(t,seconds(.1));
    
tic
tt2 = tt(wt,:);
toc
end

大致的执行时间是：

R2022b：3.92 秒

R2023a：0.09 秒

此代码是在 Windows^® 10 的AMD^® EPYC 74F3 24 核处理器 @ 3.19 GHz 测试系统上，通过调用每个版本的 timingTest 函数计时的。

R2021a: `'SamplingRate'` 将被删除

'SamplingRate' 名称-值参量将在以后的版本中删除。请改用 'SampleRate'。对应的时间表属性也命名为 SampleRate。

为了实现向后兼容性，您仍可以将 'SamplingRate' 指定为名称-值参量形式的名称。但是，该值将赋给 SampleRate 属性。

R2019b: 变量名称可以包含前导和尾随空白字符

带前导和尾随空白字符的表和时间表变量名称不会被修改。

在以前的版本中，如果您使用 'VariableNames' 名称-值对组参量来指定变量名称或将它们赋给 VariableNames 属性，系统将从变量名称中删除前导和尾随空白字符。

要手动删除此类字符，请首先对名称使用 strtrim 函数，然后将它们作为变量名称赋给表或时间表。

另请参阅

timetable

说明

创建对象

语法

描述

合并现有变量

预分配空间

设置名称或开始时间

输入参量

var1,...,varN — 输入变量 数组

rowTimes — 与时间表的行相关联的时间 datetime 向量 | duration 向量

sz — 预分配的时间表的大小 二元素数值向量

varTypes — 预分配变量的数据类型 字符向量元胞数组 | 字符串数组

Fs — 采样率 数值标量

dt — 时间步 duration 标量 | calendarDuration 标量

名称-值参数

VariableNames — 变量名称 字符向量元胞数组 | 字符串数组

DimensionNames — 维度名称 二元素字符向量元胞数组 | 二元素字符串数组

StartTime — 开始时间 datetime 标量 | duration 标量

属性

时间表元数据

DimensionNames — 维度名称 {'Time','Variables'} (默认) | 二元素字符向量元胞数组 | 二元素字符串数组

示例

Description — 时间表描述 '' (默认) | 字符向量 | 字符串标量

示例

UserData — 其他时间表信息 [] (默认) | 数组

示例

行时间元数据

RowTimes — 行时间 datetime 向量 | duration 向量

示例

StartTime — 行时间的开始时间 datetime 标量 | duration 标量

示例

SampleRate — 采样率 数值标量

示例

TimeStep — 时间步 duration 标量 | calendarDuration 标量

示例

Events — 事件 事件表 | datetime 向量 | duration 向量

变量元数据

VariableNames — 变量名称 字符向量元胞数组 | 字符串数组

示例

VariableTypes — 变量的数据类型 字符串数组 | 字符向量元胞数组

示例

VariableDescriptions — 变量描述 {} (默认) | 字符向量元胞数组 | 字符串数组

示例

VariableUnits — 变量单位 {} (默认) | 字符向量元胞数组 | 字符串数组

示例

VariableContinuity — 状态为连续或离散变量 [] (默认) | 字符向量元胞数组 | 字符串数组

示例

自定义元数据

CustomProperties — 时间表及其变量的自定义元数据 CustomProperties 对象

示例

示例

在时间表中存储和同步相关数据变量

访问行时间和变量数据

指定时间向量

默认名称

指定采样率

指定时间步

指定大小和变量类型

使用采样率预分配时间表

使用时间步预分配时间表

创建时间表并指定变量名称

局限性

提示

扩展功能

tall 数组 对行数太多而无法放入内存的数组进行计算。

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

分布式数组 使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

版本历史记录

R2025a: 维度和变量名称的最大长度增加到 2048 个字符

R2024b: 表和时间表的 VariableTypes 属性指定其变量的数据类型

R2023a: 直接对表和时间表执行计算而无需提取其数据

R2023a: 使用附加的事件表查找并标记时间表中的事件

R2023a: 改进了使用时间或 withtol 下标进行下标索引时的性能

R2021a: 'SamplingRate' 将被删除

R2019b: 变量名称可以包含前导和尾随空白字符

另请参阅

主题

`var1,...,varN` — 输入变量
数组

`rowTimes` — 与时间表的行相关联的时间
`datetime` 向量 | `duration` 向量

`sz` — 预分配的时间表的大小
二元素数值向量

`varTypes` — 预分配变量的数据类型
字符向量元胞数组 | 字符串数组

`Fs` — 采样率
数值标量

`dt` — 时间步
`duration` 标量 | `calendarDuration` 标量

`VariableNames` — 变量名称
字符向量元胞数组 | 字符串数组

`DimensionNames` — 维度名称
二元素字符向量元胞数组 | 二元素字符串数组

`StartTime` — 开始时间
`datetime` 标量 | `duration` 标量

`DimensionNames` — 维度名称
`{'Time','Variables'}` (默认) | 二元素字符向量元胞数组 | 二元素字符串数组

`Description` — 时间表描述
`''` (默认) | 字符向量 | 字符串标量

`UserData` — 其他时间表信息
`[]` (默认) | 数组

`RowTimes` — 行时间
`datetime` 向量 | `duration` 向量

`StartTime` — 行时间的开始时间
`datetime` 标量 | `duration` 标量

`SampleRate` — 采样率
数值标量

`TimeStep` — 时间步
`duration` 标量 | `calendarDuration` 标量

`Events` — 事件
事件表 | `datetime` 向量 | `duration` 向量

`VariableNames` — 变量名称
字符向量元胞数组 | 字符串数组

`VariableTypes` — 变量的数据类型
字符串数组 | 字符向量元胞数组

`VariableDescriptions` — 变量描述
`{}` (默认) | 字符向量元胞数组 | 字符串数组

`VariableUnits` — 变量单位
`{}` (默认) | 字符向量元胞数组 | 字符串数组

`VariableContinuity` — 状态为连续或离散变量
`[]` (默认) | 字符向量元胞数组 | 字符串数组

`CustomProperties` — 时间表及其变量的自定义元数据
`CustomProperties` 对象

tall 数组
对行数太多而无法放入内存的数组进行计算。

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

R2024b: 表和时间表的 `VariableTypes` 属性指定其变量的数据类型

R2023a: 改进了使用时间或 `withtol` 下标进行下标索引时的性能

R2021a: `'SamplingRate'` 将被删除