本页对应的英文页面已更新,但尚未翻译。 若要查看最新内容,请点击此处访问英文页面。

timetable

具有时间戳行和不同变量类型的时间表数组

说明

timetable 是一种特定类型的表,其中每一行关联一个时间。与表一样,时间表存储具有不同数据类型和大小的列向数据变量,只要它们具有相同的行数即可。此外,时间表提供了特定于时间的函数,可对一个或多个时间表中的时间戳数据进行对齐、合并,以及执行计算。

时间表的行时间是标记行的 datetimeduration 值。您可以按行时间和变量对时间表进行索引。要对时间表进行索引,可以使用圆括号 () 返回子表,或者使用花括号 {} 提取内容。可以使用名称来引用变量和行时间向量。有关进行索引的详细信息,请参阅按行时间和变量类型选择时间表数据访问表中的数据

创建对象

您可以使用 readtimetable 函数将文件中的数据读入表,或使用 array2timetabletable2timetable 函数将变量转换为时间表。也可以使用 timetable 函数,如下所述。

当您使用 timetable 函数时,可以指定行时间向量,或使用采样率或时间步创建行时间。此外,您可以创建为以后填写的变量值预分配了空间的时间表。

说明

示例

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

示例

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 是一个持续时间或日历持续时间值,用于指定连续行时间之间的时间长度。第一个行时间是零秒。

示例

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' 名称-值对组指定开始时间。您可以将此语法与前面语法中的任何输入参数结合使用。

输入参数

全部展开

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

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

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

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

数据类型: datetime | duration

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

预分配变量的数据类型,指定为字符向量元胞数组或字符串数组。由 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 日期时间值

'duration'

0 秒,作为持续时间值

'calendarDuration'

0 天,作为日历持续时间值

'string'

""(不包含任何字符的 1×1 字符串)

'cellstr'

{''}(具有 0×0 字符数组的元胞)

'cell'

{[]}(具有 0×0 双精度数组的元胞)

'struct'

没有字段的标量结构体

'table'

没有变量的表

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

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

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

时间步,指定为持续时间标量。

如果您将 dt 指定为日历持续时间,并指定 'StartTime' 名称-值对组参数,则 'StartTime' 的值必须是日期时间标量。

数据类型: duration | calendarDuration

名称-值对组参数

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称,Value 为对应的值。Name 必须放在引号中。您可采用任意顺序指定多个名称-值对组参数,如 Name1,Value1,...,NameN,ValueN 所示。

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

变量名称,指定为以逗号分隔的对组,其中包含 'VariableNames' 和一个由非空的不同元素构成的字符向量元胞数组或字符串数组。数组中的名称的数量必须等于时间表变量的数量。timetable 函数还将变量名称存储在时间表的 VariableNames 属性中。

变量名称可以包含任何 Unicode® 字符,包括空格和非 ASCII 字符。

开始时间,指定为由 'StartTime' 和一个日期时间标量或持续时间标量组成的逗号分隔对组。开始时间也是时间表的第一行的行时间。

仅当您还指定 'SampleRate''TimeStep' 名称-值对组参数时,才能指定 'StartTime'

  • 如果开始时间是日期时间值,则 TT 的行时间是日期时间值。

  • 如果开始时间是持续时间,则行时间是持续时间。

  • 如果时间步 dt 是日历持续时间值,则开始时间必须是日期时间值。

数据类型: datetime | duration

属性

全部展开

访问时间表元数据属性

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

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

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

时间表元数据

维度名称,指定为二元素字符向量元胞数组或二元素字符串数组。

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

如果使用字符串数组指定此属性,则将其转换并存储为字符向量元胞数组。

维度名称可以包含任何 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 = 1x2 cell array
    {'Time'}    {'Variables'}

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

TT.Time
ans = 3x1 datetime array
   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.DateTT.WeatherData 访问行时间和数据。

