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

readtimetable

基于文件创建时间表

说明

示例

TT = readtimetable(filename) 通过从文件中读取列向数据来创建时间表。

readtimetable 基于文件的扩展名确定文件格式:

  • .txt.dat.csv(适用于带分隔符的文本文件)

  • .xls.xlsb.xlsm.xlsx.xltm.xltx.ods(适用于电子表格文件)

readtimetable 为该文件中的每列在 TT 中创建一个变量并从文件的第一行中读取变量名称。

readtimetable 将表格数据中 datetimeduration 类型的第一列设置为时间表的行时间。其余列成为时间表的变量。

示例

TT = readtimetable(filename,opts) 还使用导入选项 opts

示例

TT = readtimetable(___,Name,Value) 基于文件创建一个时间表,并通过一个或多个名称-值对组参数指定其他选项。您需要在上述语法的输入参数之后指定名称-值对组。

要为数据设置特定的导入选项,您可以使用 opts 对象,也可以指定名称-值对组。当您指定除 opts 之外的名称-值对组时,readtimetable 仅支持下列名称-值对组:

  • 文本和电子表格参数 - ReadVariableNamesRowTimesSampleRateTimeStepStartTime

  • 仅文本参数 - DateLocaleEncoding

  • 仅电子表格参数 - SheetUseExcel

示例

全部折叠

基于逗号分隔的文本文件创建表。

TT = readtimetable('outages.csv');

显示表的摘要。创建时间表时,如果没有为行时间指定任何参数,则 readtimetable 函数会检测并指定数据中的第一个日期时间变量或持续时间变量 OutageTime 作为行时间变量。其余变量成为时间表的变量。

summary(TT)
RowTimes:

    OutageTime: 1468x1 datetime
        Values:
            Min         2002-02-01 12:18 
            Median      2010-03-18 21:05 
            Max         2014-01-15 02:41 

Variables:

    Region: 1468x1 cell array of character vectors

    Loss: 1468x1 double

        Values:

            Min             0       
            Median          180.26  
            Max             23418   
            NumMissing      604     

    Customers: 1468x1 double

        Values:

            Min             0           
            Median          75765       
            Max             5.9689e+06  
            NumMissing      328         

    RestorationTime: 1468x1 datetime

        Values:

            Min             2002-02-07 16:50  
            Median          2010-03-31 10:54  
            Max             2042-09-18 23:31  
            NumMissing      29                

    Cause: 1468x1 cell array of character vectors

检测文本文件的导入选项,指定变量类型,然后基于数据创建时间表。

基于文件创建导入选项对象,并检查变量选项。

opts = detectImportOptions('outages.csv');
opts.VariableOptions
ans = 
  1x6 heterogeneous VariableImportOptions (TextVariableImportOptions, DatetimeVariableImportOptions, NumericVariableImportOptions) array with properties:

    Name
    Type
    FillValue
    TreatAsMissing
    QuoteRule
    Prefixes
    Suffixes
    EmptyFieldRule

修改选项对象,为数据中的变量指定所需的数据类型。将变量 RegionCause 的数据类型更改为 categorical。

opts = setvartype(opts,{'Region','Cause'},{'categorical','categorical'});

使用 readtimetable 以及选项对象导入时间表。然后显示该时间表的汇总。

TT = readtimetable('outages.csv',opts);
summary(TT)
RowTimes:

    OutageTime: 1468x1 datetime
        Values:
            Min         2002-02-01 12:18 
            Median      2010-03-18 21:05 
            Max         2014-01-15 02:41 