TT.Properties.DimensionNames = {'Date','WeatherData'};
TT.Properties
ans = 
  TimetableProperties with properties:

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

时间表说明,指定为字符向量或字符串标量。使用 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)
Description:  Weather Data from December 2015

RowTimes:

    Time: 3x1 datetime
        Values:
            Min           18-Dec-2015 
            Median        19-Dec-2015 
            Max           20-Dec-2015 
            TimeStep      24:00:00    

Variables:

    Temp: 3x1 double

        Values:

            Min        37.3 
            Median     39.1 
            Max        42.3 

    Pressure: 3x1 double

        Values:

            Min          29.9   
            Median      30.03   
            Max          30.1   

    WindSpeed: 3x1 double

        Values:

            Min           6.5    
            Median        7.3    
            Max          13.4    

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

示例

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

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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3x1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: 1d
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

行时间元数据

行时间,指定为日期时间向量或持续时间向量。时间表的每一行都必须有一个行时间。但是,时间表的行时间可以是重复的、无序的,还可以包含 NaTNaN 值。

查看时间表时,行时间是可见的。此外,您也可以在圆括号或花括号中使用行时间来访问时间表数据。

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

示例

创建一个时间表。然后使用 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×4 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×4 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 = 1x2 cell array
    {'Time'}    {'Variables'}

TT.Time
ans = 3x1 datetime array
   01-Jan-2017
   02-Jan-2017
   03-Jan-2017

行时间的开始时间,指定为日期时间标量或持续时间标量。开始时间等于时间表第一行的行时间,并且具有相同的数据类型。

  • 如果开始时间是日期时间,则 TT 的行时间是日期时间值。

  • 如果开始时间是持续时间,则行时间是持续时间。

  • 如果时间步是日历持续时间值,则开始时间必须是日期时间值。

如果时间表为空,则开始时间为 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×4 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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3x1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

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

TT.Properties.StartTime = datetime('2018-04-09')
TT=3×4 timetable
            Time            Temperature    WindSpeed    WindDirection
    ____________________    ___________    _________    _____________

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

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

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

示例

时间步,指定为持续时间标量。

  • 如果将时间步指定为日历持续时间(例如,日历月),则行时间向量必须是日期时间向量。

  • 如果将时间步指定为持续时间(例如,秒),则行时间向量可以是日期时间或持续时间向量。

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

示例

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

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.01))
TT=5×2 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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [5x1 duration]
               StartTime: 0 sec
              SampleRate: 100
                TimeStep: 0.01 sec
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

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

TT.Properties.TimeStep = seconds(0.04)
TT=5×2 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  

数据类型: duration | calendarDuration

变量元数据

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

变量名称可以包含任何 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×4 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×4 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
ans = 3×1

   37.3000
   39.1000
   42.3000

TT.Pressure(3) = 30
TT=3×4 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   

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

使用 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)
RowTimes:

    Time: 3x1 datetime
        Values:
            Min           18-Dec-2015 
            Median        19-Dec-2015 
            Max           20-Dec-2015 
            TimeStep      24:00:00    

Variables:

    Temp: 3x1 double

        Properties:
            Description:  Temperature (external)
        Values:

            Min        37.3 
            Median     39.1 
            Max        42.3 

    Pressure: 3x1 double

        Properties:
            Description:  Pressure in Hg
        Values:

            Min          29.9   
            Median      30.03   
            Max          30.1   

    WindSpeed: 3x1 double

        Properties:
            Description:  Wind speed at sensor 123
        Values:

            Min           6.5    
            Median        7.3    
            Max          13.4    

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

使用 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)
RowTimes:

    Time: 3x1 datetime
        Values:
            Min           18-Dec-2015 
            Median        19-Dec-2015 
            Max           20-Dec-2015 
            TimeStep      24:00:00    