Variables:

    Region: 1468x1 categorical

        Values:

            MidWest        142   
            NorthEast      557   
            SouthEast      389   
            SouthWest       26   
            West           354   

    Loss: 1468x1 double

        Values:

            Min             0       
            Median          180.26  
            Max             23418   
            NumMissing      604     

    Customers: 1468x1 double

        Values:

            Min             0           
            Median          75765       
            Max             5.9689e+06  
            NumMissing      328         

    RestorationTime: 1468x1 datetime

        Values:

            Min             2002-02-07 16:50  
            Median          2010-03-31 10:54  
            Max             2042-09-18 23:31  
            NumMissing      29                

    Cause: 1468x1 categorical

        Values:

            attack                294   
            earthquake              2   
            energy emergency      188   
            equipment fault       156   
            fire                   25   
            severe storm          338   
            thunder storm         201   
            unknown                24   
            wind                   95   
            winter storm          145   

从以逗号分隔的文本文件中读取一个表,并使用您选择的行时间变量创建一个时间表。

创建一个导入选项对象并预览表格数据。

opts = detectImportOptions('outages.csv');
preview('outages.csv',opts)
ans=8×6 table
       Region           OutageTime        Loss     Customers     RestorationTime            Cause       
    _____________    ________________    ______    __________    ________________    ___________________

    {'SouthWest'}    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    {'winter storm'   }
    {'SouthEast'}    2003-01-23 00:49    530.14    2.1204e+05                 NaT    {'winter storm'   }
    {'SouthEast'}    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    {'winter storm'   }
    {'West'     }    2004-04-06 05:44    434.81    3.4037e+05    2004-04-06 06:10    {'equipment fault'}
    {'MidWest'  }    2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    {'severe storm'   }
    {'West'     }    2003-06-18 02:49         0             0    2003-06-18 10:54    {'attack'         }
    {'West'     }    2004-06-20 14:39    231.29           NaN    2004-06-20 19:16    {'equipment fault'}
    {'West'     }    2002-06-06 19:28    311.86           NaN    2002-06-07 00:51    {'equipment fault'}

通过将 RestorationTime 变量指定为时间表的行时间变量来创建一个时间表。然后,显示该时间表的汇总。

TT = readtimetable('outages.csv','RowTimes','RestorationTime');
summary(TT)
RowTimes:

    RestorationTime: 1468x1 datetime
        Values:
            Min             2002-02-07 16:50 
            Median          2010-03-31 10:54 
            Max             2042-09-18 23:31 
            NumMissing      29               

Variables:

    Region: 1468x1 cell array of character vectors

    OutageTime: 1468x1 datetime

        Values:

            Min       2002-02-01 12:18
            Median    2010-03-18 21:05
            Max       2014-01-15 02:41

    Loss: 1468x1 double

        Values:

            Min             0       
            Median          180.26  
            Max             23418   
            NumMissing      604     

    Customers: 1468x1 double

        Values:

            Min             0           
            Median          75765       
            Max             5.9689e+06  
            NumMissing      328         

    Cause: 1468x1 cell array of character vectors

输入参数

全部折叠

要读取的文件的名称,指定为字符向量或字符串标量。

根据文件的位置,filename 可以采用下列形式之一。

位置

形式

当前文件夹或 MATLAB® 路径上的文件夹

指定 filename 中文件的名称。

示例:'myFile.txt'

文件夹中的文件

如果该文件不在当前文件夹或 MATLAB 路径下的文件夹中,则在 filename 中指定完整或相对路径名。

示例:'C:\myFolder\myFile.xlsx'

示例:'dataDir\myFile.txt'

远程位置

如果文件存储在远程位置,则 filename 必须包含指定为统一资源定位器 (URL) 形式的文件的完整路径:

scheme_name://path_to_file/my_file.ext

根据您的远程位置,scheme_name 可以是下表中的值之一。

远程位置scheme_name
Amazon S3™s3
Windows Azure® Blob Storagewasb, wasbs
HDFS™hdfs

有关详细信息,请参阅处理远程数据

示例:'s3://bucketname/path_to_file/my_file.csv'

  • 如果 filename 包含文件扩展名,则导入函数基于扩展名确定文件格式。否则,您必须指定 'FileType' 名称-值对组参数以指示文件类型。

  • 在安装了 Microsoft® Excel® 软件的 Windows® 系统上,导入函数读取您的 Excel 版本可识别的任何 Excel 电子表格文件格式。

  • 如果您的系统没有 Windows 版 Excel 或者您正在使用 MATLAB Online™,则导入函数在 UseExcel 属性设置为 false 的情况下运行,并且只读取 .xls, .xlsx, .xlsm, .xltx, and .xltm 文件。

  • 对于分隔的文本文件,导入函数将文件中的空字段转换为 NaN(对于数值变量)或空字符向量(对于文本变量)。文本文件中的所有行必须有相同数量的分隔符。导入函数会忽略文件中的无用空白。

数据类型: char | string

文件导入选项,指定为 detectImportOptions 函数创建的 SpreadsheetImportOptionsDelimitedTextImportOptionsFixedWidthImportOptions 对象。opts 对象包含控制数据导入过程的属性。有关每个对象的属性的详细信息,请参阅相应的对象页。

文件类型输出
电子表格文件SpreadsheetImportOptions 对象
文本文件DelimitedTextImportOptions 对象
等宽文本文件FixedWidthImportOptions 对象

名称-值对组参数

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

示例: 'NumHeaderLines',5 表示表格数据前面的前五行是标题行。
文本和电子表格文件

全部折叠

文件类型,以逗号分隔的对组形式指定,其中包含 'FileType' 以及 'text''spreadsheet'

filename 不包含文件扩展名或扩展名不是以下任一项时,请指定 'FileType' 名称-值对组参数。

  • .txt.dat.csv(适用于带分隔符的文本文件)

  • .xls.xlsb.xlsm.xlsx.xltm.xltx.ods(适用于电子表格文件)

示例: 'FileType','text'

数据类型: char | string

文件中标题行的数目,指定为以逗号分隔的对组,其中包含 'NumHeaderLines' 和一个正整数。如果未指定,则导入函数会自动检测文件中标题行的数目。

示例: 'NumHeaderLines',7

数据类型: single | double

需要的变量数目,指定为包含 'ExpectedNumVariables' 和正整数的逗号分隔对组。如果未指定,则导入函数会自动检测变量数目。

数据类型: single | double

要从文本文件或电子表格文件中读取的数据部分,指定为以逗号分隔的对组,其中包含 'Range' 和采用以下形式之一的字符向量、字符串标量或数值向量。

指定 Range 的方式说明

起始单元格

'Cell'[row col]

将数据的起始单元格指定为字符向量、字符串标量或二元素数值向量。

  • 字符向量或字符串标量,其中包含使用 Excel A1 表示法的列字母和行号。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

  • 二元素数值向量,形式为 [row col],表示起始行和列。

根据起始单元格,导入函数通过从起始单元格开始导入,并在到达最后一个空行或页脚范围时结束,从而自动检测数据范围。

例如:'A5'[5 1]

矩形范围

'Corner1:Corner2'[r1 c1 r2 c2]

使用以下形式之一的矩形范围指定要读取的精确范围。

  • 'Corner1:Corner2' - 使用 Corner1Corner2 指定范围,这两个对角以 Excel A1 表示法定义要读取的区域。例如,'C2:N15'

  • [r1 c1 r2 c2] - 使用包含起始行、起始列、结束行和结束列的四元素数值向量指定范围。例如,[2 3 15 13]

导入函数只读取指定范围内包含的数据。指定范围内的任何空字段都作为缺失单元导入。

行范围或列范围

'Row1:Row2''Column1:Column2'

通过使用 Excel 行号标识起始行和结束行来指定范围。

根据指定的行范围,导入函数通过从第一个非空列开始读取,一直到数据的最后,从而自动检测列范围,并为每一列创建一个变量。

示例:'5:500'

也可以通过使用 Excel 列字母或列号标识起始列和结束列来指定范围。

根据指定的列范围,导入函数通过从第一个非空行开始读取,一直到数据的最后或页脚范围,从而自动检测行范围。