Variables:

    Temp: 3x1 double

        Properties:
            Units:  degrees F
        Values:

            Min        37.3 
            Median     39.1 
            Max        42.3 

    Pressure: 3x1 double

        Properties:
            Units:  mm Hg
        Values:

            Min          29.9   
            Median      30.03   
            Max          30.1   

    WindSpeed: 3x1 double

        Properties:
            Units:  mph
        Values:

            Min           6.5    
            Median        7.3    
            Max          13.4    

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

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

  • 'unset' - 使用该类型的缺失数据指示符填充值(例如对数字变量使用 NaN)。

  • 'continuous' - 使用线性插值方法填充值。

  • 'step' - 使用上一个值填充值。

  • 'event' - 使用该类型的缺失数据指示符填充值(例如对数字变量使用 NaN)。

如果您将方法指定为 retimesynchronize 的输入参数,则该方法将覆盖您在 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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: [continuous    event    event]
                RowTimes: [3x1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: 1d
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

自定义元数据

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

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

  • 要将自定义元数据的属性添加到时间表,请使用 addprop 函数。

  • 要访问或修改自定义元数据,请使用语法 timetableName.Properties.CustomProperties.PropertyName。在此语法中,PropertyName 是使用 addprop 添加该属性时选择的名称。

  • 要删除属性,请使用 rmprop 函数。

注意:只能使用 addproprmprop 为自定义元数据添加或删除属性。您不能添加或删除 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×4 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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3x1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN

   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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3x1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN

   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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [3x1 datetime]
               StartTime: 18-Dec-2015
              SampleRate: NaN
                TimeStep: NaN

   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×4 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×4 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×4 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'}
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [6x1 datetime]
               StartTime: 18-Dec-2015 08:00:00
              SampleRate: 2.7778e-04
                TimeStep: 01:00:00
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

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

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

load outdoors
outdoors(1:3,:)
ans=3×4 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 将行时间存储为日期时间向量。显示前三个时间。

outdoors.Time(1:3)
ans = 3x1 datetime array
   2015-11-15 00:00:24
   2015-11-15 01:30:24
   2015-11-15 03:00:24

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

outdoors.TemperatureF(1:3)
ans = 3×1

   51.3000
   51.5000
   51.5000

使用语法 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
      ⋮

重命名 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
      ⋮

使用 '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×5 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×3 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×2 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×2 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 秒的时间步创建规则时间表。您必须将时间步指定为持续时间或日历持续时间值。

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.01))
TT=5×2 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×2 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×4 timetable
            Time            Var1    Var2      Var3   
    ____________________    ____    ____    _________

    30-Jul-2019 17:06:41     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×4 timetable
            Time            Temperature    WindSpeed     Station 
    ____________________    ___________    _________    _________

    30-Jul-2019 17:06:41         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×4 timetable
            Time            Temperature    WindSpeed     Station 
    ____________________    ___________    _________    _________

    30-Jul-2019 17:06:41          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×4 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×4 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×3 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×3 timetable
     Time      Intensity    Distance
    _______    _________    ________

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

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

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×3 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×3 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')
ans = 5×1

   98.0000
   97.5000
   97.9000
   98.1000
   97.9000

局限性

  • 对下列输入名称使用单引号:

    • '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) 的转换或闰秒的行时间也会造成不规则性。下表指定了可能意外产生不规则时间表的行时间值和时间步。

    行时间值

    时间步

    开始时间,指定为一个月的第 29 天、第 30 天或第 31 天

    日历月数或季度数

    开始时间,指定为 2 月 29 日

    日历年数

    在从 DST 转换到标准时间的一天中凌晨 1:00 到 2:00 之间发生的行时间(当行时间指定为其时区遵守 DST 的日期时间值时)日历天数或月数

    闰秒行时间(当行时间指定为其时区为 UTCLeapSeconds 时区的日期时间值时)

    以任何日历单位(天、周、月、季度或年)指定的时间步

兼容性考虑

全部展开

R2019b 中的行为有变化

从 R2018b 起不建议使用

扩展功能

在 R2016b 中推出