指定范围内的列数必须与 ExpectedNumVariables 属性中指定的数字匹配。

示例:'A:K'

起始行号

n

使用正标量行索引指定包含数据的第一行。

根据指定的行索引,导入函数通过从指定的第一行开始读取,一直到数据的最后或页脚范围,从而自动检测数据范围。

示例:5

Excel 中的命名范围

'NamedRange'

在 Excel 中,您可以创建名称来标识电子表格中的范围。例如,您可以选择电子表格的一个矩形部分,并将其命名为 'myTable'。如果电子表格中存在此类命名范围,则导入函数可以使用它的名称来读取该范围。

示例: 'Range','myTable'

未指定或为空

''

如果未指定,则导入函数会自动检测使用的范围。

示例: 'Range',''

注意:使用范围指电子表格中实际包含数据的矩形部分。导入函数通过删减不包含数据的前导行列和尾随行列,自动检测使用范围。只包含空白的文本被视为数据,并会在使用范围内被捕获。

数据类型: char | string | double

导入的文本数据的类型,指定为以逗号分隔的对组,其中包含 'TextType''char''string' 中的任一项。

  • 'char' - 将文本数据作为字符向量导入 MATLAB 中。

  • 'string' - 将文本数据作为字符串数组导入 MATLAB 中。

示例: 'TextType','char'

导入的日期和时间数据的类型,指定为以逗号分隔的对组,其中包含 'DatetimeType' 和下列值之一:'datetime''text''exceldatenum'。值 'exceldatenum' 仅适用于电子表格文件,对文本文件无效。

导入的日期和时间数据的类型
'datetime'

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

'text'

如果将 'DatetimeType' 指定为 'text',则导入的日期和时间数据的类型取决于 'TextType' 参数中指定的值:

  • 如果 'TextType' 设置为 'char',则导入函数会以字符向量元胞数组的形式返回日期。

  • 如果 'TextType' 设置为 'string',则导入函数会以字符串数组形式返回日期。

'exceldatenum'

Excel 日期序列值

日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 https://support.microsoft.com/en-us/kb/214330

数据类型: char | string

要解释为缺失数据的文本,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

示例: 'TreatAsMissing',{'NA','TBD'} 指示导入函数将 NATBD 的任何实例都视为缺失字段。

数据类型: char | string | cell

读取第一行作为变量名称,指定为逗号分隔的对组,包含 'ReadVariableNames'truefalse。如果未指定,导入函数会自动检测变量名称是否存在。

指示符

说明

true

当要读取的区域的第一行包含表的变量名称时使用。导入函数使用检测到的变量名称为 T 中的每列创建一个变量。

false

当要读取的区域的第一行包含表中的数据时使用。导入函数将创建 'Var1',...,'VarN' 形式的默认变量名称,其中 N 是变量的数量。

未指定 未指定时,导入函数会自动检测 truefalse,并相应地继续后续步骤。

opts 之外,当您指定 ReadVariableNames 名称-值对组时,导入函数如下进行。

  • 如果 ReadVariableNames 设置为 true,则导入函数通过使用导入选项对象的 VariableNamesRangeVariableNamesLine 属性从指定的文件中读取变量名称。

  • 如果 ReadVariableNames 设置为 false,则导入函数从导入选项对象的 VariableNames 属性读取变量名称。

数据类型: logical

行时间变量,指定为由 'RowTimes' 和变量名称或时间向量组成的以逗号分隔的对组。

  • 变量名称必须为字符向量或字符串标量,其中包含输入表中任何具有 datetimeduration 值的变量的名称。变量名称指定的变量为行提供行时间标签。输入表的其余变量成为时间表的变量。

  • 时间向量必须为 datetime 向量或 duration 向量。时间向量的元素数必须等于输入表的行数。时间向量中的时间值不必是唯一、已排序或规则的。输入表中的所有变量都成为时间表中的变量。

数据类型: char | string | datetime | duration

行时间的采样率,以逗号分隔的对组形式指定,该对组由 'SampleRate' 和一个正数值标量组成。采样率是输出时间表的时间向量的每秒采样数 (Hz)。

当您使用 'SampleRate' 指定时间表的行时间向量时,默认的第一个行时间(开始时间)为零秒。要设置非零的开始时间,请指定 'StartTime' 名称-值对组。

数据类型: double

行时间之间的时间步,指定为以逗号分隔的对组,由 'TimeStep' 和持续时间标量或 calendarDuration 标量组成。'TimeStep' 参数的值指定连续行时间之间的时间长度。导入函数使用时间步长值来计算固定间隔的行时间。

当您使用 'TimeStep' 指定时间表的行时间向量时,默认的第一个行时间(开始时间)为零秒。要设置非零的开始时间,请指定 'StartTime' 名称-值对组。

如果 'TimeStep' 是日历持续时间值,则 'StartTime' 必须为日期时间值。

数据类型: duration | calendarDuration

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

要定义时间表的时间向量,请使用 'StartTime''SampleRate''TimeStep' 名称-值对组参数。

开始时间的数据类型决定行时间向量的数据类型。

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

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

数据类型: datetime | duration

保留变量名称的标志,指定为以逗号分隔的对组,由 PreserveVariableNamestruefalse 组成。

  • true - 保留作为无效 MATLAB 标识符的变量名称,如包含空格和非 ASCII 字符的变量名称。

  • false - 将无效变量名称(由 isvarname 函数确定)转换为有效的 MATLAB 标识符。

从 R2019b 开始,变量名称和行名称可以包含任何字符,包括空格和非 ASCII 字符。此外,它们可以由任何字符(而不仅仅是字母)开头。变量名称和行名称可以不是有效的 MATLAB 标识符(由 isvarname 函数决定)。要保留这些变量名称和行名称,请将 PreserveVariableNames 设置为 true

仅限文本文件

全部折叠

带分隔符的文本文件中的字段分隔符,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

示例: 'Delimiter','|'

示例: 'Delimiter',{';','*'}

数据类型: char | string | cell

要视为空白的字符,指定为包含一个或多个字符的字符向量或字符串标量。

示例: 'Whitespace',' _'

示例: 'Whitespace','?!.,'

行尾字符,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

示例: 'LineEnding','\n'

示例: 'LineEnding','\r\n'

示例: 'LineEnding',{'\b',':'}

数据类型: char | string | cell

注释样式,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

例如,要忽略同一行上百分号后面的文本,请将 CommentStyle 指定为 '%'

示例: 'CommentStyle',{'/*'}

数据类型: char | string | cell

与文件关联的字符编码方案,指定为以逗号分隔的对组,其中包含 'Encoding''system' 或标准字符编码方案名称。如果您没有指定任何编码,则 readtimetable 函数在读取文件时将使用自动字符集检测来确定编码。

如果除导入选项外您还指定了 'Encoding' 参数,readtimetable 函数将使用为 'Encoding' 指定的值,而覆盖导入选项中定义的编码方案。

示例: 'Encoding','UTF-8' 使用 UTF-8 作为编码。

示例: 'Encoding','system' 使用系统默认编码。

数据类型: char | string

来自文本文件的持续时间数据的输出数据类型,指定为以逗号分隔的对组,其中包含 'DurationType''duration''text'

导入的持续时间数据的类型
'duration'

MATLAB duration 数据类型

有关详细信息,请参阅 duration

'text'

如果将 'DurationType' 指定为 'text',则导入的持续时间数据的类型取决于 'TextType' 参数中指定的值:

  • 如果 'TextType' 设置为 'char',则导入函数会以字符向量元胞数组的形式返回持续时间数据。

  • 如果 'TextType' 设置为 'string',则导入函数会以字符串数组的形式返回持续时间数据。

数据类型: char | string

用于读取日期的区域设置,指定为逗号分隔的对组,其中包含 'DateLocale' 和一个 xx_YY 形式的字符向量或字符串标量,其中:

  • YY 是指示国家/地区的大写 ISO 3166-1 alpha-2 代码。

  • xx 是指示语言的小写 ISO 639-1 双字母代码。

有关区域设置的常见值的列表,请参阅 datetime 函数的 Locale 名称-值对组参数。

使用 %D 格式设定符来将文本读取为 datetime 值时,请使用 DateLocale 指定导入函数应使用何种区域设置来解释月份和星期几的名称及缩写。

如果除 opts 导入选项外您还指定了 DateLocale 参数,则导入函数将使用为 DateLocale 参数指定的值,而覆盖导入选项中定义的区域设置。

示例: 'DateLocale','ja_JP'

表示数值变量中小数分隔符的字符,指定为字符向量或字符串标量。导入函数使用 DecimalSeparator 名称-值对组中指定的字符来区分数字的整数部分和小数部分。

转换为整数数据类型时,带小数部分的数字将被舍入为最接近的整数。

示例: 如果名称-值对组指定为 'DecimalSeparator',',',则导入函数将文本 "3,14159" 导入为数字 3.14159

数据类型: char | string

表示数值变量中千分位的字符,指定为字符向量或字符串标量。千分位字符作为视觉分隔符,将数字按三位数一组进行分组。导入函数使用 ThousandsSeparator 名称-值对组中指定的字符来解释要导入的数字。

示例: 如果名称-值对组指定为 'ThousandsSeparator',',',则导入函数将文本 "1,234,000" 导入为 1234000

数据类型: char | string

从数值变量中删除非数值字符,指定为逻辑值 truefalse

示例: 如果名称-值对组指定为 'TrimNonNumeric',true,则导入函数将 '$500/-' 读取为 500

数据类型: logical

处理带分隔符的文本文件中连续分隔符的过程,指定为下表中的值之一。

连续分隔符规则行为
'split'将连续分隔符拆分为多个字段。
'join'将多个分隔符合并成一个分隔符。
'error'返回错误并中止导入操作。

数据类型: char | string

管理带分隔符的文本文件中的前导分隔符的过程,指定为下表中的值之一。

前导分隔符规则行为
'keep'保留分隔符。
'ignore'忽略分隔符。
'error'返回错误并中止导入操作。
仅限电子表格文件

全部折叠

要从中读取数据的工作表,指定为空字符数组、包含工作表名称的字符向量或字符串标量,或表示工作表索引的正整数标量。根据为 Sheet 属性指定的值,导入函数的行为如下表中所述。

指定的值行为
''(默认值)从第一个工作表导入数据。
名称从具有匹配名称的工作表中导入数据,不考虑电子表格文件中工作表的顺序。
整数从由整数指定的位置的工作表导入数据,不考虑电子表格文件中的工作表名称。

数据类型: char | string | single | double

用于在读取电子表格数据时启动 Windows 版 Microsoft Excel 实例的标志,指定为逗号分隔的对组,包含 'UseExcel'truefalse

您可以将 'UseExcel' 参数设置为下列值之一:

  • true - 导入函数在读取文件时启动 Microsoft Excel 的实例。

  • false - 导入函数在读取文件时不启动 Microsoft Excel 的实例。在此模式下操作时,导入函数功能支持的文件格式和交互式功能(例如公式和宏)有所不同。

UseExcel

true

false

支持的文件格式

.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods

.xls, .xlsx, .xlsm, .xltx, .xltm

支持交互功能,例如公式和宏

从 Windows 平台上的电子表格文件中读取时,如果您想启动 Microsoft Excel 实例,则将 'UseExcel' 参数设置为 true

输出参数

全部折叠

输出时间表。该时间表可以存储元数据,例如说明、变量单位、变量名称和行时间。有关详细信息,请参阅 timetable 的“属性”部分。

在 R2019a 中推出